PMC Gallery V4 Plugin

Note

The root of this plugin has a more modern build process using the latest React versions. The assets directory, however, is an older stack which requires that we, for now, keep things separate.

Configuration:

V4 Gallery Template

Since gallery uses pmc-gallery post type, a theme should preferably have single-pmc-gallery.php template available. However a vertical gallery is append after the post content using the_content on pmc-gallery post type. This is how single-pmc-gallery.php template might look like.

<?php
/**
 * Single pmc gallery template.
 */
 
if ( \PMC\Gallery\View::is_vertical_gallery() ) {
	\PMC::render_template(
		sprintf( '%s/single.php', untrailingslashit( CHILD_THEME_PATH ) ),
		[],
		true
	);
	return;
}
 
get_header();
 
// Render Gallery.
\PMC\Gallery\View::get_instance()->render_gallery();
 
wp_footer();
 
do_action( 'pmc-tags-bottom' ); // @codingStandardsIgnoreLine
do_action( 'pmc-tags-footer' ); // @codingStandardsIgnoreLine
 
get_template_part( 'inc/tags', 'bottom' );
?>
	</body>
</html>
 

Useful V4 Gallery Methods

\PMC\Gallery\View::is_vertical_gallery(): To check if the current gallery is vertical.

\PMC\Gallery\View::is_standard_gallery(): To check if the current gallery is horizontal standard gallery.

\PMC\Gallery\View::get_instance()->render_gallery(): Render gallery ( Vertical / Horizontal )

V4 Gallery Configuration:

Gallery settings can be configured using pmc_gallery_v4_config filter.

ℹ️ Please check out the full default config within the code for latest default values and more explanation. Search code for pmc_gallery_v4_config.

Example:

function filter_gallery_settings( $settings ) {
 
	// Brand Logo.
	$settings['logo'] = array(
		'src'    => get_stylesheet_directory_uri() . '/assets/build/images/_inlined/fn-footer-logo.svg',
		'width'  => 84,
		'height' => 47,
	);
 
	// Theme Style Settings.
	$settings['styles']['theme-color']                   = '#0058AA';
	$settings['styles']['vertical-headline-font-weight'] = 600;
	$settings['styles']['vertical-caption-font-weight']  = 400;
	$settings['styles']['vertical-headline-font-family'] = 'Argent CF,serif';
	$settings['styles']['vertical-caption-font-family']  = 'Georgia,serif';
	$settings['styles']['vertical-max-image-width']      = 'none';
 
	return $settings;
}
 
add_filter( 'pmc_gallery_v4_config', 'filter_gallery_settings' );

V4 List Configuration:

List settings can be configured using pmc_list_v4_config filter.

ℹ️ Please check out the full default config within the code for latest default values and more explanation. Search code for pmc_list_v4_config.

Example:

function filter_list_settings( $settings ) {
 
	// List Nav Bar.
	$settings['listNavBar']['parentElementQuerySelector']                               = '.header-sticky .lrv-a-wrapper';
	$settings['listNavBar']['parentElementStyle']['marginBottom']                       = '0';
	$settings['listNavBar']['containerElementAttributes']['style']['height']            = '36px';
	$settings['listNavBar']['renderElementAttributes']['style']['borderTop']            = 'solid 1px #ffffff';
	$settings['listNavBar']['renderElementAttributes']['style']['backgroundColor']      = 'var(--background-color-brand-accent)';
	$settings['listNavBar']['rangeElementAttributes']['className']                      = 'u-font-size-15 lrv-u-font-weight-bold';
	$settings['listNavBar']['rangeElementAttributes']['style']['color']                 = 'var(--color-grey-light)';
	$settings['listNavBar']['activeRangeElementAttributes']['style']['color']           = 'var(--color-brand-primary)';
	$settings['listNavBar']['progressBarElementAttributes']['style']['backgroundColor'] = 'var(--background-color-brand-primary)';
 
	// Theme Style Settings.
	$settings['styles']['theme-color']                       = 'var(--color-brand-primary)';
	$settings['styles']['vertical-headline-font-weight']     = 700;
	$settings['styles']['vertical-caption-font-weight']      = 400;
	$settings['styles']['vertical-headline-font-family']     = 'var(--font-family-secondary)';
	$settings['styles']['vertical-caption-font-family']      = 'var(--font-family-body)';
	$settings['styles']['horizontal-intro-card-font-family'] = 'var(--font-family-secondary)';
 
	return $settings;
}
 
add_filter( 'pmc_list_v4_config', 'filter_list_settings' );

Options:

logo

Defines the brand logo.

