Editing Albums CMS Design Principles

[[Category:Project Documentation]] [[Category:Albums CMS]] [[Category:Littled Libraries]] [[Category:jQuery/AJAX]] [[Category:Web Development]]
== AJAX ==

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

<syntaxhighlight lang="php">
/_classes/content/cache_class.php
/_classes/content/resort_class.php
</syntaxhighlight>

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

== PHP Classes ==

Classes derived from <code>album_class</code> and <code>album_xpost_class</code> that don’t have the same columns as those tables should set the <code>db_field property</code> value for those fields to FALSE in their class constructors.
<syntaxhighlight lang="php" highlight="4">
function __construct() {
	parent::__construct();
	/* any child class property initialization would go here */
	$this->layout->db_field = false;
}
</syntaxhighlight>

== JavaScript/JQuery ==

=== Album listings ===

<syntaxhighlight lang="javascript">
$('.album-listings').galleries('bindAlbumListingsHandlers');
</syntaxhighlight>

`$.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.
* <strike>Persistent highlighting of line items within listings after being clicked</strike>

=== 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.

<syntaxhighlight lang="javascript">
<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>
</syntaxhighlight>

=== 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

<syntaxhighlight lang="javascript">
$([LISTINGS_SELECTOR]).trigger('contentRefresh');
</syntaxhighlight>

=== 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. 

<syntaxhighlight lang="javascript">
$(document).ready(function() {
	$('.alt-album-container').galleries('bindAlbumListingsHandlers', {dom: {gallery_container: '.alt-album-container'}});
});
</syntaxhighlight>

==== 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. 

<syntaxhighlight lang="javascript">
$(document).ready(function() {
	$('.alt-pages-container').galleries('bindGalleryHandlers', {dom: {gallery_container: '.alt-pages-container'}});
});
</syntaxhighlight>

==== Sorting ====

* If the parent element is a `<nowiki><table></nowiki>` the sortable elements are specified with `tr.page-row`. 
* If the parent element is a `<nowiki><div></nowiki>` 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"`.

<syntaxhighlight lang="php" highlight="7-12">
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;
    }
}
</syntaxhighlight>

== Toggling galleries within album listings ==

* `.gallery-listings` element
** `data-pid` album id
** `data-tid` content identifier for the gallery, as defined by the [[Littled_Content_Properties_CMS|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 ==

* [[Gallery Listings|Album/Gallery Listings]]
* [http://littledamien.com/docs/?p=636|littledamien.com: albums cms specs & principles] (Littledamien docs)