Working with XML parameters

The elxisParameters class allows you to create HTML form elements of many different types by declaring these elements in an XML file. Elxis will parse this file and automatically generate the HTML output. Additionally elxisParameters may also handle the values of a raw parameters string stored in database or else.

Parsing XML files

You can parse an elxis extension's installation XML file (for example content.xml) or a custom XML file (for example content.category.xml). In case of parsing an exntesion installation file the XML file should follow the elxis guidelines for such a file. The general format of this file is as shown below.

<package type="component">
    <params>
        ...
    </params>
</package>

In case of parsing a custom XML file the general format is shown below (the component attribute is optional.).

<elxisparameters type="component" component="com_xxx">
	<params>
	   ...
	</params>
</elxisparameters>

Example 1: Render an XML file

Example 2: Get supplied parameters values from a raw string

• get method returns the value of a parameter. If the parameter is not set returns as output the second argument of the function.
• getML Same as get but for multilingual elements. Returns the value of the parameter in the current language, if a translation is available, else returns the value of the parameter in the default language using the method get internally.
• set method sets the value of a parameter to second argument of the function.
• def method returns the value of a parameter. If the parameter is not set then it sets that parameter with value the second argument of the function and also returns that value as output.
• A raw parameters string is a string of parameters name/value pairs separated by Unix style new lines (year=2012\nmonth=11\ndate=17).

Parameter groups

Parameters can be split into groups. It is a good practice to group similar parameters to groups. A group starts with the <params> tag and ends with a </params> tag. In the final HTML output Elxis will generate a table for each parameters group.

Each params group can have the following optional attributes.

• group Sets a title for the params group. You can also use language strings for multilingual titles. If group is set then the final generated table will have a title and the group will be able to be collapsed/expanded automatically by clicking on that title.
• groupid An integer to be used as id for the params group. Tip: needed only if you want to add show/hide groups functionality.
• collapsed Whether the group will be displayed by default collapsed or expanded.

Imporant: The value of groupid must be unique and greater than 999!

<params group="Layout" groupid="1001" collapsed="0">
	<param />
	<param />
</params>
<params group="Advanced settings" groupid="1002" collapsed="1">
	<param />
	<param />
</params>

If you want to trigger the visibility of a parameters group from an other element then you need to set a groupid for that group. You can do so by using the groupid attribute. On the example below parameter showgroup options triggers the visibility of the parameter's group with groupid 1000.

<params>
	<param type="radio" name="showgroup" default="0" label="SHOW" description="">
		<option value="0" hide="1000">HIDE</option>
		<option value="1" show="1000">SHOW</option>
	</param>
</params>
<params groupid="1000" collapsed="1">
	<param />
	<param />
</params>

XML parameter types

Elxis supports a number of XML parameter types. By using the correct parameter type each time you make the administrator's life easier.

text

Generates an input text box.

<param type="text" name="myaddress" default="" label="Address" description="" />

• Optional attribute dir (values: ltr or rtl). If dir = rtl then the text direction is set to rtl only when the current language dir is also rtl.
• Optional attribute size (value: integer, text field length).
• Optional attribute maxlength (value: integer, maximum length of characters).
• Optional attribute multilingual (value: 0 or 1). If multilingual = 1 then the text element becomes multilingual and the user is able to apply different values for each language.

The multi-language instances for a parameter get saved using the following format: {name}_ml{language}
So if name = "myaddress" the instance for the French (fr) language will be saved as myaddress_mlfr
If the element has both dir="rtl" and multilingual="1" then the text direction will switch automatically to rtl for RTL languages and to ltr for the LTR ones.

list

Generates a drop down select box.

<param type="list" name="country" default="FR" label="COUNTRY" dir="rtl" description="">
	<option value="FR" show="1001" hide="1002,1003">FRANCE</option>
	<option value="DE" show="1002" hide="1001,1003">GERMANY</option>
	<option value="GR" show="1003" hide="1001,1002">GREECE</option>
</param>

Optional attributes for select options:

• show triggers the display of a parameter(s) group(s) to ON when selected.
• hide triggers the display of a parameter(s) group(s) to OFF when selected.
• disabled makes an option not selectable (values: 0, 1).