• Type: Array

• Required: Yes

• Keys:

  • src: (string) Image url.
  • width: (int) Width of the image.
  • height: (int) Height of the image.
  • alt: (string) Logo alt text, will use site title if not provided.
  • link: (string) Logo link, will use site home url if not provided.

styles

Sets styles for the gallery.

• Type: Array
• Required: Yes
• Keys:
  • theme-color: (string) Gallery theme color code.
  • header-height(string) ( Not Required ) Header height including top border. This can be be used only if you have a logo that doesn't fit in the header correctly and you need to change the header height.
  • vertical-headline-font-weight: Vertical gallery headline font weight. ( Required )
  • vertical-caption-font-weight: Vertical gallery caption font weight. ( Required )
  • vertical-headline-font-family: Vertical gallery headline font family.( Required )
  • vertical-caption-font-family: Vertical gallery caption font family. ( Required )

socialIcons

Changes the social icons configuration, gallery has defined seven social icons ( facebook, twitter, pinterest, tumblr, whatsapp, reddit, linkedin ) however it can accept any number of social icons with their custom configuration.

• Type: Array
• Required: No
• Keys:
  • facebook: ( array ) Facebok configuration
  • twitter: ( array ) Twitter configuration.
  • pinterest: (array) Pinterest configuration
  • tumblr: (array) Tumblr configuration.
• Custom configuration for above keys ( If needed )
  • icon: (string) Custom icon.
  • shareLink: (string) Social Share link
  • params: (array) Parameters to be added to the social link url.
  • attributes: (array) Attributes to be added to the link.

showThumbnails

Shows or hides thumbnails.

• Type: Boolean
• Required: No
• Default: true

adAfter

Defines after how many slides the sidebar ad will refresh.

• Type: Int
• Reqruired: No
• Default: 1

adsProvider

Defines the ads provider, useful for boomerang.

• Type: String
• Reqruired: No
• Default: 'boomerang'

interstitialAdAfter

Defines after how many slides the interstitial ad slide will appear.

• Type: Int
• Required: No
• Default: 5

zoom

Shows or hides zoom icon.

• Type: Boolean
• Required: No
• Default: true

pinit

Enables or disables pin it feature for each slide ( Not in the header social icons )

• Type: Boolean
• Required: No
• Default: false

sponsored

Shows sponsored text along with gallery title on horizontal gallery.

• Type: String
• Required: No
• Default: ''

subscriptionsLink

If used shows a subscription link at the end of the slide above Next text in horizontal gallery.

• Type: String
• Required: No
• Default: ''

mobileCloseButton

Use close icon image url to the X icon used on desktop in mobile. This is a special icon requested by HL.

• Type: String
• Required: No
• Default: ''

Other Notes

1. Since vertical gallery ads are lazy loaded it requires waypoints script.
2. devicepx script on VIP which would make the zoomed image responsive, so it should be disabled by using add_filter( 'devicepx_enabled', '__return_false' )
3. global_pmc_gallery_urlhashchanged is called after the url hash changes, which can be used for additional advert code from the theme. The function recieves gallery type as its arument.

Ads:

Three ad locations have been used in the gallery

1. right-rail-gallery : Used on the right rail of standard and runway gallery. gallery4-right-rail-ad div id should be used in ad configuration.

2. gallery-interstitial: Interstitial ad used on standard gallery. Disabled by default. gallery4-interstitial-ad div id should be used in ad configuration.

3. in-gallery-x: The ad which shows in-between the gallery slides on vertical gallery. gallery4-in-gallery-x-ad div id should be used in ad configuration.

Boomerang Ad: If adsProvider is set to boomerang (which is the default), gallery would expect boomerang ads for all the above ads. The configuration for boomerang is hardcoded with each ad configuration and can be changed using gallery filter. The are the default configuration.

right-rail-gallery

'boomerang' => array(
	'id'          => 'gallery4-right-rail-ad',
	'displayType' => 'flexrec',
	'targeting'   => array(
		'key'   => 'pos',
		'value' => 'top',
	),
),

gallery-interstitial

'boomerang' => array(
	'id'          => 'gallery4-interstitial-ad',
	'displayType' => 'medrec',
	'targeting'   => array(
		'key'   => 'pos',
		'value' => 'top',
	),
),

in-gallery-x

'boomerang' => array(
	'id'          => 'gallery4-in-gallery-x-ad',
	'displayType' => 'medrec',
	'targeting'   => array(
		'key'   => 'pos',
		'value' => 'top',
	),
),

Filters:

Galleries

pmc_gallery_adjacent_gallery

apply_filters( 'pmc_gallery_adjacent_gallery', null, $post_id, $args );

Short circuit the function `PMC\Gallery\View::get_adjacent_gallery and return your own.

pmc_gallery_attachment_taxonomy_enable

apply_filters( 'pmc_gallery_attachment_taxonomy_enable', false );

pmc_gallery_cheezcap_options

apply_filters( 'pmc_gallery_cheezcap_options', $cheezcap_options );

pmc_gallery_data

apply_filters( 'pmc_gallery_data', $gallery_data, $gallery, $invalidated );

Filters return data of function PMC\Gallery\View::fetch_gallery. Ideal for manipulating gallery data right before it goes to template.

pmc_gallery_link_post_types

apply_filters( 'pmc_gallery_link_post_types', [ 'post' ] );

Posts types to add the meta box for "Add Link to a Gallery"

pmc_gallery_runway_cheezcap_options

apply_filters( 'pmc_gallery_runway_cheezcap_options', $cheezcap_options );

Cheezcap options for Runway galleries

pmc_gallery_standalone_slug

apply_filters( 'pmc_gallery_standalone_slug', 'gallery' );

Default rewrite slug for post type pmc-gallery

pmc_gallery_v4_default_gallery

apply_filters( 'pmc_gallery_v4_default_gallery', ( 'post-new.php' === $pagenow ) ? 'vertical' : 'horizontal' );

Default selected gallery type for the fieldmanager select control.

pmc_gallery_v4_enable_runway_gallery_options

apply_filters( 'pmc_gallery_v4_enable_runway_gallery_options', false );

Enable Runway Gallery options.

pmc_gallery_v4_gallery_display

apply_filters( 'pmc_gallery_v4_gallery_display', false );

Use this filter to force the gallery display type. To do so, provide callback which returns 'horizontal', 'vertical', or 'runway'.

pmc_gallery_v4_has_custom_rewrite_rule

apply_filters( 'pmc_gallery_v4_has_custom_rewrite_rule', false );

Set this to true if handling rewrite rules for galleries will be handled theme-side.

pmc_gallery_v4_is_featured_article

apply_filters( 'pmc_gallery_v4_is_featured_article', ( ! empty( $featured_article_term ) ) );

Override for PMC\Gallery\View::is_featured_article(). Currently only used internally, in unit tests.

pmc_gallery_v4_query_attachments_generate_count

apply_filters( 'pmc_gallery_v4_query_attachments_generate_count', true, $query );

Filter the ability to generate the count of how many times a given image is used in a gallery.

pmc_gallery_v4_show_on_landing_pages

apply_filters( 'pmc_gallery_v4_show_on_landing_pages', true );

Controls the default state of the "Exclude from landing page" post option.

⚠️ The name of this filter is logically backwards. When true (default), "Exclude from landing page" is CHECKED by default on new galleries. Setting to false UNCHECKS this post option by default, thus post will NOT be "excluded from landing page".

This is not an override for existing galleries. This only controls the default value upon gallery creation, which can still be manually checked or unchecked.

Lists

pmc_gallery_list_items_per_page

apply_filters( 'pmc_gallery_list_items_per_page', 100 );

Default maximum number of list items per page.

pmc_gallery_lists_standalone_slug

apply_filters( 'pmc_gallery_lists_standalone_slug', 'lists' );

Default rewrite slug for post type pmc_list

pmc_gallery_v4_lists_has_custom_rewrite_rule

apply_filters( 'pmc_gallery_v4_lists_has_custom_rewrite_rule', false );

Set this to true if handling rewrite rules for lists will be handled theme-side.

pmc_list_data

apply_filters( 'pmc_list_data', $list_response, self::$id );

Filters return data of function PMC\Gallery\Lists::fetch_list. Ideal for manipulating list data right before it goes to template. This filter runs after pmc_list_item_data.

pmc_list_item_data

apply_filters( 'pmc_list_item_data', $data_to_fill, $item );

Identical to pmc_list_data except limited to only the list array itself. This filter runs before pmc_list_data.

pmc_gallery_v4_lists_list_item_image_caption

apply_filters( 'pmc_gallery_v4_lists_list_item_image_caption', $image_caption, $list_item );

Filters image captions for list items

Enabling Runway Gallery for a theme.

1. Port all metaboxes from WWD related to Runway Gallery.
2. Pass runway gallery menu as an array in runwayMenu key using the same pmc_gallery_v4_config filter from the theme.
3. See \PMC\Gallery\View::get_current_gallery_type() to check how a term is used to determine runway gallery which is the way its checked on WWD.