Auto Photo Albums by castlecode

Thank you for purchasing this plugin. If you have any questions that are beyond the scope of this help file, please feel free to email via my user page contact form here. Thank you!

Heads up! inside the example folder you'll find a file named plugin_only.html, that file/page contains ONLY the code needed for the plugin! You can base on that file to start installing your gallery!

Including files

These are all the files you need to import in your .html page so the plugin can work.

  1. <!-- Auto Photo Albums CSS files -->
  2. <link rel="stylesheet" href="plugin/components/Font Awesome/css/font-awesome.min.css"> <!-- only if you use Font Awesome -->
  3. <link rel="stylesheet" href="plugin/components/Fancybox/jquery.fancybox.min.css"> <!-- only if you use fancybox -->
  4. <link rel="stylesheet" href="plugin/components/Media Boxes/css/mediaBoxes.css">
  5. <link rel="stylesheet" href="plugin/autoPhotoAlbums.css">
  6.  
  7. <!-- jQuery 1.8+ -->
  8. <script src="plugin/components/jQuery/jquery-1.11.3.min.js"></script>
  9.  
  10. <!-- Auto Photo Albums JS files. -->
  11. <script src="plugin/components/Isotope/jquery.isotope.min.js"></script>
  12. <script src="plugin/components/imagesLoaded/jquery.imagesLoaded.min.js"></script>
  13. <script src="plugin/components/Transit/jquery.transit.min.js"></script>
  14. <script src="plugin/components/jQuery Easing/jquery.easing.js"></script>
  15. <script src="plugin/components/jQuery Visible/jquery.visible.min.js"></script>
  16. <script src="plugin/components/Modernizr/modernizr.custom.min.js"></script>
  17. <script src="plugin/components/Fancybox/jquery.fancybox.min.js"></script> <!-- only if you use Fancybox -->
  18. <script src="plugin/components/Media Boxes/js/jquery.mediaBoxes.dropdown.js"></script>
  19. <script src="plugin/components/Media Boxes/js/jquery.mediaBoxes.js"></script>
  20. <script src="plugin/jquery.autoPhotoAlbums.js"></script>
  21.  
Heads up! even if you already got isotope included in your page you need to include the one that comes with the plugin since it is the latest version and I changed the namespace.

It’s not required, but I recommend placing the CSS files in <head> and the JavaScript files and the JS initialization code in the footer of your site (before the closing </body> tag). If you already have jquery.js on your site, don’t include it a second time.

HTML

Here is the basic HTML for the Auto Photo Albums. Place it anywhere in your page! The plugin will automatically take care of filling that div with the images for the gallery

  1. <div id="grid"></div>

PHP File

In the example folder you'll find a file named "auto_photo_albums.php" this file is the one that reads the images from its folder and that's why you need PHP since it is a PHP script file

It is very important that you place this php file in the same directory where your HTML/PHP page is, otherwise the JS plugin will not be able to find it

Initializing

Once you got the HTML markup in your site you need to initialize the plugin in Javascript.

You need to take the id from the previous step in the HTML (In the example above would be: id="grid") and use it for the initialization.

  1. <script>
  2.     
  3.     $('#grid').autoPhotoAlbums(); 
  4.     
  5. </script>

And here is where you can pass all the options available. For example:

  1. <script>
  2.     
  3.     $('#grid').autoPhotoAlbums({
  4.         directory       : 'galleries/gallery',
  5.         configFile      : '',
  6.     }); 
  7.     
  8. </script>

You can see all the options available here

Important! This JS initialization must be placed after all the JS files you imported in the first step.

Drag & Drop images into your folder

No albums, only images

If you don't want any album only images then you can just drag and drop your images in the gallery folder!
The folder will look like this:

The plugin will take care of reading them, just refresh your page and you will see this images automatically added to the gallery!


With albums

If you want albums then inside the "gallery" folder you need to create subfolders that will be the albums of your gallery (e.g. Illustrations, Photography, Drawings, etc.) and inside those folders you can place the images you want. And that's it, refresh the page.
The caption box that shows when you move the mouse over an image will be the name of the image!
The directory will look like this:

