User Guide

General Concepts

Uber List comprises 4 main components:

  • A dashboard page showing what Uber List compatible plugins are available. You don't need to know anything about that to get started, so by all means have a look, but wait until later before reading about Uber List plugins.
  • The Uber List block itself. This is what our getting started exercises will be based on.
  • Uber List templates for the core Page List and Search blocks. You can ignore that for now, we will come back to it later.
  • Some Magic Data symbols that help with list items.

Uber List works by using a Magic Data expression to create a list. This can be a list of pages, users, files, eCommerce products, or anything else you can build a list for using Magic Data symbols.

The display of list items uses a stack or HTML area as a template. The stack or HTML in turn contains more Magic Data expressions that are evaluated to adapt the template for each item in the list.

The completed templates for list items may then optionally be wrapped and paginated using simple or animated transitions.

Tip for Power Users!

I tend to develop pages containing Uber Lists with three browser tabs open:

  1. On the dashboard Symbols page with the built in symbol tester and documentation.
  2. On the dashboard Stack Edit page for the stack that templates the list.
  3. On the site page with the actual Uber List block I am adding / testing.

Getting Started - Replicating a Page List

An easy starter exercise is to replicate a Page List. In most cases, you would just use a Page List block. Nevertheless, knowing how to replicate a Page List is a foundation upon which you can develop more sophisticated Uber Lists and introduces many important aspects of using Uber List.

Start in the dashboard and create a stack to act as a template for each list item. You can give it any name you want, perhaps "Uber List plain page list".

In that stack, add an HTML block and enter some HTML containing Magic Data expressions:

<h3>[% ORIGINAL_PAGE PAGE_LINK %]</h3>
<div>
[% ORIGINAL_PAGE PAGE_DESCRIPTION TRUNCATE_TO_WORD 150 %]...
<em>[% ORIGINAL_PAGE URL AS_NAMED_LINK " more." %]</em>
</div>

Save and approve your stack.

When the template is filled ORIGINAL_PAGE refers to each list item. You could alternatively use UBER_LIST_ITEM. This will be the same as ORIGINAL_PAGE for lists of pages and can be used more generally to refer to any type of item listed.

PAGE_LINK generates a link to the page, which our template places in the heading for the item.

Below that we get the PAGE_DESCRIPTION and truncate it to 150 characters at a word boundary using TRUNCATE_TO_WORD 150. Look carefully and this is followed by … as ellipses.

We then get the URL for the page and show it AS_NAMED_LINK with the name "more".

That's it. Our template is complete. You could add an alternate block template or use block design to style the template. Or you could leave it as-is and apply some styling later in the Uber List block. What you should not do is apply a Magic Data template at this stage. Applying such a template would result in the Magic Data in the block being evaluated before Uber List can use it as a template!

Now navigate to the page where you want to show the page list, edit the page and add an Uber List block.

In the Uber List block only two of the tabs are relevant to our simple exercise. "Create List" and "Item Template". For now, you can ignore the other tabs.

To create the list, we need to enter a Magic Data expression. For example, we could enter:

PAGE LIST_PAGES 50

This would list up to 50 pages immediately beneath the current page. Or to list pages beneath another page, enter the page name or page ID as a starting point for the list.

1 AS_PAGE LIST_PAGES 50

Will list pages beneath the home page.

'about' AS_PAGE LIST_PAGES 50

Will list pages beneath the about page.

You can then use the green "Test" button to check how your expression evaluates. Remember that evaluating an expression will not have saved it to the block you are editing!

When you have a page listing expression fully tested, go to the "Item Template" tab and select the stack you have already created.

That's it. The block can now be saved and the page published. You should see a list remarkably like that generated by a Page List block.

You can see an Uber List doing just that in the right sidebar of this page and all the other add-on support pages of this site. It is all the one Uber List in the page type defaults adapting itself using Magic Data.

You can also see a bigger list Addon pages - Plain Uber List with, for comparison, a conventional Page List block at Addon pages - Core Page List with Default template. Details of how such an Uber List is generated are given further down on this page.

Enhancing the list data

To enhance the list content, we can either edit our stack or create a new stack and edit the Uber List block to use that stack.

For example, suppose we want to show a bit more information about a page. This time we could use more than one block in the stack. Create a new stack with a useful name like "Uber List page list with info".

Add a content block for a heading:

<h4>[% ORIGINAL_PAGE PAGE_LINK %]</h4>

I have shown the HTML tag here, but you would simply use the content editor to apply the h4 styling.