previewlist

Generates a drop down select box with the ability to display a preview image for each option.

<param type="previewlist" name="myweather" default="" label="Weather" dir="rtl" position="right" width="68" height="68" description="">
	<option value="">SELECT</option>
	<option value="clear" image="components/com_weather/images/weather-clear.png">Sunny day</option>
	<option value="few-clouds" image="components/com_weather/images/weather-few-clouds.png">Few clouds</option>
	<option value="clouds" image="components/com_weather/images/weather-clouds.png">Clouds</option>
	<option value="showers" image="components/com_weather/images/weather-showers.png">Showers</option>
	<option value="storm" image="components/com_weather/images/weather-storm.png">Storm</option>
	<option value="snow" image="components/com_weather/images/weather-snow.png">Snow</option>
</param>

Additional param attributes:

• position Sets the position of the preview image. Options: left, right, top, bottom. Default value: bottom
• width The width of the preview image in pixels. Default valuue: 120
• height The height of the preview image in pixels. Default valuue: 80

Additional option attributes:

• image the relative path to the image file for that option.

folderlist

Generates a drop down select box having options the folder names inside a given directory. The given directory should be the relative path from elxis root.

<param type="folderlist" name="lang" default="" label="Language" directory="language/" description="Select language" />

The directory attribute supports the multisite keyword. You can provide such a keyword to distinguise the directory path based on the current multisite. Note that the keyword will only be triggered on subsites (ELXIS_MULTISITE > 1). Supported keywords: {multisite}, {multisite/}, {/multisite} and {/multisite/}. Note the optional slashes surrounding the multisite keyword.

<param type="folderlist" name="img_folder" default="" label="Images folder" directory="media/images/{multisite/}" description="Select folder" />

In the above example the directory will become:
media/images/ if multisites are disabled or if we are on the mother site
media/images/site2/ if multisites are enabled and we are on sub-site with id 2
media/images/site3/ if multisites are enabled and we are on sub-site with id 3
etc...

imagelist

Generates a drop down select box having options the existing images inside a given directory. The given directory should be the relative path from elxis root. You can optionally display a preview of the images if the position attribute is set.

<param type="imagelist" name="img" default="" label="Image" directory="media/images/" description="" />

If the optional attribute position is set then a preview of the image is also being displayed.

Optional param attributes:

• position When set it triggers the display of a preview image to ON. Sets the position of the preview image. Options: left, right, top, bottom. If position is left or right then this value is reversed automatically by Elxis on RTL languages. Default value: bottom.
• width The width of the preview image in pixels. Default valuue: 120
• height The height of the preview image in pixels. Default valuue: 80

<param type="imagelist" name="img" default="" label="Image" position="bottom" width="100" height="80" directory="media/images/" description="" />

Parameter type imagelist support the multisite keyword for the directory attribute. See folderlist for more.

radio

Generates a group of radio boxes. Optionally it can toggle visibility of other parameter groups (attributes show and hide).

<param type="radio" name="cache" default="1" label="CACHE" description="ENABLE_CACHE_D">
	<option value="0" show="1000" hide="1001">NO</option>
	<option value="1" show="1001" hide="1000">YES</option>
</param>
<params groupid="1000" collapsed="1">
    ...
</params>
<params groupid="1001" collapsed="0">
    ...
</params>

textarea

Generates a textarea box. Optional attributes: cols, rows and dir.

<param type="textarea" name="txt" default="" cols="30" rows="5" dir="rtl" label="Comments" description="" />

category

Generates a category selection drop down list. Optional attributes: dir.

<param type="category" name="mycat" default="" dir="rtl" label="Category" description="Select category" />

country

Generates a country selection drop down list.

<param type="country" name="mycountry" default="" label="Country" description="" />

range

Generates an integer select drop down box. The start and end points are set by the first and last attributes and step sets the increasing or decreasing step between the options values.

<param type="range" name="pickyear" first="2010" last="2030" step="1" default="2012" label="Year" description="" />

If, for example, first=4, last=12 and step=2 the following options will be generated: 4, 6, 8, 10, 12
If the first option is greater than the last option then the range will be reversed meaning that the options values will be generated in descending order.
Example: first=10, last=-4, step = 2. Generated options: 10, 8, 6, 4, 2, 0, -2, -4