Without limit

Is not over, you can keep creating folders of images inside a folder inside a folder inside a folder and the plugin will read them all and create a navigation breadcrumb at the top so you can go back.
The directory will look like this:

Thumbnails

Now is time to add some thumbnails to each image.

To improve performance you can add thumbnails to the gallery.
The thumbnails will be used in the grid and the original images in the lightbox (when you click on a thumbnail).
To make a thumbnail just add a folder named "thumbnails" and inside place the thumbnails of your images, the thumbnail must have the exact same name of the original image so the plugin can recognize it.

For example if you wish to add a thumbnail for an image named "Black Dress.jpg" you will do it like this:

You don't need to add a thumbnail for each image, just for the ones you like.

Important: make sure that the folder of the thumnails is named "thumbnails" all in lowercase and that the thumbnail has the exact same name of the original.
Heads Up! For performance be careful with the size of your images, the images in the live preview are around 180kb and the thumnails around 30kb.

Config File (.txt)

You can place a .txt file inside your gallery so you can add/edit some extra information about your images or albums, for example, maybe you wish to add a youtube video for some of your images or some tags or you can even add some extra description to your albums.

So first place a .txt file inside your folder, for example config.txt, as follows:

Then open it in some text editor and add the following text

  1. album           => Category 1
  2. description     => Lorem ipsum dolor sit amet.
  4. image           => Category 1/Autumn.jpg
  5. link            => https://codecanyon.net/item/auto-photo-albums-multi-level-image-grid/5319229
  6. popup_src       => https://www.youtube.com/watch?v=5guMumPFBag
  7.  
  8. image           => Category 2/Empty Cups.jpg
  9. popup_src       => https://www.youtube.com/watch?v=5guMumPFBag
  10.  
  11. image           => Category 3/Morning.jpg
  12. popup_src       => https://www.youtube.com/watch?v=UrIbxk7idYA

This is just en example .txt file, as you can see you need to specify the URL of the image/album and then below you can add some extra variables to each, like link, popup_src, ratio, description, etc

Important the "=>" is important since the plugin will use it to divide the variable from the value.

Also the empty lines between images is very important so the plugin can differentiate between several images, you can use 1 or 2 or 3 empty lines between each image! as follows:

These are the default variables the plugin uses so you can modify them if needed, also you can add your own:

  1. image           => Category 1/Autumnn.jpg
  2. link            => https://codecanyon.net/?param=param
  3. name            => My Image Name
  4. thumb_src       => Category 1/thumbnails/Autumnn.jpg
  5. ratio           => 1x1
  6. popup_src       => https://www.youtube.com/watch?v=5guMumPFBag
  7. popup_type      => iframe

Options

Here you can see all the JS options available for the auto photo albums.

