Adding parameters to a Joomla 2.5 plugin

So far we have created a very basic plugin that simply shows our predefined text in articles. You probably have noticed that while we were configuring the plugin there was no other parameters to configure, we have simply enabled the plugin. But many other plugins have many parameters to configure, and how we can have such parameters be added to our plugin? Yes, we are going to learn that now.

Let us modify the plugin so that instead of ‘Hello World’ we can show anything we want. We will specify our desired text through a parameter, and that text will be displayed in article.

Adding parameter in XML file

Like other extensions, parameters in Joomla 2.5 plugins are contained in XML file within fields and fieldsets. We have already created helloworld.xml file. Let us edit that and make the changes so that it looks like the following:

Save helloworld.xml file with the above changes. Then compress the whole directory and install the plugin from Extension Manager screen.

Setting value for parameter

We have added a parameter to the plugin and instaleld the new plugin. Now let us go to Extensions > Plugin Manager and click on Hello World plugin. That will show Plugin Manager: Hello World screen.

As you see on this screen, we have to select Enabled in Status field. Then on the right hand side you see Basic Options section, under which we see our parameter field with label Alternative Text. Type some text, say ‘Welcome, Friends!’ in this text field. This is the value for our plugin parameter and this will be displayed in artcile.

At this point, if you go to the frontend and view any article, you’ll still see old text ‘Hello, World!’. This is because we have not yet modified our plugin file helloworld.php to use the plugin parameter. Let us do this now.

Using plugin Parameter from PHP

Once we have saved our plugin parameter, we can use it in our plugin thpugh php code. You can access a plugin parameter by using following syntax:

As you see, we have to mention the attrbute name. For our parameter, attribute name is mytext. So we will use that name. We will also add some logic there – first, we check whether value for mytext is set or not; if it is set we show that value, if not, we show our old friend ‘Hello, World!’. So, following will be our updated helloworld.php code:

After these change, copress the whole folder again and install it from Extension Manager. Now go Plug-in Manager and be sure that Hello World plugin is enabled and text is entered.

Configuration is done and now you can move to front end to see the result. Click on any article and, voila, you got it!

Now you can see the text ‘Welcome, Friends!’ under title of the article.

Joomla 2.5 plugin parameter fields

In previous section, we have learned how to add a paramter to a plugin. We simply added the parameter to our plugin without explaining much aboit that. Now let use try to understand how we add plugin parameter fields in Joomla! 2.5.

In our example, we have added a parameter with the following code:

If we analyze the code we get the following attributes of the field element:

  • name : name attribute of a field element is must and it indicates the name of the attriute field. Variables are passed by this name. Later on in php code we need to refer to this name. In our example, we have named our parameter field as mytext. Later in helloworld.php we have used $this->params->get('mytext') to ge the value of this field.
  • type : Another required attribute for a parameter field. This indicates type of field we want. For Joomla! 2.5, there are various types of fields available. In our example, we have used type="text" which means we want a text field.
  • default : This attribute indiates the default value for the field. The value we put in this attribute are displayed by default. In our example code, we have put default="" which means default is null.
  • label : label attribute of a field element is used to indicate label of the parameter field. In our example, we set the field label as Alternative Text. This label controls what the user sees the setting labeled as when configuring.
  • description : This attribue indicates the detailed description of the field that enables users to understand how the field is expected to be filled in. Generally, content of description attribute is displayed as tooltip when mouse is taken over the field label.

Parameter types for plugin

We have already learned that type attribute is used to set type of the parameter field. For Joomla 2.5 plugins, there are various input types we can use. In our code so far, we have only used the text input type. Now we will explore some other types of plugin parameter fields.

Radio

In normal forms, you have seen the radio boxes where multiple options are displayed and you are allowed to select only one options. In Joomla! plugin parameters, you may also need such radio boxes to choose a value from. We can make such form field by using type="radio" attribute. Following code shows how to create a raido box:

As you see, we have added a field named color and its type is set as type="radio". As child of this element options are added. The output of the above will be as shown in the following screen shot.

Accessing the value of a radio button within your plugin’s php file (helloworld.php) is similar to getting the value of a standard text type field. As our field’s name above is color, we’ll get the value of the user’s color using that name, as in:

Dropdown list

Often you have seen drop down lists in forms. You can also use such lists for plugin parameters. In previous example, we have seen how to show color options as radio list. That can also be shown as drop down list. Hwowever, we will create another field of type list by adding type="list" attribute to field’s definition. Look into the following code:

Here we have created a filed named font-size. It has three options. As we have set Again, accessing the parameter value itself is done in the same manner:

Text parameter input type

To make this a well rounded tutorial, we’ll also include the text input type (even though we referenced it in a previous article).

Example Code:

To access this value, again use the following code in your plugin’s php file:

So we use $this->params->get() to get the value of a parameter.

Where goes the parameter values?

The parameter values are stored in a text field in database table. Its saved in params field in j25_extensions extension table. The table contains the following information:

  • name/element : This is the name of the plugin
  • folder : As this is a content plugin, it is in the content folder.
  • enabled : This controls whether or not the plugin is enabled.
  • manifest_cache : This holds much of the information that was found in the plugin’s xml file, such as who wrote the plugin and the author’s contact information.
  • params : Any custom parameters that you create will be stored in the params field.

So far we have seen, how to create different types of parameter fields. In our next part of this tutorial, we will look into some more advanced topics. See you then!

Other posts of the series

  1. Tutorial: Developing Joomla! Content Plugin
  2. Adding parameters to a Joomla 2.5 plugin
  • http://www.sakshiinfoway.com/ sakshi

    Thanks for this article regarding adding parameters.