For the additional information a good structure to use is a definition list. You could use whatever text and formatting you like in the same content block, but content blocks are not the easiest for definition lists, so I would use an HTML block next in the stack, or be really lazy and use a Structured Content block for its instant definition list template.

<dl>
<dt>Description:</dt>
<dd>[% ORIGINAL_PAGE PAGE_DESCRIPTION TRUNCATE_TO_WORD 100 %]...<em>[% ORIGINAL_PAGE URL AS_NAMED_LINK " more" %]</em></dd>
<dt>Added:</dt>
<dd>[% ORIGINAL_PAGE PAGE_PUBLIC_TIME DATE "d M Y" %]</dd>
<dt>Updated:</dt>
<dd>[% ORIGINAL_PAGE PAGE_VERSION_TIME DATE "d M Y" %]</dd>
<dt>Author:</dt>
<dd>[% PAGE OWNER EMAIL AS_NAMED_LINK ( UID USERNAME ) %]</dd>
</dl>

A definition list <dl> contains terms <dt> and definitions <dd>. Here, the terms are fixed text and the definitions are created using Magic Data. Looking at the Magic Data above, you should be getting the idea by now as we use further symbols to pull in more information about the listed page.

If you have any problems with the Magic Data expressions, you can use the dashboard Symbol tester page to try out snippets or more complex expressions. To test them, you may need to swap ORIGINAL_PAGE for PAGE, develop the expression and test it, then swap it back to ORIGINAL_PAGE before pasting into your stack.

Remember to save and approve your stack, then go back to your page to edit the Uber List block.

For now, all you need to do is change the block to use our new "Uber List page list with info" stack and save it.

Publish the page and now the test page will now show the enhanced information in the list.

You could change the Magic Data and blocks in the stack to show pretty much anything you wanted. Perhaps you have a page thumbnail image attribute or some category attributes or you want to insert a map. All are easily accessible using a combination of Magic Data and any concrete5 block. Because Uber List processes the Magic Data for the whole stack, you don't need to worry about the availability of Magic Data templates for these blocks.

Styling the list

Now we have more sophisticated data in our Uber List, it would be good to add a bit of style to the way it is displayed.

To do that we edit the Uber List block again and use the "Item Wrapper" tab. A Content wrapper uses any block template originally developed for a core Content block to wrap each list item in turn. There are a few free templates in the Marketplace, or a great spread of templates in Enlil Transparent Content, or you can easily cook your own template for a Content block.

If you don't have any content block templates to hand, you can easily move on with our exercise by selecting the Content wrapper and then selecting none. Remember you can also style blocks within your stack, so there are many alternatives.

Having selected a Content wrapper, you can now give each item a fixed width, padding and margins. Assuming your listing page has a full width Main area, a good width to set is about 200. Check the box to float this left, hide overflow, and give it 5 pixels of margin right and bottom. You may want to do some maths to come up with good widths to go with your theme.

Save and publish again and your list will now be tiled as cards in a grid.

Uber List templates

Depending on the length of information for each of the pages in your list, the grid of cards may be a bit ragged.

Uber List smartens this up with a range of item width and height settings and alternate block templates. From the block Custom Template dialog you can select:

  • Equal Height List Items - does as its name suggests.
  • CSS Columns - creates css columns and fits the list into them.

If you have Blocks By AJAX installed, there are also AJAX variants of the list templates.

Finally, there is a Remote Settings template. Don't try and use that one yet, we will come back to it later.

If most of your list items are roughly similar height, Equal Height List Items is probably a good template to select.

Clearing Flow

Depending on how your list is floated and the template used, you may also want to clear the overall flow. In web terms, this is usually called Clearfix. It tells a browser to draw an end to floated items and start cleanly below it on the page.

You can select various flow clearing options in the "General Options" tab of the Uber List block edit dialog. The most likely option to be needed is "Clear flow after list".

Bigger Lists

Depending on your site, maybe you want to list more than one level of pages. To do that, you will need to develop a more complicated page listing expression in the Create List tab of the Uber List block edit dialog. There are plenty of examples on the Magic Data and Uber List support pages.

A good general expression to work from is:

1 AS_PAGE LIST_PAGES 20 MERGE_INTO m1
APPLY_EACH
  LIST_PAGES 100 MERGE_INTO m1
  NULL
END_APPLY_EACH
m1 RECALL
REDUCE
SORT_BY
  PAGE_NAME
END_SORT_BY

This will start at the home page - id 1 - and list 20 pages into a memory that we arbitrarily name m1. Then, for each of those pages, it will list 100 further pages and merge those into m1.

