Custom WordPress themes and plugins

2BC Image Gallery Documentation

Welcome to the 2BC Image Gallery documentation page. The 2BC Image Gallery settings documentation as well as shortcode and filters are explained here. 2BC Image Gallery is a WordPress plugin. This plugin will add a new category feature to the Media section of WordPress. This will allow for the tagging of photos and grouping them into Galleries.

Once photos have been tagged, there are several ways to display the galleries. We have built a responsive, AJAX driven front-end. But in the spirit of writing good code, we have included many options to try and make this plugin very flexible. Please find the documentation on these options below.

For an example please check the 2BC Image Gallery Demo page.

Overview

How To Install

Automatic

  1. Log in to the WordPress administration panel with an administrator account
  2. Click Plugins > Add New
  3. Search for 2BC Image Gallery
  4. Find the plugin in the list of results and click the Install Now button
  5. Click OK to confirm the plugin installation. If there are any file permission issues, WordPress may ask for a valid FTP account to continue. Either enter the FTP credentials, or proceed to the Manual installation instructions.
  6. Click the Activate Plugin link after the installation is complete

Manual

  1. Download a copy of the plugin and save it to the local computer. Make sure that the folder has been unzipped.
  2. Using an FTP program (such as FileZilla), connect to the server that is hosting the website
  3. Find the root folder for the site and browse to the following directories: wp-content > plugins
  4. Upload the un-compressed2BC Image Gallery plugin folder in to the plugins folder on the server
  5. Log in to the WordPress administrator panel and click Plugins > Installed Plugins
  6. Find the 2BC Image Gallery plugin in the list and click the Activate link

Back to top

Settings Screen

The settings screen is available by logging into the WordPress admin section and clicking Settings > 2BC Image Gallery.

  1. Gallery Page – Select a page to display the image galleries. The 2BC Image Gallery shortcode can also be used to display galleries.
  2. Page Content – If the gallery is being displayed via the page selector, this option will control if the gallery is shown before, after, or is to replace the page contents, or the template tag inside of the contents – %%2bc_image_gallery%%.
  3. Sort Method – This will control how galleries are sorted: by upload date, alphabetically by file name, or random.
  4. Sort Order – Which direction to sort the galleries, ascending, or descending. Select descending and date to display the latest galleries by date, or ascending and file name to display alphabetically from a to z. This does not apply to the random setting.
  5. Paginate Galleries – This will break up galleries into pages instead of trying to load all the images on one page. This is highly recommended when displaying galleries with a large amount of pictures to reduce load time.
  6. Images Per Page – If galleries are paginated, this will control how many images are displayed on each page
  7. Gallery Thumb Source – If the gallery does not a have a custom thumb set, this will decide how to generate the thumbnails: the Last image added to the gallery, the First image added, or Random
  8. Background Color: Image Thumbs – This option will allow for customization of the image thumbs background color.
  9. Hide Default Styling – Enable this option to get rid of the default gallery styling. This will allow for easy custom styling via the theme’s CSS.
  10. Disable AJAX – Enable this option to disable the AJAX javascript from loading. This will mean that the page will refresh to display new images, instead of smoothly loading inside of the same page. This also means that there cannot be more than one gallery per page.

image_gallery_settings_v2_2

  1. Display Image Title – Controls whether the image title is displayed when viewing the single image in the modal window
  2. Slideshow Delay – Controls how long it takes to load the next image when the Play button is clicked
  3. Background Color: Modal Window – This option will allow for customization of the modal window background color.

Calendar Based Galleries

image_gallery_settings_v2_3

  1. Add Calendar Based Galleries – This option will automatically add calendar-based galleries to new uploaded images such as January, and 2014, based on when the image was uploaded.
  2. Separate Calendar Galleries – This option will separate any calendar-based galleries into their own unique section. The year and month sections are displayed above the custom galleries
  3. Show Month Galleries – If calendar-based galleries are being separated, this will show all of the month-based galleries, below the year-based galleries.

Back to top

How To Display Galleries

The 2BC Image Gallery can be displayed by either selecting a page in the settings screen, by using the shortcode in the page contents, or by calling the PHP function in a page template. All three methods are described below.

Display via page selector

Set the 2BC Image Gallery options as desired, and select an existing page for the Gallery Page setting. Once saved, any existing galleries should be displayed on the selected page. Use the Page Content option to control if the galleries are displayed before or after the page content, or if the galleries should replace all existing content on the page. There is also an option to use a template tag – %%2bc_image_gallery%%. This will result in something similar to the 2BC Image Gallery Demo page, where it has page contents above and below the gallery. This option will look for the template tag inside of the page and replace it, while leaving the rest of the contents in place.

Display via shortcode

[2bc_image_gallery]

There are many more options available via the shortcode. Any arguments not set while calling the shortcode are set to options on the settings page. Enter any of the following arguments to change how the galleries are displayed:

  • display_gallery – Enter a gallery ID to display that galleries images
  • page_num – If the galleries are paginated, this will control which page is displayed
  • parents – Filter galleries by a comma separated list of other galleries. For instance, display pictures from custom galleries that are also in the 2014 gallery.
  • galleries – Enter a comma separated list of galleries to display
  • sort_method – Sort galleries by file upload date – date, or file name – title
  • sort_orderdesc for descending, or asc for ascending
  • paginate_galleries – Enter 1 to turn the pagination feature on
  • images_per_page – If galleries are paginated, control how many images are displayed per page
  • default_gallery_thumb – Select how non-custom gallery thumbnails are generated: last image added to the gallery, first image added, or random
  • display_title – Turn the display of the image title on or off when viewing a single image
  • slideshow_delay – Control the amount of delay between images when the play button is clicked
  • separate_galleries – Enter 1 to separate calendar-based galleries into their own section
  • show_months – If calendar-based galleries are being displayed separately, enter 1 to show month-based galleries as well
  • noajax – Enter 1 to stop the AJAX javascript from loading, which will cause the page to refresh instead of smoothly re-loading inside of the same page.
  • back_button – For certain use cases where the Back To Gallery button must lead to a custom page, or be disabled completely. Set to 0 to disable the button completely, or set to a custom URL to control where the button directs to.

