Getting started with elements

Universal Content Puller Elements is a developer level content display for Universal Content Puller Once installed, you will have Element and Element List content displays.

  • The Element content display renders your element once, so will typically be configured to pass all the data from the transform.
  • The Element List content display renders your element once for each item in a list of content passed by the transform, passing data for that item in the list.

Bundled Elements

Universal Content Puller Elements includes some basic elements as diagnostic aids and as examples of how to use Universal Content Puller Elements.

  • dump.php is a potentially verbose diagnostic. Each $variable passed to the element from the content display is listed and either rendered directly or dumped using var_dump_safe(). Use it to see what is coming out of the content transform and see how your configured data mapping is passed to an element.
  • content_dump.php is usually a less verbose diagnostic. If scalar $content is provided, it is echoed directly. If more complex $content is provided, it is dumped with a print_r(). If no $content is provided, the list of $variables names passed to the element is echoed.

With both elements, if $page is provided the page name will be shown as a heading.

You can download some examples to import at the bottom of this page.

Your Elements

Use the bundled elements as diagnostics and use the examples from the bottom of this page as learning aids. In practice, your own elements will be more practical and end user oriented.

For example:

  • Application specific formatting of items in a list. Use UCP to pull and transform a list of just about anything, then code a simple element to manage how each item is displayed. UCP takes care of fetching the list, caching, pagination, sanitization and ajax.
  • Custom formatting a table. Use UCP to pull a table of data, then output it with an element that provides custom formatting of the table. Again, UCP takes care of fetching the table, caching, pagination, sanitization and ajax.

Selecting Elements

Universal Content Puller Elements searches out and presents a select control for all /elements in /packages and /application.

  • Any element found in a subfolder called /universal_content_puller_elements/ is coded green, on the assumption that elements placed in such a named subfolder have already been coded to be compatible with Universal Content Puller Elements.
  • Any element in /application/elements not already coded green is coded yellow.
  • Other elements may also be compatible, but it is up to you as a developer to make sure any element you configure within Universal Content Puller Elements will not break your page.

Data provision and mapping

Data mapping is split into three sections.

  • Basic Data - The $content provided from the content transform, the current $controller, the CMS $app and the CMS page object $page
  • Universal Content Puller Data - More complex data and objects specific to how Universal Content Puller is configured. Most elements will have no need for this data. Using it requires a more detailed understanding of how Universal Content Puller works internally.
  • Transform data - pick individual items from the transform data by key/index and map it to variables passed to the element.

The Basic Data is easy to use. It is what you, as a Concrete CMS developer, are already familiar with and is covered by the concrete CMS documentation.

If you are using Universal Content Puller with an content source pulling from a page or page list, setting Adjust page context to source page will change the context the element is rendered and $page to that of the source page.

Pagination

The Element List content display takes a list of content from the transform and renders the element once for each item of content.

With that in mind, it supports the usual Universal Content Puller pagination options. Furthermore, the Universal Content Puller Data section (see above) is extended to include the data used to calculate the pagination. For example, an element could be coded to use this data to identify the current index of an item of content.

Fine Tuning the Element Selector

By default, the Package/Element selector shows all packages that have /elements, their /elements, and /application/elements.

This is constrained by configuration in application/config/generated_overrides/jl_universal_content_puller_elements.php. This configuration file contains 3 lists

  • exclude_packages - a list of package handles that are completely excluded from selection in Universal Content Puller Elements, except elements beneath /universal_content_puller_elements/ subfolders.
  • exclude_package_elements - a list of package_handle/elements/path/to/exclude to target specific elements.
  • exclude_any_elements - a list of partial matches, to exclude elements with paths containing strings such as /edit_ and /dashboard_ and similar, the kind of names used in edit and dashboard dialogs and hence unlikely to be suitable for with Universal Content Puller.

You are free to add to these configuration lists to remove clutter from your own element selection, or to remove from these lists if one of your required elements is being filtered unnecessarily.

Download some examples

Some example uses of UCP elements based on a Concrete CMS v8 and v9 installs with sample content.

These pull content from the sample content blog and use the example Element List element to display it in different ways.

  • Use the support tab of the block edit dialog to copy/paste and Import the JSON from any of these files.
  • The UCP settings may need minor adjustment to work with different installations.

For Concrete Version 8

For a standard v8 install with Elemental sample content.

UCP Elements Examples for concrete v8.zip

For Concrete Version 9

For a standard v9 install with Atomik sample content.

UCP Elements Examples for concrete v9.zip

Additional Pages

About this Sidebar

Creating a sidebar for a group of pages without messing about with stacks is an easy use-case for Universal Content Puller.

This sidebar is edited once, within the main addon page for Universal Content Puller.

It is then pulled into all UCP sub-pages using a UCP block.

The Content Source is Parent Page, set to pull the Sidebar area from 2 pages from the top. The Content Transform is Selector, set to remove container and row classes that, when unnecessarily nested, could mess up the Bootstrap grid. The Content Display is Plain, which just outputs the transformed text.

In the advanced settings, sanitization is disabled as we trust the source page and don't want to strip out any formatting or functionality from the pulled sidebar.