Special Offer for Full Website Development Package More Info

joomla custom fields parameters explaination

Custom fields is one of most excited fefature of Joomla, it helps add any field type and show it flexibly in your Joomla website. In our previous blog post: Joomla Custom Fields Part 1, we have introduced an overview about Joomla custom fields and how to manage custom fields. In this blog post, we will focus on explaining function and how to use each custom field type.

Common Parameters for Custom Fields

On the 1st tab ("General") of a Custom Field, you will notice that some parameters vary depending on the type of field :

Custom Fields all have the following common parameters :

  • Name: "The name will be used to identify the field. Leave this blank and Joomla will fill in a default value from the title."
    With other words, it is the technical name of the field for a possible use in the PHP code (in an override or an alternate layout for example).
  • Label: The label displayed on the screen, typically on the left of the field.
  • Description: The help text or information displayed on the label tooltip.
  • Required: (Y / N) is this a mandatory field or not
  • Default value: when a user edits the field, is it simply empty or does it show a default value

cf episode3 common parameters

The other parameters of the "General" tab displayed after those common parameters depend on the type of Field chosen :

Calendar

  • Display time : (Y / N) Do you just want a "date" or "date and time" field.

Checkbox

  • Values ​​for the checkbox: enter values ​​that can be checked.

Color

  • (no additional parameters).

Editor

  • Show buttons : should the editor-xtd buttons be shown or not (those buttons which come natively with Joomla or with some third-party extensions).
  • Buttons to hide : even if you show the editor-xtd buttons, you can still choose to hide some of them
  • Width : width of the editor in the interface (in pixels). Default is 100%
  • Height : height of the editor in the interface (in pixels). Default is 250px.
  • Filter: see explanation below.

User groups

  • Multiple : if set to "No" the field will allow the selection of a single group of users, if set to "Yes" it will be possible to select multiple groups of users.

List

  • Multiple : if set to "No" the field will allow the selection of a single item from the list, if set to "Yes" it will be possible to select multiple items.
  • Values ​​in the list : enter the values ​​of the values ​​which will be displayed in the list.

Image list

  • Directory : The path to the folder containing the images to be listed.
  • Multiple : if set to "No" the field will allow the selection of a single image, if set to "Yes" it will be possible to select multiple images.
  • Image class a class to the image or images in the front-end.
    Example of HTML in the front-end with a shadow class: <img src="/images/headers/windows.jpg" class="shadow">.

Media

  • Directory : The path to the folder containing the media to list.
  • Preview : If set to "Yes" the field displays a button to preview the selected photo.
  • Image class: adds a class to the image in the front-end.
    Example of HTML in the front-end with a shadow class: <img src="/images/headers/windows.jpg" class="shadow">.

Integer

  • Multiple : if set to "No" the field will allow the selection of a single number, if set to "Yes" it will be possible to select several numbers.
  • First : Number to start the list of numbers.
  • Last : Number to end the list of numbers.
  • Incrementation : the "step" between two numbers.
  • Example:
    • if you set First = 15, Last = 27, Increment = 5
      then the drop-down list will show: 15, 20, 25

Radio

  • Values : List of values ​​from which one of them can be selected.

SQL

Using this field requires knowledge of the SQL language basics that can extract data from the database of your Joomla site.

  • Query : the SQL query to retrieve a field named 'value' and a field named 'text'. The 'text' field will be used to make up the visible part of the list. The 'value' field will be retrieved when the user selects an item from the list. Warning: it is recommended to use the '#_' to replace the prefix of the table.
  • Multiple : if set to "No" the field will allow the selection of a single item from the list, if set to "Yes" it will be possible to select multiple items.
  • Examples:
    • To display a drop-down list of articles in my category ID 12, the query to use will be:
      SELECT id AS value, title AS text FROM #__content WHERE catid = 12
    • To display the list of contacts of my Joomla site, the query to use will be:
      SELECT id AS value, name AS text FROM #__contact_details

Text

  • Filter : the notion of input filter is explained later in this article.
  • Maximum length : the maximum number of characters to enter in this text field (HTML attribute 'maxlength').

URL

  • Protocols : Select the allowed protocols so that the links entered correspond to the desired use of this field.
    • the choices are: HTTP, HTTPS, FTP, FTPS, FILE, MAILTO
  • relative URLs : if set to "No" the field will only allow the complete URLs, if set to "Yes" it will be possible to input relative urls (so to another page of the current site).

User

  • The field "Default value" is replaced by "Default user".

Text area

  • Rows: The height of visible text area in lines.
  • Columns : The width of visible text area in characters (this parameter would probably not be used used in modern respnsive templates. One would generally prefer to use a CSS style to define the width of this zone).
  • Maximum length : the maximum number of characters to enter in this text field (HTML attribute 'maxlength').
  • Filter : the notion of input filter is explained later in this article.

To see the rendering in Administration and Frontend of all these fields, please see the article "Custom Fields Episode 1".

Custom Field Display Settings

On the second tab called "Options", you'll find rendering settings:

  • Placeholder: Placeholder text which will appear inside the field as a hint to the user for the required input.
  • Render class: CSS classes used to display the field on Frontend,
  • Edit class: CSS classes used to display the field when you edit it in Backend and Frontend.

The 3 following display options "Show label", "Show on" and "Automatic Display" were explained in episode 1.