Option Type Default Description
directory string 'galleries/gallery' The location where your images are
ignoreAlbums JS array [] An array of albums/folders that will be ignored by the plugin
configFile string 'config.txt' The name of the file that will be used to add extra information to your images and albums
nameDivider string '-' In the name, everything before this characters will not be shown
linkTarget string 'new_window' The link target, either 'new_window' or 'self'
limit boolean or integer false If you wish to limit the number of images to be shown then change false to some number, i.e 10 or 20
breadcrumb boolean true Show the breadcrumb
breadcrumbHome string 'Home' The name of the first item in the breadcrumb
deeplinkingOnAlbums boolean true Enable deeplinking when you navigate through your albums
scrollTop boolean true When you open an album the browser will scroll to the top of that album (so you can see it from the start)
scrollTopSpeed integer 200 The speed of the animation that will scroll to the top
thumbnailsOrder string 'byName' You can use any of these options: 'byDate', 'byDateReverse', 'byName', 'byNameReverse', 'random'
albumsFirst boolean true Show first the albums then the thumbnails
globalAlbumRatio boolean or string false If you want to specify a global ratio for all your albums. Change false to something like: '1x1' or '255x150'
globalThumbRatio boolean or string false If you want to specify a global ratio for all your thumbnails. Change false to something like: '1x1' or '255x150'
search boolean true Activate (true) or Deactivate (false) the search input field
searchWord string 'search' The serch text placeholder in the input text
albumTemplate string You can change the template of the albums
itemTemplate string You can change the template of the thumbnails
GRID OPTIONS
boxesToLoadStart number 8 The number of boxes to load when it first loads the grid
boxesToLoad number 4 The number of boxes to load when you click the load more button or when the "lazzy load" mode is triggered
lazyLoad boolean true When you reach the bottom of the grid the plugin will try to load more media boxes (The bottom of the grid must hit the bottom of your browser window)
horizontalSpaceBetweenBoxes number 15 The horizontal space between media boxes
verticalSpaceBetweenBoxes number 15 The vertical space between media boxes
columnWidth string or number 'auto' The width of each column, if you set it to 'auto' it will use the columns option instead
columns number 4 This will only work if you set the columnWidth to 'auto' and it is the number of columns you wish to display in the grid so it can adapt to its container automatically
resolutions array click me Here you define the columnWidth, the columns, the horizontalSpaceBetweenBoxes and the verticalSpaceBetweenBoxes for different resolutions, for example if for mobile resolutions (like phones) you want to show only 1 column of media boxes this is the place to configure it. You can have as many resolutions as you want or have none
I want an example!
waitUntilThumbWithRatioLoads boolean true When the thumbnails got the ratio specified, if it's set to true it will wait until the thumbnail is loaded (showing a progress wheel) and then show the thumb, if not you will see the progress as it gets loaded
waitForAllThumbsNoMatterWhat boolean false Even if the thumbnails got the ratio specified wait until all of them are loaded in order to show the grid layout and the content
thumbnailOverlay boolean true Show the thumbnail overlay?
overlayEffect string 'fade' The overlay effect All the overlay effects!
overlaySpeed number 200 The speed of the overlay effect
overlayEasing string 'default' The easing of the overlay effect All the easing effects!
showOnlyLoadedBoxesInPopup boolean false In the popup show only the boxes that are loaded in the grid. It needs to be set to false for deeplinking.
deepLinkingOnPopup boolean true Activate deep linking for the popup, for a correct functionality you need to set to false the option showOnlyLoadedBoxesInPopup and also set an id to the grid container, for example id="grid".
deepLinkingOnSearch boolean false Activate deep linking for the search, for a correct functionality you need to set to false the option showOnlyLoadedBoxesInPopup and also set an id to the grid container, for example id="grid".
LoadingWord string 'Loading...' The loading word
loadMoreWord string 'Load More' The load more word
noMoreEntriesWord string 'No More Entries' The no more entries word
popup string 'fancybox' Which popup you are going to use, either 'fancybox' or 'magnificpopup'
magnificpopup array check options below The options you can use when using Magnific Popup
fancybox array check options below The options you can use when using Fancybox

