Content Sources

Content Source plugins determine where Universal Content Puller pulls content from. Internally they then provide content as a text string or as an array and must be followed by a Content Tranform plugin that is compatible with the data the source provides. UCP will warn in the edit dialog and provide error information if a  transform is incompatible with the source.

Take care when pulling content not to create recursive loops. UCP includes built in recursion protection and will report when recursion is detected. Nevertheless, if you try hard you may be able to create a convoluted loop of recursion that UCP cannot detect and that will subsequently lead to a broken page.

If that happens, you may

  1. Revert the page version from the dashboard sitemap.
  2. Set 'panic' to true in the UCP config settings at application/config/generated_overrides/jl_universal_content_puller. This will render all UCP blocks as markers while you edit the offending block and fix the problem.

Current content sources fall broadly into categories:

  1. Stacks and areas of pages on the site.
  2. Files from the filemanager.
  3. Sources by file path or URL.
  4. Null - a null source.
[ Universal Content Puller ]

Content Source Plugins

Content Source Plugins connect Universal Content Puller to content sources.

Functionality can be extended by adding plugin classes for additional Content Source Plugins. Content Source Plugins are simple classes that provide the functionality to adapt UCP to alternative content sources. They should inherit from ContentSourcePluginBase. Details are provided by comments in the code.

Plugins can be added by placing the plugin classes at packages/anyPackageName/src/JtF/UCP/ContentSources/Plugins/PluginName or application/src/JtF/UCP/ContentSources/Plugins/PluginName. Plugins can also be similarly placed beneath the plugin type's namespace declared in a package controller's AutoloaderRegistries.

[ Universal Content Puller ]

Child Area

Pull an area from a child page.

For the current page or a selected page, find the nth child and pull the selected area from that page.
Provides content as a string.

Child pages can be sorted in with page list options:

  • Highest review first
  • Lowest review first
  • Sitemap order
  • Reverse sitemap order
  • Most recent first
  • Earliest first
  • Alphabetical order
  • Reverse alphabetical order
  • Most recently modified first
  • Random
A positive index counts from the front of the listed children. A negative index counts from the end of the listed children. An index of zero or 1 is the first of the listed children.

For example, on a blog index page, you could use UCP to pull the first content block of the most recent blog post.

[ Universal Content Puller ]

Express List

List Express data.

Select an Express entity and list objects.
Provides content as a array.

[ Universal Content Puller ]

File

From the File Manager.

Pull the content of a file from the concrete5 file manager.
Provides content as a string.

[ Universal Content Puller ]

Global Area

Pull a global area.

The content of the global area will be rendered by UCP. A subset of the blocks in the area can be specified by slice and/or filter.
Provides content as a string.

[ Universal Content Puller ]

None

A null source.

Return absolutely nothing, as an empty string.
Provides content as a string.

[ Universal Content Puller ]

Page Area

Pull an area from another page.

Specify a page and an area on that page to be rendered by UCP. A subset of the blocks in the area can be specified by slice and/or filter.
Provides content as a string.

Useful for localised areas of common content where a few pages need to show the same content without resorting to stacks or global areas.

[ Universal Content Puller ]

Page List

List pages from the site.

Pull a list of pages with their properties and attributes.
Provides content as a array.

[ Universal Content Puller ]

Parent Area

Pull an area from an ancestor page.

Specify an ancestor page and an area on that page to be rendered by UCP. A subset of the blocks in the area can be specified by slice and/or filter.
Provides content as a string.

Positive ancestor levels are ancestors counted in from from the top of the sitemap. Negative ancestor levels are ancestors counted back from the current level in the sitemap. The ancestor level selected is constrained when pulled to be between the home page and the current page. Useful for localised areas of common content where a few pages need to show the same content without resorting to stacks or global areas.

[ Universal Content Puller ]

Stack

Pull a stack.

The content of the stack will be rendered by UCP. A subset of the blocks in the stack can be specified by slice and/or filter.
Provides content as a string.

[ Universal Content Puller ]

URL

Retrieve from a URL or file path.

Pull the content of a file from a URL or file path.
Provides content as a string.

Only if both the URL source supports pagination and the content display plugin supports pagination, enabling Paginate at source will allow the URL string to manage pagination before the content is passed (via a transform) to the display.

To facilitate this, the URL string can make use of the placeholders '{{limit}}', '{{offset}}' and '{{page}}'. UCP will then fill in the limit, page and/or offset with the relevant values. Behind the scenes, where '{{offset}}' is supported the value inserted in '{{limit}}' may be slightly larger than the page size to facilitate detection of the last page and orphans.

[ Universal Content Puller ]

URL With Form

Retrieve from a URL or file path making use of GET or POST parameters from the request or page or user attributes.

