J5.x

Adding custom fields/Calendar Field

From Joomla! Documentation

< J5.x:Adding custom fields
Joomla! 
5.x
Tutorial
Custom Fields - Creating a Calendar Field


Introduction[edit]

The Calendar Field provides an input box for entry of a date. 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.

It provides you with a way for Editors to enter dates that will be consistent in position and format, dependent on how you use it.

Related Information[edit]

See:

Creating the field[edit]

We will create a Calendar Field for use in our articles.

In this example we will add a visited date on our aircraft pages.

From the Sidebar Menu in the Backend choose Content then Fields.

Access article fields via the sidebar menu

Before clicking the New button, check the dropdown list below the New button is set to Article - this is the default setting for use in the Article view.

NOTE: Although this tutorial covers creating a calendar field for use in an article, the following steps are the same if you were creating one for use in the Contacts Component (remember to set the view before clicking new) or for use in the Users Component.

Click New.

The Field Editor will open on the General tab.

Editor General Tab

Enter a Title This should be specific to the purpose of the new field. Avoid generic titles in case you want to use other calendar fields in other places.

On the Type field choose Calendar.

The Name field will be filled in automatically on saving the field but you can enter a different one. It should be lowercase and separated by hyphens.

The Label field is automatically set to be the same as the Custom Field Title but you can enter whatever you want. The value you enter is output on the Frontend if you choose to show the Label.

Add a Description if it will be useful. It is not required.

Set the Required Field to Yes or No with the toggle button. Setting to Yes will make the field a required one that cannot be skipped.

The Only Use In Subform field can be set to Yes if you only want the field available as a Subform child field.

If you use the Default Date the value can be an ISO 8601 format (YYYY-MM-DD HH:MM:SS) or NOW, which displays the actual date. Caution: Even if you do not specify the time in the default date, the time is displayed when the option Show time is active.

Special options within this field are:

  • Show time
    If enabled, the calendar field expects a date and time and will also display the time. The formats are localized using the regular language strings.

Restricting availability of the Custom Field[edit]

In the example shown we have set a Field Group of Aircraft. This means the Custom Field will be available via a tab named Aircraft in the Article Editor.

The Custom Field has also been set to use the Aircraft category. This means the Custom Field will only be available in articles set to the Aircraft category.

At this point you have entered sufficient information to create the Custom Field and make it available for use.

Calendar Custom Field Options[edit]

Form Options[edit]

Options for using the Custom Field Form.

Placeholder - You can add a placeholder to guide authors.

Field Class - You can add a class used in your CSS style sheet to style the field.

Label Class (Form) - You can add a class used in your CSS style sheet to style the label in the form.

Editable In - Set for Frontend Editing, Backend Editing or both.

Display Options[edit]

Options for the display of the Custom Field Output on the Frontend.

Display Class - You can add a class that is used in your style sheet to target the container that holds or wraps the field.

Value Class - You can add a class that is used in your style sheet to target the styling of the field.

Label - Show or hide the Custom Field Label.

Label Class (Output) - You can add a class that is used in your style sheet to target the the styling of the Custom Field Label that is output.

Automatic Display - This is closely linked to the Component Output.

  • After Title places the field output after the Component Title (after the article title, contact title or user title)
  • Before Display Content (above the article, contact, or user content)
  • After Display Content (below the article, contact, or user contact)

Note that these 3 settings assume default Joomla! output and could look different with other templates or if Custom Overrides are in use.

  • Do not automatically display will only display the output where you choose to display it by using Joomla's Insert Field function or your custom overrides if you use them.

Prefix You can add a Prefix to be output before the Custom Field output.

Suffix You can add a Suffix to be output after the Custom Field output.

Layout If they are used, you can select an alternative layout for the Custom Field

Display when Read-Only If you need to hide the field - this relates to user access control levels (ACL)

Save the Custom Field[edit]

Click Save & Close and the Custom Field is available to use.

Using the field in the Backend[edit]

In the Article Editor select the Custom Fields tab to access the Custom Field. In the this example we have a Field Group named Aircraft that was assigned to the Category Aircraft. As the Article is assigned to the Aircraft category, the Aircraft tab is available that will contain one or more Custom Fields assigned to that Field Group. If you are not using Field Groups look for a tab named Fields.

Custom Fields Editor Tab in the Backend

Once you have selected the tab it will display all the fields you have created. In this example we have only the Date Visited field we created. Note the asterisks symbol - it denotes that it is a required field (this is turned off or on in the field options when you create it).

Click the calendar icon to open the calendar date picker and select the date. When you have done, save and close the article.

Use Calendar Custom Field in the Backend

Frontend Output of the Calendar Custom Field[edit]

In the Frontend, you can see the field as you see in the following image. The option in Automatic display is responsible for the position of the field and your template is responsible for the layout of the field.

Fields are only displayed in the Frontend if you have filled them with data in the article. If it is not a required field, can you forget it?

Calendar Custom Field Frontend Output

Note that the output is displayed with a bullet point - this is the default layout and may look different dependent on your template.

It is possible to change the layout and date format by creating a template custom override.