Here is an example with all of the arguments:

[2bc_image_gallery display_gallery="1" page_num="2" parents="1,2" galleries="2,3" sort_method="title" sort_order="asc" paginate_galleries="1" images_per_page="60" default_gallery_thumb="last" display_title="1" slideshow_delay="5000" separate_galleries="1" show_months="1" noajax="1" back_button="0"]

Display via function call

The function call is very similar to the shortcode call, with a few additional steps. The arguments must be contained in an array, and the function must be echoed.

The function call must be made within a <?php tag, such as within a page template. Here is an example:

$twobc_image_gallery_args = array(
	'galleries' => '1,2',
	'paginate_galleries' => '1',
	'images_per_page' => '60',
);
echo twobc_image_gallery_get_display($twobc_image_gallery_args);

Back to top

The thumbnail for the gallery will automatically be set to a gallery image based on the plugin settings. However this can be customized.

When adding or editing a gallery, find the Gallery Featured Image ID field. Click the Choose or Upload an Image button and select an image from the WordPress Media Library.
Screenshot of the 2BC Image Gallery featured image option
Back to top

Filters

2BC Image Gallery does not currently have any actions. There are many filtered elements to allow for customization. All strings have been passed through the WordPress gettext filter using the 2bc-image-gallery text domain, meaning they can be translated, or changed entirely by hooking to the gettext filter.

  • twobc_image_gallery_tax_labels – Applied to the taxonomy labels. The hooked function should return an array of taxonomy labels:
    array(
    	'name' => 'Galleries',
    	'singular_name' => 'Gallery',
    	'menu_name' => 'Galleries',
    	'search_items' => 'Search Galleries',
    	'all_items' => 'All Galleries',
    	'edit_item' => 'Edit Gallery',
    	'view_item' => 'View Gallery',
    	'update_item' => 'Update Gallery',
    	'add_new_item' => 'Add New Gallery',
    	'new_item_name' => 'New Gallery Name',
    	'popular_items' => 'Popular Galleries', // non-hierarchical only
    	'separate_items_with_commas' => 'Separate galleries with commas', // non-hierarchical only
    	'add_or_remove_items' => 'Add or remove galleries', // JS disabled, non-hierarchical only
    	'choose_from_most_used' => 'Choose from the most used galleries',
    	'not_found' =>'No galleries found',
    )
  • twobc_image_gallery_tax_args – Applied to the register_taxonomy options. The hooked function should return an array of taxonomy options:
    array(
    	'hierarchical' => false,
    	'labels' => $tax_galleries_labels,
    	'public' => true,
    	'show_ui' => true,
    	'show_admin_column' => true,
    	'update_count_callback' => '_update_generic_term_count',
    	'query_var' => true,
    	'rewrite' => false,
    	'sort' => false,
    )
  • twobc_image_gallery_year_title – Applied to the year section title of the gallery display. The hooked function should return an HTML ready string:
    'Galleries by year'
  • twobc_image_gallery_month_title – Applied to the month section title of the gallery display. The hooked function should return an HTML ready string:
    'Galleries by month'
  • twobc_image_gallery_calendar_months – Applied to the array of month names used to tag photos. The hooked function should return an array of months, 1-12:
    array(
    	'January',
    	'February',
    	'March',
    	'April',
    	'May',
    	'June',
    	'July',
    	'August',
    	'September',
    	'October',
    	'November',
    	'December',
    )
  • twobc_image_gallery_custom_title – Applied to the custom section title of the gallery display. The hooked function should return an HTML ready string:
    'Custom Galleries'
  • twobc_image_gallery_output_list – Applied to the entire output of the image_gallery_get_display() function. This will contain the HTML markup for when the galleries are being displayed. This should allow for functions to make edits via PHP DOM, before the galleries are displayed on the page.
  • twobc_image_gallery_output_thumb – Applied to the output for the category thumb.
  • image_gallery_output_ajax – Applied to output of the AJAX response to build the gallery view
  • twobc_image_gallery_title – Applied to the title of the image gallery when the contents are being displayed
  • twobc_image_gallery_button_back – Applied to the Back to galleries button. The hooked function should return an HTML ready string:
    '&laquo; Back to galleries'
  • twobc_image_gallery_previous_page_button – Applied to the previous page button. The hooked function should return an HTML ready string:
    '&laquo;'
  • twobc_image_gallery_next_page_button – Applied to the next page button. The hooked function should return an HTML ready string:
    '&raquo;'
  • twobc_image_gallery_output_modal – Applied to the AJAX modal output. This will contain the HTML markup for when an image is being displayed in the lightbox. This should allow for functions to make edits via PHP DOM, before the image is displayed.
  • twobc_image_gallery_add_month – Applied to the month-based tag that is being added to the image during upload. The hooked function should return a slug-ready string:
    'January'
  • twobc_image_gallery_add_year – Applied to the year-based tag that is being added to the image during upload. The hooked function should return a slug-ready string:
    '2014'

Back to top