This content source is an extension of the URL content source with the addition of further parameters pulled in from an on-page form or other provision of GET or POST parameters or the values of page or user attributes.
Provides content as a string.

This content source does not provide the actual form. Providing the form is entirely up to you and in its simplest guise could be just an HTML block. Use of any of the forms blocks or packages may also be feasible, but you will need to disconnect the form display from actually submitting to the form controller. The form simply needs to refresh the page without actually doing anything, so allowing UCP to use the form data without interference. Furthermore, you don't actually need to have a form on the page with UCP! UCP reads the URL query string data, so you could have a form on another page or simply a hard coded link with a query embedded to navigate to the UCP page using URL With Form.

Only if both the URL source supports pagination and the content display plugin supports pagination, enabling Paginate at source will allow the URL string to manage pagination before the content is passed (via a transform) to the display.

To facilitate this, the URL string can make use of the placeholders '{{limit}}', '{{offset}}' and '{{page}}'. UCP will then fill in the limit, page and/or offset with the relevant values. Behind the scenes, where '{{offset}}' is supported the value inserted in '{{limit}}' may be slightly larger than the page size to facilitate detection of the last page and orphans.

In addition to the pagination placeholders '{{limit}}', '{{offset}}' and '{{page}}', the URL may contain further placeholders such as '{{form_field_name}}' and '{{another_form_field_name}}' to insert parameters to the URL from the form or query parameters. These placeholders are then filled from the concrete5 site page's query string or post data values. Each placeholder should be provided with a default value, which will default to an empty string.

Parameters may be any form input name or url parameter name. In addition, special parameters are:

  • CCM_CID - The cID of the current page
  • CCM_URL - The URL of the current page
  • CCM_CATTR_attribute_handle - A page attribute that must evaluate to a scalar value
  • CCM_UID - The uID of the current user
  • CCM_EMAIL - The email address of the current user
  • CCM_UATTR_attribute_handle - A user attribute that must evaluate to a scalar value

[ Universal Content Puller ]

User List

List registered users.

Pull a list of users with their properties and attributes.
Provides content as a array.

[ Universal Content Puller XX Sources ]

Any Database

Retrieve data from tables in any database.

Choose from your concrete5 installation's pre-configured databases and enter a simple SQL select statement to retrieve data from that database.
Provides content as an array.

The query is checked for some obviously dangerous statements to prevent accidental damage. This checking is not intended to be foolproof and could be circumvented. This content source should only be installed and enabled where those with edit access to UCP are trusted and competent.

The checking may also return false positives where, for example, a table or column name matches a potentially dangerous keyword - better safe than sorry!

If you need to do anything more complicated with SQL, don't do it with this Universal Content Puller plugin! You could develop a custom source plugin for Universal Content Puller with your SQL embedded in it. This plugin offers a good staring point to copy from.

The available databases need to be configured in /application/config/database.php as described in the documentation page Connecting to Multiple Databases.

If the content display plugin supports pagination, enabling Paginate at source will allow the source to manage pagination before the content is passed (via a transform) to the display.

To facilitate this, the query string should include the SQL 'LIMIT {{limit}} OFFSET {{offset}}'. UCP will then fill in the offset and limit with the relevant values. Behind the scenes, the value inserted in '{{limit}}' will be slightly larger than the page size to facilitate detection of the last page and orphans.

[ Universal Content Puller XX Sources ]

Any Database with Form

Retrieve data from tables in any configured database making use of GET or POST parameters from the request or page or user attributes.

This content source is an extension of the Any Database content source with the addition of further parameters pulled in from an on-page form or other provision of GET or POST parameters, or the values of page or user attributes.
Provides content as an array.

This content source does not provide the actual form. Providing the form is entirely up to you and in its simplest guise could be just an HTML block. Use of any of the forms blocks or packages may also be feasible, but you will need to disconnect the form display from actually submitting to the form controller. The form simply needs to refresh the page without actually doing anything, so allowing UCP to use the form data without interference. Furthermore, you don't actually need to have a form on the page with UCP! UCP reads the URL query string data, so you could have a form on another page or simply a hard coded link with a query embedded to navigate to the UCP page using Any Database with Form.

The query is checked for some obviously dangerous statements to prevent accidental damage. This checking is not intended to be foolproof and could be circumvented. This content source should only be installed and enabled where those with edit access to UCP are trusted and competent.

The checking may also return false positives where, for example, a table or column name matches a potentially dangerous keyword - better safe than sorry!

If you need to do anything more complicated with SQL, don't do it with this Universal Content Puller plugin! You could develop a custom source plugin for Universal Content Puller with your SQL embedded in it. This plugin offers a good staring point to copy from.

