Pile gallery developers image

Logical, well commented code with plenty of hooks for your integration needs

We’re theme and plugin developers ourselves and we know how important it is to be able to work well with the resources you use. Pile Gallery was not only built to support other developers but we welcome any comments and advise you may have on how to make it better!

Getting Started

Pile Gallery allows users to display grouped galleries (based on taxonomies or custom selections) in post content. This is achieve by creating a custom post type named pile_gallery which in turn is used to populate a shortcode. The contents of each Pile Gallery is set up in the posts for this post type. The ID of the post is added to the pile_gallery shortcode which displays the gallery. Shortcode parameters can be used to fine-tune the display of the gallery.

Theme Integration

There are three ways to integrate Pile Gallery into the theme. The choice is yours, it mostly depends on the architecture of your theme. We suggest taking a look at the policies of the marketplace you are selling on (if any). Some might not allows plugin functionality in a theme which would force you to choose the TGM activation method for example.

Method 1: Bundle As A Separate Plugin

One of the easiest way to add Pile Gallery to your theme or plugin is to simply bundle the package as an installable WordPress plguin. This is not integration per-se, you are asking your customers/clients to install Pile Gallery as a regular plugin.

Method 2: Use TGM Plugin Activation

The TGM Plugin Activation Class is one of the best ways to put your plugin into a theme (or other plugin) if marketplace policies or other considerations do not allow you to simply include the functionality. It allows your users to install and even automatically activate plugins in singular or bulk fashion using native WordPress classes, functions and interfaces. You can reference pre-packaged plugins, plugins from the WordPress Plugin Repository or even plugins hosted elsewhere on the internet.

The first thing you'll need to do is place the Pile Gallery installable zip file somewhere inside your theme structure. We recommend creating a plugins folder and adding it there. You'll also need to add the TGM Activation Class and include it from within your functions.php file, or main plugin file. Once done, use the functions.php or main plugin file to define the required/recommended plugins.

add_action( 'tgmpa_register', 'my_included_plugins' );
function my_included_plugins() {
 
    $plugins = array(
 
        array(
            'name'               => 'Pile Gallery',
            'slug'               => 'pile-gallery',
            'source'             => get_stylesheet_directory() . '/plugins/pile-gallery.zip',
            'required'           => true,
            'version'            => '1.0',
            'force_activation'   => false,
            'force_deactivation' => false,
        ),
  
    );
 
    $config = array(
        'default_path' => '',                     
        'menu'         => 'tgmpa-install-plugins',
        'has_notices'  => true,                   
        'dismissable'  => true,                   
        'dismiss_msg'  => '',                     
        'is_automatic' => false,                  
        'message'      => '',                     
        'strings'      => array(
            'page_title'                      => __( 'Install Required Plugins', 'tgmpa' ),
            'menu_title'                      => __( 'Install Plugins', 'tgmpa' ),
            'installing'                      => __( 'Installing Plugin: %s', 'tgmpa' ),
            'oops'                            => __( 'Something went wrong with the plugin API.', 'tgmpa' ),
            'notice_can_install_required'     => _n_noop( 'This theme requires the following plugin: %1$s.', 'This theme requires the following plugins: %1$s.' ),
            'notice_can_install_recommended'  => _n_noop( 'This theme recommends the following plugin: %1$s.', 'This theme recommends the following plugins: %1$s.' ),
            'notice_cannot_install'           => _n_noop( 'Sorry, but you do not have the correct permissions to install the %s plugin. Contact the administrator of this site for help on getting the plugin installed.', 'Sorry, but you do not have the correct permissions to install the %s plugins. Contact the administrator of this site for help on getting the plugins installed.' ),
            'notice_can_activate_required'    => _n_noop( 'The following required plugin is currently inactive: %1$s.', 'The following required plugins are currently inactive: %1$s.' ),
            'notice_can_activate_recommended' => _n_noop( 'The following recommended plugin is currently inactive: %1$s.', 'The following recommended plugins are currently inactive: %1$s.' ),
            'notice_cannot_activate'          => _n_noop( 'Sorry, but you do not have the correct permissions to activate the %s plugin. Contact the administrator of this site for help on getting the plugin activated.', 'Sorry, but you do not have the correct permissions to activate the %s plugins. Contact the administrator of this site for help on getting the plugins activated.' ),
            'notice_ask_to_update'            => _n_noop( 'The following plugin needs to be updated to its latest version to ensure maximum compatibility with this theme: %1$s.', 'The following plugins need to be updated to their latest version to ensure maximum compatibility with this theme: %1$s.' ),
            'notice_cannot_update'            => _n_noop( 'Sorry, but you do not have the correct permissions to update the %s plugin. Contact the administrator of this site for help on getting the plugin updated.', 'Sorry, but you do not have the correct permissions to update the %s plugins. Contact the administrator of this site for help on getting the plugins updated.' ),
            'install_link'                    => _n_noop( 'Begin installing plugin', 'Begin installing plugins' ),
            'activate_link'                   => _n_noop( 'Begin activating plugin', 'Begin activating plugins' ),
            'return'                          => __( 'Return to Required Plugins Installer', 'tgmpa' ),
            'plugin_activated'                => __( 'Plugin activated successfully.', 'tgmpa' ),
            'complete'                        => __( 'All plugins installed and activated successfully. %s', 'tgmpa' ),
            'nag_type'                        => 'updated'
        )
    );
 
    tgmpa( $plugins, $config );
 
}

For more information about how this all works, check out the previously mentioned website, or view the source on Github.

Method 3: Include Functionality

Since the plugin was built using an object oriented approach it is very easy to just plop it into your theme/plugin files and treat it as a simple include. After unzipping the installable plugin zip, place the pile-gallery folder into your project and simply include the main file, Pile Gallery will take care of the rest.

include( 'pile-gallery/pile-gallery.php' )

A Note About Licences

Please note that you must have a licence in order to use the premium version in these ways. You must either have a personal licence for each domain or sub-domain you use it in, or you must have a developer licence which lets you use it in as many projects as you like.

Hook Reference

We've included a number of hooks in the plugin for your developing pleasure. If you require something different please do let us know, our goal is to make Pile Gallery easy to work with.

pile_gallery/before_shortcode

This action runs just before the gallery is shown. It can be used to inject some HTML before the gallery. It takes two parameters. The first parameter, $atts contains the attributes passed to the shortcode. The second parameter, $pile is an array which defines the piles and their contents.

pile_gallery/after_shortcode

This action runs just after the gallery is shown. It can be used to inject some HTML after the gallery. It takes two parameters. The first parameter, $atts contains the attributes passed to the shortcode. The second parameter, $pile is an array which defines the piles and their contents.

pile_gallery/pile_content

This filter runs on all piles, regardless of their type (post, media or custom). It takes one parameter, the $pile array which contains the piles and their contents.

pile_gallery/pile_content_[type]

This filter runs on piles of the given type. The type may be post, gallery or custom. This filter always runs after the general pile_gallery/pile_content filter. It takes one parameter, the $pile array which contains the piles and their contents.

pile_gallery/post_query_args

This filter allows you to modify the arguments passed to the WP_Query object while retrieving the posts for Pile Galleries which are based on posts. Beware, removing the tax_query will remove the retrieval by category. This hook receives two parameters. The first is $args which is the original array, the second is $id, the ID of the pile gallery post.

pile_gallery/gallery_query_args

This filter allows you to modify the arguments passed to the WP_Query object while retrieving the posts for Pile Galleries which are based on media items. Beware, removing the tax_query will remove the retrieval by category. This hook receives two parameters. The first is $args which is the original array, the second is $id, the ID of the pile gallery post.