Editing Refactoring a CMS to Use Shared LITTLED Libraries

==Configuration==

===Update content settings in site sections CMS===

*AJAX scripts
**Listings: <code>/_hostmgr/_ajax/utils/listings.php</code> or <code>/_hostmgr/[CONTENT]/_ajax/listings.php</code>
**Delete: <code>/_hostmgr/_ajax/utils/delete_record.php</code>
**Update cache: <code>/_hostmgr/_ajax/utils/update_cache.php</code>
**Resort: <code>/_hostmgr/_ajax/utils/resort.php</code>
*ID parameter
*Sortable flag
*Cache Content flag

===Rename existing directories in VCS===

*<code>common</code> > <code>_config</code>
*<code>common/*.js</code> > <code>_scripts/*.js</code>
*<code>inline</code> > <code>_ajax</code>
*<code>forms</code> > <code>_templates/forms</code>
*<code>content</code> > <code>_templates/content</code>

===Refactor PHP content class===

*Refactor include directives
*(Optional) add Netbeans-friendly class documentation
*Wrap code within functions in <code>try { /*...*/ } catch (Exception $ex) { /*...*/ }</code>
*Use <code>db_content_class</code> as base class for all classes that represent records in the database.

===Refactor PHP content filtering class===

*Refactor include directives
*(Optional) add Netbeans-friendly class documentation
*Refer to a class that’s been refactored for logic updates within the class’s routines.
*Use <code>filter_collection_class</code> as base class for any class that represents records in the database.
*Add <code>$site_section</code> property to any class that handles listings and pagination.<br/>TODO: Consider making this a property of <code>filter_collection_class</code>.
*Add <code>$section_operations</code> property to any class that handles listings and pagination.<br/>TODO: Consider making this a property of <code>filter_collection_class</code>.

===Add content handlers to PHP cache and resort classes===

*Add include directives for PHP content and content filtering classes to cache_class
*Add case for the content type in class routines as necessary
**<code><strike>cache_class::update_content()</strike></code>
**<code>cache_class::set_initial_properties()</code>
**<code>cache_class::update_keywords()</code>
**<code>cache_class::set_filters()</code>
**<code>cache_class::set_content()</code>
**<code>cache_class::load_json_content()</code>
**<code>cache_class::refresh_content_after_edit()</code>
**<code>cache_class::refresh_content_after_image_edit()</code>
**<code><strike>resort_class::retrieve_section_properties()</strike></code>

===Refactor config files===

*<code>_config/core_includes.php</code>
**fix paths to include files.
*Refactor <code>_config/scripts.php</code>
**add definition for <code>SECTION_BASE_URI</code>
**<code>*_SCRIPT</code> > <code>*_URI</code>
**<code>ADMIN_HTTP_ROOT_URI."section_name/"</code> > <code>SECTION_BASE_URI."</code>

===Local AJAX scripts===

*Refactor include directives
*(Optional) refactor to use <code>ajax_page_class</code>
*Add any necessary scripts
**<code>listings.php</code>

===Local JavaScript libraries===

* Minify existing libraries
** Created “source” version of existing libraries: <code>lib.js</code> > <code>lib-source.js</code>
** Compress existing libraries: http://javascriptcompressor.com/
* Wrap content-specific code in jQuery plugin code:
<syntaxhighlight lang="javascript">
(function($) {

	var methods = {
		<methodName>: function() {
			return this.each(function() {
				/* custom code goes here... */
			});
		}
	};

	$.fn.<pluginName> = function( method ) {
	
		/* method calling logic */
		if (methods[method]) {
			return methods[method].apply(this, Array.prototype.slice.call(arguments, 1));
		}
		else if ( typeof method === 'object' || !method ) {
			return methods.init.apply(this, arguments);
		}
		else {
			$.error('Method ' + method + ' does not exist on jQuery.<pluginName>.');
		}

	};

})(jQuery);
</syntaxhighlight>
* Use <code>$.cms()</code> JQuery binding routines as much as possible
* See also: [[Binding JQuery Handlers]]

==Listings pages==

===Page setup & initialization===

*(Optional) Update comments to use Netbeans editor folds: <code>//<editor-fold></code>
*Refactor include directives
*Refactor local CMS page URI definitions (<code>*_SCRIPT</code> > <code>*_URI</code>)
*Add <code>$breadcrumbs</code>, <code>$sTitle</code> as global variables in the page’s <code>initialize()</code> function.
*When calling <code>$filters->format_query_string()</code>, make sure not to append any values for <code>P_FILTER</code>.
*Remove calls to <code>urlencode()</code> when formatting URLs for header links.
*Use shared AJAX script for any “update cache” links.
*Configure breadcrumbs.

===Page framework===

* Refactor header and footer includes to use the path <code>ADMIN_TEMPLATE_DIR."framework/"</code>.
* Use appropriate PHP include rollup for CSS/JavaScript resources for the page, e.g.
<syntaxhighlight lang="php">
include (ADMIN_TEMPLATE_DIR."framework/css/listings_css_and_scripts.php");
</syntaxhighlight>

* Use JQuery initialization