The last parameter was introduced with Joomla 3.8.7:

  • Display when read only

This new parameter allows to define if users who are not authorized people to edit a field (read-only) will still see the field in the form.

Please find the detailed explanations at https://github.com/joomla/joomla-cms/pull/20068

In some cases, it may indeed be necessary (in editing mode) not to allow the modification of the contents of a field for certain groups of people. Example: You could enable the "Edit Custom Field Value" on the Permissions tab only for the "Editor" group. "Authors" (who have less rights than the "Editors") would then not be allowed to modify this Custom Field.

But with this parameter it becomes possible to let those "Authors" see that field and its value, even if they can not edit it anyway.

cf episode3 readonly1

cf episode3 readonly2

The choice "Inherited" will be treated in another episode because it concerns the use of "Groups of fields".

Display example with Bootstrap styles

The rendering and editing classes are customizable according to the CSS of your templates. However, as Joomla 3 integrates Bootstrap 2 (in the backend and also in the front-end if you use the template Protostar. If you use another template based on another version of Boostrap or on another framework, the philosophy is the same of course), it is possible to refer to the online documentation to take advantage of built-in styles.

Bootstrap includes "rendering styles" for "Label" and "Badge":

More details at: http://getbootstrap.com/2.3.2/components.html#labels-badges

Example of a field width with Bootstrap styles

For entry fields, Bootstrap provides styles for defining the width of an input field: "input -......."

More details at: http://getbootstrap.com/2.3.2/base -css.html # forms

So you can use the styles presented above in the rendering classes (Frontend) and editing classes (Backend and Frontend):

With the above styles, the rendering when you edit that checkbox field in administration will give a "xlarge" display with a "badge-info" (blue) style:

The rendering will be similar if you modify the article in Frontend:

Here is the rendering of the article in front-end if you use "label label-warning" as Render Class. These styles do indeed add an orange box around the selected values ​​of checkboxes:

In this example, "Show Label" is set to "Hide".

Warning: if you have set Automatic Display to "Do not automatically display" because you create your own template overrides or alternate layouts, then the Render Class will not be taken into account! (the logic is probably that if you make an override/alternate layout, you already completely control the code and therefore the classes that you want to put).

Further information on setting up a Custom Field

Version Management of Articles

If you use versioning in Joomla content, be aware that Custom Fields will not be versioned (it would be a nice feature though).

Source: https://docs.joomla.org/J3.x:Adding_custom_fields/en#Versioning

Filtering input

Some fields (Text, Editor, Text Area) provide a "Filter" setting.

This setting allows you to have control on the input on those fields.

The possible values ​​are:

    • No : no filtering of the data entered.
    • Raw : (raw) I guess the same result as "No".
    • Safe HTML : allows the input of "safe HTML" code (no scripts, ...).
    • Text : filtering according to the parameters of the general configuration ("Text Filters" tab).
    • Alpha numeric : only alphanumeric characters are accepted.
    • Integer : only integers without decimals are accepted.
    • Float : only figures (with or without decimals) are accepted.
    • Telephone : allows the entry of a telephone number in international format only (country code and local telephone number, separated by a period, eg 33.1234567).

What next features can we expect from Custom Fields ?

Joomla 3.9.0 will bring some new interesting features on the use and implementation of Custom Fields.

Here is a selection of a few I have spotted and I take this opportunity to thank all the people involved in these Pull Requests :)

Alternative Layout for a Custom Field

Details: https://github.com/joomla/joomla-cms/pull/18571

Would you like to be able to change the HTML rendering of a Custom Field using alternate layouts?

In your template, create a new substitution file by clicking on "New file":

In the popup window, select on the left the source file for your substitution:

html> layouts> joomla> form> field

Then, on the right of the popup window, give a name for the substitution file (example here: "attention"), specify that it is a PHP file.

Finally click on the blue button "Create":

This process is already possible in your sites in Joomla 3 and allows you to create an alternative layout for the rendering of an article, a module ...
But what is new Joomla 3.9.0 is that it will be possible to assign that Alternate Layout in the configuration of any field!

Indeed when you edit one of your Custom Fields in a site running Joomla 3.9.0+, a new parameter will be available in the "Options" tab. This "Layout" field will allow you to assign your Alternate Layout:

Multiple entries for the same Custom Field (Repeatable Fields)

Details: https://github.com/joomla/joomla-cms/pull/20243

In many cases, you want to create a certain number of Custom Fields of a given type, but you don't know the maximum potential number.
Example: the ingredients of a recipe. For some recipes, 3 will be enough, but for others you will need 15... or even more but you don't know in advance how many.

That is why a new field type will appear with Joomla 3.9.0 : the "Repeatable" field.

This type of field will allow you to build a subform composed of one or even several fields (for example : actor's name and actor's picture for movies. Or ingredient and quantity of that ingredient for recipes) by choosing from 5 types of fields supported in these subforms (Editor, Media , Number, Text, Text Area):

Once you have configured your repeatable field, when you edit an article you will get 3 buttons allowing to enter as many values as you wish :

  • Green Button (+) adds a new entry/row.
  • Red button (-) deletes an entry/row.
  • Blue button (with arrows) allows to reorder the elements by "drag and drop".

Adding label Class for input

Details on https://github.com/joomla/joomla-cms/pull/18431