Editing JQuery Initialization on Listings Pages (section)

==Listings JQuery handlers==
*<code>$('#listings-container').listings('bindListingsHandlers')</code>
*<code>$('#listings-container')</code> targets the element containing the listings. <code>#listings-container</code> is the most common element for this, but any appropriate selector can be specified.
*Inline edits: <code>.inline-edit-cell</code> double-click
*Pagination & paging button handlers (<code>.page-btn</code>)
*Update cache: <code>.update-cache-btn</code> click
*Delete records: <code>.trash-btn</code> click
*Makes button icons for the following elements: <code>.details-btn</code>, <code>.preview-btn</code>, <code>.edit-btn</code>, <code>.print-btn</code>, <code>.update-cache-btn</code>, <code>.trash-btn</code>.
*Button element handlers should persist after listings content is refreshed.
*<code>$.listings('bindListingsHandlers')</code> in turn calles <code>$.listings('bindListingsButtons')</code>. The two routines are separated so <code>$.listings('bindListingsHandlers')</code> doesn't need to be called multiple times to avoid attaching duplicate handlers to listings elements.
*This routine does not refresh the handlers or buttons after the listings are refreshed. This can be achieved with
<syntaxhighlight lang="javascript">
$(document).ready(function() {
	$('#listings-container').listings('bindListingsHandlers');
	LITTLED.init({setSortables: function() {
			$('#listings-container').listings('bindListingsButtons');
		}
	});
});
</syntaxhighlight>

===Pagination===
====Content CMS====
* Specify a listings handler script with the "listings uri" setting.
* Default handler is <code>/hostmgr/_ajax/utils/listings.php</code>
** Default handler requires that the content and filters objects for that type of content have been defined within the local <code>cache_class</code>.

====HTML====
<syntaxhighlight lang="php">
<table id="listings-table" data-tid="<?=$filters->site_section->id->value?>" data-p="<?=$filters->calc_rec_position()?>">
</syntaxhighlight>
* The listings container is a table.
* Attributes of <code>table</code> element:
** <code>id</code> default value <code>#listings-table</code>. Used as jQuery selector for paging functionality.
** <code>data-tid</code> content type contained within table. Used to retrieve paging content. 
** <code>data-p</code> Index of the first record on the page. E.g. on the 2nd page with 50 records per page the value would be 51. 

====PHP====
<syntaxhighlight lang="php">
include (COMMON_TEMPLATE_DIR."framework/navigation/listings_page_links.php");
</syntaxhighlight>
* This include is placed outside the <code>table id="listings-table"</code>element and inside the <code>div id="listings-container"</code> element.
* Upldate local <code>cache_class</code> to support the content type. See [[Adding Content Types to the Local Cache Class]]

====JavaScript/jQuery/AJAX====

===Operations buttons===

====Markup====

Sample:
<syntaxhighlight lang="html4strict" enclose="div">
<td class="centered">
	<div class="listops"><!--
		--><button class="edit-btn" data-id="<?=$so->id?>" data-tid="<?=ShippingOption::SECTION_ID?>" data-op="edit" title="edit shipping option">edit shipping option</button><!--
		--><button class="trash-btn" data-id="<?=$so->id?>" data-tid="<?=ShippingOption::SECTION_ID?>" data-op="delete" title="delete shipping option">delete shipping option</button>
	</div>
</td>
</syntaxhighlight>

* Use the <code>button</code> element when the button will trigger a JQuery handler.
* Use the <code>anchor</code> element when the button links to another page.
* Buttons are wrapped in a <code>div</code> container with <code>listops</code> class.
* The <code>class</code> attribute value of the button/anchor determines the icon that is loaded and (optionally) the AJAX handler that is invoked upon clicking the button.
* Required attributes for AJAX handlers:
** <code>data-id</code>
** <code>data-tid</code>

=== Inline edits ===

==== Markup ====
* Element to be edited is placed in a container with class <code>inline-edit-cell</code>.
* Pre-existing templates located in <code>[COMMON_TEMPLATE_DIR]forms/ajax/</code>.
** <code>access_cell.php</code>
** <code>date_cell.php</code>
** <code>name_cell.php</code>
** <code>page_cell.php</code>
** <code>slot_cell.php</code> '''<<< deprecated''' Use <code>$.resort('bindResort')</code> instead. (<<< add link to documentation)
** <code>status_cell.php</code>
<syntaxhighlight lang="php">
<td><? include (COMMON_TEMPLATE_DIR."forms/ajax/name_cell.php"); ?></td>
<? /* or */ ?>
<div><? include (COMMON_TEMPLATE_DIR."forms/ajax/name_cell.php"); ?></div>
</syntaxhighlight>

==== PHP ====
* The content include file expects an object containing the properties of the field.
* Create an object that contains the field properties within the listings loop:
<syntaxhighlight lang="php" highlight="3">
while ($row = mysql_fetch_object($rs))
{
	$name = (object)array("id"=>$row->id, "table"=>"package", "value"=>$row->code);
	/* listings template including inline edit content includes goes here */
}
</syntaxhighlight>

==== JavaScript/jQuery/AJAX ====
* Both <code>$.listings('bindListingsHandlers')</code> and <code>$.galleries('bindAlbumListingsHandlers')</code> bind the dblclick handlers for the cell:
<syntaxhighlight lang="javascript">
$('.inline-edit-cell').on('dblclick', methods.editCell);
</syntaxhighlight>
* <code>$.listings('editCell')</code> contains the logic that loads the editable input into the cell after double-clicking the cell.

==== Customized inline elements ====

* Create include files for the flattened cell and the editing form.
** The class will be `inline-edit-cell`
** Add the following attributes: `data-id`, `data-t`, and `data-op`.
<syntaxhighlight lang="html4strict">
<div class="inline-edit-cell" data-id="<?=$name->id?>" data-t="<?=$name->table?>" data-op="name"><?=$name->value?></div>
</syntaxhighlight>