How to create Custom Fields Layout Overrides to use in Articles Anywhere

In this tutorial you will learn how to create and use both Layout Overrides and Value Layout Overrides for Joomla! Custom Fields when displaying them with Articles Anywhere.

Introduction

With the Pro version of Articles Anywhere, you can display any Joomla! Custom Field of an article using the name of that specific field.

Let's say you want to show the value of the custom field "Habitat" - that has a field name habitat_area - of article "Lions". You can simply do:

{article Lions}[habitat_area]{/article}

By default the custom field will be output as plain text without any html markup around it.

But in the data tag you are able to customize the output of the custom field by setting a Layout and even a Value Layout.

Let's take a look at how this is done, along with code examples to create those layouts:

Custom Field Layouts

First of all, if you want to output the custom field through its Layout, like the core plugin does, you can do:

[habitat_area layout="true"]

Articles Anywhere will use the layout assigned to that custom field in its Render Options (option introduced in Joomla 3.9).

However, in the data tag you can override the set layout with another one (to be placed inside templates/my_template/html/layouts/com_fields/field/), by simply inserting the name of the file in the layout="..." attribute:

[habitat_area layout="habitat-field"]

Alternatively, you can also insert the full path to your custom layout file:

[habitat_area layout="templates/my_template/html/layouts/com_fields/field/habitat-field.php"]

Layout Example

As a starting point when creating a custom layout file, you can see how the default layout file is made (which is located at: components/com_fields/layouts/field/render.php).

So you can copy this render.php file to - for instance - templates/my_template/html/layouts/com_fields/field/habitat-field.php. And then edit it to meet your needs.

The following custom layout file example will output the custom field in a nice Bootstrap well format like:

Africa, Asia, Europe
<?php
defined('_JEXEC') or die;

if (empty($displayData['field']))
{
return;
}

$field = $displayData['field'];
$value = $field->value;

if ($value == '')
{
return;
}

$label = JText::_($field->label);
$showLabel = $field->params->get('showlabel');
$labelClass = $field->params->get('label_render_class');
?>
<div class="well">
<?php if ($showLabel == 1) : ?>
<h3 class="page-header <?php echo $labelClass; ?>">
<?php echo $label; ?>
</h3>
<?php endif; ?>
<span>
<?php echo $value; ?>
</span>
</div>

Value Layouts

In addition to the Field Layout, Articles Anywhere also allows you to customize the output specifically related to the "value" part of a custom field.

This can come especially useful if you need further control on custom field types that have multiple values (like lists, checkboxes and multi-select fields).

You can pass the name of your custom value layout file to the data tag with a value_layout="..." attribute:

[habitat_area value_layout="bullet-list-values"]

Or use the full path to the layout file:

[habitat_area value_layout="templates/my_template/html/layouts/com_fields/field/bullet-list-values.php"]

Example: Simple Field

The following file examples are for cases where your custom field only contains a single value, such as in fields of type "Text", or "Integer".

Say we want to display a numeric value with a nice format, with grouped thousands (for instance, a value of "1350230" will be displayed as "1,350,230"):

<?php
defined('_JEXEC') or die;

if (empty($displayData['values']))
{
return;
}

$value = reset($displayData['values']);

if (is_numeric($value))
{
$value = number_format($value);
}
?>
<span class="formatted-value"><?php echo $value; ?></span>

Or if you want to hide the value from guests visitors, and only show it if the user is logged-in:

<?php
defined('_JEXEC') or die;

if (empty($displayData['values']))
{
return;
}

$value = reset($displayData['values']);

if (JFactory::getUser()->guest)
{
$value = 'Log in to see the value...';
}
?>
<span class="my-value"><?php echo $value; ?></span>

Or you could simply leave the value as it is and just wrap it in a span element with a certain class. You get the idea.

Example: List Field

Customizing Value Layouts is especially useful if you need further control on custom field types that have multiple values, such as in fields of type "List", or "Checkboxes".

The following file example will output the multiple values in a bullet points list like:

  • Africa
  • Asia
  • Europe
<?php
defined('_JEXEC') or die;

if (empty($displayData['values']))
{
return;
}
?>
<ul>
<?php foreach ($displayData['values'] as $value => $text) : ?>
<li class="item_<?php echo $value; ?>">
<?php echo $text; ?>
</li>
<?php endforeach; ?>
</ul>

Example: Articles Field

You can also use a custom Value Layout when displaying a custom field of type "Articles Field", another Regular Labs Extension. Articles Field is a Joomla! custom field type that gives you the ability to choose and display a list of articles, allowing you to directly link articles to each other.

The Pro version of Articles Field already allows to fully customize the output of the linked articles in the article page, thanks to its Custom HTML Layout feature. But what if you would like to output an Articles Field with a different/alternate layout when displaying it through Articles Anywhere? You can, too!

Similarly to the above example for a List Field (the concept is the same), the following file example will wrap the output of each linked article in a label style (span with a label class):

<?php
defined('_JEXEC') or die;

if (empty($displayData['values']))
{
return;
}
?>
<?php foreach ($displayData['values'] as $id => $output) : ?>
<span class="label" id="item_<?php echo $id; ?>">
<?php echo $output; ?>
</span>
<?php endforeach; ?>

But... that is rather limiting. As you might want to put together a completely different layout compared to what you have defined for the default output.

For example, say you have "Conference" articles, and for each conference, you assign "Speakers" articles via Articles Field. You might want to show a full size image and the bio of the Speaker in the detailed view of the conference, but only display a resized picture and the name of the speaker in a Timetable page.

Well, you can do this by using Articles Anywhere again inside this Value Layout file. Yes, pretty crazy inception stuff, but it works! This allows you to take advantage of the full range of Data Tags offered by Articles Anywhere to customize the layout.

The below Value Layout file passes the list of linked articles IDs to Articles Anywhere. Then, Articles Anywhere outputs a resized image and the title for each linked article:

<?php
defined('_JEXEC') or die;

if (empty($displayData['values']))
{
return;
}

$values = $displayData['values'];
$ids = array_keys($values);
?>

{articles articles="<?php echo implode(',', $ids); ?>"}
<div class="item">
<div class="pull-left item-image">
[link][image-intro height="20"][/link]
</div>
[link][title][/link]
</div>
{/articles}

Note: The ability to create an alternate Value Layout for "Articles Field" is only possible when using the "Articles" field type. It won't work when the field uses the "Articles - Linked" type, as in that case the field value is just a toggle between true or false.

For a complete overview of all the features included in Articles Anywhere, head over to the full Documentation, and check out the Video Tutorials