If the content display plugin supports pagination, enabling Paginate at source will allow the source to manage pagination before the content is passed (via a transform) to the display.

To facilitate this, the query string should include the SQL 'LIMIT {{limit}} OFFSET {{offset}}'. UCP will then fill in the offset and limit with the relevant values. Behind the scenes, the value inserted in '{{limit}}' will be slightly larger than the page size to facilitate detection of the last page and orphans.

In addition to the pagination placeholders 'LIMIT {{limit}} OFFSET {{offset}}', the select statement to retrieve data should also use '?' placeholders for parameters to the query. These placeholders are then mapped to query string or post data values. By using placeholders, the user entered values are fully escaped to prevent SQL injection. If pagination at source is configured, the query to count the total should use the same '?' placeholders.

Parameters may be any form input name or url parameter name. In addition, special parameters are:

  • CCM_CID - The cID of the current page
  • CCM_URL - The URL of the current page
  • CCM_CATTR_attribute_handle - A page attribute that must evaluate to a scalar value
  • CCM_UID - The uID of the current user
  • CCM_EMAIL - The email address of the current user
  • CCM_UATTR_attribute_handle - A user attribute that must evaluate to a scalar value

[ Universal Content Puller XX Sources ]

Site Database

Retrieve data from tables in the site database.

Enter a simple SQL select statement to retrieve data from the concrete5 site database.
Provides content as an array.

The query is checked for some obviously dangerous statements to prevent accidental damage. This checking is not intended to be foolproof and could be circumvented. This content source should only be installed and enabled where those with edit access to UCP are trusted and competent.

The checking may also return false positives where, for example, a table or column name matches a potentially dangerous keyword - better safe than sorry!

If you need to do anything more complicated with SQL, don't do it with this Universal Content Puller plugin! You could develop a custom source plugin for Universal Content Puller with your SQL embedded in it. This plugin offers a good staring point to copy from.

If the content display plugin supports pagination, enabling Paginate at source will allow the source to manage pagination before the content is passed (via a transform) to the display.

To facilitate this, the query string should include the SQL 'LIMIT {{limit}} OFFSET {{offset}}'. UCP will then fill in the offset and limit with the relevant values. Behind the scenes, the value inserted in '{{limit}}' will be slightly larger than the page size to facilitate detection of the last page and orphans.

[ Universal Content Puller XX Sources ]

Site Database with Form

Retrieve data from tables in the site database making use of GET or POST parameters from the request.

This content source is an extension of the Site Database content source with the addition of further parameters pulled in from an on-page form.
Provides content as an array.

This content source does not provide the actual form. Providing the form is entirely up to you and in its simplest guise could be just an HTML block. Use of any of the forms blocks or packages may also be feasible, but you will need to disconnect the form display from actually submitting to the form controller. The form simply needs to refresh the page without actually doing anything, so allowing UCP to use the form data without interference. Furthermore, you don't actually need to have a form on the page with UCP! UCP reads the URL query string data, so you could have a form on another page or simply a hard coded link with a query embedded to navigate to the UCP page using Site Database with Form.

The query is checked for some obviously dangerous statements to prevent accidental damage. This checking is not intended to be foolproof and could be circumvented. This content source should only be installed and enabled where those with edit access to UCP are trusted and competent.

The checking may also return false positives where, for example, a table or column name matches a potentially dangerous keyword - better safe than sorry!

If you need to do anything more complicated with SQL, don't do it with this Universal Content Puller plugin! You could develop a custom source plugin for Universal Content Puller with your SQL embedded in it. This plugin offers a good staring point to copy from.

If the content display plugin supports pagination, enabling Paginate at source will allow the source to manage pagination before the content is passed (via a transform) to the display.

To facilitate this, the query string should include the SQL 'LIMIT {{limit}} OFFSET {{offset}}'. UCP will then fill in the offset and limit with the relevant values. Behind the scenes, the value inserted in '{{limit}}' will be slightly larger than the page size to facilitate detection of the last page and orphans.

In addition to the pagination placeholders 'LIMIT {{limit}} OFFSET {{offset}}', the select statement to retrieve data should also use '?' placeholders for parameters to the query. These placeholders are then mapped to query string or post data values. By using placeholders, the user entered values are fully escaped to prevent SQL injection. If pagination at source is configured, the query to count the total should use the same '?' placeholders.

Parameters may be any form input name or url parameter name. In addition, special parameters are:

  • CCM_CID - The cID of the current page
  • CCM_URL - The URL of the current page
  • CCM_CATTR_attribute_handle - A page attribute that must evaluate to a scalar value
  • CCM_UID - The uID of the current user
  • CCM_EMAIL - The email address of the current user
  • CCM_UATTR_attribute_handle - A user attribute that must evaluate to a scalar value

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.