Tutorial for Conditional Content

There is a Free and a Pro version of Conditional Content.
The parts in this tutorial that only concern the Pro version will be marked with: PRO

Introduction

Conditional Content is a flexible and powerful Joomla! system plugin (that also comes with an editor button plugin).

Want to show some text only to registered users?
Or hide some content in December?
Want to display a message for mobile users?
Or hide an image every Monday?
Want to have a piece of text only visible for people from Europe?

You can do that and a whole lot more with Conditional Content!

With Conditional Content you can restrict or grant access to parts of the content (text, images...) based on a wide selection of conditions (device, user groups, date ranges, languages, menu items and more).

Creating conditions is a easy as placing {show} or {hide} around your desired content.

You can use Conditional Content anywhere in your site, including within articles, modules, or even 3rd party components and template overrides.

How to use it (syntax)

You can restrict or grant access to your desired content by placing either {show} or {hide} plugin tags around it.

Inside the opening tag, enter the desired conditions with a condition="value" syntax, which you might recognise from how html works.

Basic Examples

For example, to show a piece of text only to guests (not logged-in visitors), you can do:

{show accesslevels="Guest"}You are not logged in yet!{/show}

Each condition can also have multiple values, separated with a comma. For example, to hide a piece of text during the weekends:

{hide days="6,7"}Call us now!{/hide}

You can place any type of content between the {show} and {hide} plugin tags. So also rich content and images. And you can place these {show} and {hide} plugin tags right into your WYSIWYG editor.

Alternative Content

Conditional Content also offers the ability to display alternative content when the set conditions are not met. This can be accomplished by either using a {show-else} or {hide-else} tag.

This example displays a message based on whether a visitor is or is not logged-in.

{show accesslevels="Guest"}
You are not logged in yet!
{show-else}
You are logged in now!
{/show}

Multiple Conditions

You can also combine multiple conditions and use them at the same time:

{show accesslevels="Guest" device="mobile"}
This text will only show for not-logged visitors from mobile devices.
{/show}

Editor Button

But the best part, is that you don't really have to learn and remember the code syntax.

To make your life easier and save a lot of time, you can use the handy Conditional Content editor button, which helps you insert all the conditions you need with a simple interface.

You can use this editor button located below the text input area, to place {show} or {hide} tag with the desired conditions into your article (or other editor fields).

When clicking on the Editor Button, you will be presented with three tabs:

Content

Here you can select whether you want the content to be shown or hidden, and enter your custom block of text.

By default, the content field will be a html editor. But you can also make it use your current Joomla Editor. To do so, customize the Editor Button Options in the Conditional Content plugin settings.

Alternative Content

Here you can enter the alternative content to display when the set conditions are not met.

Conditions

Here you are able to assign any of the available conditions in a easy-to-use interface.

Conditions

Conditional Content supports a wide selection of conditions, such as device, user groups, date ranges, languages, menu items and more. These conditions define when or to whom you want to show the content.

By clicking on the Conditional Content editor button, you will be able to insert all the available conditions in a easy-to-use interface, as part of the "Conditions" tab.

If all of the conditions are set to Ignore, the piece of text will show up (when using {show}) or be hidden (when using {hide}) on all pages. As soon as you set one or more of the conditions to Include or Exclude, the piece of text will be limited to the specified conditions.

Matching Method

As mentioned above, you can use and combine any of the conditions. You don't have to just use one.

To control how multiple conditions are applied, there is a Matching Method option. This determines whether all or any conditions need be matched:

  • ALL: Will be published if ALL of below conditions are matched at the same time.
  • ANY: Will be published if ANY (one or more) of below conditions are matched at any time. This will add a matching_method="any" attribute in the plugin tag.

Condition groups where "Ignore" is selected will be ignored.

Note: When setting any or more conditions to Exclude, the Matching Method should be set to ALL. Otherwise, using ANY would result in one Exclude condition to always match and the piece of text to show everywhere else.

Condition Types

Each condition type has three possible states/options.

  • Ignore (default)
  • Include: the content will be shown/hidden in all circumstances that do match that condition.
  • Exclude: the content will be shown/hidden in all circumstances that do not match that condition. This will add a ! after the condition type name in the plugin tag.

By default all conditions are ignored, meaning the condition is not used.
To use an condition, you set the option to Include or Exclude depending on the desired effect.

Below you find all the available conditions, which can either be easily set with the Editor Button, or manually entered in the plugin tags.

Near each option you find the respective attribute and values that can be used in the tag. The manual syntax for the {show} or {hide} tags is the same seen in the above examples of the Tutorial:

{show condition="value1,value2" condition="value1,value2"}...{/show}

Menu Items

In addition to single Menu Items, it's possible to automatically include or exclude all current and future menu items placed under a menu type.

