Editing Variable-Length Line Item Edits

== Overview ==

Documentation of the `lineitems.js` library and how to use it on CMS pages to edit lists of records that are linked to parent records.

== Markup ==

=== Cross-site request forgery ===

* A CSRF token is created and saved as a session variable.
* The value of this variable is saved in a hidden element on the page: `#csrf-token` where it will then be available in jQuery.

=== Line item listings ===

* Outer container has `.line-items-container` class. 
** This element does not get modified by jQuery.
** The class is used as a selector in jQuery to target the parent of the individual line items.
* Each individual line item element has `.line-item` class. 
** The class name is used as a selector in jQuery to assign edit handlers to the individual line items.
** When iterating through the line item objects in PHP, they should be rendered using a separate PHP include file. This way, that line item include file can be shared between the front-end PHP template and the AJAX script that updates page content.
** The `.line-item` element must have the following attributes defined:
*** `data-id`: Record id of the line item in the database.
*** `data-type`: PHP class name of the object that can fetch and save the line item data to and from the database. 
* New item button:<syntaxhighlight lang="html4strict" enclose="div">
<button class="add-line-btn" data-pid="[PARENT_RECORD_ID]" data-type="[CONTENT_PHP_CLASS_NAME]" title="add new [OBJECT NAME]">add new [OBJECT_NAME]</button>
</syntaxhighlight>

=== Edit form ===

* The edit form markup will include the `.line-item` element. 
* The flattened display of the line item will be replaced in its entirety with the edit form markup.
* The edit form will be replaced in its entirety with the updated flattened display of the line item once editing has been completed.
* The edit form will include the following variables as hidden form elements:
** `class`: Name of PHP class that handles line item edits.
** `id`: Line item record id, if editing an existing line item record.
** `pid`: The record id of the parent record that the line item is linked to, if editing a new line item record.*

== CSS ==

Boilerplate CSS can be found in the shared Compass files: `[COMMON_BASE_DIR]stylesheets/shared/cms/_forms.scss`

There is nothing critical here to the operation of the line item edits. 

The line item elements can be table rows or divs. 

If they are divs, consider creating CSS rules for `.line-item` that will render divs contained within it horizontally, and arrange them so that they line up vertically, e.g:

<syntaxhighlight lang="css">
.line_item div {
	display: table-cell;
	vertical-align: top;
	margin-right: 8px;
}
</syntaxhighlight>

== JavaScript ==

=== Libraries ===

* `[COMMON_LIB]littled/lineitemsjs`

=== Binding handlers and buttons ===

Default binding handlers and buttons:

<syntaxhighlight lang="javascript" highlight="2">
$(document).ready(function() {
	$('.line-items-container').lineitems('init');
});
</syntaxhighlight>

The defaults can be overridden by passing in custom configuration in the 2nd argument:
<syntaxhighlight lang="javascript" highlight="3-13">
$(document).ready(function() {
	$('.line-items-container').lineitems('init', {
		edit: {
			selector: '.custom-selector',
			event: 'click',
			uri: '/path/to/custom/edit_ajax.php'
		},
		del: {
			uri: '/path/to/custom/del_ajax.php'
			callback: function(evt, options) {
				console.log('Custom handler called.');
			}
		}
	});
});
</syntaxhighlight>

=== Default selectors ===

* `.line-item`: Row element with the following attributes holding values that are passed to the AJAX scripts:
** `data-id`: Record id of the line item in the database.
** `data-type`: Name of the PHP class that will be instantiated to fetch and save edits to the line item in the AJAX script.
* `.add-line-btn`: Button with click handler to add new line items to the list.
* `.line-item`: Row element with double-click handler to edit existing line items.
* `.save-line-btn`: Button added to the DOM while editing or deleting a line item that commits the changes.
* `.cancel-line-btn`: Button added to the DOM while editing or deleting a line item that cancels the edit.
* `#csrf-token`: Hidden element holding a CSRF token value that is then passed to the AJAX script to prevent cross-site forgery.
=== Default ajax handlers ===

* Adding & editing: `[COMMON_LIB]_ajax/utils/edit_line_item.php`
* Deleting: `[COMMON_LIB]_ajax/utils/del_line_item.php`

== PHP ==

=== Classes ===

* `[COMMON_LIB]content/ajax_page_class.php`
* Custom class to fetch and save the line item data from and to the database.

=== AJAX utility scripts ===

* `[COMMON_LIB]_ajax/utils/edit_line_item.php`
* `[COMMON_LIB]_ajax/utils/del_line_item.php`

=== Content include files ===

==== Shared templates ====