<syntaxhighlight lang="javascript">
$(document).ready(function() {
    $('#listings-container').cms('bindListingsHandlers');
});
</syntaxhighlight>

:* See [[Binding JQuery Handlers]]
:* See [[JQuery Initialization on Listings Pages]]
:* See [[Sorting Listings|Configuration notes for sorting]].

* Make sure to include a container for error messages on the page:

<syntaxhighlight lang="html4strict">
<div id="error-container" class="error" style="display:none;"></div>
</syntaxhighlight>

*Wrap listings in a container that will allow JQuery script to locate them:
<syntaxhighlight lang="html4strict">
<div id="listings-container" class="listings">
    <? include (SECTION_BASE_DIR."_templates/content/[CONTENT-TYPE]_listings.php"); ?>
</div>
</syntaxhighlight>
*Remove any includes for popup containers.

===Filters form===

*Update any lib routines to use the analogous routine from a utility class. E.g. <code>db_utils_class::display_cached_options()</code>
*Form container has id <code>“listings-filters”</code> and class <code>“listings-filters ui-corner-all”</code>. Make sure to include JQuery UI stylesheet and that the local stylesheet contains the relevant definitions.

<syntaxhighlight lang="html4strict">
<div id="listings-filters" class="listings-filters ui-corner-all">
</syntaxhighlight>

*Form element has method “get”, id “filters_form”, and class “filters”.

<syntaxhighlight lang="php">
<form action="<?=SECTION_CMS_URI ?>" method="get" id="filters_form">
</syntaxhighlight>

*Store “next” filter value in form.

<syntaxhighlight lang="php">
<input type="hidden" name="<?=$filters->next->param ?>" value="<?=$filters->next->value ?>" />
</syntaxhighlight>

*Table element within form does not have any attributes.

<syntaxhighlight lang="html4strict">
<table>
</syntaxhighlight>

* Use <code><nowiki><label></nowiki></code> tags around all form inputs.
*Any textbox inputs that collect date values should be assigned the <code>“datepicker”</code> class.
<syntaxhighlight lang="php">
<td><label>name <input type="text" name="<?=$filters->name->param ?>" value="<?=$filters->name->value ?>" maxlength="50" /></label></td>
</syntaxhighlight>
*Submit button markup:

<syntaxhighlight lang="php">
<input type="submit" class="filter-btn ui-corner-all" name="<?=P_FILTER ?>" value="filter" />
</syntaxhighlight>

===Listings content include file===

*(Optional) Add include directive for the section’s scripts config file for the benefit of the cache_class routines. Test if one of the script definitions is defined. If not, include the scripts config file.

<syntaxhighlight lang="php">
if (!defined("[CONTENT-TYPE]_DETAILS_URI"))
{
    require_once (realpath(dirname(__FILE__).'/../../')."/_config/scripts.php");
}
</syntaxhighlight>

*Add try/catch for retrieving listings.
*Remove include directives for any stand-alone routines that render pagination links.
*Use shared include file to render pagination links.

<syntaxhighlight lang="php">
include (COMMON_TEMPLATE_DIR."framework/navigation/listings_page_links.php");
</syntaxhighlight>

