joomla:header_image:documentation:custom_id_rules

Custom ID Rules

(Commercial Unlimited License only)

Custom ID's allows any URL GET, POST or Cookie Value used by a third party extension to get assigned to an ID Marker used in the File Naming Convention.

Please refrain from using the ID Markers already being used by Header Image for the Content Contexts. In particular these:
  • id … carries the ID of the current content item
  • Itemid … carries the Menu Item ID of the current content item

Custom ID rules are part of the Section Module Rules of the modules settings:

The Syntax for Custom ID Rules is a simple assignment of <value>=<marker>. One Custom ID Rule per line, multiple rules are allowed.

ID Rule Syntax
<value>=<marker>
 
<value> ... is the URL GET, POST or Cookie Value used by the third party extension
<marker> ... is the Marker used for identifying that value in the filenames



Custom Rules for ID's as numbers

Most Components use Integer Numbers for their ID's. For those number based ID's the notation is to assign a <value> & <marker> pair for the ID's that shall get integrated into the file selection:

Example
extID=ex
mapID=map

With above example the following example URL of

index.php?option=com_extension&task=view&Itemid=132&extID=3

assigns the URL parameter extID to the Filename Marker ID ex, such that a file named himg_ex3.png will get scored as related file for that page.

Custom Rules for ID's as text

Some Components use Text Names for their ID's. For those use this notation to get those integrated into the file selection:

Example
chronoformname=#

Using the # will use the Text Value and selectes a file in case that text is found in it.

With above example the following example URL of

index.php?option=com_chronocontact&chronoformname=someform&Itemid=132

assigns the URL parameter chronoformname to the Filename, such that a file named himg_someform.png will get scored as related file for that page.

See also the Chronoforms Example below.

To check your Custom ID Rules, use the Debug Mode to see which values Header Image will retrieve as Custom ID's. All relations are Case-Sensitive.



Custom ID from a PHP file

Sometimes a ID is not available from the Page Request, and some PHP code would be necessary to query the database to retrieve a certain ID to be used with Header Image. This is possible by using PHP file to create a Custom ID:

Custom ID Rule with a PHP script
templates/php/sobi2catid.php=scat


Above Custom ID Rule defines the PHP Script templates/php/sobi2catid.php to be executed in order to determine a value for the scat marker:

|h templates/php/sobi2catid.php
<?
/*
 * Requires JOOMLA 1.5.x
*/
(defined( '_VALID_MOS' ) || defined( '_JEXEC' )) or die( 'Direct Access to this location is not allowed.' );
 
	/*
	 * For SOBI2
	 * ---------
	 * This reads the SOBI2 Category ID for any open SOBI2 Entry
	 */
 
	$value='0';
	$db = &JFactory::getDBO();
 
	/*
	 * Get the SOBI2 Category ID if in request and COM_SOBI2 is active
	 */
	if (JRequest::getVar('option', '')=='com_sobi2') {
 
		/*
		 * This may give some ID ambiquous with Content Category ID
		 */
		$value = JRequest::getInt('catid', 0);
 
		/*
		 * We want to refine the SOBI2 Category ID:
		 * Get the SOBI2 Content ID from the request and get Category ID from content if one is requested
		 */
		$sobi2_id = JRequest::getInt('sobi2Id', 0);
		if ($sobi2_id>0) {
 
		  	// Load the SOBI2 Entry from the database
		  	$db->setQuery( "SELECT * FROM #__sobi2_item WHERE itemid=".$sobi2_id );
		  	$row = $db->loadObject();
		  	if ($row!==null) {
		  		// Determine the SOBI2 Category ID
		  		$param = new JParameter($row->params);
		  		$value = $param->get('def_cid', 0);
		  	}
 
			// Alternatively load the Category-Item relationships
		  	$db->setQuery( "SELECT * FROM #__sobi2_cat_items_relations WHERE itemid=".$sobi2_id );
		  	$rows = $db->loadObjectList();
		  	if ($rows!==null) {
		  		// Determine the SOBI2 Category ID
		  		$value = Array();
		  		foreach ($rows as $row) {
		  			$value[] = $row->catid;
		  		}
		  	}
 
		}
 
	}
 
	/*
	 * Return the value to the extension
	 * CustomID returned may be INTEGER value or ARRAY() of INTEGER values 
	 */
	return $value;
 