Selection menuitems Select the menu items to assign to.
Values: ID of the menu items

Home Page

Unlike selecting the home page (default) item via the Menu Items, this will only match the real home page, not any URL that has the same Itemid as the home menu item.
This might not work for all 3rd party SEF extensions.

Selection homepage Values: true, false

Date & Time

The date and time conditions use the date/time of your servers, not the ones of the visitors system.

Date
Start Publishing date Enter the date to start publishing
Format: 2019-11-23 16:30
Finish Publishing date Enter the date to end publishing
Format: to 2019-11-30 23:59
Seasons PRO
Selection seasons Select seasons to assign to.
Values: winter, spring, summer, fall (= autumn)
Months PRO
Selection months Select months to assign to.
Values: 1 - 12 (= January - December)
Days of the week PRO
Selection days Select days of the week to assign to.
Values: 1 - 7 (= Monday - Sunday)
Time PRO
Start Publishing time Enter the time to start publishing.
Format: to 16:30
Finish Publishing time Enter the time to end publishing.
Format: to 23:59

Languages

Selection languages Select the languages to assign to.
Format: en-GB

Joomla! Content PRO

This condition is based on what Joomla content page is displayed, including Page Types, Categories and specific Articles.

Page types
Selection contentpagetypes Select on what page types the condition should be active.
Values: archive, article, categories, categoryblog, category, featured, form
Categories
Selection cats Select the categories to assign to.
Values: ID of the categories
Articles
Selection articles Select the articles to assign to.
Values: ID of the articles

If you want to go deeper with Articles-based conditions, you can use another Regular Labs Extension, Articles Anywhere. Articles Anywhere features If Structures, that allows you to check against the value of any article data, attribute, as well as custom fields.

An example of what you would be able to do with Articles Anywhere If Structures:

{article}{if my-custom-field = 5}...{/if}{/article}

Tags PRO

Selection tags Enter the tags to assign to. Use commas to separate the tags.
Format: Fluffy,Cuddly
Match all tags Select to only let the condition pass if all of the selected items are matched. Use a plus to separate the tags.
Format: Fluffy + Cuddly

Access Levels

Selection accesslevels Select the access levels to assign to.
Format: Guest,Registered

User Group Levels

Selection usergrouplevels Enter the user groups to assign to. Use commas to separate the user groups.
Format: Manager,Administrator
Match all usergrouplevels Select to only let the condition pass if all of the selected items are matched. Use a plus to separate the user groups.
Format: Manager + Administrator

Users PRO

Selection users Select the users to assign to.
Values: ID of the users

Components PRO

Selection components Select the components to assign to.
Format: com_content,com_contact

Templates PRO

Selection templates Select the templates to assign to.
Template Format: protostar
Template Style Format: protostar--9 (add --id)

URL PRO

The URL conditions allows control over specific pages or groups of pages, with support for Regular Expressions.

URL matches urls Enter (part of) the URLs to match. Use commas to separate each different match.
Format: my-url/,my-page/
Use Regular Expressions urls_regex URL parts will be matched using regular expressions. So make sure the string uses valid regex syntax.
Values: true, false

Devices

Selection devices Select the devices to assign to. Keep in mind that device detection is not always 100% accurate. Users can setup their device to mimic other devices.
Values: desktop, tablet, mobile

Operating Systems PRO

Selection os Select the operating systems to assign to. Keep in mind that operating system detection is not always 100% accurate. Users can setup their browser to mimic other operating systems.
Values: Names of operating systems

Browsers PRO

Browsers browsers Select the browsers to assign to. Keep in mind that browser detection is not always 100% accurate. Users can setup their browser to mimic other browsers.
Values: Names of browsers

IP Addresses PRO

IP Addresses / Ranges ips A comma seperated list of IP addresses and IP ranges.
Format: 127.0.0.1,128.0-128.1,129

Geolocating PRO

Geolocating is not always 100% accurate. The geolocation is based on the IP address of the visitor. Not all IP addresses are fixed or known.
To be able to use this condition, you need to install the Regular Labs GeoIP library.

Continents continents Select the continents to assign to.
Values: Names of continents
Countries countries Select the countries to assign to.
Values: Names of countries
Regions / States regions Select the regions / states to assign to.
Values: Region codes
Postal Codes postalcodes This can only be used for a limited number of countries and IP addresses.
Format: A comma separated list of postal codes (12345) or postal code ranges (12300-12500).

Custom PHP PRO

This gives you the opportunity to assign to just about anything you can think of. You just need to know what PHP code you should use.

With PHP you can call on all data/information available in the variables, url, database, etc. And then do your checks on this data. You can tell the control the display by ending the PHP code with a return true or false based on your checks.

For examples and ready-to-use PHP scripts, check out the PHP Assignment Guide.