You can pass all the options to the autoPhotoAlbums JS function like this (these are the default values)

  1. <script>
  2.     
  3. $('#grid').autoPhotoAlbums({
  4.     directory           : 'galleries/gallery',
  5.     directoryURL        : '',
  6.     ignoreAlbums        : [],
  7.     configFile          : 'config.txt',
  8.  
  9.     nameDivider         : '-', // In the name, everything before this characters will not be shown
  10.     linkTarget          : 'new_window', // 'new_window' or 'self'
  11.     limit               : false,
  12.     breadcrumb          : true,
  13.     breadcrumbHome      : 'Home',
  14.     deeplinkingOnAlbums : true,
  15.     scrollTop           : true,
  16.     scrollTopSpeed      : 200,
  17.  
  18.     /* Thumbnails options */
  19.  
  20.     thumbnailsOrder     : 'byName', // byDate, byDateReverse, byName, byNameReverse, random
  21.     albumsFirst         : true,
  22.     globalAlbumRatio    : '200x200',
  23.     globalThumbRatio    : false,
  24.  
  25.     /* search options */
  26.  
  27.     search              : true,
  28.     searchWord          : 'search',
  29.     
  30.     /* Template options */
  31.  
  32.     albumTemplate        :  ' <div class="media-box-image"> '+
  33.                                 ' <div data-thumbnail="{{album_cover}}" {{ratio}} data-title="{{name}}" data-alt="{{name}}"></div> '+
  34.  
  35.                                 ' <div class="media-box-album"> '+
  36.                                     ' <div class="media-box-album-name">{{name}}</div> '+
  37.                                     ' <div class="media-box-album-count"> '+
  38.                                         ' {{image_count}} images <span hide_if_empty="{{album_count}}">and {{album_count}} album(s)</span> '+ 
  39.                                     ' </div> '+ 
  40.                                 ' </div> '+
  41.                             ' </div> ',
  42.  
  43.     itemTemplate        :   ' <div class="media-box-image mb-open-popup" {{link}} data-src="{{popup_src}}" data-title="{{name}}" data-type="{{popup_type}}"> '+
  44.                                 ' <div data-thumbnail="{{thumb_src}}" {{ratio}} data-title="{{name}}" data-alt="{{name}}"></div> '+
  45.                                 
  46.                                 ' <div class="thumbnail-overlay"> '+
  47.  
  48.                                     ' <div class="thumbnail-overlay-animated" data-from="top"> '+
  49.                                         ' <div class="thumbnail-overlay-title">{{name}}</div> '+
  50.                                     ' </div> '+
  51.  
  52.                                 ' </div> '+
  53.                             ' </div>',
  54.  
  55.     /* Media Boxes options */
  56.  
  57.     grid : {
  58.         boxesToLoadStart                : 9,
  59.         boxesToLoad                     : 9,
  60.         lazyLoad                        : true,
  61.         lazyLoadInLoadMoreView          : false,
  62.         horizontalSpaceBetweenBoxes     : 30,
  63.         verticalSpaceBetweenBoxes       : 30,
  64.         columnWidth                     : 'auto',
  65.         columns                         : 3,
  66.         resolutions                     :   [
  67.             {
  68.                 maxWidth: 960,
  69.                 columnWidth: 'auto',
  70.                 columns: 3,
  71.             },
  72.             {
  73.                 maxWidth: 650,
  74.                 columnWidth: 'auto',
  75.                 columns: 2,
  76.                 horizontalSpaceBetweenBoxes: 10,
  77.                 verticalSpaceBetweenBoxes: 10,
  78.             },
  79.             {
  80.                 maxWidth: 450,
  81.                 columnWidth: 'auto',
  82.                 columns: 1,
  83.                 horizontalSpaceBetweenBoxes: 10,
  84.                 verticalSpaceBetweenBoxes: 10,
  85.             },
  86.         ],
  87.         waitUntilThumbWithRatioLoads    : true, // When they have dimensions specified
  88.         waitForAllThumbsNoMatterWhat    : false, // Wait for all the thumbnails to load even if they got dimensions specified
  89.         thumbnailOverlay                : true, //Show the overlay on mouse over
  90.         overlayEffect                   : 'fade', // 'push-up', 'push-down', 'push-up-100%', 'push-down-100%', 'reveal-top', 'reveal-bottom', 'reveal-top-100%', 'reveal-bottom-100%', 'direction-aware', 'direction-aware-fade', 'direction-right', 'direction-left', 'direction-top', 'direction-bottom', 'fade'
  91.         overlaySpeed                    : 200,
  92.         overlayEasing                   : 'default',
  93.         showOnlyVisibleBoxesInPopup     : false,
  94.         deepLinkingOnPopup              : true,
  95.         deepLinkingOnSearch             : false,
  96.         LoadingWord                     : 'Loading...',
  97.         loadMoreWord                    : 'Load More',
  98.         noMoreEntriesWord               : 'No More Entries',
  99.         percentage                      : false,
  100.         popup                           : 'fancybox', // fancybox, magnificpopup, none
  101.         magnificpopup                   :   {
  102.             gallery: true,
  103.             alignTop: false,
  104.             preload: [0,2],    
  105.         },
  106.         fancybox                        :   {
  107.             loop                : false, // Enable infinite gallery navigation 
  108.             margin              : [44, 0], // Space around image, ignored if zoomed-in or viewport smaller than 800px
  109.             keyboard            : true, // Enable keyboard navigation
  110.             arrows              : true, // Should display navigation arrows at the screen edges
  111.             infobar             : false, // Should display infobar (counter and arrows at the top)
  112.             toolbar             : true, // Should display toolbar (buttons at the top)
  113.             buttons             :   [ // What buttons should appear in the top right corner.
  114.                                         'slideShow',
  115.                                         'fullScreen',
  116.                                         'thumbs',
  117.                                         'close'
  118.                                     ],
  119.             idleTime            : 3, // Detect "idle" time in seconds
  120.             protect             : false, // Disable right-click and use simple image protection for images
  121.             animationEffect     : 'zoom', // Open/close animation type, it could be: false, 'zoom', 'fade', 'zoom-in-out'
  122.             animationDuration   : 330, // Duration in ms for open/close animation
  123.             transitionEffect    : 'fade', // it could be: false, 'fade', 'slide', 'circular', 'tube', 'zoom-in-out', 'rotate'
  124.             transitionDuration  : 330, // Duration in ms for transition animation
  125.             slideShow           : { autoStart : false, speed : 4000 }, // slideshow settings
  126.             fullScreen          : { autoStart : false, }, // activate or deactivate fullscreen when open
  127.             thumbs              : { autoStart : false, hideOnClose : true },    // Display thumbnails on opening/closing
  128.             touch               : { vertical : true, momentum : true }, // Allow to drag content
  129.             compensateScrollbar : '.fancybox-compensate-for-scrollbar',
  130.         },
  131. }); 
  132.     
  133. </script>

Template

You may have noticed two options named "albumTemplate" and "itemTemplate" in the previous section, in there you can specify the HTML of each album and thumbnail you can add/edit/remove HTML, here's an example template:

  1. itemTemplate :  ' <div class="media-box-image mb-open-popup" {{link}} data-src="{{popup_src}}" data-title="{{name}}" data-type="{{popup_type}}"> '+
  2.                     ' <div data-thumbnail="{{thumb_src}}" {{ratio}} data-title="{{name}}" data-alt="{{name}}"></div> '+
  3.                     
  4.                     ' <div class="thumbnail-overlay"> '+
  5.  
  6.                         ' <div class="thumbnail-overlay-animated" data-from="top"> '+
  7.                             ' <div class="thumbnail-overlay-title">{{name}}</div> '+
  8.                         ' </div> '+
  9.  
  10.                     ' </div> '+
  11.                 ' </div>',

Each variable is inside double brakets, for example: {{name}} is the name of the image.

here you can also pull variables from the .txt file, for example if you add a variable in the .txt file like this: text => some random text here you can pull that variable in the template like this: {{text}}. The plugin will take care of replacing that variable with what you have specified in the .txt file

Heads up! In the different examples of the plugin (inside the example folder) you'll find different templates for each example, you can take some ideas from there.
Important! Be careful while playing with the template, specially with the ' at the start and end of each line and also the + at the end of each line! Because if they are not correctly formated Javascript will throw an error!

Handy Stuff

When you order the images 'ByName' and you want to control the order of the images and albums just add a-, b-, etc... at beginning of the name of each image/album (the a-,b-, etc... will not be visible in the gallery):





By default the plugin will choose a random image inside the album and use it as the "album cover" image.
But you can name an image "albumCover" (albumCover.png, albumCover.jpg, etc) and the plugin will use it as the "album cover" image (this image will not be shown in the grid when you open that album).





You can change the default configuration for a specific album
For example: by default the gallery has 3 columns but maybe in a specific album you wish to have 4 columns, then in that album add a file named "settings.txt" and in that file add the new JS settings, something like this: 

  1. "grid"          :   {
  2.                         "columns" : 4,
  3.                         "fancybox" : {
  4.                             "transitionEffect" : "tube"
  5.                         }
  6.                     }
You need to be very careful with the JS format, for example all strings must have double quotes (i.e. "grid"), also don't leave an extra comma at the end.
You can validate your JS format here: https://jsonlint.com/ just wrap your settings in a {} and that's it, test it out, for example: