For developers

Overview

Photo Gallery RB is built to be extended without touching its files. Galleries are posts of the type pgrb_gallery; their items and settings are in post meta (_pgrb_items, _pgrb_settings), image tags in the taxonomy pgrb_tag on attachments. Every item reaches the renderer in the same shape, whether it is a photo, a video or a feed post.

For styling, see Style → For theme developers.

A new content source

A source is a class that extends PGRB_Source: it declares the API keys it needs (shown on Connections), the fields of one feed (shown in the gallery editor), and turns a feed into items. Register it on pgrb_register_sources:

add_action( 'pgrb_register_sources', function () {
	class My_Portfolio_Source extends PGRB_Source {
		public $id    = 'my-portfolio';
		public $label = 'My Portfolio';
		public $color = '#0a7cff';

		// Site-wide keys, kept on Photo Gallery → Connections.
		public function credentials() {
			return array(
				'api_key' => array( 'label' => 'API key', 'type' => 'password', 'required' => true ),
			);
		}

		// The fields of one feed, in the gallery editor.
		// "How many", "Check for new posts" and "Tag for filters" are added to every source.
		public function fields() {
			return array(
				'album' => array( 'type' => 'text', 'label' => 'Album', 'default' => '' ),
			);
		}

		public function fetch( $config, $creds ) {
			$data = $this->get_json(
				'https://api.example.com/albums/' . rawurlencode( $config['album'] ),
				array( 'Authorization' => 'Bearer ' . $creds['api_key'] )
			);
			if ( is_wp_error( $data ) ) {
				return $data;
			}
			$items = array();
			foreach ( array_slice( $data['photos'], 0, $config['limit'] ) as $p ) {
				$items[] = $this->item( array(
					'uid'     => $p['id'],
					'src'     => $p['url'],
					'w'       => $p['width'],
					'h'       => $p['height'],
					'thumb'   => $p['thumb'],
					'title'   => $p['title'],
					'link'    => $p['page'],
					'date'    => $p['created'],
				) );
			}
			return $items;
		}
	}
	PGRB_Sources::register( new My_Portfolio_Source() );
} );

item() takes uid, type (image or video), src, w, h, thumb, tw, th, title, caption, description, link, date, video and provider (for videos), credit and credit_link. Results are cached for the feed’s “Check for new posts” time, and the last good result is kept as a backup when the service fails — fetch() only has to talk to the API. get_json() handles timeouts and error messages of the API.

Filters

Filter	Arguments	Use
`pgrb_items`	`$items, $settings, $context`	change, add or remove the items of a gallery; `$context` is `edit` (editor) or `view` (site)
`pgrb_settings_schema`	`$schema`	add a setting; it is sanitized, saved and shown in the editor like the built-in ones
`pgrb_editor_tabs`	`$tabs`	add a tab to the editor’s settings
`pgrb_render_gate`	`$html, $gallery_id, $settings`	return HTML to show instead of the gallery, e.g. a login form
`pgrb_can_view_gallery`	`$can, $gallery_id`	who may load the gallery’s further pages over REST
`pgrb_gallery_before`, `pgrb_gallery_after`	`$html, $gallery_id, $settings`	HTML above and below the gallery, inside its Shadow DOM
`pgrb_item_extra`	`$html, $item, $settings`	HTML added to each item, e.g. a button
`pgrb_gallery_data`	`$data, $gallery_id, $settings`	the data the gallery’s JavaScript gets
`pgrb_lightbox_item`	`$data, $item`	the data the lightbox gets for one item
`pgrb_gallery_css`	`$css, $settings`	the CSS inside the gallery’s Shadow DOM
`pgrb_load_google_fonts`	`$load, $family`	`false` — never load fonts from Google

Actions

Action	When
`pgrb_register_sources`	register content sources
`pgrb_enqueue`	a gallery is on the page: enqueue your own scripts (`$settings` passed)
`pgrb_editor_assets`	the gallery editor loads: enqueue editor add-ons

JavaScript events

Event	On	Detail
`pgrb-ready`	the `<photo-gallery-rb>` element	the gallery is set up
`pgrb-act`	the `<photo-gallery-rb>` element	`{ act, key, button }` — a click on an element with `data-act` inside the gallery, e.g. a button added with `pgrb_item_extra`; `key` is the item’s key
`pgrb-lightbox-open`	`document`	`{ lightbox, host }` — the lightbox opened

document.addEventListener( 'pgrb-lightbox-open', function ( e ) {
	console.log( 'Lightbox opened for gallery', e.detail.host.id );
} );

All events bubble out of the Shadow DOM (composed: true).

Removing the data

Deleting the plugin removes its options, but keeps the galleries and tags — deleting a plugin should not delete someone’s work. To remove them too, add this to wp-config.php before deleting the plugin:

define( 'PGRB_DELETE_DATA', true );

Documentation