Custom PHP php Enter a piece of PHP code to evaluate. The code must return the value true or false.

Format:

return ( $user->name == 'Peter van Westen' );

If you need to go deeper with more specific conditions options, you can use another Regular Labs Extension, Advanced Module Manager. AMM gives you the ability to assign modules with several additional options for each condition type. This means you could enter your custom text inside a module, and then include the module in your content, and your custom conditions set with Advanced Module Manager will be respected.

What about caching?

Depending on how you set up caching in your Joomla site, the content placed inside the {show} or {hide} tags might get cached too.
This may have an undesired affect on what content is shown, depending on what conditions you use.

Joomla generally caches pages on a page level (url) and language level. So in most cases it should not matter when that content is cached, Conditional Content will still output what you expect.

For certain conditions however, for example Date & Time related conditions, or Devices, cache might get in the way, so you might want to change some stuff in how that content is cached.

For example, when using the Conditional Content tags in a module, you could switch off the caching for that module.Or with some 3rd party caching extensions you can also switch off caching for certain scenarios.

Strip surrounding HTML tags

When inserting Conditional Content, the content editor might add surrounding html tags (such as div, p, span) to the {show} or {hide} plugin tags:

<p>{show usergrouplevels="registered"}</p>
<div>Your content</div>
<p>{/show}</p>

This can cause unwanted generated output with the surrounding html tags, and therefore adding extra paragraphs or divs before and after your content.

You can prevent this behaviour from happening by enabling the general Strip surrounding tags option in the Conditional Content plugin settings, which will always remove html tags surrounding the {show} or {hide} plugin tags.

Or you can individually override this setting in the{show} or {hide} plugin tags by adding a trim="..." attribute with either a true (on) or false (off) value.

{show usergrouplevels="registered" trim="true"}...{/show}

Settings

Conditional Content has some options, giving you control over how it works and behaves. Here is the full list of the options you can find in the Conditional Content system plugin settings:

Editor Button Options

Button Text This text will be shown in the Editor Button.
Enable in frontend If enabled, it will also be available in the frontend.
Use Editors Enable to use the Joomla editor for the content and alternative content fields in the editor button popup.

Tag Syntax

Show Tag The word to be used in the tags.

Note: If you change this, all existing tags will not work anymore.
Hide Tag The word to be used in the tags.

Note: If you change this, all existing tags will not work anymore.
Tag Characters The surrounding characters of the tag syntax.

Note: If you change this, all existing tags will not work anymore.
Options: {...}, [...], {{...}}, [[...]], [:...:], [%...%]

Advanced Options

Strip Surrounding Tags Select to always remove html tags (div, p, span) surrounding the plugin tag. If switched off, the plugin will try to remove tags that break the html structure (like p inside p tags).
Disable on Components Select in which frontend components NOT to enable the use of this extension.
Remove in Disabled Components If selected, the plugin syntax will get removed from the component. If not, the original plugins syntax will remain intact.
Enable in administrator If enabled, the plugin will also work in the administrator side of the website.

Normally you will not need this. And it can cause unwanted effects, like slowing down the administrator and the plugin tags being handled in areas you don't want it.
Place HTML comments By default HTML comments are placed around the output of this extension.
These comments can help you troubleshoot when you don't get the output you expect.
If you prefer to not have these comments in your HTML output, turn this option off.

Installation

You can either install Conditional Content by using the core extension manager available in the Joomla! Administrator Control Panel, or by using the powerful Regular Labs Extension Manager.

Note: When updating Conditional Content, you do not need to uninstall it first. The package will update all the files automatically.

Keep in mind that when you update to a major new version (or uninstall first), you might lose some configuration settings.

Regular Labs Extension Manager

It is very easy to install/update any Regular Labs Extension using the Regular Labs Extension Manager.

Please see the Tutorial for the Regular Labs Extension Manager for more detailed information...

Joomla! Extension Manager

To install via the Joomla! Extension Manager, just follow these steps:

  1. Log into your Joomla administrator;
  2. In the menu, choose: Extensions >> Extensions;
  3. Choose the tab: Install from Web (or enable it if you haven't done so yet);
  4. Select the search field and enter Conditional Content and hit enter;
  5. Click on the Conditional Content listing;
  6. Click on Install;
  7. Click on Install to confirm.
Joomla! Installer - Install from Web

Or if you need to install the Pro version or cannot install via the 'Install via Web' method for some reason:

  1. Download the extension install file (.zip);
  2. Log into your Joomla administrator;
  3. In the menu, choose: Extensions >> Extensions;
  4. Choose the tab: Upload Package File;
  5. Click on the Choose File button and select the extension zip;
  6. Click on Upload & Install.
Joomla! Installer - Upload Package File

If you have problems installing Conditional Content, please try the manual installation process as described here: docs.joomla.org/Installing_an_extension