*[[Sorting Listings#html|Add attributes to table elements to support pagination and sorting]].
*Remove “slot” column from listings.
*Use <code>list</code> and <code>list-alt</code> CSS classes for alternating rows to support onHover behaviors.
*Use shared templates for inline edit elements:

<syntaxhighlight lang="php">
<? include (COMMON_TEMPLATE_DIR."forms/ajax/status_cell.php"); ?>
</syntaxhighlight>

* See [[Keywords#Displaying keyword lists within listings pages|Displaying keyword lists within listings pages]]
* See [[JQuery_Listings_Operations_Buttons|JQuery listings operations buttons]]

==Edit Pages==

===Page setup & initialization===

*The points under the [[#Page_Setup_.26_Initialization|listings pages setup & initialization]] apply here also.
*Refactor stand-alone routines such as <code>parse_numeric_input()</code> to use analogous routines in shared utility classes, e.g <code>validation_class::parse_numeric_input()</code>.
*Set exception handler for the page that will load the page framework with the caught error displayed at the top:

<syntaxhighlight lang="php">
set_exception_handler("exception_handler");
</syntaxhighlight>

and

<syntaxhighlight lang="php">
function exception_handler($ex)
{
    global $nav_menu, $breadcrumbs, $sTitle, $sParam, $input, $filters;
    $input->error_string = $ex->getMessage();
    include (SECTION_BASE_DIR."_templates/edit_[CONTENT-TYPE]_page.php");
}
</syntaxhighlight>

===Page framework===

*Points under [[#Page_framework|listings pages framework]] that don’t refer to the listings apply here also.
*Page framework is located in

<syntaxhighlight lang="php">
include (SECTION_BASE_DIR."_templates/edit_[CONTENT-TYPE]_page.php");
</syntaxhighlight>

====Gallery listings====
*If editing an existing record, load gallery listings with
<syntaxhighlight lang="javascript">
$(document).ready(function() {
<? if ($input->id->value>0): ?>
	$('#pages-<?=$input->id->value?>').galleries('retrieveGallery', function() {
		$('#pages-<?=$input->id->value?>').galleries('bindImageOverlayHandlers');
	});
<? endif; ?>
});
</syntaxhighlight>
* <code>$.galleries('retrieveGallery')</code> in turn calls <code>$.galleries('bindGalleryHandlers')</code>. All AJAX button handlers should be fully active after the gallery listings are rendered.
* The gallery images still need to be retrieved in PHP when the parent record is read even though they are displayed with this AJAX call. TODO: fix this so that the gallery properties are retrieved even when the gallery images are not retrieved.
<syntaxhighlight lang="php">
$input->read(true); /* <<< true = retrieve gallery images */
</syntaxhighlight>

*[[Sorting Listings|Sorting gallery listings]]

====TinyMCE WYSIWYG editors====
*JavaScript includes
<syntaxhighlight lang="javascript">
<script type="text/javascript" src="/scripts/tiny_mce/tiny_mce.js"></script>
<script type="text/javascript" src="/scripts/tinymce_config.js"></script>
</syntaxhighlight>
*The first one, the TinyMCE library, is in the common directories. The second one is local, and allows local configuration of the WYSIWYG editors.
*Assign a textbox <code>class="mce-editor"</code> to have a TinyMCE WYSIWYG editor attached to it.
<syntaxhighlight lang="php" highlight="7">
class content_type extends db_content_class
{
    function __construct()
    {
        parent::__construct();
        $this->description = new string_textarea_class("Description", self::DESCR_PARAM, false, "", 2000);
        $this->description->class = "mce-editor";
    }
}
</syntaxhighlight>
====Edit form====
* Form data to preserve in hidden inputs:
<syntaxhighlight lang="php">
		<input type="hidden" name="<?=P_REFERER?>" value="<?=((isset($_REQUEST[P_REFERER]))?($_REQUEST[P_REFERER]):(""))?>" />
		<input type="hidden" name="MAX_FILE_SIZE" value="10240000" />
		<input type="hidden" name="<?=P_ID?>" value="<?=$input->id->value?>" />
		<input type="hidden" name="<?=$input->id->param?>" value="<?=$input->id->value?>" />
		<input type="hidden" name="<?=$input->slot->param ?>" value="<?=$input->slot->value ?>" />
<? $filters->preserve_in_form(); ?>
</syntaxhighlight>

* [[Album_Image_Uploads#Album-based_content_using_a_gallery_image_as_a_thumbnail|Thumbnail upload controls]]

* Default form submission buttons and controls (including "next operation" radio options). Work off the contents of that include file for custom controls.
<syntaxhighlight lang="php">
<? include (COMMON_TEMPLATE_DIR."forms/submit_container.php"); ?>
</syntaxhighlight>

===Main page logic===

*Remove checks on <code>if($input->error())</code>. Let the exception handler catch and handle these errors.
*Put status messages in session variables:
<syntaxhighlight lang="php">
$_SESSION[P_MESSAGE] = $sStatus;
</syntaxhighlight>

*For image and thumbnail uploads, and album-based content types displaying galleries:
**[[Albums CMS Configuration]]
**[[Album Image Uploads]]
* See also [[Neighbor Links Navigation]]

==Details Pages==
Sample inline edit funcationality setup:
<syntaxhighlight lang="javascript" enclose="div">
$(document).ready(function(){

	/* with album-based content, this loads the gallery of images on the page */
	$('#pages-<?=$input->id->value?>').galleries('retrieveGallery', function() {
		
		/* callback code executed after the gallery is fully loaded into the DOM */
		$('#pages-<?=$input->id->value?>')

		/* with a gallery of full-sized images this would load edit & delete buttons after clicking the images */
		.galleries('bindImageOverlayHandlers')

		/* with a listings-style of presentation this would enable inline editing of keywords within the gallery */
		.keywords('bindListingsHandlers');
	});

	/* adds edit and delete buttons to thumbnail image */
	/* this works for both album-based thumbnails and stand-alone images linked to the parent record */
	$('.image-upload-container').galleries('bindImageOverlayHandlers');

	/* enables inline editing of keywords */
	$('.metadata').keywords('bindListingsHandlers');

	/* optional key navigation through records */
	$(document).listings('bindKeyPageNavigation', {
		leftKeyURL: '<? if ($filters->prev_id > 0): print([CONTENT_SLUG]_DETAILS_URI."{$sParam}&id={$filters->prev_id}"); else: print([CONTENT_SLUG]_URI.$sParam); endif; ?>',
		rightKeyURL: '<? if ($filters->next_id > 0): print([CONTENT_SLUG]_DETAILS_URI."{$sParam}&id={$filters->next_id}"); else: print([CONTENT_SLUG]_URI.$sParam); endif; ?>',
		upKeyURL: '<?=[CONTENT_SLUG]_URI.$sParam ?>'
	});
}
</syntaxhighlight>

* For image and thumbnail uploads, and album-based content types displaying galleries:
** [[Albums CMS Configuration]]
** [[Album Image Uploads]]
* See also [[Neighbor Links Navigation]]

[[Category:CMS Documentation]]