Sorting Listings

Overview

A jQuery plugin that enables drag-n-drop resorting of listings displayed in the browser.

Future development

Currently the library works with the Littledamien and Damien Jay sites. It works with different content types, but is hard-coded to expect certain behaviors from the AJAX script that commits the changes.

The goal is to make a new version of the resort.js plugin that will be more generic and customizable.

The goal on the AJAX handler side is to create a reusable Symfony bundle.

Content Properties CMS

CMS > Content Properties

• Is Sortable: checked
• Sorting URI: /hostmgr/_ajax/utils/resort.php (default shared AJAX handler script)

JavaScript

Sorting logic is defined in littled/resort.js which is wrapped up in littled.js.

Example:

$(document).ready(function() {
	/* options can be passed as first argument to resort() */
	$('.listings table:first').resort();
});

Settings

• uris
  • resort: URL of the AJAX script that will commit the resorted listings. (default: /_ajax/utils/resort.php)
• dom
  • listings_container: The listings container selector. (default: '.listings')
  • sortable_selector: Selector used to define sortable elements. (default: tr.rec_row)
• keys
  • record_id: Name of the key storing the id of the record(s) being repositioned. (default: 'id')
  • position_offset: Name of the key that stores the position of the first record currently being displayed relative to the first record in the entire set of matching listings. (default: 'po')

Markup

When loading modal dialogs and refreshing listings content, the library looks to the data-po attribute of .listings table:first by default.

Default markup

|
+-- <div class="listings">
     |
     +-- <table data-po="n">
          |
          +-- <tr>
          |    |
          |    +-- <th>
          |    |
          |    (...)
          |
          +-- <tr class="rec-row">
          |
          (...)

Example of alternate markup

|
+-- <ul class="list-group" data-po="n" data-type="Foo">
|    |
|    +-- <li class="list-group-item" data-id="n">
|    |    |
|    |    +-- <div>
|    |    |
|    |    (...)
|    |
|    (...)
|
(...)

PHP

Input (proposed)

• po Position offset of the first record in the listings from the first record in the entire unfiltered collection.
• id Array of record ids resorted to the desired arrangement.
• type Name of the entity represented in the listings.
• filters Associative array of filters to apply, for example if resorting only those items in a certain group.

Output

• Output as JSON by default.
• status Simple string containing a plain English result to be displayed in the browser as confirmation of the operation.
• error String containing error message if any errors were encountered.

Littledamien configuration

/_classes/site_content/cache_class.php

Add include directives for both the parent page’s content and content filter classes:

require_once (APP_CLASS_DIR."site_content/press_class.php");
require_once (APP_CLASS_DIR."site_filters/press_filters_class.php");

Update the set_filters() routine to include the filter class representing the page’s content type.

/_classes/site_content/cache_class.php

Potentially no changes need to be made to this class on a content-type-by-content-type basis as long as the default action for all content types is

if ($this->filters instanceof filters_collection_class) {
    $this->filters->parse_filters();
    $this->filters->page_len->value = null; /* get all available records */
}

If some other action needs to be taken for a specific content type then a new case would need to be created in the retrieve_section_properties() routine.

Paging is handled with

include (COMMON_TEMPLATE_DIR."framework/navigation/listings_page_links.php");

MySQL

Tables with sortable records must contain

• An id column containing a unique id for the record.
• A slot column holding the value of the record’s position in the listings relative to all other records.