Documentation

Getting started

Animated Pagination

Add a Front End List Magic block above a page list block. On the permission tab, set 'nobody'. On the pagination tab, set a page length and a transition animation. Drop, Left/Right, Swing at about 800ms is usually a good transition to start with. Leave everything else at its default value.

In the actual page list block, set it to show all pages in the list with no pagination.

Save the page and enjoy the animation as you 'paginate' up and down through the page list!

You can do the same for any list, including various Page List templates, List Files From Set, and lists of thumbnails such as the basic and Sortable Fancybox Galleries.

Front End Selection and Sorting

The magic of Front End List Magic does not stop at pagination. You can also use it to modify the content and sorting of a list.

On the permission tab of the edit dialog, select who has access (typically the 'page owner' - yourself). On the frontend options tab, leave the default options set. These should include 'enable sorting' and 'enable hide/reveal'.

Save the block and the page. You will now see a 'Front End List Magic' prompt with a checkbox on the page. Check this and you can now sort the list content by drag/drop and check/uncheck items to show to others on the page. Uncheck the prompt and the list will appear as you have modified it.

Only you see these controls. Others just see the selected and sorted list.

There are many more advanced options and capabilities to make things slicker, adapt the magic to other types of list, to position the pagination and even detailed diagnostics to help you get to grips with particularly awkward lists.

VERY IMPORTANT: Front End List Magic needs to work with the complete list !!

Front End List Magic does its magic by using jQuery to find and catalogue the items within a list. To do this, it needs to see the complete list when the page loads, not just part of it. It will not work propely with:

  • Any list that is already paginated
  • Any set of search results (unless the results are effectively static)
  • Any list that is built using AJAX.

Many list blocks that already provide pagination have an option to disable pagination, thus making them compatible with Front End List Magic. Before adding a Front End List Magic block, have a look the edit dialog for the list block and check that you have disabled pagination.

Remeber - Disable Pagination in any list block before applying Front End List Magic to that block.

Lists need their own containers

Front End List Magic identifies a list by finding its container. For example:

  • ‘li’ elements within a ‘ul’ or ‘ol’ container
  • Any elements within a ‘div’ container
  • Heading elements followed by text elements within an overall ‘div’ container

Some list making blocks do not automatically put the list elements within a container (for example, the some templates for the Page List block). To enable Front End List Magic to do its stuff, you can get Concrete5 to helpfully place a ‘div’ container about the list by adding Design (Set Block Styles) to such list blocks. 

A useful trick is to use the CSS tab of Set Block Styles to insert a css rule ‘display:none;’. As well as forcing Concrete5 to place a ‘div’ element about the list, this will also hide the list content when the page is loaded until Front End List Magic has sorted and selected from the list, so preventing a flash of the un-processed list while a page is loading. The Front End List Magic option “Make hidden list show” is enabled by default.

List items need an attribute that provides a unique key

Front End List Magic identifies each item in a list by looking for attributes that provide a unique and immutable key. For example:

  • In a page list each item has a link to the actual page, so Front End List Magic can key on the ‘href’ html attribute of each link.
  • In an image list each item contains an image, so Front End List Magic can key on the ‘src’ html attribute of each image.
  • In a file list each item contains a link to the actual file, so Front End List Magic can key on the ‘href’ html attribute of each link.
  • In the thumbnail list for an image gallery each item contains a thumbnail image and a link to the full size image, so Front End List Magic can key on the ‘href’ html attribute of each link or the ‘src’ html attribute of each thumbnail.

Custom list templates

If you are building a custom template for an awkward list and none of the above apply, you can easily make it compatible with Front End List Magic by attaching a unique ‘id’ to each element.

However, do not base such a unique id on the Concrete5 block id or location of the block within the page. Both of these can change leading to Front End List Magic becoming disconnected from the list it is working with.

If you only have one list using the custom template on a page, a simple id=my-list-1 … id=my-list-99 approach provides a unique and immutable key that is perfect for Front End List Magic to work with.

Advanced List Selection Options

For the vast majority of uses, the default options of Front End List Magic is all you will need. However, there are list formats and contents that push the capabilities of Front End List Magic, so you may need to use the Advanced Options of the Selection of List tab.

