Auto Grid 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.php, that file/page contains ONLY the code needed for the plugin! You can base on that file to start installing your gallery!

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

<!-- Media Boxes CSS files -->
<link rel="stylesheet" href="plugin/components/Font Awesome/css/font-awesome.min.css">
<link rel="stylesheet" href="plugin/components/Magnific Popup/magnific-popup.css"> <!-- Only if you are going to use Magnific Popup -->
<link rel="stylesheet" href="plugin/components/Fancybox/jquery.fancybox.min.css"> <!-- Only if you are going to use fancybox -->
<link rel="stylesheet" href="plugin/components/Media Boxes/css/mediaBoxes.css">

<!-- The PHP file that scans a folder in your server -->
<?php require_once("../plugin/auto_grid.php"); ?>

<!-- jQuery 1.8+ -->
<script src="plugin/components/jQuery/jquery-1.11.3.min.js"></script>

<!-- Media Boxes JS files -->
<script src="plugin/components/Isotope/jquery.isotope.min.js"></script>
<script src="plugin/components/imagesLoaded/jquery.imagesLoaded.min.js"></script>
<script src="plugin/components/Transit/jquery.transit.min.js"></script>
<script src="plugin/components/jQuery Easing/jquery.easing.js"></script>
<script src="plugin/components/jQuery Visible/jquery.visible.min.js"></script>
<script src="plugin/components/Modernizr/modernizr.custom.min.js"></script>
<script src="plugin/components/Magnific Popup/jquery.magnific-popup.min.js"></script> <!-- Only if you are going to use Magnific Popup -->
<script src="plugin/components/Fancybox/jquery.fancybox.min.js"></script> <!-- Only if you are going to use fancybox -->
<script src="plugin/components/Media Boxes/js/jquery.mediaBoxes.dropdown.js"></script>
<script src="plugin/components/Media Boxes/js/jquery.mediaBoxes.js"></script>
<script src="plugin/jquery.autoGrid.js"></script>

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 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.

Here is the basic HTML for the Auto Grid. Place it anywhere in your page! Here you specify the url of the folder that the plugin will scan looking for images to build the gallery, in this case is galleries/gallery

<div id="grid" auto-grid-data="<?php echo get_auto_grid_data("galleries/gallery"); ?>"></div>

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.

<script>
    
    $('#grid').autoGrid(); 
    
</script>

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

<script>
    
    $('#grid').autoGrid({
        filter: true,
        search: false,
    }); 
    
</script>

You can see all the options available here

No categories and neither navigation bar filter

If you don't want categories and neither a navigation bar filter just a grid of images then you can just drag and drop them 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 grid!

With categories and navigation bar filter

If you want categories inside the "gallery" folder you need to create subfolders that will be the categories of your gallery (e.g. Illustrations, Photography, Drawings, etc.) and inside those folders you put the images you want. And that's it, refresh your page and you will see now your gallery with the images you just add with the folders as filters. 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:

Now is time to add some thumbnails to each image.

To improve performance you can add thumbnails for the grid and then when you click in one of them the plugin will open a lightbox with the real one. To make a thumbnail just add a folder named "thumbnails" and inside put the thumbnails of your images, the thumbnail must have the same name of the real 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 the thumbnail image has the exact same name of the real one.

Heads Up! For performance take care of your images size, the images on the live preview are around 180kb and the thumnails are around 30kb so the gallery is faster.

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

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

image           => Category 1/Autumn.jpg
link            => https://codecanyon.net/item/auto-grid-responsive-gallery/3864088
popup_src       => https://www.youtube.com/watch?v=5guMumPFBag

image           => Category 2/Empty Cups.jpg
popup_src       => https://www.youtube.com/watch?v=5guMumPFBag

image           => Category 3/Morning.jpg
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 and then below you can add some extra variables to each, like link, popup_src, ratio, 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:

All the available variables you can use per image are the following:

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

Finally you need to tell the plugin which .txt file to use, and you can do that by passing it next to the gallery directory like this:

<div id="grid" auto-grid-data="<?php echo get_auto_grid_data("galleries/gallery", "config.txt"); ?>"></div>

