General Overview and Guide

Header Image detects the context of any currently shown content, that is it retrieves several ID's the current displayed content item in the frontend may belong to. The current supported ID's are:

• Content-ID
• Section-ID where this content belongs to
• Category-ID where this content belongs to
• Menu-ID (Item-ID) where this content is related to
• Parent Menu-ID of the Menu-ID where this content is related to
• Author-ID of the contents Author

Additionally following 3rd Party Components are supported by this module for additional context relations:

• VirtueMart with Category-ID and Content-ID detection
• Mosets Tree with Category-ID detection

With this content context information, Header Image is able to select image, media or HTML/PHP files and to display those within the Template. The module expects filenames to be according to its standard, otherwise files will get unrecognized.

Preparing any files to get recognized by Header Image means naming those according to the following conventions:

<Filename Prefix>(ci#)(c#)(s#)(i#)(pi#)(a#)(_sequence#).<Extension>

Example:

himg_ci22c2s4.png

Only numbers are accepted and associated to ID Markers, any non-number characters are stripped from the ID's.

The individual naming parts (ID Markers) mean:

That is any prefix to the filename that is identifying every file of the file pool as one possible file assigned to the Header Image modules. Every file that shall get recognized by context requires to carry this prefix. The prefix is your choice and requires definition in the modules settings.

Every Content has a unique ID, that is displayed in the Content Lists of Joomla!. Within the filename this ID number has to be prefixed with a 'ci' to identify the number as Content Item ID.
With the built-in support for the VirtueMart extension, this ID may get overridden by the respective Category ID's when this component is actively displayed on your frontpage.

The Category ID contents may be related to as displayed in the Category Manager of Joomla!. Within the filename this ID number has to be prefixed with a 'c' to identify the number as Category ID.
With the built-in support for the VirtueMart, MTree and DocMan extensions, this ID may get overridden by the respective Category ID's when these components are actively displayed on your frontpage.

The Section ID contents may be related to as displayed in the Section Manager of Joomla!. Within the filename this ID number has to be prefixed with a 's' to identify the number as Section ID.

The Item ID contents may be related in the Menu Structure and as displayed in the Menu Manager of Joomla!. Within the filename this ID number has to be prefixed with a 'i' to identify the number as Item / Menu ID.

The parent Item ID of the contents Item ID as displayed in the Menu Manager of Joomla!. This is the ID of parent menu entry to the contents menu relation. Within the filename this ID number has to be prefixed with a 'pi' to identify the number as Parent Item ID.

The Author ID of the contents author as displayed in the User Manager of Joomla!. Within the filename this ID number has to be prefixed with a 'a' to identify the number as Author ID.

This is a optional sequence number to identify additional files to be files eligible for forming a Slideshow. The sequence number requires prefix of a underscore '_' and at least a 2 digit sequence number and requires to be placed at the end of the filename, suffixed with the files extension. Sequence numbering starts at '1' for the first additional image.

Example:

himg_ci22c2s4_01.png
himg_ci22c2s4_02.png

himg_ci22c2s4.png     ... the static image for the context
himg_ci22c2s4_01.png  ... the first additional slideshow image (the slideshow now consists of 2 images)
himg_ci22c2s4_02.png  ... the second additional slideshow image (the slideshow now consists of 3 images)

The file extension of the image, media or HTML/PHP file. For HTML/PHP files only the extensions .htm, .html, .php are recognized.

• Filename Prefix is required at the beginning
• ci#, c#, s#, i#, pi#, a# may be in any order in its assigned position within the filename
• sequence# is required to be prior to the Extension, prefixed with a underscore '_' to the individual IDs
• Extension is required at the end

All files for use with Header Image require to be in a common folder, located in the tree structure of the current used Joomla! template. This module also allows to select random default files if there is no related context file. Such random default files are to be stored in a separate folder, also in the tree structure of the current used Joomla! template.

This defines the folder where the image files can be found. Never use a leading slash in the default folder path, as it is a path relative to the Joomla! installation directory.

Example:

templates/my_template/images/headers

With this option you can allow localization of the files. Meaning that, dependant on the selected site language, that the files from a localized folder are used. This feature requires Joom-Fish for multi-language sites. The used language codes are according to ISO.

The individual options are:

• No - Do not use any localization
• Yes (4-letter Abbreviations) - Will use 4-letter abbreviations for current selected language
• Yes (2-letter Abbreviations) - Will use 2-letter abbreviations for current selected language

In the folder structure your Header Image files (and the Random Default files) are located, create one additional subfolder for each language code, in the following example we use the 4-letter abbreviations for languages:

Example:

images/headers/         ... folder common to all localized images
images/headers/en_en/   ... folder containing the localized images for English (English)
images/headers/ge_de/   ... folder containing the localized images for German (Deutsch)

Localize your header and random files and store them in the respective localized subfolders, use the same filename. Now the module is able to select localized versions of you header files.

Header Image is able to show the individual context ID's of a single content item when its parameter Debug Mode is set to ON:

Then the individual and current ID's are displayed with its abbreviation and some example filename that would result for the current page. Use this feature to name your files such that the content relation does fit. Further information on paths, their accessability and contents are displayed as well, helping when experiencing any undesired effects.

When using Smart selection of files for the File Selection Mode setting, Header Image is comparing the available files against the current content context by building a score of match.

That score is built such that:

• For each matching Section, Category and other ID one file receives one match point PLUS.
• For each non-matching Section, Category or other ID one file receives one match point MINUS.
• For each matching component name when used with the Use Component Filter one file receives one match point PLUS.
• All match points of one file are accumulated for one file (summed up).
• The file with the highest match point score wins and is selected for the further use.

This approach allows to have specific files for Sections, Categories and files on specific content or author available with Header Image always selecting the nearest match as highest scoring file.

Example:

Our example content has the following ID's: - Section: 1 - Category: 2 - Content-ID: 9

The following files are, according to the selection criterias described until here, selected for:

himg_s1.png      ... For all Content of Section 1 if there is no nearer match
himg_s1c2.png    ... For all Content of Section 1, Category 2 if there is no nearer match
himg_s1c2ci9.png ... For Content ID 9 when shown and assigned to Section 1, Category 2

For some individual contexts of content this pool of files is used such:

• Let's assume we are currently seeing the content with Content-ID 9, so the himg_s1c2ci9.png file is selected as nearest match.
• Let's assume we are currently seeeing a different content with Content-ID 6 assigned to Section 1 and Category 2, the himg_s1c2.png file is selected as nearest match.
• Let's assume we are currently seeing another different content with Content-ID 5 assigned to Section 1 and Category 3, the himg_s1.png file is selected as nearest match.