In the Advanced Options, you can select which attributes Front End List Magic will search for and the priority of searching. For example, maybe you want image ‘src’ to take priority over link ‘href’. Or maybe you want the list items to be identified by ‘alt’ attributes of image tags, by the ‘title’ attribute of any tag, by a ‘data’ attribute, or by your own custom attribute. 

If a list item contains multiple items with similar attributes and that confuses Front End List Magic, you can specify a ‘Key selector’, so that Front End List Magic will only use items that match the ‘Key selector’ when looking for attributes to key on. 

For example, “h2.ccm-page-list-title>a” could be used to ensure Front End List Magic only keys on the primary page link of a highly designed page list, and not on any other links that may appear in the teaser text or icon images used to beautify the list.

Finally, to select the container of the list, rather than specifying an offset from the Front End List Magic block, you could specify a jQuery selector for the container.

When the underlying list changes

Suppose you have a gallery thumbnail list built from a file set, or a page list for yor site. Maybe you are asking “What happens when I add a new image to the gallery, or add a new page to my site?”

Front End List Magic provides three options to configure what happens. New list items can be shown at the top of the list, before existing items, or at the bottom of the list, after all existing items. You can also decide whether new list items should be shown or hidden.

Front End List Magic in Stacks and Global Areas

If you add Front End List Magic to a global area or stack, by default Front End List Magic assumes you want to manage lists that are shown differently on each individual page the global area or stack is used on.

However, maybe you have a list block in a global area that you want to manage as a single item across all pages the global area is used on. Checking “Global behaviour” means that Front End List Magic will associate a single set of sort/show/hide magic across wherever the associated global list block is shown.

Pagination

Front End List Magic provides extensive options for pagination of a list with animated transtions and optional widow/orphan control. 

Just select the pagination and transition options and Front End List Magic will paginate the associated list for you.

Transtions available include slide, fade, curtain, explode and many others. Combined with transtion speed, a full range of easing options and transition directions, there are way too many variations to list.

Problems and Diagnostics

If Front End List Magic is not doing any magic with your list, the first thing to check is the Selection of List tab to make sure the offset specified in the Location of list selector is appropriate.

This offset is controlled by DOM elements. DOM elements do not map 1:1 with Concrete5 blocks. Now may be the time to have a quick look at the browser developer console to count the offset of Front End List Magic from the list you want it to manage.

Note that Front End List Magic ignores all script, link and style elements.

Offsets can also change depending on which user is logged in (for example, blocks that are only rendered for particular users or groups). The safest place to put Front End List Magic is immediately above or below the list block it is working with.

In addition to looking at document structure in the developer console, Front End List Magic provides a suite of built in diagnostic options.

Diagnostics can be shown to all users, or just user(s) with Front End List Magic permission.

Highlighting list items and containers gives visual feedback that the right list and items are being selected.

Diagnostic output provides a trace of how Front End List Magic walks through the DOM to find a list, the items in the list, and what it is keying on. This can be output to the page or the developer console. Output can be a full and verbose output, or just critical errors, such as not being able to identify unique keys for the list items.

Developer integration

Front End List Magic fires a Concrete5 event on_felm_list_updated when a list is changed. See /tools/update_list.php.

This could be used, for example, to synchronise a list within Concrete5 with changes made to the display of the list through Front End List Magic.

Under the hood

Front End List Magic does its magic by using jQuery to find and catalogue the items within a list, saving that catalogue and changes made to it on the web server via AJAX.

Then, when the page is shown, the saved catalogue is served with the page and Front End List Magic finds the list again and re-arranges it to match the catalogue, putting any remaining (ie new) items either at the front or end of the list.

To make Front End List Magic work with any list on a page, the block controller creates a set of css specifically adapted to the list that each Front End List Magic block is working on and inserts those styles in the page header and the JavaScript.

Get me back to my original list!!

If you want to return your list to its original state, before Front End List Magic did its stuff, simply delete the corresponding Front End List Magic block from the page and remove any Design (Set Block Styles) you have aplied to the corresponding list block.