The Rule form: SUCCEED and FAIL actions

The SUCCEED and FAIL Actions forms are identical. The SUCCEED Actions get run when a rule succeeds (i.e. every part of the rule is set to Ignore or returns success/true), while the FAIL Actions get run if any part of the rule returns false.

1. Set Template

This gives a drop-down list of all installed templates. If you want to change template as the result of the rule, select the new template here.

2. Site Default Menu Item

This gives a list of all menu items on the site. Joomla allows you to set one menu item as the “Default” — that is, the menu item that will be used as the front page of your site when there’s no other page requested (e.g. http://www.example.com/). This control allows you to change which page is used as the default

Obviously, if an inner page was being requested on your site, then this has no effect. This control is particularly useful when using different templates for different sub-domains, as it also allows you to set a different default page per sub-domain.

3. Active Menu Item (from v1.10)

The “Active” menu item is the menu item that often gets highlighted in some way on the page, to indicate the “current” page. There are times however when you may want a menu item to be displayed as “Active” which does not actually correspond to the current page. One example of this is if you are making use of an off-screen (hidden) menu item. In this case you may wish for one of the existing main menu items to be highlighted instead.

Just use the drop-down to select which menu item should be displayed as “Active” as a result of the SUCCEED or FAIL action.

This feature depends on the module or template to display the menu correctly. The module or template displaying the menu must use the $menu object provided by Joomla as the data source for the displayed menu. This structure includes a variable indicating the active menu item, and that’s what Chameleon manipulates. If the module or template ignores this and recreates the menu directly from the database, or assumes that the current Itemid should be used as the Active menu item, then this feature has no effect.

The standard mod_mainmenu module for displaying menus in Joomla works correctly with this feature.

4. Unpublish Menus and Menu Items (from v1.7)

This control allows you to selectively unpublish certain menu items as a result of the rule. Hold down the Ctrl key (Windows) or Cmd key (Macintosh) to make multiple selections. If you click on the name of a complete menu (e.g. “Example Pages Menu”) then all items inside that menu will be unpublished for the current page request.

The menu item is not actually unpublished in the database — the effect is simply that it won’t show up on any of the menus during the current page request.

Example 1: hide a “Logout” menu item for anyone who is logged in
Example 2: hide the existing “Home” menu item when you are changing the Default menu item to a different one, perhaps based on sub-domain
Example 3: remove certain Virtuemart menu items when a certain combination of products is in the shopping cart.

Important note: Any SEF URLs that are found in normal content & modules, and pointing to the unpublished menu item may break depending on the SEF extension used. This is because Joomla’s standard SEF looks up the currently published menus in order to create the SEF version of the URL. Obviously, if you have dynamically unpublished the menu item, then Joomla won’t find the information required to create the URL. However, sh404SEF and AceSEF have been tested and do not have this problem.

5-6. Cookies / Session Variables

These controls allow you to set session (short term) or Cookie (long term, up to 10 years) variables based on the results of the rule. There are 4 session variables (A-D) and 4 cookies (A-D). Each variable can be "set" or "unset", or you can unset all of them.

You get Chameleon to set a cookie or session variable in order to remember the result of this rule for next time. Then you can set up another rule to detect this cookie or session variable, and set a template accordingly.

Options:

• ## Ignore ##
• Set Session variable A
• Set Session variable B
• Set Session variable C
• Set Session variable D
• Remove Session variable A
• Remove Session variable B
• Remove Session variable C
• Remove Session variable D
• Remove Session variables A-D
• Set permanent cookie A
• Set permanent cookie B
• Set permanent cookie C
• Set permanent cookie D
• Remove permanent cookie A
• Remove permanent cookie B
• Remove permanent cookie C
• Remove permanent cookie D
• Remove permanent cookies A-D

Example:

• Set a Session variable as a result of detecting a particular URL as a landing page (e.g. http://www.example.com/info?landing=1).
• In the SUCCEED action, set Session variable A, and continue to the next rule.
• In the 2nd rule, detect Session variable A, and in the SUCCEED action set a special template.
• In this way, someone who visits the landing page will see the special template for the rest of their session, until they quit their browser or the Joomla session times out. If you want the new template to be used for that person forever, use a permanent cookie rather than a Session variable.

7. Run PHP

Use this box to run arbitrary PHP code as a result of SUCCESS or FAILURE. See the documentation for the Advanced PHP panel for more information on PHP programming.

8. Execution Flow

If there are more rules in the rule chain what should happen next? Sometimes you want to detect a particular condition then immediately set a template and not process any more rules. Other times you might want to continue processing more rules, in case another rule further down the line decides to set a different template.

Options:

• Stop processing
• Process next rule in chain
• Redirect to another Joomla page, or external URL

If you choose to redirect, you can pick a Joomla page from the drop-down, or specify an external URL.

See the Chameleon Flow Diagram for more information about the execution flow in Chameleon.

Extended Succeed/Fail Actions (from v1.17 for Joomla 1.5 / v2.16 for Joomla 1.7)

9. Page Title

Set the Page Title (the <title> tag in the <head> of the HTML document) here. You can use substitutions such as {title} (the previous title of the page before replacement), {metadescription} and {metakeywords} to use the values of these fields.

10. MetaDescription

Set the Meta Description (the tag in the <head> of the HTML document) here. You can use substitutions such as {title} (the previous title of the page), {metadescription} and {metakeywords} to use the values of these fields.

11. MetaKeywords

Set the Meta Keywords (the tag in the <head> of the HTML document) here. You can use substitutions such as {title} (the previous title of the page), {metadescription} and {metakeywords} to use the values of these fields.

12. HTML Head Include (1 and 2)

This section allows you to add arbitrary CSS, JS, or include JS/CSS files in the <head> of your HTML document. This can be used to make subtle or major changes to the look or functionality of the page without having to use a whole new template. You can include up to two files/code snippets per Succeed action.

Examples:

• Use the CSS feature to change the background image of a page depending on the domain
• Use the Raw HTML feature to insert different Google Analytics codes on different pages of the site
• Use the JS file feature to only add JS libraries to pages that actually need them