?>
Any script file used with this is executed using the PHP eval_() function, which may proof difficult when debugging the PHP script file used for the Custom ID rule. When having the requirement to do this, set the setting for Debug Mode to On (show PHP errors).



Here are now some Custom ID rules for specific third party extensions:

GMaps Extension

Homepage: http://gmaps.firestorm-technologies.com

To assign the MapID to the Marker map use:

Custom ID Rule
mapId=map
When being used with Header Image

This maps the mapId parameter to the map ID of any file used with Header Image.

Example Filenames
himg_map10.png
himg_map12.png



SOBI2 Extension

Homepage: http://www.sigsiu.net

To assign the CatID (Category ID) to the Marker scat use:

Custom ID Rule
catid=scat


This maps the catid parameter whenever used to the scat ID. Please be aware that this may create Category ID's ambiquous with the Content Category ID.

Alternatively you may also use a script based Custom ID Rule for SOBI2 to make the results more accurate:

Custom ID Rule with script
templates/sobi2catid.php=scat


Use the script shown in Custom ID from a PHP file above to determine the SOBI2 Category ID also for its content items, place it into the templates folder and name it sobi2catid.php. You may also choose a different location for the file, if so adapt the path and filename in the Custom ID rule accordingly.

When being used with Context Module

The Version for Joomla 1.5 of the Commercial Unlimited License has some examples for Custom ID scripts included in the extensions directory modules/mod_contextmodule_ce/plugins, you may use these also:

Determines SOBI Category ID on either current Category View or Article View
modules/mod_contextmodule_ce/plugins/sobi2.php=scat
Determines SOBI Category ID on current Category View only
modules/mod_contextmodule_ce/plugins/sobi2catid.php=sccat
Determines SOBI Category ID on current Article View only
modules/mod_contextmodule_ce/plugins/sobi2article.php=sacat


When wanting to have a accurate Category ID for both the Category View and the Article View, you need to use separate rules for sccat and sacat, as any other approach might render ambiquous results:

Context Rule for SOBI2 with accurate SOBI2 Categories for Category View and Article View
sccat[4]=18
sacat[4]=18


This above example uses Module ID 18 with the SOBI2 Category of 4 when detected in the SOBI Category View (sccat) or the SOBI Article View (sacat).

When being used with Header Image

To narrow down the Cateogry ID from other catid parameters used by other extensions, use the Component Filter setting.

The Version for Joomla 1.5 of the Commercial Unlimited License has some examples for Custom ID scripts included in the extensions directory modules/mod_headerimage_ce/plugins, you may use these also:

Determines SOBI Category ID on either current Category View or Article View
modules/mod_headerimage_ce/plugins/sobi2.php=scat
Determines SOBI Category ID on current Category View only
modules/mod_headerimage_ce/plugins/sobi2catid.php=sccat
Determines SOBI Category ID on current Article View only
modules/mod_headerimage_ce/plugins/sobi2article.php=sacat


Example Filenames
Without "Component Filter":
himg_scat10.png
himg_scat12.png
 
With "Component Filter" as "Suffix to Filename":
himg_com_sobi2_scat10.png
himg_com_sobi2_scat12.png
 
With "Component Filter" as "Image Subfolder":
com_sobi2/himg_scat10.png
com_sobi2_himg_scat12.png



ChronoForms

Homepage: http://www.chronoengine.com

To use the current Form Name for identification, use:

Custom ID Rule
chronoformname=#


When being used with Header Image

This will tell Header Image to look for the Form Name assigned to the chronoformname variable in the Filenames.

Example Filenames
himg_contactdemo_s2.png
himg_someotherform_pi3.png
 
With "Component Filter" as "Image Subfolder":
com_chronocontact/himg_contactdemo.png
com_chronocontact/himg_someotherform.png



DocMan

Homepage: http://www.docman.com

To use the current DocMan Category for identification, use:

Custom ID Rule
gid=dcat


The ID's for the DocMan Categories are visible in the Category Overview of DocMan.

When being used with Context Module

Use dcat in your Context Rules.

When being used with Header Image

This will tell Header Image to use the DocMan Category assigned to the dcat marker in the Filenames.

Example Filenames
himg_dcat23.png
himg_dcat33.png
 
With "Component Filter" as "Image Subfolder":
com_docman/himg_dcat23.png
com_docman/himg_dcat33.png