The NULL prevents the content of m1 piling onto other bits of list and dropping out through END_APPLY_EACH. Then we REDUCE to remove duplicates and SORT_BY PAGE_NAME.

You probably don't want to try this on a site with 2000+ pages, that would take Magic Data a while to evaluate, but the big numbers allow for some large sub-lists balanced out by some smaller sub-lists.

You can start the 2-level list anywhere by changing the 1 to another page id, path or name.

If you want all pages beneath a specific page, you can use the LIST_ALL_PAGES symbol for a simpler expression:

1 AS_PAGE LIST_ALL_PAGES 100
SORT_BY
  PAGE_NAME
END_SORT_BY

This will start at the home page - id 1 - and list up to 100 pages at any level beneath that page.

There are a selection of other LIST_ALL_xxx symbols that can be used to provide quick lists of many items, including variations with filtering by attributes. Check the Symbols Documentation for details.

The symbols LIST_ALL_xxx_WITH_FILTER and  LIST_ALL_PAGES_OF_TYPE can be combined with AND_WITH_FILTER and AND_SORT_BY and other query building symbols to build more complex list queries directly from the database for fast evaluation of big lists.

Pagination

Now we have a bigger list, it may be getting a bit cumbersome to show all in one go. This brings us nicely to the "Pagination" tab of Uber List's edit dialog.

If our grid runs 4 across a page, then maybe 4 or 8 would be good numbers to paginate by. For now just move the slider, Save the dialog and Publish the page and let Uber List's default settings take care of the rest.

The list will now be paginated within the web site page by JavaScript.

Transitions

While on the "Pagination" tab, you will no doubt have noticed the section below the Pagination slider caller "Page transitions". Go on, have a play, I know you want to. I won't describe all the possibilities in detail. The best way to learn these is to experiment.

Not all the settings work together, for example, Direction is not relevant to a Fade. With Easing, its usually best to keep it simple with Linear or Swing. Or maybe Bounce. Most visitors wont want it your list wobbling 7 times before changing. It will just annoy them. Explode is always fun!

Transitions are also limited by the jQuery and jQuery.UI libraries used to implement them. Sometimes a particular combination just doesn't work as you would expect.

Transition speed is in milliseconds. Good numbers are usually between 400ms and 800ms. Any faster is hardly worth bothering with. Much longer can get a bit tedious for your visitors.

By default, transitions are applied to each item in the list independently. However, there is an option to "Group items by page". In that case, each paginated group of Uber List items will be wrapped in a div element and the transition applied to the whole div.

Again, sometimes this works better and sometimes not. Its up to you to experiment and find what meets your requirement. Bear in mind that different browsers could behave differently.

Uber List has a config/site parameter UBER_LIST_BAD_IE_V that turns off transitions for any Internet Explorer version at that version or lower. The default setting is 8. You can also select to disable transitions for mobile devices.

You can see a variety of transitions in action on the associated example pages. I recommend you start with Addon pages - Full Width List with direct loading then follow the trail of examples from there.

Lazy Load

Introduced with version 1.5 or Uber List, the Lazy Load settings can be used to speed up the initial load of a list by delaying the loading of all but the initially visible items.

Suppose you have a list paginated into groups of 8 items, where each item requires several Magic Data tokens to be rendered within a stack. Its just the kind of list used in many of the examples shown on this site.

Working all that out in one go can consume a fair bit of server time, maybe even pushing the limits of cheap shared hosting accounts. By limiting the initial load to 8 or 16 items (1 or 2 pages) with a simple placeholder for all other items, the page can still be shown reasonably quickly.

Once the initial items are shown, further parameters to do with X and Y distance from the viewport, a time interval between ajax loads, and the number to load in each ajax request, can be adjusted to suit the list format, content and server resources. 

On this site, most large Uber Lists load 16 items initially then batches of 8 at a time with unlimited X and Y separation and about 200ms between batches.

List more than just pages!

Uber List is not limited to pages. Using Magic Data you can list anything you want that there is a Magic Data symbol for - pages, users, files, products and more. If that is not enough and you know a bit of php, new Magic Data symbols are so easy to write you can easily create symbols to list and show data from anything you want to.

The key symbol for lists other than page lists is UBER_LIST_ITEM.  If the expression in "Create List" is listing users, each UBER_LIST_ITEM will be a user. If the expression in "Create List" is listing files, each UBER_LIST_ITEM will be a file. There are no limitations imposed by Uber List. If you can list something with Magic Data symbols, then you can use it in an Uber List and UBER_LIST_ITEM is the symbol you can use in your template to adapt to each item of the list.

