Dynamic Content

Load dynamic content into your layouts and create site-wide templates for categories and articles using the YOOtheme Pro page builder.

YOOtheme Pro allows you to load content, which is managed in Joomla, from the database into your layouts. This can be the article's title or featured image. Whenever that content changes, it will be automatically updated across your entire website. This is not limited to article fields. Any content from Joomla can be loaded into your layouts.


Content Sources

All builder elements are able to load dynamic content. First, you need to select a content source which defines fields available for mapping. It can be selected in the Advanced tab of an element under Dynamic Content.

Dynamic content field

For elements which have multiple content items, for example the Grid or the Slideshow element, the Dynamic Content option can be found in the Advanced tab of each item and not of the element itself. This way each item can have a different content source.

The options under Dynamic Content are grouped depending on where the source comes from.

Type Description
Page Content sources which are provided by the page you are browsing. On a single article page, it's the article itself, and on the category page, it's the category itself and its articles.
Custom Content sources which are custom queried. They are independent of the current page. For example, you can load the latest articles or all blog categories into a page.
External External sources which are custom queried. They are independent of the current page. For example, you can load images from a specific folder into a page.
Site A content source with general fields of your site.

Content sources

In general, a content source can be Articles, Categories, Tags, Users or Files. YOOtheme Pro also differentiates between a source which contains a single item or multiple items. In addition, a source can have related content sources, for example the article author or tags. Let's go into details.


Page Sources

Depending on the page you are browsing Joomla provides different content sources. These sources are used when creating templates for those pages. For example, the template for the single article page will render different article content depending on which singe article you are browsing.

Here is an overview of all supported pages and their content sources.

Page Sources
Single Article The Article itself
Category Blog The Category itself and all its Articles
Featured Articles All featured Articles

Pages with an Articles source are usually divided into separate pages. The number of articles displayed per page is defined by the total number of Leading Articles, Intro Articles and Links which can be set in the Blog/Featured Layout options in Joomla.

Note that Articles is a multiple items source, while all other page sources only contain a single item.


Custom Sources

Custom sources allow you to load custom queried content which is not automatically available on the page you are browsing. For example, you can load the latest articles or all blog categories into a page. Unlike page sources, custom sources are not divided into separate paginated pages.

Following custom sources are available.

Source Type Description
Custom Article Single Manually select an article or use filter options to specify which article should be loaded. Only article from the selected categories is loaded. Articles from child categories are not included. Use the shift or ctrl/cmd key to select multiple categories.
Custom Articles Multiple Articles are only loaded from the selected categories and tags. Articles from child categories are not included. Use the shift or ctrl/cmd key to select multiple categories or tags. If no category or tag is selected, all articles are loaded. Additionally, you can load featured articles only.
Custom Category Single Manually select a category.
Custom Categories Multiple Categories are only loaded from the selected parent category.

Custom article


External Sources

External sources allow you to load custom queried content which is not available in the Joomla database, but comes from the file system. For example, you can load all images from a specific folder. Just like custom sources, external sources are not divided into separate paginated pages.

Following external sources are available.

