|
|
(4 intermediate revisions by 4 users not shown) |
Line 1: |
Line 1: |
− | {{review}}
| + | Parameters are one way that data may be stored for a Joomla! Extension. Each parameter consists of two parts: |
− | Parameters are one way in which data may be stored for a Joomla! Extension. Each parameter consists of two parts: a simple text string of the form {NAME} = {VALUE}, in which the parameter value is recorded (usually concatenated into a single string with other parameter values, and stored in a table field); and a form field in the Extension backend, which allows a user to enter the parameter value, and which is defined by an xml <code><param></code> element. | + | * A simple text string of the form {NAME} = {VALUE}, in which the parameter value is recorded. The strings are usually concatenated into a single string with other parameter values and stored in a table field. |
| + | * A form field in the Extension backend that allows a user to enter the parameter value, and which is defined by an XML <code><param></code> element. |
| | | |
− | Joomla! defines 20 different core parameter types, each of which gives a predefined behviour and appearance in the backend. This makes it very easy for developers to implement a range of different form data entry types (text boxes, radio buttons, calendar selectors, etc) with a minimum of effort. This behaviour and appearance is determined by the <code>type</code> attribute of the <code><param></code> element, as detailed below. | + | Joomla! defines 21 core parameter types, each of which gives a predefined behaviour and appearance in the back-end. This makes it very easy for developers to implement a range of form data entry types (text boxes, radio buttons, calendar selectors and so on) with a minimum of effort. This behaviour and appearance is determined by the <code>type</code> attribute of the <code><param></code> element. See [[J1.5:Standard parameter types]] for a complete list and details of each type. |
− | | + | <noinclude>[[Category:Development]][[Category:Parameters]]</noinclude> |
− | === Calendar ===
| |
− | '''Description:''' This provides a text box for entry of a date. If the parameter has a value saved, this value is shown in the text box. If not, the default value (if any) is displayed. An icon next to the text box provides a link to a pop-up calendar, which can also be used to enter the date value.
| |
− | | |
− | '''Screen shot:'''
| |
− | | |
− | [[Image:Params.calendar.jpg]] | |
− | | |
− | '''XML definition:'''
| |
− | <source lang=xml><param name="mycalendar" type="Calendar" default="5-10-2008" label="Select a date" description="" format="%d-%m-%Y" /></source>
| |
− | *Name: The name under which the parameter value is stored.
| |
− | *Default: The default date.
| |
− | *Label: A label displayed next to the text box to indicate the purpose of the parameter.
| |
− | *Description: Text which is shown as a tooltip when a user moves the mouse over the text box.
| |
− | *Format: The date format to be used.
| |
− | | |
− | | |
− | ----
| |
− | | |
− | ===Category===
| |
− | '''Description:''' This provides a drop down list of categories from a given section. If the parameter has a value saved, this value is selected when the page is first loaded. If not, the default value (if any) is selected.
| |
− | | |
− | '''Screen shot:'''
| |
− | | |
− | [[Image:Params.category.jpg]]
| |
− | | |
− | '''XML definition:'''
| |
− | <source lang=xml><param name="mycategory" type="Category" label="Select a category" description="" section="3" />
| |
− | </source>
| |
− | *Name: The name under which the parameter value is stored.
| |
− | *Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
| |
− | *Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
| |
− | *Section: The section ID number from which the categories should be selected. (This can be found in the Section Manager.)
| |
− | | |
− | | |
− | ----
| |
− | | |
− | ===Editors===
| |
− | '''Description:''' This provides a drop down list of the available WYSIWYG editors. If the parameter has a value saved, this value is selected when the page is first loaded. If not, the default value (if any) is selected.
| |
− | | |
− | '''Screen shot:'''
| |
− | | |
− | [[Image:Params.editors.jpg]]
| |
− | | |
− | '''XML definition:'''
| |
− | <source lang=xml><param name="myeditor" type="Editors" default="" label="Select an editor" description="" /></source>
| |
− | *Name: The name under which the parameter value is stored.
| |
− | *Default: The default editor.
| |
− | *Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
| |
− | *Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
| |
− | | |
− | | |
− | ----
| |
− | | |
− | ===File list===
| |
− | '''Description:''' This provides a drop down list of files from a certain directory. If the parameter has a value saved, this value is selected when the page is first loaded. If not, the default value (if any) is selected.
| |
− | | |
− | '''Screen shot:'''
| |
− | | |
− | [[Image:Params.filelist.jpg]]
| |
− | | |
− | '''XML definition:'''
| |
− | <source lang=xml><param name="myfile" type="Filelist" default="" label="Select a file"
| |
− | description="" directory="administrator" filter="" exclude="" stripext="" /></source>
| |
− | *Name: The name under which the parameter value is stored.
| |
− | *Default: The default file name.
| |
− | *Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
| |
− | *Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
| |
− | *Directory: The directory containing the files to be listed.
| |
− | *Filter: A text string which is used to filter the list of files shown. Only those files whose names contain the string will be shown.
| |
− | *Exclude: Similarly, a text string which is used to exclude files from the list.
| |
− | *Stripext: Strip these characters.
| |
− | | |
− | | |
− | ----
| |
− | | |
− | ===Folder list===
| |
− | '''Description:''' This provides a drop down list of folders from a certain directory. If the parameter has a value saved, this value is selected when the page is first loaded. If not, the default value (if any) is selected.
| |
− | | |
− | '''Screen shot:'''
| |
− | | |
− | [[Image:Params.folderlist.jpg]]
| |
− | | |
− | '''XML definition:'''
| |
− | <source lang=xml><param name="my folder" type="Folderlist" default="" label="Select a folder" description=""
| |
− | directory="administrator" filter="" exclude="" stripext="" /></source>
| |
− | *Name: The name under which the parameter value is stored.
| |
− | *Default: The default folder name.
| |
− | *Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
| |
− | *Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
| |
− | *Directory: The directory containing the folders to be listed.
| |
− | *Filter: A text string which is used to filter the list of folders shown. Only those folders whose names contain the string will be shown.
| |
− | *Exclude: Similarly, a text string which is used to exclude folders from the list.
| |
− | *Stripext: Strip these characters.
| |
− | | |
− | | |
− | ----
| |
− | | |
− | ===Help sites===
| |
− | '''Description:''' This provides a drop down list of the help sites in your Joomla! installation. These can be found at administrator\help\helpsites-15.xml. If the parameter has a value saved, this value is selected when the page is first loaded. If not, the default value (if any) is selected.
| |
− | | |
− | '''Screen shot:'''
| |
− | | |
− | [[Image:Params.helpsites.jpg]]
| |
− | | |
− | '''XML definition:'''
| |
− | <source lang=xml><param name="myhelpsite" type="Helpsites" default="" label="Select a help site" description="" /></source>
| |
− | *Name: The name under which the parameter value is stored.
| |
− | *Default: The default help site.
| |
− | *Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
| |
− | *Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
| |
− | | |
− | | |
− | ----
| |
− | | |
− | ===Hidden===
| |
− | '''Description:''' This provides a hidden text box for recording system information at the time the parameters are (last) saved. If the parameter has a value saved, this value is entered in the text box. If not, the default value (if any) is entered.
| |
− | | |
− | '''Screen shot:''' As the name says, this parameter is a hidden one. No output will be displayed.
| |
− | | |
− | '''XML definition:'''
| |
− | <source lang=xml><param name="mysecretvariable" type="Hidden" value="" /></source>
| |
− | *Name: The name under which the parameter value is stored.
| |
− | *Value: The data which needs to be collected.
| |
− | **Two examples:
| |
− | ***The ID of the user: <source lang=xml>value="<?php echo $this->user->get('id'); ?>"</source>
| |
− | ***The date on which the parameters were saved: <source lang=xml>value="<?php echo date( 'j M Y' ); ?>"</source>
| |
− | | |
− | | |
− | ----
| |
− | | |
− | ===Image list===
| |
− | '''Description:''' This provides a drop down list of images: .png, .gif, .jpg, .bmp and .ico. If the parameter has a value saved, this value is selected when the page is first loaded. If not, the default value (if any) is selected.
| |
− | | |
− | '''Screen shot:'''
| |
− | | |
− | [[Image:Params.imagelist.jpg]]
| |
− | | |
− | '''XML definition:'''
| |
− | <source lang=xml><param name="myimage" type="Imagelist" default="" label="Select an image" description="" directory="" exclude="" stripext="" /></source>
| |
− | *Name: The name under which the parameter value is stored.
| |
− | *Default: The default image.
| |
− | *Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
| |
− | *Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
| |
− | *Directory: The directory containing the images to be listed.
| |
− | *Exclude: A text string which is used to exclude certain images from the list. Any images whose names contain the string will be excluded.
| |
− | *Stripext: Strip these characters.
| |
− | | |
− | | |
− | ----
| |
− | | |
− | ===Language===
| |
− | '''Description:''' This provides a drop down list of the installed languages for the Front-end or Back-end. If the parameter has a value saved, this value is selected when the page is first loaded. If not, the default value (if any) is selected.
| |
− | | |
− | '''Screen shot:'''
| |
− | | |
− | [[Image:Params.language.jpg]]
| |
− | | |
− | '''XML definition:'''
| |
− | <source lang=xml><param name="mylanguage" type="Languages" client="site" default="" label="Select a language" description="" /></source>
| |
− | *Name: The name under which the parameter value is stored.
| |
− | *Client: Use 'site' when you want to display the Front-end languages, and 'administrator' when you want to display the Back-end languages.
| |
− | *Default: The default language.
| |
− | *Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
| |
− | *Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
| |
− | | |
− | | |
− | ----
| |
− | | |
− | ===List===
| |
− | '''Description:''' This provides a drop down list of custom-defined entries. If the parameter has a value saved, this value is selected when the page is first loaded. If not, the default value (if any) is selected.
| |
− | | |
− | '''Screen shot:'''
| |
− | | |
− | [[Image:Params.list.jpg]]
| |
− | | |
− | '''XML definition:'''
| |
− | <source lang=xml><param name="mylistvalue" type="List" default="" label="Select an option" description="" >
| |
− | <option value="0">Option 1</option>
| |
− | <option value="1">Option 2</option>
| |
− | </param></source>
| |
− | *Name: The name under which the parameter value is stored.
| |
− | *Default: The default list option.
| |
− | *Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
| |
− | *Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
| |
− | *Option: A list entry. The text between the <code><option>...</option></code> tags is what is shown in the drop down list.
| |
− | *Option value: The value that will be saved for the parameter when a given option is selected.
| |
− | **N.B. Don't forget to close the parameter with <code></param></code>!
| |
− | | |
− | | |
− | ----
| |
− | | |
− | ===Menu===
| |
− | '''Description:''' This provides a drop down list of the available menus from your Joomla! site. If the parameter has a value saved, this value is selected when the page is first loaded. If not, the default value (if any) is selected.
| |
− | | |
− | '''Screen shot:'''
| |
− | | |
− | [[Image:Params.menu.jpg]]
| |
− | | |
− | '''XML definition:'''
| |
− | <source lang=xml><param name="mymenu" type="Menu" default="" label="Select a menu" description="" /></source>
| |
− | *Name: The name under which the parameter value is stored.
| |
− | *Default: The default menu.
| |
− | *Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
| |
− | *Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
| |
− | | |
− | | |
− | ----
| |
− | | |
− | ===Menu item===
| |
− | '''Description:''' This provides a drop down list of the available menu items from your Joomla! site.
| |
− | | |
− | '''Screen shot:'''
| |
− | | |
− | [[Image:Params.menuitem.jpg]]
| |
− | | |
− | '''XML definition:'''
| |
− | <source lang=xml><param name="mymenuitem" type="MenuItem" default="" label="Select a menu item" description="" /></source> | |
− | *Name: The name under which the parameter value is stored.
| |
− | *Default: The default menu item.
| |
− | *Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
| |
− | *Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
| |
− | | |
− | | |
− | ----
| |
− | | |
− | ===Password===
| |
− | '''Description:''' This provides a text box for entry of a password. The password characters will be obscured as they are entered. If the parameter has a value saved, this value is entered (in obscured form) into the text box. If not, the default value (if any) is entered.
| |
− | | |
− | '''Screen shot:'''
| |
− | | |
− | [[Image:Params.password.jpg]] | |
− | | |
− | '''XML definition:'''
| |
− | <source lang=xml><param name="mypassword" type="Password" default="" label="Enter a password" description="" size="5" /></source>
| |
− | *Name: The name under which the parameter value is stored.
| |
− | *Default: The default password.
| |
− | *Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
| |
− | *Description: Text which is shown as a tooltip when a user moves the mouse over the text box.
| |
− | *Size: The width of the text box in characters.
| |
− | | |
− | | |
− | ----
| |
− | | |
− | ===Radio===
| |
− | '''Description:''' This provides radio buttons to select different options. If the parameter has a value saved, this value is selected when the page is first loaded. If not, the default value (if any) is selected.
| |
− | | |
− | '''Screen shot:'''
| |
− | | |
− | [[Image:Params.radio.jpg]] | |
− | | |
− | '''XML definition:'''
| |
− | <source lang=xml><param name="myradiovalue" type="Radio" default="0" label="Select an option" description="" >
| |
− | <option value="0">1</option>
| |
− | <option value="1">2</option>
| |
− | </param></source>
| |
− | *Name: The name under which the parameter value is stored.
| |
− | *Default: The default radio option.
| |
− | *Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
| |
− | *Description: Text which is shown as a tooltip when a user moves the mouse over the text box.
| |
− | *Option: A radio option. The text between the <code><option>...</option></code> tags is shown as the label for the radio button.
| |
− | *Option value: The value that will be saved for the parameter when a given option is selected.
| |
− | **N.B. Don't forget to close the parameter with <code></param></code>!
| |
− | | |
− | | |
− | ----
| |
− | | |
− | ===Section===
| |
− | '''Description:''' This provides a drop down list of the sections from your Joomla! site. If the parameter has a value saved, this value is selected when the page is first loaded. If not, the default value (if any) is selected.
| |
− | | |
− | '''Screen shot:'''
| |
− | | |
− | [[Image:Params.section.jpg]]
| |
− | | |
− | '''XML definition:'''
| |
− | <source lang=xml><param name="mysection" type="Section" default="" label="Select a section" description="" /></source>
| |
− | *Name: The name under which the parameter value is stored.
| |
− | *Default: The default section.
| |
− | *Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
| |
− | *Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
| |
− | | |
− | | |
− | ----
| |
− | | |
− | ===Spacer===
| |
− | '''Description:'''' This provides a separator between parameter entry elements.
| |
− | | |
− | '''Screen shot:'''
| |
− | | |
− | [[Image:Params.spacer.jpg]]
| |
− | | |
− | '''XML definition:'''
| |
− | <source lang=xml><param type="Spacer" /></source>
| |
− | | |
− | | |
− | ----
| |
− | | |
− | ===SQL===
| |
− | '''Description:''' This provides a drop down list of entries obtained by running a query on the Joomla! database. The first results column returned by the query provides the values for the drop down box. If the parameter has a value saved, this value is selected when the page is first loaded. If not, the default value (if any) is selected.
| |
− | | |
− | '''Screen shot:'''
| |
− | | |
− | [[Image:Params.sql.jpg]]
| |
− | | |
− | '''XML definition:'''
| |
− | <source lang=xml><param name="title" type="SQL" default="" label="Select an article" description="" query="SELECT id, title FROM #__content" /></source>
| |
− | *Name: The name under which the parameter value is stored. This should be the same as the query results column that you want to be displayed in the drop-down box.
| |
− | *Default: The default value.
| |
− | *Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
| |
− | *Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
| |
− | *Query: The MySQL query which provides the data for the drop down box.
| |
− | | |
− | | |
− | ----
| |
− | | |
− | ===Text===
| |
− | '''Description:''' This provides a text box for data entry.
| |
− | | |
− | '''Screen shot:'''
| |
− | | |
− | [[Image:Params.text.jpg]]
| |
− | | |
− | '''XML definition:'''
| |
− | <source lang=xml><param name="mytextvalue" type="Text" default="" label="Enter some text" description="" size="10" /></source>
| |
− | *Name: The name under which the parameter value is stored.
| |
− | *Default: The default text.
| |
− | *Label: A label displayed next to the text box to indicate the purpose of the parameter.
| |
− | *Description: Text which is shown as a tooltip when a user moves the mouse over the text box.
| |
− | *Size: The width of the text box in characters.
| |
− | | |
− | | |
− | ----
| |
− | | |
− | ===Text area===
| |
− | '''Description:''' This provides a text area for entry of multi-line text.
| |
− | | |
− | '''Screen shot:'''
| |
− | | |
− | [[Image:Params.textarea.jpg]]
| |
− | | |
− | '''XML definition:'''
| |
− | <source lang=xml><param name="mytextarea" type="Textarea" default="default" label="Enter some text" description="" rows="10" cols="5" /></source>
| |
− | *Name: The name under which the parameter value is stored.
| |
− | *Default: The default text.
| |
− | *Label: A label displayed next to the text area to indicate the purpose of the parameter.
| |
− | *Description: Text which is shown as a tooltip when a user moves the mouse over the text area.
| |
− | *Rows: The height of the visible text area, in lines.
| |
− | *Cols: The width of the visible text area, in characters.
| |
− | | |
− | | |
− | ----
| |
− | | |
− | ===Time zones===
| |
− | '''Description:''' This provides a drop down list of time zones.
| |
− | | |
− | '''Screen shot:'''
| |
− | | |
− | [[Image:Params.timezones.jpg]]
| |
− | | |
− | | |
− | '''XML definition:'''
| |
− | <source lang=xml><param name="mytimezone" type="Timezones" default="-10" label="Select a timezone" description="" /></source>
| |
− | *Name: The name under which the parameter value is stored.
| |
− | *Default: The default time zone. Use for example '-10' for UTC -10:00
| |
− | *Label: A label displayed next to the drop down box to indicate the purpose of the parameter.
| |
− | *Description: Text which is shown as a tooltip when a user moves the mouse over the drop down box.
| |
− | | |
− | [[Category:Development]]
| |