As an example, lets create a nice list for the banners images provided with concrete5 default content. First, go to the file manager and add these images to a file set called "banners".

Then we need to go to the dashboard stacks page and create a stack for our list template. It can have any name, but for the purposes of this example I will call it "Uber List File Display".

The stack content is a variation of the one we created for our extended page list content.

First, a content block containing:

<p>[% UBER_LIST_ITEM AS_FILE FILE_THUMBNAIL 230 %]</p>

Then a definition list. You can do this manually in an HTML block or use a Structured Content block to do it the easy way.

<dl>
<dd>Title:</dd>
<dt>[% UBER_LIST_ITEM AS_FILE FILE_NICE_TITLE %]</dt>
<dd>Width:</dd>
<dt>[% UBER_LIST_ITEM AS_FILE ATTRIBUTE width %] pixels</dt>
<dd>Height:</dd>
<dt>[% UBER_LIST_ITEM AS_FILE ATTRIBUTE height %] pixels</dt>
<dd>Download:</dd>
<dt>[% UBER_LIST_ITEM AS_FILE FILE_DOWNLOAD_URL AS_NAMED_LINK ( UBER_LIST_ITEM AS_FILE FILE_NICE_TITLE ) %]</dt>
</dl>

Together, this Magic Data will insert a 230 pixel thumbnail, the file title, the width and height, and a download link.

Now we need an Uber List to list the banners and show the stack:

Banners AS_FILESET LIST_FILES 20

In the "Item Template" tab, select the "Uber List File Display" stack. In the "Item Wrapper" tab, select a suitable content block template, float it left, hide any overflow, give it a width of 250 pixels and 5 pixel margins bottom and right.

For Pagination, 3 items per page is about right for a full width page type, or if you want 2 rows make it 6 items per page. With the rest, you can pick what you want for transitions and height fixing.

Save and publish and we have a nice list of files in the set with supporting information.

45_Fileset_List.png

You could use a similar approach to listing users, pulling in avatars to the template stack or an image file linked by a file attribute called 'mugshot', then showing contact details.

List Cache

The only tab we have not mentioned yet is the "List Cache". This allows the evaluation of the expression on the "Create List" tab or even rendered list items to be cached for a period of time.

When the cache is enabled, further settings are available to choose how broadly lists are cached across users, groups and pages that an Uber List block appears on. Globally is most efficient, but ignores any security issues and can also give unexpected results if an Uber List block is copied or otherwise rendered in more than one place.

By default the cache only keeps the list output by the "Create List" tab, not the individual list items. You can select  to also cache each rendered list item. For simple list items, this will have little or even negative benefit. However, where list items themselves involve complex Magic Data evaluation or other time-expensive blocks, caching the rendered list items can improve responsiveness.

So that multiple cache entries do not all expire their cache at the same time, you can add some jitter. This is especially useful where rendered list items are also cached.

Keeping Magic Data in context

As you are no doubt aware by now, each item listed by an Uber List is shown by filling in a stack based template using Magic Data.

This means that, for listed items to accurately reflect the item they are listing, the Magic Data must be evaluated in the context of that list item. Only within that cycle of the loop that outputs a list will the ORIGINAL_PAGE or UBER_LIST_ITEM be accurate. 

If the Magic Data in the template is executed too soon, perhaps when the stack is initially rendered or by Magic Data enabled templates within the stack, the all important context will not yet be known.

This is why it is usually not a good idea to apply a Magic Data block template within the stack Uber List is using as a template. Applying such a template would result in the Magic Data in the block being evaluated before Uber List can use it!

However, sometimes you cant get away with it. Some blocks have Magic Data built into their default templates. Some blocks, such as Sorcerer's Map, need to evaluate Magic Data within the block to determine what they are showing. Hence an Uber List option on the "Item Template" tab you will probably be wondering about, "Fetch template item-by-item". 

For efficiency, Uber List normally fetches the template stack once, then uses that template repeatedly to fill it for each list item. When "Fetch template item-by-item" is checked, Uber List will fetches the template stack repeatedly, once for each list item and within the context of the list item. This means that any Magic Data evaluated within the stack will now have the correct context for the list item.

Remote settings for Really Big lists

The Remote Settings template only shows in edit mode. When a page is viewed, rather than outputting a list the settings from the Uber List block are held for later use.

