Albums CMS Design Principles

AJAX

When adding a new album-based CMS section, the following files may need to be updated with the new content type:

/_classes/content/cache_class.php
/_classes/content/resort_class.php

Obviously if a file includes the cache_class then the new content type will be available to that file.

PHP Classes

Classes derived from album_class and album_xpost_class that don’t have the same columns as those tables should set the db_field property value for those fields to FALSE in their class constructors.

function __construct() {
	parent::__construct();
	/* any child class property initialization would go here */
	$this->layout->db_field = false;
}

JavaScript/JQuery

Album listings

$('.album-listings').galleries('bindAlbumListingsHandlers');

$.galleries('bindAlbumListingsHandlers') binds

• Content refresh events
• Page navigation
• Toggling galleries
  • Hides gallery containers to prime them to be expanded by the album's "toggle gallery" button.
• Image details lightbox dialogs
• Image preview tooltips
• Inline editing of images
• Initialize "operations" buttons for each album record (details, edit, toggle gallery, update cache, delete, etc.)
• Inline edits of things like titles, status, dates, etc.
• Persistent highlighting of line items within listings after being clicked

Album details

Typical handlers on album details pages:

• Load the gallery content.
• Bind overlay handlers for the album's thumbnail image.
• Bind handler to allow inline editing of album keywords.
• Bind "delete record" handler to links/buttons in the page header.
• Bind "update cache" handler to links/buttons in the page header.

<script type="text/javascript">
$(document).ready(function() {

	/* Load gallery content & bind handlers for the gallery listings content. */
	$('.gallery-listings').galleries('retrieveGallery');	

	/* Album thumbnail handlers. */
	$('.image-upload-container').galleries('bindImageOverlayHandlers');

	/* Enable inline keyword editing. */
	$('.metadata').keywords('bindListingsHandlers');

	/* "delete record" link in the page header 
	   The default action is to refresh with listings content, 
	   which isn't appropriate on a details page. */
	$('.hdr-delete-link').formDialog({
		dialogClass: 'delete-confirmation',
		callbacks: {update_content: function(data) {
				data.settings = options;
				methods.updatePageContentAfterDelete(data)
		}}
	});

	/* "update cache" link in the page header */
	$('.update-cache-btn').on('click', $.littled.updateCache);
});
</script>

Gallery listings

Retrieving listings content

$.galleries('retrieveGallery')

• Calls AJAX script to retrieve gallery content.
  • Relies on data-tid property of the DOM container for section id.
  • Relies on site_section.listings_uri in the database for the url of the AJAX script that delivers the listings content.
• Loads gallery listings content into the DOM container.
• Binds gallery listings handlers to the content.

Binding gallery listings handlers

$.galleries('bindGalleryHandlers') binds

• Image details lightbox
• Image preview rollovers
• Line-item edit operation buttons (details,edit,delete)
• Page navigation within the gallery
• Gallery filters interactivity
• Inline data edits
• Inline keyword edits
• Record sorting
• Calendar popups

This method is invoked automatically in $.galleries('retrieveGallery').

Refreshing listings content

Listings content refreshes for either Album listings or Gallery listings is achieved with

$([LISTINGS_SELECTOR]).trigger('contentRefresh');

Listings selectors

Albums

The default container for albums is .album-listings.

The default container can be overridden with the dom.album_container setting of the $.galleries library.

$(document).ready(function() {
	$('.alt-album-container').galleries('bindAlbumListingsHandlers', {dom: {gallery_container: '.alt-album-container'}});
});

Galleries

The default container for galleries is .gallery-listings.

The default container can be overridden with the dom.gallery_container setting of the $.galleries library.

$(document).ready(function() {
	$('.alt-pages-container').galleries('bindGalleryHandlers', {dom: {gallery_container: '.alt-pages-container'}});
});

Sorting

• If the parent element is a `<table> the sortable elements are specified with tr.page-row.
• If the parent element is a <div> the sortable elements are marked with .page-cell`.

Refreshing listings content

See also Littled Library Pagination

Albums

Album content is refreshed after

• Following a link to a new page in the listings
• Deleting a record

Galleries

Gallery content is refreshed after

• The parent page's content is fully loaded
• Following a link to a new page in the listings
• Applying new filter values
• Deleting a page from the gallery

Gallery listings container properties

• listings and gallery-listings classes
  • .gallery-listings is the default selector used to target the gallery listings in the DOM after an AJAX content edit has been performed.
• data-tid attribute holding the gallery's content id.
• data-p attributes holding the position of the first record on the current page of listings relative to the entire set of matching listings.

AJAX scripts pass back markup in the content property of a JSON collection.

The $.galleries jQuery library dumps the markup using its dom.album_container and dom.gallery_container properties.

Filter values applied to the listings content are passed to AJAX scripts using the dom.filters_form and dom.gallery_filters properties of the $.galleries library.

The content that is passed back to the page from the AJAX script is determined in the PHP cache_class.

• cache_class::refresh_content_after_edit()
• cache_class::refresh_content_after_image_edit()
  • Typically this will load content from a template determined by the type of object being used to make the edit.
  • The default gallery listings template is CMS_COMMON_TEMPLATE_DIR."content/albums/gallery_listings.php".

public static function refresh_content_after_edit( &$content, &$filters, &$json ) {
	global $sParam;
	switch(1) {
		case ($content instanceof image_link_class):
			cache_class::refresh_content_after_image_edit($content, $filters, $json);
			break;
		case ($content instanceof Book):
			ob_start();
			include (CMS_BASE_DIR."books/_templates/content/book_listings.php");
			$json->content->value = ob_get_contents();
			ob_end_clean();
			break;			
		default:
			ob_start();
			include (CMS_COMMON_TEMPLATE_DIR."content/albums/album_listings.php");
			$json->content->value = ob_get_contents();
			ob_end_clean();
			break;
    }
}

Toggling galleries within album listings

• .gallery-listings element
  • data-pid album id
  • data-tid content identifier for the gallery, as defined by the Content Properties CMS
• PHP template
  • (CMS_COMMON_TEMPLATE_DIR)_content/albums/gallery_listings_container.php
  • album id: $album->id->value
  • content type id: $filters->gallery->site_section->id->value

See Also

• Album/Gallery Listings
• albums cms specs & principles (Littledamien docs)