|
|
| (17 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| − | =Using parameters with a component=
| |
| | | | |
| − | ==Background==
| |
| − | One thing that sets Joomla! components apart from other types of Extension (i.e. modules and plugins) is the ability to store data in the Joomla! MySQL database. Typically, this data will be content for displaying on a page (such as the content of an article, or its title) or data about how that content should be displayed (e.g. a setting specifying whether or not the title should be shown). A component normally creates at least one table in the database to store this data - for example, data for articles (associated with the com_content component) are stored in the <code>jos_content</code> table (where ''jos'' is the table prefix for the site).
| |
| − |
| |
| − | However, choosing exactly where to store each item of data requires a little more thought. There are essentially two choices: each data item may be stored in its own field, or a collection of data items may be stored within a single parameters field. (Of course, there is nothing to stop you making use of both methods, for different data items, within the same component). Which approach you use for a given data item is largely a matter of personal choice, although there are some factors to consider:
| |
| − | * Core code included in the Joomla! installation makes it very easy to produce the appropriate form elements for entering data into '''parameters''' in the backend. If you choose to save the data in separate fields, you will need to code the appropriate form elements yourself.
| |
| − | * Again, Joomla! core code allows you to set default values for '''parameters''' across the whole component. Individual component items (e.g. individual articles) can then choose to use the default values, or to override them with values specific to that item. See below for details of how to do this.
| |
| − | * It is not possible to extract individual parameter values directly from the database. Instead, the whole parameters field must be extracted and parsed to obtain the different parameter values. This means that it is not very easy, for example, to run MySQL queries that search for a parameter with a particular value. Any data that you want to run queries against should be given its '''own table field'''.
| |
| − | * Similarly, it is not possible to run data validation on parameter fields before saving data.
| |
| − | In general, parameters are conventionally used to store data relating to the ''presentation'' of information. The information itself is generally stored in separate fields.
| |
| − |
| |
| − | ==Types of component parameter==
| |
| − |
| |
| − | ===1. Component-wide default parameters===
| |
| − |
| |
| − | These parameters are set once for the whole component, and are generally used to provide the 'default' parameter settings for the component on that particular site.
| |
| − |
| |
| − | ===2. Menu item specific parameters===
| |
| − |
| |
| − | A menu link to an individual component item (e.g. an article) can also have parameters associated with it, which can affect the way the component item is displayed ''using that link''. The types of parameters available will depend on the way that the component item is displayed (the 'view' in MVC terms, but don't worry if this doesn't mean anything to you!). However, the precise values of those parameters can be set for each menu link individually. If there is another menu link to that same component item, then it is important to realise each menu link may have different parameter values, and so the same article may be displayed differently in the two cases.
| |
| − |
| |
| − | A menu link can also override the component-wide default parameters, so that the override values (if set) are used in place of the default values ''for that component item when accessed via that menu link''. As you would expect, when no override value is set, the default value is used instead, in the normal manner.
| |
| − |
| |
| − | ===3. 'Article' specific parameters===
| |
| − |
| |
| − | Finally, each component item (e.g. article) can have parameters which apply to that item, regardless of how it is accessed (i.e. via any available menu link, or even without reference to a menu at all!). If the component designer wants, the article specific parameters can also be set up to use the 'override' behaviour, so that they default to the current values of the corresponding component-wide parameters, though this is not essential. Again, this is described further below.
| |
| − |
| |
| − | ==Storing the parameters and their values.==
| |
| − |
| |
| − | In general, a set of parameters is stored within the database in a single <code>text</code> field. Different parameters are separated by <code>newline</code> characters ('/n' in MySQL - each parameter will appear on a different line when you look at the data in something like phpMyAdmin). Each parameter consists of the parameter name and value, separated by an equals sign (=). As an example:
| |
| − |
| |
| − | <source lang="text">
| |
| − | parameter1=parameter1value
| |
| − | parameter2=
| |
| − | parameter3=parameter3value
| |
| − | parameter4=parameter4value
| |
| − | </source>
| |
| − |
| |
| − | Here, parameter1, parameter3, and parameter4 have all been assigned values, whilst parameter2 has no value. If these parameters were set up as overrides, parameter2 would show the default value.
| |
| − |
| |
| − | ===1. Component-wide default parameters===
| |
| − |
| |
| − | These are stored in the <code>params</code> field of the jos_components table, in the row corresponding to the particular component to which they apply.
| |
| − |
| |
| − | ===2. Menu item specific parameters===
| |
| − |
| |
| − | These are stored in the <code>params</code> field of the jos_menu table, in the row corresponding to the particular menu item to which they apply.
| |
| − |
| |
| − | ===3. 'Article' specific parameters===
| |
| − |
| |
| − | These are stored in a text field in the table created by the component. Whilst there is no strict rule for naming the field, it is common to extend the above pattern using the <code>params</code> name. However, com_content stores article parameters in a field called <code>attribs</code>.
| |
| − |
| |
| − | ==Accessing the parameters - backend==
| |
| − |
| |
| − | Joomla! includes some shortcuts to enable component creators to easily add parameter forms to the backend of their component. These forms allow a site administrator to enter a parameter value by, for example, entering some text in a box, choosing from a drop-down list, or selecting a radio button. To create these forms, each parameter needs to have an associated <code><param /></code> object in an XML file. The type of <code><nowiki><param /></nowiki></code> object determines the form elements that will be shown in the backend. A list of the available form elements is given [[Using_the_core_parameter_types|here]]. More information is given below about the XML file names, structure and location required for each set of parameters.
| |
| − |
| |
| − | ===1. Component-wide default parameters===
| |
| − |
| |
| − | These are defined in a file named <code>config.xml</code> which is located in <code>/PATH_TO_JOOMLA/administrator/components/com_COMPONENT_NAME/</code>. The file should have the following structure:
| |
| − | <source lang="xml">
| |
| − | <root>
| |
| − | <params>
| |
| − | <param />
| |
| − | ...
| |
| − | </params>
| |
| − | </root>
| |
| − | </source>
| |
| − | Note that the <code><root></code> element can have any name you wish, but there must be one element at the root of the document (this is a requirement for a well-formed XML document). You can have more than one <code><params></code> element, but only the first one will be considered.
| |
| − |
| |
| − | So that administrators to access these parameters, you will need to add a button to the toolbar in the backend of your component. This can be done using the code:
| |
| − | <source lang="php">
| |
| − | JToolBarHelper::preferences( 'com_COMPONENT_NAME' );
| |
| − | </source>
| |
| − | which is typically placed in the PHP file responsible for the backend output. (For example, using an MVC structure, you might place this code at the top of <code>/PATH_TO_JOOMLA/administrator/components/com_COMPONENT_NAME/views/VIEW_NAME/tmpl/default.php</code>.
| |
| − |
| |
| − | This adds a <code>Parameters</code> button to the toolbar:
| |
| − |
| |
| − | [[Image:Toolbar_newsfeed.png]]
| |
| − |
| |
| − | Clicking on the toolbar button produces a pop-up window containing the form fields for each parameter defined in <code>config.xml</code>.
| |
| − |
| |
| − | It is possible to define default values for each of these parameters in the <code><param /></code> statements in the <code>config.xml</code> file. However, in order to save these default values to the database, a user would need to click on the <code>Parameters</code> button (at which point any field not having a pre-saved value will be given the default value), and then click the 'Save' button. Since you won't want to rely on your users doing this before using the component, Joomla! 1.5 allows you define default values for the component parameters, to be saved to the database on installation. These default values are set in the installation XML file (typically called <code>COMPONENT_NAME.xml</code>), which has the following structure:
| |
| − | <source lang="xml">
| |
| − | <install>
| |
| − | ...
| |
| − | <params>
| |
| − | <param />
| |
| − | ...
| |
| − | </params>
| |
| − | ...
| |
| − | </install>
| |
| − | </source>
| |
| − | Although the structure of these <code><param /></code> elements is superficially similar to those from the <code>config.xml</code> file, you should note that the <code><param /></code> elements from the install file are never used to produce form fields. There is therefore no benefit to setting the types of parameter. The only attributes required for the <code><param /></code> elements are the <code>name</code> and <code>default</code> values - it is these values which will be copied to the database on installation.
| |
| − |
| |
| − | ===2. Menu item specific parameters===
| |
| − |
| |
| − | A menu item is associated with a particular view from your component's frontend - following the menu link in the frontend will display that view (usually for a particular component item). Joomla! 1.5 allows you to define parameters for a particular view, so that a copy of those parameters can be associated with each menu item using the view. You can also choose to override the component-wide default parameters as mentioned above, so that the override values will apply to the particular menu item.
| |
| − |
| |
| − | The view parameters are defined in an XML file stored in the ''frontend'' template directory and with the same name as the template, i.e. <code>/PATH_TO_JOOMLA/components/com_COMPONENT_NAME/views/VIEW_NAME/tmpl/TEMPLATE_NAME.xml</code>. The structure of the file is:
| |
| − | <source lang="xml">
| |
| − | <metadata>
| |
| − | ...
| |
| − | <state>
| |
| − | ...
| |
| − | <params>
| |
| − | <param />
| |
| − | ...
| |
| − | </params>
| |
| − | <advanced>
| |
| − | <param />
| |
| − | ...
| |
| − | </advanced>
| |
| − | </state>
| |
| − | </metadata>
| |
| − | </source>
| |
| − |
| |
| − | Displaying the forms for these parameters is handled automatically by the core <code>com_menus</code> component, which creates a number of slider panes on the right hand side (in the default Kepri backend template) of the menu item edit screen. Any parameters defined within the <code><params></code> tag will appear in the <code>Parameters - Basic</code> slider pane. Any parameters defined within the <code><advanced></code> tag will appear in the <code>Parameters - Advanced</code> slider pane.
| |
| − |
| |
| − | For the override of the component-wide default parameters, <code>com_menus</code> uses the same <code>config.xml</code> file as above, so there is no need to define these parameters again.
| |