The Remote Settings template currently works with an Uber List template for the core Page List and Search blocks, but may be extended to other list such as eCommerce Product Lists in the future. The Page List or Search blocks are set up in the usual way using the block's own add/edit dialog. Then when the block is output, each listed item is rendered using the Uber List settings.

The combination of an Uber List template for a Page List or Search block with remote control gives you complete control of what is shown in each listed page and how each item is formatted. Even the search results for the site search within this site are formatted using Uber List!

Obviously, because the list items come from the other blocks, there is no point evaluating a complex expression in the Uber List "Create List" tab, so a good expression to enter is NULL. Similarly, any settings in the Uber List "List Cache" tab are ignored by the Remote Settings template.

The time to use the combination of a Page List block to create the list and Uber List to format the list through Remote Settings is when lists start to get very long.

Uber List by itself is great for small to medium sized lists, especially with the optional lazy loading, but the sophistication of the templating mechanism and all-in-one list creation with JavaScript paging can make the rendering time of really big lists unacceptable with a pure Uber List block.

By combining a Page List block with an Uber List template controlled by Remote Settings, we can make use of the server-side pagination of big lists provided by the Page List block with the individual item templating provided by Uber List. Its not as slick as Uber List by itself, but it can display lists that go beyond Uber List's capabilities.

Magic Data Symbols

Uber List provides some special symbols to extend Magic Data. The symbols provided will no doubt grow as Uber List is further developed. So take this section as a snapshot of the most important symbols provided.

UBER_LIST_ITEM

UBER_LIST_ITEM is the most important of these symbols. You can rely on this symbol to reflect the current list item and context within the stack used as an item template. When listing pages, this will be the same as CURRENT_PAGE, as used in most of our examples.

However, Uber List is not limited to pages. If the expression in "Create List" is listing users, each UBER_LIST_ITEM will be a user. If the expression in "Create List" is listing files, each UBER_LIST_ITEM will be a file. There are no limitations imposed by Uber List. If you can list something with Magic Data symbols, then you can use it in an Uber List and UBER_LIST_ITEM is the symbol you can use in your template to adapt to each item of the list.

LIST_ALL_xxxx

A growing suite of LIST_ALL_xxx symbols provides rapid listing of many types of items with filtering by attributes. These are really useful for reducing a really big list of pages to a filtered subset, such as pulling out blog pages with a specific tag.

BLOG_THUMBNAIL

BLOG_THUMBNAIL will retrieve the thumbnail associated with a blog page.

PAGE_TEASER

To use PAGE_TEASER you must also have the Page List Teasers addon installed. For a page, this will return the associated teaser drawn directly from the page content. 

If Page List Teasers is not installed, this symbol will return the page description.

You must be very careful if you use this symbol in an Uber List where the list page itself could appear in the list. Evaluating a teaser could result in the Uber List evaluating itself, and so on ad-infinitum into a recursive loop!

To block such infinite recursion, Uber List limits the number of blocks rendered on a page. By default this is just 10 blocks, though the limit can be adjusted by a config/site definition of UBER_LIST_LIMIT.

Just allowing recursion to meet this limit is inefficient. A much better strategy is to remove the page showing an Uber List in the "Create List" expression. For example:

PAGE PARENT LIST_PAGES 50
REMOVE_FROM_LIST ( PAGE )

Note that you only need to do this when a list item is in danger of becoming recursive, such as within a PAGE_TEASER. If a list item template stack does not render content directly from a list item, there is no danger and most Uber List lists can safely list themselves.

concrete5 Block and Page cache

While the Uber List block itself is not enabled for block caching, once on a page the generated list is eminently compatible with forced full page caching. Just take care to ensure that doing so does not circumvent any permissions you may have placed on block visibility with a page.

To speed list processing, Uber List implements a built in List Cache (see above)

Plugin Architecture

Uber List uses a plugin architecture for Item Templates and Item Wrappers. The plugins provided with Uber list use a stack as a template and use a core Content block as a wrapper. So every Uber List item is templated by a stack and any template compatible with a core Content block can be used to wrap Uber List items.

The plugin mechanism is the same as that used for Universal Content Puller, so developers interested in creating new template or wrapper plugins should refer to Developing Content Sources.

Item Wrappers are similar to Universal Content Puller wrappers, so any Universal Content Puller Wrapper can easily be adapted for use with Uber List and vice-versa.

List Item Templates are similar to those for Universal Content Puller Content Sources, so any Universal Content Puller Content Source that returns a string (as opposed to a list) can potentially be adapted for use as a List Item Template with Uber List and vice-versa.

Please see the Uber List Plugin Documentation page for details.

Last updated: over a year ago