first and last can be negative or positive integrers. step must be always greater than 0. The default step value is 1.

month

Generates a month drop down select box.

<param type="month" name="pickmonth" default="0" short="0" label="Month" description="" />

Optional param attributes

• short Sets the display of abbriviated month names on or off.

If month value is less than 1 (0 for example) then the value is switched to the current month (1, ..., 12)

usergroup

Generates a user group select box. For each option the group's access level (0, ..., 100) is also being displayed in the HTML output.

<param type="usergroup" name="pickgroup" default="0" label="User group" description="" />

username

Generates a user select box.

<param type="username" name="pickuser" default="0" label="User" realname="0" description="" />

Optional param attributes

• realname Sets the display of user's real name or username in the option fields.

This list will display up to 200 users ordered by their firstname or username.

hidden

Generates a hidden field.

<param type="hidden" name="pickhidden" autovalue="{TIMESTAMP}" default="" label="hidden" description="" />

The autovalue attribute can set the value of the element to any of the supported options bellow:
{UID} sets the value of the hidden element to the current user id.
{GID} sets the value of the hidden element to the current user group id.
{DATETIME} sets the value of the hidden element to the current datetime (YYYY-mm-dd HH:ii:ss).
{TIMESTAMP} sets the value of the hidden element to the current UNIX timestamp.
{LANGUAGE} sets the value of the hidden element to the current language identifier (en, el, it, de, etc...)

comment

Displays a comment text. The text can be entered either in default attribute or inside the param tags. You can also use a language string or even CDATA and write HTML.

<param type="comment" name="members_com" default="SELFDISPMEMBLI" label="" description="" />

<param type="comment" name="members_com" default="" label="" description="">SELFDISPMEMBLI</param>

<param type="comment" name="members_com" default="" label="" description="">
    <![CDATA[<span style="color:#ff9900;">hello!</span>]]>
</param>

color

Generates a text field that can triggers a javascript colour picker (HEX values).

<param type="color" name="mycolour" default="" label="Colour" description="Pick colour" />

position

Generates a template position select box.
If the optional attribute none is set to 1 the option to select no position is also available.
If the optional attribute global is set to 1 the option to select a global setting is also available.
Note that the value of the global setting stored after selecting this option is always _global_.

<param type="position" name="mypos" default="left" none="0" global="0" label="Position" description="Select template position" />

collection

Generates a menu collection position select box.

<param type="collection" name="mycol" default="mainmenu" label="Collection" description="Select menu collection" />

file

Generates a file upload box. The file will be uploaded to the specified path with the filename of the parameter name. If the upload path does not exist Elxis will create it automatically. You can not upload files in the Elxis root folder.

<param type="file" name="custom_image" path="modules/mod_opensearch/" filetype="png,jpg,jpeg,gif" maxsize="0" resizewidth="0" resizeheight="0" default="" label="CUSTOM_IMAGE" description="CUSTOM_IMAGE_DESC" />

• name The parameter name and the uploaded file name.
• path the relative path from elxis root to the folder that the file will be uploaded to. Can not be empty or slash.
• filetype comma separated list of allowed extensions (lowercase)
• maxsize The maximum allowed file size in bytes
• resizewidth (for images only) If greater than zero the image will be resized to the given width (you must also set resizeheight).
• resizeheight (for images only) If greater than zero the image will be resized to the given height (you must also set resizewidth).

Elxis allows the upload of the following file types: png, jpg, jpeg, gif, ico, svg, psd, mp3, ogg, avi, mpg, mpeg, wma, wmv, mkv, aac, mp4, flv, swf, doc, docx, pps, ppt, xlsx, xls, csv, odp, odf, ods, rtf, pdf, txt, xsl, xslt, css, xml, zip, rar, tar, gz, bzip2, gzip

Uploading files via parameters is only allowed in Elxis administration area and when the SECURITY_LEVEL configuration option is 0 (normal). If upload fails the parameter will keep its original value.

Parameter type file support the multisite keyword for the path attribute. See folderlist for more.