* Add '''save''' and '''cancel''' buttons to a line item edit form.
** `[COMMON_LIB]_templates/forms/ajax/line_item_submit_buttons.php`
* Templates to support Content Template line-items edits within the Content Properties CMS pages.
** `[COMMON_LIB]_templates/content/content_template_line_item.php`
** `[COMMON_LIB]_templates/forms/content_template_delete_confirmation.php`
** `[COMMON_LIB]_templates/forms/content_template_edit_form.php`

==== Case-by-case templates ====

* '''Line item module''' containing all the individual line item elements. 
** This element is not modified by jQuery at any point.
* '''Individual line items''' Template containing the flattened (non-interactive) presentation of an existing line item.<br />This is used by both the front-end display template and the AJAX script to display and update the line item listings.
* '''Line item edit form'''
** Included in the template is a `.line-item` element containing the form and form elements. 
** Within the `lineitems.js` library handler, the existing `.line-item` element will be replaced with the new `.line-item` element containing the editing form markup.
* '''Delete confirmation form'''
** Same as the editing form, this template must contain a `.line-item` element that in turn contains the delete confirmation form elements.

== Workflow ==

=== MySQL ===

==== `content_template` definition ====

<syntaxhighlight lang="sql" enclose="div">
CREATE TABLE \`content_template\` (
  \`id\` int(11) NOT NULL auto_increment,
  \`site_section_id\` int(11) NOT NULL,
  \`name\` varchar(45) NOT NULL,
  \`path\` varchar(255) NOT NULL,
  \`location\` enum('local','shared','shared-cms') default NULL,
  PRIMARY KEY  (\`id\`),
  UNIQUE KEY \`idx_content_template_site_section_id_name\` (\`site_section_id\`,\`name\`),
  CONSTRAINT \`fk_site_section_content_template\` FOREIGN KEY (\`site_section_id\`) REFERENCES \`site_section\` (\`id\`) ON DELETE CASCADE ON UPDATE NO ACTION
);
</syntaxhighlight>

==== Content Template properties ====

* `site_section_id`: id of the child `site_section` record.
* `name`: must be specific to its function, e.g. "details", "delete", or "edit".
* `path`: relative to the site section's base directory as defined in the `site_section` table, and should not have a leading slash.
* `location`: either "local" or "shared" depending on if the template exists in the common directory for all sites.

=== Content Properties CMS ===

==== Configuration ====

A "CMS Content Sections" `site_section` record is required for the content templates.

<syntaxhighlight lang="sql" enclose="div">
insert into \`site_section\` (\`id\`,\`name\`,\`slug\`,\`table\`,\`root_dir\`) values (27,'CMS Content Sections','cms-content-sections','site_section','');

insert into \`section_operations\` (\`label\`,\`section_id\`,\`id_param\`,\`delete_uri\`,\`comments\`) values 
('content',27,ssid','/sections/_ajax/del.php','cms content operations');
</syntaxhighlight>

A "Content Template" `site_section` record is required to manage line-item edits. This is a child of the "CMS Content Sections" record.

<syntaxhighlight lang="sql" enclose="div">
insert into \`site_section\` (\`id\`,\`name\`,\`slug\`,\`root_dir\`,\`table\`,\`parent_id\`,\`root_dir\`) values
(33,'Content Template',null,'/sections/','content_template',27,'');

insert into \`section_operations\` (\`label\`,\`section_id\`,\`id_param\`) values 
('content template',33,'');
</syntaxhighlight>

Add content templates records to control line-item edits within the content properties CMS. Once these are added, the Content Properties CMS can be used to define new content template types.

<syntaxhighlight lang="sql" enclose="div">
INSERT INTO \`content_template\` (\`site_section_id\`, \`name\`, \`path\`, \`location\`) VALUES
(33, 'details', 'content/content_template_line_item.php', 'shared-cms'),
(33, 'edit', 'forms/content_template_edit_form.php', 'shared-cms'),
(33, 'delete', 'forms/content_template_delete_confirmation.php', 'shared-cms');
</syntaxhighlight>

Those 3 shared templates exist in the shared development project under `[SHARED_ROOT_DIR]_templates\content\` and `[SHARED_ROOT_DIR]_templates\forms\`

==== Registering new content templates ====

Use the '''Content Properties CMS''' to define templates for additional content templates.

* Create a `site_section` record for the parent content type if it doesn't already exist.
* Create a separate `site_section` record representing the line-item as a child of the parent content type.
** Set the "parent", "root directory", and "table name" properties. 
** Make sure to store the id of the new `site_section` record in the `SECTION_ID` property of the PHP class.
* Add records for any templates used to display or edit the line items to the `content_template` table in the database. 
** When editing a `site_section` record, add & edit content templates in the '''Content Templates''' module. 
** Click the '''plus sign''' button to define a new template.
** Double-click existing templates to edit them.
** Typically 3 templates are defined: "edit", "view", and "delete".
** The '''path''' is always relative to a `_templates` directory. Usually it will start with either `content\` or `forms\` and '''location''' setting will control determining the remainder of the path when including the templates.

=== PHP ===

Create a PHP class to represent the line item records. 

<syntaxhighlight lang="php">
require_once (COMMON_CLASS_DIR."db/db_content_class.php");

class ContentTemplate extends db_content_class
{
	public $id;
	public $name;
	public $site_section_id;
	public $base_dir;
	public $path;
	public $location;
	public $parent_id;

	const SECTION_ID = 33;

	function __construct( $id=null, $parent_id=null, $name='', $base_dir='', $path='', $location='')
	{
		$this->id = new integer_input_class("Template id", "templateID", true, $id);
		$this->site_section_id = new integer_input_class("templateParentid", "contentTypeID", true, $parent_id);
		$this->name = new string_text_input_class("Name", "templateName", true, $name, 45);
		$this->path = new string_text_input_class("Path", "templatePath", true, $path, 255);
		$this->location = new string_select_input_class("Location", "templateLocation", false, $location, 20);

		$this->parent_id = &$this->site_section_id;
	}

	/* [...] */
}
</syntaxhighlight>

* The class must have `parent_id` property. 
** If the class has property that links it to the parent record but isn't named "parent_id" (as in the example above with the `site_section_id`), then add a `$parent_id` property and point it to the existing property in the class's constructor:<br />`$this->parent_id = &$this->site_section_id;`
* Add an include for the class in the project's local `cache_class.php`.

=== Markup ===

Create PHP include files containing markup to display & edit the line items.

==== Line item group container ====

One `div` (or `section`) to act as a container for the line items.
* This `div` should be outside the include file for the individual line items, either in its own include file, or placed directly in the details and editing include file.
* CSS class is `line-items-container`.
* Include a `button` for adding new line items (class `add-line-btn`).
** CSS class is `add-line-btn`.
** `data-pid` attribute contains the parent record's id.
** `data-type` attribute contains the name of the PHP class that will be used to save edits to the line.

==== Individual flattened line items ====

The line item is placed in a container `div`.
* CSS class `line-item` to enable double-clicks to edit the item. (That's the default CSS class. It can be overridden within the $.lineitem library's settings.)
* `data-type` with the name of the PHP class.
* `data-id` with the record id of the line item.
* (optional) `title` attribute to give some indication that the element is clickable.

==== Line item edit form ====

* `div` container with `line-item` CSS class.
* `form` element
* Hidden input with `name="<?=P_COMMIT ?>"` and `value="1"`
* Hidden input with `name="class"` with the PHP class's name as its value.
* Hidden inputs storing record id and parent id values.
* Form inputs for each of the object's properties.
* Submit buttons include: `[COMMON_TEMPLATE_DIR]forms/ajax/edit_line_item_submit_buttons.php`

==== Line item deletion confirmation form ====

* `div` container with `line-item` and `delete-confirmation` CSS classes.
* `form` element
* Hidden input with `name="<?=P_COMMIT ?>"` and `value="1"`
* Hidden input with `name="class"` with the PHP class's name as its value.
* Plain text description of the line item, optionally inside of an element with `infoblock` as its CSS class.
* Submit buttons include: `[COMMON_TEMPLATE_DIR]forms/ajax/delete_line_item_submit_buttons.php`

=== JavaScript ===

Logic for line-item edits exists in `littled.js`.

The main content type's details and editing pages will include jQuery binding of the line item handlers.

<syntaxhighlight lang="javascript" highlight="3">
(function($) {
	$(function() {
		$('.line-items-container').lineitems('init');
	});
});
</syntaxhighlight>

Any necessary overrides of the line item editing configuration can be set using the 2nd argument to the 'init' routine: 

<syntaxhighlight lang="javascript" highlight="2-6">
$('.line-items-container').lineitems('init', {
	errorContainer: '.error-container',
	edit: {
		event: 'click',
		selector: '.edit-line-btn',
		uri: '/path/to/custom/editing_script.php'
	}
});
</syntaxhighlight>

== Examples ==

* [http://damienjay.dbarchowsky.com/books/ damienjay.com Books CMS] Samples links
* [http://littled.dbarchowsky.com/contacts/ littledamien.com Contacts CMS] Contact status and contact history
* [http://luzern.dbarchowsky.com/hostmgr/advice/edit.php Luzern Labs Advice CMS ] (deprecated)

[[Category:CMS Documentation]]
[[Category:JavaScript]]
[[Category:PHP]]
[[Category:JQuery/AJAX]]
[[Category:Littled Libraries]]
[[Category:Web Development]]