Here you can see all the JS options available for the media boxes.

Option	Type	Default	Description
`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`
`thumbnailsOrder`	string	'byName'	You can use any of these options: `'byDate'`, `'byDateReverse'`, `'byName'`, `'byNameReverse'`, `'random'`
`fewThumbsFromEach`	boolean	true	Get few images from each category if not it will get them in order (in the all category)
`globalRatio`	boolean or string	false	If you want to specify a global ratio for all your images 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
`filter`	boolean	true	Activate (`true`) or Deactivate (`false`) the filter navigation bar
`filterAll`	boolean	true	Activate (`true`) or Deactivate (`false`) the filter "All"
`filterAllWord`	string	'All'	You can change the text of the 'All' word to something else
`filterLayout`	string	'inline'	You can use any of these options: `'inline'` or `'dropdown'`
`filterDefault`	string	'All'	The category filter that will be selected when the page loads
`filterDropdownEvent`	string	'hover'	You can use any of these options: `'hover'` or `'click'`
`filterOrder`	string	'byName'	You can use any of these options: `'byDate'`, `'byDateReverse'`, `'byName'`, `'byNameReverse'`, `'random'`
`itemTemplate`	string		You can change the template of the boxes
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!
`multipleFilterLogic`	string	'AND'	It can be 'AND' or 'OR' depending on how you wish to combine the filters when you are using multiple
`minBoxesPerFilter`	number	0	This is the minimum of media boxes per filter. If the number of boxes in a filter is less than the number specified here it will try to load more boxes from that filter category
`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.
`considerFilteringInPopup`	boolean	true	The popup take in consideration the filter, so it shows only boxes from the filter specified.
`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"`.
`deepLinkingOnFilter`	boolean	true	Activate deep linking for the filter, 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 autoGrid JS function like this (these are the default values)

<script>
    