Source Type Description
File Single Manually select a file or a folder or load a file by choosing a path glob pattern and setting the offset. For example, specify the file format using files/*.zip or images/*.{jpg,png}. The path is relative to the system folder. To relate the path to the current child theme use ~theme/*.
Files Multiple Load all files from a selected folder or set a path glob pattern to filter files. For example, specify the file format using files/*.zip or images/*.{jpg,png}. The path is relative to the system folder. To relate the path to the current child theme use ~theme/*.

External file


Multiple Items Sources

Most builder elements can only render a single item. Multiple items elements, on the other hand, for example the Grid or the Slideshow element, have the ability to render multiple content items. The content item of the element will render as many items as available in the content source.

Multiple items element

If you select a content source which has multiple items, there are two options available to define which items are rendered.

Option Description
Start Set the starting point. If the value is 1, it starts with the first item.
Quantity Limit the number of items. If the value is left empty, all items will be loaded. This option is disabled for elements which can only render a single item.

Start and quantity

The combination of the Start and Quantity options allows you to split content source items into different visual layout parts. For example, you can show a number of articles in a hero slideshow followed by a grid showing the rest of the articles.

Note When templating an index or a category page, the Quantity option should only be used when splitting content sources. This is because the number of articles on those pages is already defined in Joomla.

Order and Direction

Custom sources have additional options to order their items. Mind that the item order of page sources are defined by Joomla. Depending on whether the custom source is a article or a category, there are different order options available.

Order Description
Published Order by published date.
Created Order by created date.
Modified Order by modified date.
Alphabetical Order alphabetically.
Hits Order by number of hits.
Article Order Order by the Joomla article ordering.
Featured Articles Order Order by the Joomla featured articles ordering.
Random Order randomly.
Custom Fields Order by any custom field.

Set the order direction of the items.

Direction Description
Descending Start with the last item.
Ascending Start with the first item.

Additionally, you can set the ordering from alphabetic to alphanumeric. It treats multi-digit numbers at the beginning of the string as a single character as opposed to alphabetical ordering which treats each digit separately. For example, alphanumeric ordering will sort 2. Chapter before 12. Chapter and not vice versa.

Order and direction


A source can have related content sources, for example the article has a related author and tags. Fields of all related content sources which contain a single item, like the author, are available for mapping together with the fields of the chosen content source. On the other hand, related content sources with multiple items, like article tags, have to be selected under the Multiple Items Source option.

Multiple items source

Following related content sources are available for an article.

Related Source Type Description
Author Single The article author
Category Single The category the article belongs to
Tags Multiple The tags the article belongs to
Category: Child Categories Multiple The child categories of the category the article belongs to
Category: Tags Multiple The tags of the category the article belongs to

Related article sources

Following related content sources are available for a category.

Related Source Type Description
Parent Category Single The parent category of the category
Child Categories Multiple The child categories of the category
Tags Multiple The tags the category belongs to
Parent Category: Child Categories Multiple The child categories of the parent category
Parent Category: Tags Multiple The tags the parent category belongs to

Related category sources


Field Mapping

Once a content source is selected, its fields are available for mapping. To map a content field to an element's field, open the Content tab of an element. Each element field shows a Dynamic button on the right which opens a dropdown with a list of all available content fields.

Dynamic button

Select the content field to map it to the element's field. For example, you can map the article’s title and featured image to the title and image fields of the Panel element. Use the search to easily find the needed field.

Field mapping

Instead of the former field, the dynamic field is shown with its name and source.

Dynamic field

The following actions are available.

Action Description
Dynamic Button Open a dropdown with all content fields available for mapping.
Edit Icon Open the available field options.
Delete Icon Remove the field mapping. The former field is shown again.

Content Fields

YOOtheme Pro can load fields from an Article, Category, Tag and User. Custom fields from Joomla are available for mapping as well. While most fields like title, published date or an image simply render their content, some fields are pseudo-fields, which means there is no actual field to fill out. Their content is provided by Joomla or depends on different fields.

Pseudo-fields Description
Teaser Render the intro text if the read more tag is present, otherwise the whole article content.
Meta Render the published date, author and category fields in a formatted string. Category and author are automatically linked to the category page and author's profile page respectively. Mind that the author will only be linked if you create a contact page for the user under Components → Contacts in Joomla.
Tags Render a comma-separated list of all tags which are automatically linked to their tag page.
Link Render the link to the item's page.

The following pseudo-fields render content which is added by Joomla plugins to the articles. For example, this could be a third-party comments system.

Field Description
After Display Title Render the afterDisplayTitle event.
Before Display Content Render the beforeDisplayContent event.
After Display Content Render the afterDisplayContent event.

Important Mind that the Content and Teaser fields should only be mapped on templates and not on individual page layouts. This is because these fields are used to store the actual page content and the builder layout itself.


Field Options

There are several options available to manipulate the content of a field. Some field types have additional options.

Field options

Note The order in which the options are applied is: Date Format → Content Length → Search and Replace → Before and After

Before and After

All fields have options to add text before and after their content.

Option Description
Before Add text before the field value. For example, if it's an email address, for example info@example.com, and you add mailto: to the Before option, the created link mailto:info@example.com, will open the user's email program.
After Add text after the field value. For example, if it's a pricing number, for example 20, and you add a unit like to the After option, the price 20€ will be displayed in your layout.

Note Text in the Before and After fields can be translated by using the WPML String Translation plugin.

Search and Replace

All fields have options to perform a search and replace on their content. This is very powerful and allows advanced manipulation of the field content.

Option Description
Search Select a predefined search pattern or enter a custom string or regular expression to search for. The regular expression has to be enclosed between slashes. For example my-string or /ab+c/.
Replace Enter the replacement string which may contain references. If left empty, the search matches will be removed.

The predefined URL Protocol pattern (/https?:\/\//) will remove the HTTP/HTTPS protocol from an URL, if the replacement string is left empty. For example https://yootheme.com will convert to yootheme.com. This pattern allows you to link to an external page and display a shortened URL with just one custom field.

Learn more about search and replace in the PHP preg_replace function documentation and about regular expressions in the MDN Regular expressions documentation. The best place to test regular expressions is Regex101.

Content Length

Text fields have an additional option to limit the content length.

Option Description
Content Length Limit the content length to a number of characters. All HTML elements will be stripped.

Content length option

Date Format

Date fields have an additional option to format the date.

Option Description
Date Format Select a predefined date format or enter a custom format, for example M j, Y (Aug 6, 1999) or m/d/Y (08/06/1999).

Date format option

Learn more about it in the PHP Date function documentation.

Teaser Field

The teaser field has an additional option to show the excerpt text instead of the intro text.

Option Description
Excerpt Prefer excerpt over intro text. To use an excerpt field, create a custom field with a name excerpt.

Teaser field option

Meta Field

Meta fields have additional options to display their content.

Option Description
Format Display the meta text in a sentence or a horizontal list.
Separator Set a separator between fields if the format is a list.
Link Style Set the link style.
Display Show or hide fields in the meta text. Additionally, you can choose from which taxonomy the term list is shown.
Date Format Select a predefined date format or enter a custom format, for example M j, Y (Aug 6, 1999) or m/d/Y (08/06/1999).

Meta field options

Tags Field

Tags fields have additional options to display their content.

Option Description
Separator Set a separator between tags.
Link Show or hide linking tags.
Link Style Set the link style.

Tags field options


Custom Fields

YOOtheme Pro can load custom fields from an Article, Category and User. Joomla allows you to add custom fields and field groups to articles and categories in the Article manager and to users in the User manager. Learn more in the official Joomla custom fields documentation.

Custom fields which contain a single item, like the Text field, are available for mapping together with the default content fields and are grouped under Fields or the field group name.

Custom fields with single item

On the other hand, custom fields with multiple items, like the Checkboxes field, have to be selected under the Multiple Items Source option. They are grouped under Fields or the field group name.

Custom fields with multiple items

Some fields, like the Repeatable field, have an option to allow users to select one or multiple items. Depending on the option, the field will be available for mapping together with the default content fields or has to be selected under the Multiple Items Source option.

Enable multiple items

All Joomla custom fields are supported.

Name Type Description Documentation
Calendar Single Date picker field View
Checkboxes Multiple Checkbox field providing name and value View
Color Single Color picker field View
Editor Single WYSIWYG editor field View
Integer Single/Multiple Select field for integers View
List Single/Multiple Select field providing name and value View
List of Images Single/Multiple Select field for images of a folder View
Media Single Media picker field View
Radio Single Radio field providing name and value View
Repeatable Multiple Repeat a customizable set of fields View
SQL Single/Multiple Select field providing custom queried text and value View
Text Single Input field View
Textarea Single Textarea field View
Url Single Input field for an URL View
User Single User picker field View
Usergroup Single/Multiple Select field for user groups View

YOOtheme Pro has additional support for the following third-party fields.

Name Type Description Documentation
Articles Single/Multiple Select field providing all Article fields. Articles Field

Invalid Sources and Fields

There are cases in which content sources or mapped fields are invalid. For example, templates loaded from the layout library can use content sources or fields which don't exist in the current Joomla site. Or content sources or fields could also be deleted or renamed in Joomla but still be used in the layout.

Here is a list of all cases when a content source or a field is invalid.

  1. A selected page source doesn't exist on the current page.
  2. A selected custom source doesn't exist in the Joomla installation.
  3. A mapped field doesn't exist in the selected content source.
  4. A content source is selected but none of its fields are mapped.

Invalid content sources and fields are highlighted red. To quickly find those cases, the dynamic content status icon is also highlighted red in the YOOtheme builder.

Invalid sources and fields


Dynamic Conditions

Use conditional logic to display an element depending on a field of a chosen content source. Once a content source is selected, its fields are available under Dynamic Condition. Pick a field to which the condition should apply.

Dynamic conditions field

Set a condition, and the element will only be displayed if the condition is met. Some conditions require a value for comparison.

Condition and value

Condition Description
Is empty The content of the field is empty
Is not empty The content of the field is not empty
Is equal to The content of the field is equal to the entered value
Is not equal to The content of the field is not equal to the entered value
Contains The content of the field contains the entered value
Does not contain The content of the field does not contain the entered value
Less than The content of the field is less than the entered value
Greater than The content of the field is greater than the entered value

Learn more about the conditions in the PHP Comparison Operators documentation. Note that the string comparisons are case-sensitive.

YOOtheme Pro Documentation