Joomla basics for newbies

In our Explore the Core series, experienced Joomla users help you find your way through Joomla's powerful core features. In this month's issue, Marc Dechèvre shows us what you can do with Joomla's built-in custom fields (spoiler alert: a lot). Dive in and explore!

Custom Fields shipped with Joomla 3.7 back in 2017. This was an initiative of Allon Moritz, a well-known Joomler from Switzerland.

And like many Joomlers, I am very grateful to him because Custom Fields are definitely a game-changer! No matter whether you are a basic user, an advanced user or a developer.

Since then almost all the websites I have built make (extensive) use of Custom Fields.

It makes indeed Joomla so powerful because you can build quite complex websites with a customized layout in a simple way and by sticking to the core... which in turn is very interesting to get a website that is light and easy to maintain.

Although most users know it is there, not everybody has already taken the time to play with it and to realize how useful it is.

So this is why we wanted to dedicate one of the "Explore the core" episodes of the Joomla Community Magazine to Custom Fields.

This article is not meant as a step-by-step tutorial about Custom Fields (there are other articles covering these aspects, see the links hereafter) but more as an overview of what can be achieved.

What Types of Custom Fields?

Joomla ships natively with 16 different types of Custom Fields, namely:

1. Calendar Field
2. Checkboxes Field
3. Color Field
4. Editor Field
5. Integer Field
6. List Field
7. List of Images Field
8. Media Field
9. Radio Field
10. Repeatable Field
11. SQL Field
12. Text Field
13. Textarea Field
14. Url Field
15. User Field
16. Usergroup Field

The Types names speak for themselves, but two of them deserve a special focus:

• the SQL Field allows of course to create literally anything directly from the database. So your imagination is your only limit...
• the Repeatable Field was introduced in a later stage. By nature, it is very powerful since -as its name suggests- it allows the creation of Block of Fields that can be repeated without even knowing in advance the number of repetitions. For example: for a website gathering Recipes, the number of ingredients vary for each recipe and if the maximum number of ingredients for a recipe is X you definitely don't want to create X (or 2X) Custom Fields. In such a case you would simply create an Ingredients Repeatable Custom Field containing two "subfields": Ingredient's Name and Ingredient's quantity. Then the setup is very quick and whatever the number of ingredients of each recipe you are covered!

Note: in Joomla 4 the Repeatable Field will be replaced by the Subform Field. This is very good news because it will make the concept of "Repeatable" Fields even more generic/universal:

• in Joomla 3 the Repeatable Field allows to choose only amongst the following Types: Editor, Media, Number, Text, Text Area
• whereas in Joomla 4 the new Subform Field will allow choosing amongst any other Type of field installed (native or not)

In what parts of Joomla can I use Custom Fields?

In other words, what Components are supporting Custom Fields?

The most common use-case for Custom Fields is to enrich Content (com_content), namely Articles or even Categories.

Another typical use-case is the Contact Component (com_contact), either to add fields

• to the Contacts themselves, allowing to have a native customized directory of persons
• or to the Contact Form, meaning that you can stick to the core even for more advanced forms

The Users Component (com_users) also integrates Custom Fields.

In other words, if you want to have more information about your users you can do it without any third-party extension.

Last but not least, Custom Fields are like Categories or Tags in Joomla: any third-party component can integrate them easily, which means that

• developers don't have to reinvent the wheel: they can easily make their extensions more flexible/powerful
• and users can easily customize the content of all those compatible extensions in a standardized way

What can I do with Custom Fields

There are two main usages for Custom Fields.

Providing additional content to articles/contacts/users

Let's take the example of this JoomlaDay website.

Each session is a Joomla Article having a series of Custom Fields:

• Speaker
• Day and Time
• Room
• Pitch

Customizing further the layout of articles/contacts/users

Keeping the example of the JoomlaDay website, I wanted to have a timetable where every session would be automatically displayed

• in the right column (corresponding to the room)
• in the right row (corresponding to the slot)

To get this I simply added two Custom Fields of Type List to the Articles of the Category Session:

• Room with a list of predefined Rooms: main, workshop, ...
• Slot with a list of predefined Slots: slot-am-1, slot-am-2, ...

Using a Blog view displaying all Articles of Category Session, I made an Override in order to simply add to each Article classes corresponding to the Room and the Slot (example: class="slot-am-2 workshop")... and thanks to CSS Grid each article would automatically appear in the right "cell" of the timetable.

Another example is illustrated in this demo: http://www.greendog.fr/experimentations

In particular, the 6th Override demo uses the Custom Field "color" in order to assign an overlay color to each Article. This color is not displayed in the Article itself but used in the Override which retrieves each color and puts it as background for each Article.

How to integrate Custom Fields in the Content?

Is an Override always needed?

Of course not!

By default, speaking about Articles which are the most common case, Custom Fields can be individually set to appear

• After Title
• Before Display (meaning before the Content the of Article, knowing that according to your Joomla settings other things can appear between Title and Display, like Tags/Author/Dates/...)
• After Display
• Do not automatically display

The latter makes sense in three different cases:

1. the Custom Field is only meant to be seen in the Administration interface
2. the Custom Field will be manually inserted "in the middle" of an Article thanks to the Fields button appearing with the Editor
3. the Custom Field will be automatically displayed in a customized layout, which can be called
   1. an Override (when it applies to all Articles)
   2. an Alternate Layout (when it only applies to some Articles or Categories). An Alternate Layout can then typically be selected via the Options of the Article itself or via the Menu Item

With an Override, the sky is the limit

Rule #1: even if you have never made an Override and even if you have never seen a line of code (PHP), don't be afraid.

Just give it a try.

One of the big strengths of Joomla is precisely that the code separates by design

• the "engine"
• and the "view"

Curious to see how to integrate Custom Fields in your Overrides?

In this detailed article published last year the procedure is explained step by step:

https://magazine.joomla.org/all-issues/april-2020/custom-fields-episode-4-a-step-by-step-tutorial

What if I need another non-native "Type" of Custom Field?

By tweaking an existing Custom Field

This can be done by creating an Alternate Layout and assigning it to a given Custom Field.

Since Joomla 3.7

Since the start, it was possible to create an Alternate Layout for Custom Fields. However, it was originally only possible to use an Alternate Layout when manually inserting the Field in an Article.

Example: inserting {field 1,my-own-layout} in an article would display the Custom Field having ID 3 using an Alternate Layout named my-own-layout.php.

Since Joomla 3.9

Joomla 3.9 introduced a new Option allowing to assign directly an Alternate Layout to a Custom Field so that it is automatically used.

Let me quickly show how this works since this is not very well known / much documented so that many might have missed this handy feature.

Create an Alternate Layout for the Custom Field

Create the following file

/templates/[my_template]/html/layouts/com_fields/field/my-own-layout.php

(note: underscores are not allowed in the name of that file)

where you paste the content of the following file 

/components/com_fields/layouts/field/render.php

which is actually the default layout used to render Custom Fields

Customize my-own-layout.php according to your wishes.

To take an easy example, let's suppose that you want an Alternate Layout to give some Custom Field of Type "URL" the look of a Button showing the text "Download the report".

As you probably know, "btn btn-primary" are the two classes that are used in Boostrap in order to give a button style with the primary color of the website (the good old Protostar is based on Bootstrap 2, most current templates are based on Bootstrap 3 or 4. But of course, you can adapt those classes if your template uses another CSS framework or if you want to use your own classes).

In my-own-layout.php the following code echoes/displays/renders the Custom Field:

<?php echo $value; ?>

Actually, it does not simply display the raw value (ie what is written in the database, namely the URL) but it "renders" it (ie it transforms it into a hyperlink).

This is so because $value is defined earlier in the file as

$value = $field->value;

So if I change

1. $value = $field->value; into $value = $field->rawvalue; 
2. <?php echo $value; ?> into <span class="btn btn-primary"><a href="/<?php echo $value; ?>">Download the report</a></span>

then the simple URL is transformed into a nice-looking button with the desired text.

Of course, once you get the idea, you realize that you can now transform the existing Custom Field into anything.

For example if the Custom Field of Type "URL" is used to put the link to an online video, you can easily replace that URL by a video player.

As you can see Custom Fields Alternate Layouts are an easy way to create your own Custom Field "Types" without even having to create a new Plugin for it.

Assign the Layout as Default

Edit your Custom Field. The Layout option is to be found under the tab Option > Render Options > Layout.

Instead of choosing "Use Default" you can now select in the list any Alternate Layout you have created.

By creating my own plugin

Of course, if you want to have your own parameters for your own new Type of Custom Field then you should go the classical way.

Each Custom Field Type is in fact no more than a simple Plugin.

So if you create your own Plugin then you have all freedom.

This is of course more a Developer thing, but even as a newbie you can do it: plugins indeed only consists of a few short files.

So you can simply duplicate a similar existing Custom Field Type and customize it to your needs.

By installing an existing Custom Field Type

There are so many Custom Fields out there that you will almost never need to create your own.

The first place to look is of course the Joomla Extensions Directory (JED), where a dedicated Category has been created: https://extensions.joomla.org/category/authoring-a-content/custom-fields/

Many Custom Fields are not published on the JED though: they are for example only published on Github since they are just little plugins consisting of a few files.

Amongst the most common extra Types of Custom Fields, we can think of

• image galleries
• link to other articles
• video (YouTube / Vimeo / ...)
• maps (Google Maps / OpenStreetMap / ...)
• ...

Read more

There are many resources about Custom Fields, starting with the official Documentation:

https://docs.joomla.org/J3.x:Adding_custom_fields

In the present Magazine several articles were already devoted to Custom Fields:

• https://magazine.joomla.org/all-issues/march-2018/how-far-can-we-go-with-joomla-and-custom-fields
• https://magazine.joomla.org/all-issues/may-2018/custom-fields-episode-2-how-to-manage-your-custom-fields
• https://magazine.joomla.org/all-issues/october-2018/custom-fields-episode-3-all-the-parameters-one-can-wish-for
• https://magazine.joomla.org/all-issues/april-2020/custom-fields-episode-4-a-step-by-step-tutorial

And the good news is: in the near future I plan to release another couple of articles about Custom Fields.

In particular a list of resources, namely

• a list of all the Custom Fields Types or Extensions exploiting Custom Fields (like Filters, ...)
• and a list of all the Presentations (slides, videos, ...) related to Custom Fields