Blog

Customizing the Joomla result messages per view

Whenever you publish, unpublish, trash, archive, or delete an item a message is shown like 1 item published. This message is informative but general as well. When you are in the article view this message will read 1 article published. This is already more specific, this tells us exactly that 1 article has published and not just an item. Most components have more than 1 view and each view will display the same message 1 item published like the Smart Search in Joomla. That can be done better.

1 item published

 Let's take an example component with multiple views and these views are:

  • Products
  • Payment
  • Shipment

By default all these views will respond with the message 1 item published, our goal is to customize the result message to become:

  • 1 product published
  • 1 payment published
  • 1 shipment published

In addition we want the messages to be also pluralized in case multiple entries are published. This means the result message becomes:

  • 2 products published
  • 2 payments published
  • 2 shipments published

Controller

The plural controller handles all the tasks related to publishing, unpublishing, trashing, archiving and deleting. This is also the place where the result messages are constructed. By default the result message is constructed using the following code:

$ntext = $this->text_prefix . '_N_ITEMS_PUBLISHED';

One thing to note is the use of $this->text_prefix. This is the little bit of magic that makes the messages customizable. By default this variable gets set to the option variable in the URL which is the unique identifier for a component for example com_content, com_banners and so on. In our case that will be com_example.

In the language file we would only need to add the string COM_EXAMPLE_N_ITEMS_PUBLISHED and we would be done. However our goal is to not use 1 message for all but to have each view show a specific message. To be able to achieve that we need to add the $text_prefix in each of our controllers. So what needs to be done is to add the following prefixes:

  • Products
    protected $text_prefix = 'COM_EXAMPLE_PRODUCT';​
  • Payments
    protected $text_prefix = 'COM_EXAMPLE_PAYMENT';​
  • Shipments
    protected $text_prefix = 'COM_EXAMPLE_SHIPMENT';​

Now we will have a customized message per view as the final language strings will be:

  • COM_EXAMPLE_PRODUCT_N_ITEMS_PUBLISHED
  • COM_EXAMPLE_PAYMENT_N_ITEMS_PUBLISHED
  • COM_EXAMPLE_SHIPMENT_N_ITEMS_PUBLISHED

Pluralization

When items are published for example you can have more than 1 item that is published, in that case you want to see the message say 2 items published instead of 2 item published. The latter is incorrect language so we need a system to be able to deal with that. That system is called pluralization and is included in Joomla.

The message is translated using the following command:

Text::plural($ntext, count($cid))

The plural function contains all the magic in regards to dealing with plurals in a language. Plurals come by default in 3 forms:

  • 0
  • 1
  • MORE

Some languages have others as well, Russian for example has 2 as well. This is only of concern for the translators as long as you implement plurals using JText::plural().

The plurals are added to the language strings we defined earlier. Using the 3 forms, we get the final languages strings as:

  • COM_EXAMPLE_PRODUCT_N_ITEMS_PUBLISHED_0
  • COM_EXAMPLE_PRODUCT_N_ITEMS_PUBLISHED_1
  • COM_EXAMPLE_PRODUCT_N_ITEMS_PUBLISHED_MORE
  • COM_EXAMPLE_PAYMENT_N_ITEMS_PUBLISHED_0
  • COM_EXAMPLE_PAYMENT_N_ITEMS_PUBLISHED_1
  • COM_EXAMPLE_PAYMENT_N_ITEMS_PUBLISHED_MORE
  • COM_EXAMPLE_SHIPMENT_N_ITEMS_PUBLISHED_0
  • COM_EXAMPLE_SHIPMENT_N_ITEMS_PUBLISHED_1
  • COM_EXAMPLE_SHIPMENT_N_ITEMS_PUBLISHED_MORE

So instead of the original 1 language string, we now have 9 language strings that allow us to make very specific messages.

 No selected items

There is one special case we should not forget about, that is when no item has been found. Joomla then generates the language string COM_EXAMPLE_NO_ITEM_SELECTED. Since we customized the text prefix, this now becomes:

  • COM_EXAMPLE_PRODUCT_NO_ITEM_SELECTED
  • COM_EXAMPLE_PAYMENT_NO_ITEM_SELECTED
  • COM_EXAMPLE_SHIPMENT_NO_ITEM_SELECTED

Language file

The final language strings are now known and can be added to the language file. Each language string is going to use a placeholder for the number, this is to replace it with the actual number of items that have been published.

COM_EXAMPLE_PRODUCT_NO_ITEM_SELECTED="No product selected"
COM_EXAMPLE_PRODUCT_N_ITEMS_PUBLISHED_0="No product published"
COM_EXAMPLE_PRODUCT_N_ITEMS_PUBLISHED_1="1 product published"
COM_EXAMPLE_PRODUCT_N_ITEMS_PUBLISHED_MORE="%s products published"
COM_EXAMPLE_PAYMENT_NO_ITEM_SELECTED="No payment selected"
COM_EXAMPLE_PAYMENT_N_ITEMS_PUBLISHED_0="No payment published"
COM_EXAMPLE_PAYMENT_N_ITEMS_PUBLISHED_1="1 payment published"
COM_EXAMPLE_PAYMENT_N_ITEMS_PUBLISHED_MORE="%s payments published"
COM_EXAMPLE_SHIPMENT_NO_ITEM_SELECTED="No shipment selected"
COM_EXAMPLE_SHIPMENT_N_ITEMS_PUBLISHED_0="No shipment published"
COM_EXAMPLE_SHIPMENT_N_ITEMS_PUBLISHED_1="1 shipment published"
COM_EXAMPLE_SHIPMENT_N_ITEMS_PUBLISHED_MORE="%s shipments published"

All done and now you can customize the messages as you need.