$('#grid').autoGrid({
    nameDivider : '-', // In the name, everything before this characters will not be shown
    linkTarget  : 'new_window', // 'new_window' or 'self'
    limit       : false,

    /* Thumbnails options */

    thumbnailsOrder   : 'byName', // byDate, byDateReverse, byName, byNameReverse, random
    fewThumbsFromEach : true,
    globalRatio       : false,

    /* Filter options */
    
    search             : true,
    searchWord         : 'search',
    filter             : true,
    filterAll          : true,
    filterAllWord      : 'All',
    filterLayout       : 'inline', // 'inline' or 'dropdown'
    filterDefault      : 'All',
    filterDropdownEvent: 'hover', // 'hover' or 'click'
    filterOrder        : 'byName', // 'byDate', 'byDateReverse', 'byName', 'byNameReverse', 'random'

    /* Template options */

    itemTemplate :  ' <div class="media-box-image mb-open-popup" {{link}} data-src="{{popup_src}}" data-title="{{name}}" data-type="{{popup_type}}"> '+
                        ' <div data-thumbnail="{{thumb_src}}" {{ratio}} data-title="{{name}}" data-alt="{{name}}"></div> '+
                        
                        ' <div class="thumbnail-overlay"> '+

                            ' <div class="thumbnail-overlay-animated" data-from="top"> '+
                                ' <div class="media-box-title">{{name}}</div> '+
                            ' </div> '+
                            ' <div class="thumbnail-overlay-animated" data-from="bottom"> '+
                                ' <div class="media-box-date">{{filter}}</div> '+
                            ' </div> '+

                        ' </div> '+
                    ' </div>',

    /* Media Boxes options */

    grid : {
        boxesToLoadStart                : 9,
        boxesToLoad                     : 9,
        minBoxesPerFilter               : 9,
        lazyLoad                        : true,
        lazyLoadInLoadMoreView          : true,
        horizontalSpaceBetweenBoxes     : 30,
        verticalSpaceBetweenBoxes       : 30,
        columnWidth                     : 'auto',
        columns                         : 3,
        resolutions                     :   [
            {
                maxWidth: 960,
                columnWidth: 'auto',
                columns: 3,
            },
            {
                maxWidth: 650,
                columnWidth: 'auto',
                columns: 2,
                horizontalSpaceBetweenBoxes: 10,
                verticalSpaceBetweenBoxes: 10,
            },
            {
                maxWidth: 450,
                columnWidth: 'auto',
                columns: 1,
                horizontalSpaceBetweenBoxes: 10,
                verticalSpaceBetweenBoxes: 10,
            },
        ],
        multipleFilterLogic             : 'AND',
        waitUntilThumbWithRatioLoads    : true, // When they have dimensions specified
        waitForAllThumbsNoMatterWhat    : false, // Wait for all the thumbnails to load even if they got dimensions specified
        thumbnailOverlay                : true, //Show the overlay on mouse over
        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'
        overlaySpeed                    : 200,
        overlayEasing                   : 'default',
        showOnlyVisibleBoxesInPopup     : false,
        considerFilteringInPopup        : true,
        deepLinkingOnPopup              : true,
        deepLinkingOnFilter             : true,
        deepLinkingOnSearch             : false,
        LoadingWord                     : 'Loading...',
        loadMoreWord                    : 'Load More',
        noMoreEntriesWord               : 'No More Entries',
        percentage                      : false,
        popup                           : 'fancybox', // fancybox, magnificpopup, none
        magnificpopup                   :   {
            gallery: true,
            alignTop: false,
            preload: [0,2],    
        },
        fancybox                        :   {
            loop                : false, // Enable infinite gallery navigation 
            margin              : [44, 0], // Space around image, ignored if zoomed-in or viewport smaller than 800px
            keyboard            : true, // Enable keyboard navigation
            arrows              : true, // Should display navigation arrows at the screen edges
            infobar             : false, // Should display infobar (counter and arrows at the top)
            toolbar             : true, // Should display toolbar (buttons at the top)
            buttons             :   [ // What buttons should appear in the top right corner.
                                        'slideShow',
                                        'fullScreen',
                                        'thumbs',
                                        'close'
                                    ],
            idleTime            : 3, // Detect "idle" time in seconds
            protect             : false, // Disable right-click and use simple image protection for images
            animationEffect     : 'zoom', // Open/close animation type, it could be: false, 'zoom', 'fade', 'zoom-in-out'
            animationDuration   : 330, // Duration in ms for open/close animation
            transitionEffect    : 'fade', // it could be: false, 'fade', 'slide', 'circular', 'tube', 'zoom-in-out', 'rotate'
            transitionDuration  : 330, // Duration in ms for transition animation
            slideShow           : { autoStart : false, speed : 4000 }, // slideshow settings
            fullScreen          : { autoStart : false, }, // activate or deactivate fullscreen when open
            thumbs              : { autoStart : false, hideOnClose : true },    // Display thumbnails on opening/closing
            touch               : { vertical : true, momentum : true }, // Allow to drag content
            compensateScrollbar : '.fancybox-compensate-for-scrollbar',
        },
}); 
    
</script>

You may have noticed an option named "itemTemplate" in the previous section, in there you can specify the HTML of each box/item you can add/edit/remove HTML, here's an example template:

itemTemplate :  ' <div class="media-box-image mb-open-popup" {{link}} data-src="{{popup_src}}" data-title="{{name}}" data-type="{{popup_type}}"> '+
                    ' <div data-thumbnail="{{thumb_src}}" {{ratio}} data-title="{{name}}" data-alt="{{name}}"></div> '+
                    
                    ' <div class="thumbnail-overlay"> '+

                        ' <div class="thumbnail-overlay-animated" data-from="top"> '+
                            ' <div class="media-box-title">{{name}}</div> '+
                        ' </div> '+
                        ' <div class="thumbnail-overlay-animated" data-from="bottom"> '+
                            ' <div class="media-box-date">{{filter}}</div> '+
                        ' </div> '+

                    ' </div> '+
                ' </div>',

Each variable is inside double brakets, for example: {{name}} which 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!

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

Auto Grid by castlecode

Including files

HTML

Initializing

Drag & Drop images into your folder

No categories and neither navigation bar filter

With categories and navigation bar filter

Thumbnails

Config File (.txt)

Options

Template

Handy Stuff