A new feature in Joomla 5.2 makes life so much easier for Joomla component developers!

It's called the ModalSelect standard field, and it provides a really easy way to implement a modal window in your component.

What is a Modal?

Just in case you weren't sure ...

As an example, a modal is what appears when you create a menuitem pointing to a single article, and you click on "Select" to choose the article to appear. It's a much better way of presenting the articles to a user, compared to, say, a dropdown list of articles.

How does it work?

The modal above is an HTML iframe element displaying clickable elements. When you click on an element some JavaScript code communicates the id of your selection to the main window, so that it gets set in the form input element there. In the case of creating a menuitem, the selected article gets put into the Select Article field of the form.

However, in a custom component you had to write this JavaScript code yourself, and getting it correct could be quite tricky. (How to do it is documented in the Joomla 3 MVC Tutorial Adding a Modal step.)

That's where the ModalSelect field is so useful. Now to implement a modal allowing a user to select an article you just include the ModalSelect field in your form definition XML like this:

<field
  type="ModalSelect"
  name="article"
  label="Article"
  select="true"
  titleSelect="Selecting the Article"
  urlSelect="index.php?option=com_content&amp;view=articles&amp;layout=modal&amp;tmpl=component"
  clear="true"
  sql_title_table="#__content"
  sql_title_column="title"
  sql_title_key="id"
/>

Using ModalSelect in a Custom Component

Within your custom component you're likely to have your own database entities, and you may want to have a modal to allow users to select one of those entities. This is also possible with the ModalSelect field.

(The ModalSelect field has been in use within Joomla core for a few Joomla 5 releases, but it's only since Joomla 5.2 that you can use it with your own entities).

If you want to enable a ModalSelect for your custom component, then you need to do the following.

For your equivalent of the administrator com_content articles view you need to write your equivalent of administrator/components/com_content/tmpl/articles/modal.php.

This differs from articles.php (in the same folder) in the following key details, which you need to replicate:

1. include the system modal-select-field.js code:

   $this->document->getWebAssetManager()->useScript('modal-content-select');

2. specify '&tmpl=component' within the `<form action="...">` URL. This means that the display will use the template component.php file instead of index.php file within the iframe, and will avoid displaying the Joomla toolbar, for example.
3. on your fields within the display which you want to allow users to select by clicking, add the following attributes
   

   $attribs = 'data-content-select'
           . ' data-id="' . $row->id . '"'
           . ' data-title="' . $this->escape($row->title) . '"';

    (Change `$row->id` and `$row->title` to match your fields).

The 'data-content-select' is used by the Joomla dialog to define that this HTML element should be clickable.

The 'data-id' and 'data-title' fields are used to define the values of the id and title for the ModalSelect field.

You'll also need to select this modal.php tmpl file by specifying "&amp;layout=modal" within the `urlSelect` attribute.

Then you can include your ModalSelect field in one of your XML form definitions, setting the urlSelect attribute to point to modal.php layout.

Examples

The Joomla MVC Component tutorial has been updated for Joomla 4, and the modal functionality changed to use the ModalSelect field. You can find the code at this repo, and the key sections of code are in:

• admin/tmpl/helloworlds/modal.php (the form displayed in the modal iframe)
• site/tmpl/helloworld/default.xml (the XML form used to set up a menuitem to a "helloworld" greeting)

During the covid pandemic I wrote a little event booking tool as a custom component on our Joomla website. As numbers at meetings were limited, people had to use the tool to book places. The administrator "bookings" form displayed all the bookings, and I implemented a modal within the filter fields for that bookings form to enable the administrator to view the bookings for a particular event.

I updated the code to use the ModalSelect field, and if you're interested you can find it at:

• admin/tmpl/events/modal.php (the form displayed in the modal iframe)
• admin/forms/filter_bookings.php (the filter fields XML form)

The ModalSelect field is documented in the Joomla Manual (make sure the version you have selected is 5.2 or later). You can find there a link to an "example form" component. You can download this, add a ModalSelect into the XML form there, and try it out for yourself.

Acknowledgements

Thanks are due to Fedir Zinchek who (as far as I know) designed and implemented this great feature.