Tutorial:

Introduction

Conditional Content is a Joomla! system plugin (and editor button plugin).
You can restrict or grant access to content (text, images, etc.) on any page based on a wide selection of conditions.

How to use it (syntax)

You can restrict or grant access to your special content by placing either {show} or {hide} plugin tags around it. Within each opening tag add the desired conditions.

You can place the {show} and {hide} plugin tags right into your WYSIWYG editor. Either type these in manually or use the Conditional Content editor button.

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

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

Or hide 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.

Alternative Content

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

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

Examples

Here are a few examples that demonstrate the flexibility and power of Conditional Content:

User Access

Present guests with message that they are not logged in:

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

Alternative Content

Display message based on whether visitor is not-logged or logged in:

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

Devices

Show mobile version image on mobile devices by rendering "-MobileVersion" image suffix:

<img src=/images/coupon{show device="mobile"}-mobile_version{/show}.jpg

Days of the week

Hide a message on weekends:

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

Conditions

Conditional Content supports a wide selection of conditions.

These conditions define when or to whom you want to show the content.

If you click on the Conditional Content editor button, you will be presented with all the available conditions.

The different conditions have 3 states:

  • Ignore (default)
  • Include
  • Exclude

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

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.

Matching Method

Should all or any conditions be met?

ALL
The content will be shown/hidden if ALL of below conditions are met.

ANY
The content will be shown/hidden if ANY (one or more) of below conditions are met.
Condition groups where 'Ignore' is selected will be ignored.

Menu Items

Menu Items Select the menu items to assign to.

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.

Date & Time

The date and time assignments use the date/time of your servers, not that of the visitors system.

Date

Start Publishing Enter the date to start publishing
Finish Publishing Enter the date to end publishing
Seasons Select seasons to assign to.

Options: winter, spring, summer, fall (= autumn)
Months Select months to assign to.

Options: 1 - 12 (= January - December)
Days of the week Select days of the week to assign to.

Options: 1 - 7 (= Monday - Sunday)

Time

Start Publishing Enter the time to start publishing.
Finish Publishing Enter the time to end publishing.

Users

Access Levels Select the access levels to assign to.
User Group Levels Select the user groups to assign to.
User IDs Enter the user ids to assign to. Use commas to separate ids.

Languages

Languages Select the languages to assign to.

IP Addresses

IP Addresses / Ranges A comma and/or enter seperated list of IP addresses and IP ranges. For instance:
127.0.0.1
128.0-128.1
129

Geolocating

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 assignment, you need to install the Regular Labs GeoIP library.

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

Templates

Templates Select the templates to assign to.

URL

URL matches Enter (part of) the URLs to match.
Use a new line for each different match.

Devices

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.

Options: desktop, tablet, mobile

Operating Systems

Operating Systems 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.

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

Options: Chrome, Firefox, Edge, MSIE, Opera, Safari

Components

Components Select the components to assign to.

Tags

Tags Enter the tags to assign to. Use commas to separate the tags.

Joomla! Content

Page types Select on what page types the assignment should be active.

Options: archive, article, categories, categoryblog, category, featured, form
Categories Select the categories to assign to.
Articles Select the articles to assign to.

Custom PHP

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

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

What about caching?

Depending on how you set up caching in your Joomla setup, the content in which you place the {show} or {hide} tags can be cached too.
This may have an undesired affect on what content is shown. This also depends on what conditions you use.

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

For other conditions, you might want to change some stuff in how the content is cached.
When using the Conditional Content tags in a module, you could for instance switch off the caching for that module.
In some 3rd party caching extensions you can also switch off caching for certain scenarios.

Strip surrounding 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 usergroup="registered"}</p>
<div>Your content</div>
<p>{/show}</p>

This can cause unwanted generated output with the surrounding html Tags rendering 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" setting in the Conditional Content plugin settings, which will always remove html tags surrounding the {show} or {hide} plugin tags.

You can also 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 usergroup="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:

Advanced Options

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: {...}, [...], {{...}}, [[...]], [:...:], [%...%]
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.

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.
FAQs:

The {show} / {hide} tags are not being converted

The Conditional Content plugin is not published

Check if the Conditional Content plugin is published. Go to Extensions >> Plugin manager and search for the system plugin System - Regular Labs - Conditional Content. Then publish it.

There is markup on the {component} tags

If you have copy/pasted code directly into your editor, you might also have copied along hidden HTML tags. So this will also cause the {show} / {hide} tags to break:

{<span>show</span> ...}

Remove the extra styling or other html tags around and in the tags that might cause problems.

How does caching affect Conditional Content?

Depending on how you set up caching in your Joomla setup, the content in which you place the {show} or {hide} tags can be cached too.
This may have an undesired affect on what content is shown. This also depends on what conditions you use.

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

For other conditions, you might want to change some stuff in how the content is cached.
When using the Conditional Content tags in a module, you could for instance switch off the caching for that module.
In some 3rd party caching extensions you can also switch off caching for certain scenarios.

I want to use a condition for something that is not available

If you are using the FREE version, see if the condition is available in the PRO version.

In the PRO version there is also the ability create a condition using custom PHP code. This gives you the opportunity to show/hide your content based on 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 Conditional Content to show/hide the content by ending the PHP code with a return true or false based on your checks.

For examples and ready-to-use PHP scripts, please see The PHP Assignment Guide.

Free vs Pro:

Show content based on conditions
Hide content based on conditions
Editor button::Use the editor button to easiliy select the conditions and generate the required tags.
Conditions
Menu Items
Home Page::Show content based on if the page is the real homepage.
Date Range
Access Levels
User Group Levels
Languages
Devices::Show content based on different device types: Mobile, Tablet, Desktop

Extra fields::You can add extra custom fields to the modules. You can use these fields in your templates module chrome files to add extra functionality. In the Parameters you can set up 5 extra fields with custom labels. You can get the value of these fields in the module chrome functions via php with values extra1 - extra5, like $params->get('extra1');
Conditions
Seasons, Months, Days, Time
Users::Show content based on User ids
Geolocating::Show content based on IP Geolocationg: country, region, state and postal codes
Templates
URLs
Operating Systems
Browsers::Show content based on different Browsers
Components
Tags
Joomla! Content::Show content based on Joomla Page types, Categories and Articles.
Custom PHP::Create your own custom php check. This will make it possible to show/hide content depending on virtually anything you can think of.

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 based on a wide selection of conditions (based on device, user groups, date ranges, languages and menu items to name a few).

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

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

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

Or you can hide a promo graphic on weekends:

{hide days="6,7"}<img src="/images/week-special.jpg">{/hide}