Variable-Length Line Item Edits

Overview

Documentation of the lineitemEdit.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:

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

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

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:

.line_item div {
	display: table-cell;
	vertical-align: top;
	margin-right: 8px;
}

JavaScript

Libraries

• [COMMON_LIB]littled/lineitemModule.js

Binding handlers and buttons

Default binding handlers and buttons:

$(document).ready(function() {
	$('.line-items-container').lineitemModule('init');
});

The defaults can be overridden by passing in custom configuration in the 2nd argument:

$(document).ready(function() {
	$('.line-items-container').lineitemModule('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.');
			}
		}
	});
});

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.

Utility scripts

• [COMMON_LIB]_ajax/utils/edit_line_item.php
• [COMMON_LIB]_ajax/utils/del_line_item.php

Content include files

Shared templates

• [COMMON_LIB]_templates/forms/ajax/line_item_submit_buttons.php
  Adds save and cancel buttons to a line item edit form.

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

Examples

• littledamien.com ontacts CMS Contact status and contact history
• Luzern Labs Advice CMS (deprecated)