Description of the module configuration form for MetaMod.
- This title will appear at the top of the module position, if the “Show Title” option is chosen (next). In most cases you are likely to want this to be turned OFF, because you will want the titles of the included modules to display, rather than the overall “MetaMod” title.
- Show Title
- No/Yes: (standard module control) In many cases you won’t want this turned on, because the included modules will have their own titles.
- (standard module control) Don’t forget to turn this on!
- (standard module control) The module position the modules will be loaded into.
- (standard module control)
- Access Level
- (standard module control)
- Menu Assignment section:
- (standard module control)
- Module Cache
- Use system settings / Disable: If your system cache is turned on, then the results of the MetaMod will also be cached unless you use this control. This control allows you to opt out of caching for this module, meaning that the “rules” will be re-run on every page view.
- Cache time
- If caching is enabled, this controls the number of seconds that the cache will be held for before being refreshed.
- Off/On/Advanced: If you are having trouble working out why your modules are not being included, or what the values of $id, $Itemid etc are, then turn this on. You’ll see a summary of information in the module position, about all these parameters, and which modules it decided to include in the end.
“Advanced” mode will display some example PHP code in the front-end of your site, which can be used in MetaMod configuration to precisely identify the page that you are on. See the Page Identification page for more information about this feature.
- Module Class Suffix
- a suffix which will be added to the CSS class name of the
orelements surrounding the entire module and any other modules it contains. MetaMod Pro note: with MetaMod Pro there is no extra HTML surrounding the “included” modules, so this control has no effect on them.
- Start and End date/time (freeform)
- These fields are extremely versatile. They control when MetaMod will start/stop including other modules. If you specify a date, the modules will start or stop at that exact point in time. If you include only a time of day, then the modules will start or stop at that time every day.
If this is not versatile enough, then don’t use the start/stop date/time boxes, and use the PHP box instead (find recipes on the Recipes page).
- 10 Oct 2007
- 1 January 2008
- 10 Oct 2007 9:30
- 10 Oct 2007 9:30PM
- 01:00 [starts/ends at 1AM every day]
- 22:03:59 [starts/ends at 22:03:59 every day]
- Start date/time (freeform)
- The main title of the MetaMod module is not controlled by the Start and End date/time – if you have “Show title” turned on then the title will always show, regardless of the Start and End date/time settings. Enter a date, time or both, for when the module will start to include other modules.
- End date/time (freeform)
- Note: if you enter a date without a time, then the time period will end at the BEGINNING (midnight) of the day that you specify. Therefore to allow a module to show up until midnight on the 2nd of October, enter “3 October” as the end date.
- Time Zone:
- Choose either “Default Joomla” to use the default Joomla time zone setting, or choose a new time zone from the drop-down list. The advantage of setting a time zone here is that time zones in this list obey Daylight Savings — the standard Joomla time zone does not. This matters if you are setting particular times of the day to display modules, because otherwise Daylight Savings time can put your timings out by an hour during some times of the year.
- Show Quick Module(s) to:
- All users / Logged in users only / Non-logged in users only
- GeoIP Check
- Checks to see if the GeoIP.dat file is installed on your system. It looks for a folder in your Joomla installation called “geoip” and a file in it called “GeoIP.dat”. Because MaxMind updates their database monthly, you need to get a fresh file from their website, and it’s not included in this module. See GeoLite Country page, or download latest database. If Chameleon or ChameleonLite is installed, you can use the auto-downloader in Chameleon to download the data files, and these will be used by MetaMod.
- Enable GeoIP/GeoCity
- Disabled/GeoIP Country/GeoLite City (free)/GeoCity (commercial): Because looking up the country code of the web visitor takes a little time, MetaMod won’t do it unless you say you want it. Select your database here if you want to use the “Only these countries” or “Exclude these countries” fields below, or if you want to use the variables $fromCountryId or $fromCountryName in the PHP block. You will also need to download the relevant database from Maxmind and install them on your server.
- Only these countries
- Enter a comma-separated list of 2-letter country codes. Only visitors from these countries will see the modules that you specify below. Don’t forget to turn on the lookup, above.
- Exclude these countries
- Enter a comma-separated list of 2-letter country codes. If a visitor comes from one of these countries, the modules will not be shown. Don’t forget to turn on the lookup, above.
- $language handling
- Choose how the PHP variable “$language” will be determined. Choose from: “Browser’s preferred language”, “Most preferred language from supplied list” or “Joomla front-end language”.
- Preferred list of languages
- Comma-separated list of preferred language codes, lower case. If “Most preferred language from supplied list” is specified above, then $language will contain the language from this list that appears highest in the browser’s preferred language settings. E.g. a browser may be set up for “ar,fr”. If you only test for the first language in the list, but have no content to display for Arabic (ar), you might miss the opportunity to present your French (fr) content. So by specifying a list of the languages you do cater for here, MetaMod will return the one that ranks highest for a particular visitor. If ‘Strict language comparison’ is turned off, then specifying a major language here (e.g. fr) will match any variants of that in the user’s browser, such as fr-fr, fr-ch, fr-be or plain fr. EXAMPLE: de,fr-fr,fr-be,cs
- Strict language comparison
- For use with “Most preferred language from supplied list” above. If turned off, then specifying a language without a region here (e.g. plain “fr” and not “fr-be” or “fr-ch”) will match any variants of that in the user’s browser, such as fr-fr, fr-ch, fr-be or plain fr.
- Style for included modules
- Specify how the included modules will appear. These are standard Joomla options for what will surround the contents of a module. All included modules for this MetaMod module will share this parameter. If you want to use a different parameter for one of the included modules, then make another MetaMod module to wrap the target module, and include the second MetaMod inside the first one.
- In a table (default) – usestag for title
- Multiple divs (for rounded corners) – uses
tag for title
- XHTML – in div, uses
tag for title
- Naked – no div, no title
MetaMod Pro note: with MetaMod Pro there is no extra HTML surrounding the “included” modules, so this control has no effect on them.
- Style override for included modules
- The standard Joomla styles for included modules can be chosen from the previous dropdown, but what happens if your template defines custom module styles? This parameter is your chance to specify exactly which style the included module(s) should use. e.g. for the YooTheme “Evolution” template, many of the module positions use a style called “yoo”. So you would enter than in this box. MetaMod Pro note: with MetaMod Pro there is no extra HTML surrounding the “included” modules, so this control has no effect on them.
- Quick module id or position include
- Here’s where you can put in a module id, module position, or comma-separated list of ids and/or positions. The modules that you specify will be displayed inside this MetaMod module in the order that you give, subject to the date and country constraints that you specify above. If you have some PHP rules below that return more module numbers, they will be displayed AFTER any modules specified here.
- Auto-enable included modules?
- This handy control allows MetaMod to include even modules that are “disabled”. The most common use for this is so that you can set your “target” module to “disabled”, but still let the MetaMod include the module. This helps to prevent the target module from showing up twice on the page (once because of being enabled, and once through the MetaMod including it). There are times when you may not want to use this – e.g. if you are including an entire module position, you may want the ability to toggle various modules on and off by enabling/disabling them. In this case, you can set the control to “none” or “modules specified by id”, so that modules inside included positions won’t get auto-enabled.
- Here’s where you can get creative with your modules, and create rules. At the end of each rule, return the id number of the module that you want to display. If you want to display more than one, return an array or a comma-separated string of id numbers.
You get access to a number of PHP variables which you can use in addition to $_SERVER, $_GET, $_POST and $_COOKIE variables:
- $fromCountryId – the upper-case 2-letter ISO country code (e.g. GB, US, NL, DE). View the official ISO 3166 country code list.
- $fromCountryName – the official ISO country name, mixed-case. (e.g. United Kingdom, United States, Netherlands, Germany)
- $geoip- if you have enabled GeoLiteCity or GeoIPCity, a record containing the following items:
- $geoip->country_name - full country name, as above
- $geoip->country_code - 2-letter ISO country code, as above
- $geoip->country_code3 - 3-letter ISO country code (e.g. GBR, USA, FRA, DEU)
- $geoip->region - 2-letter code. For US/Canada, ISO-3166-2 code for the state/province name, e.g. “GA” (Georgia, USA). Outside of the US and Canada, FIPS 10-4 code., e.g. “M9” (Staffordshire, UK)
- $geoip->city - full city name
- $geoip->postal_code - For US, Zipcodes, for Canada, postal codes. Available for about 56% of US GeoIP Records. More info.
- $geoip->dma_code - 3-digit DMA/Metro code (US only)
- $geoip->area_code - 3-digit telephone prefix (US Only)
- $id – the id of the item in the main component on the page (e.g. “24:content-layouts”)
- $option – the option (i.e. the component name) of the main component on the page (e.g. com_content)
- $view – the “view” of the main component on the page (e.g. “article”, “category”, “categories” etc.)
- $Itemid – the Itemid of the main component on the page (identifies which menu item was clicked)
- $db – in case you want to query the database for anything (for experts!)
- $user– contains information about the logged-in user:
- $user->usertype ("" or "Public Frontend"=not logged in [test for both], otherwise "Registered", "Author", "Editor", "Publisher", "Manager", "Administrator" or "Super Administrator")
- $user->registerDate e.g. “2007-05-17 01:25:52”
- $user->lastvisitDate e.g. “2007-11-02 18:51:29”
- $language - a lower-case language code. By default this returns the default language of the web visitor’s browser, but can alternatively return the language code of the Joomla front-end, or intelligently find the best match between a user’s browser languages and a list of languages that you provide. Typical language strings returned include: en, en-gb, en-us, fr, de and many others.
- $language_code - the first part of $language, if it contains both a language code and a region code. e.g. if $language is "en-gb" then $language_code is "en".
- $language_region - the region code of $language, if it contains one. e.g. if $language is "en-gb" then $language_region is "gb".
Available PHP Constants (from MetaMod 1.5h onwards)
These constants can be used in your rules just like variables, except they don't need a "$" in front of them.
- Time and Date related. These constants are calculated according to the time zone set in the time zone drop-down in MetaMod. If you choose your nearest region/city with the time zone drop-down, then the times and dates also respect daylight savings time.
- MM_DAY_OF_WEEK – 0=Sunday, 6=Saturday
- MM_DAY_OF_MONTH – 1 to 31
- MM_MONTH – 1-12
- MM_YEAR – YYYY format
- MM_HOUR – 0-23
- MM_MINUTE – 0-59
- MM_SECOND – 0-59
- MM_TIME – this is presented as a 24-hour clock number, including seconds, but without “:” characters. e.g. 10:11:59 AM = “101159”, 15:29 (3:29 PM) = “152900”. This makes it easy to show a module between two times of day, e.g. if (MM_TIME >= 101159 && MM_TIME <= 152900) return 101;
- MM_DATE – this is presented as a YYYYMMDD number e.g. 25th Dec 2008 = 20081225. This makes it easy to show a module between two dates, e.g. between 1st and 24th May 2009 (inclusive): if (MM_DATE >= 20090501 && MM_DATE <= 20090524) return 101;
- User/group related. These make it as easy as possible to make rules based on what group a logged-in user is a member of.
- MM_LOGGED_IN – true if the user is logged in, no matter what group thay are part of
- MM_NOT_LOGGED_IN – true if the user is not logged in
- MM_USER_REGISTERED / MM_USER_NOT_REGISTERED – true if the user is logged in and a member (or NOT) of the “Registered” group
- MM_USER_AUTHOR / MM_USER_NOT_AUTHOR – true if the user is logged in and a member (or NOT) of the “Author” group
- MM_USER_EDITOR / MM_USER_NOT_EDITOR – true if the user is logged in and a member (or NOT) of the “Editor” group
- MM_USER_PUBLISHER / MM_USER_NOT_PUBLISHER – true if the user is logged in and a member (or NOT) of the “Publisher” group
- MM_USER_MANAGER / MM_USER_NOT_MANAGER – true if the user is logged in and a member (or NOT) of the “Manager” group
- MM_USER_ADMINISTRATOR / MM_USER_NOT_ADMINISTRATOR – true if the user is logged in and a member (or NOT) of the “Administrator” group
- MM_USER_SUPER_ADMINISTRATOR / MM_USER_NOT_SUPER_ADMINISTRATOR – true if the user is logged in and a member (or NOT) of the “Super Administrator ” group
- For examples see the recipes section.