Joomla! Documentation™

Tobias Zulauf - zero24

I'm a specialist for system integration in Germany. I'm involved with Joomla! since 2011.

• tobias.zulauf[at]community.joomla.org
• https://www.jah-tz.de
• https://github.com/zero-24
• https://volunteers.joomla.org/joomlers/tobias-zulauf

---

Implement fields into your component

This article describes how to apply a basic implementation of the custom fields feature to your custom component.

Ever wanted to show additional attributes in your items? Through custom fields, you have a seamlessly integrated way to show them in the backend and frontend of your site.
Custom fields offers 15 different types, if you need more you can create your own plugin (different tutorial).
The custom fields extension is placed in core and can be used in a similar way to the categories extension. Basically there are just 2 files you need to extend with the following code for the basic backend part.
Note! In the example code we will use for your component the name com_example.

The Backend Part

How to add fields to the backend lists

Similar to com_categories there are just a few lines needed to add the fields in the backend view. Just add the following lines to the method addSubmenu in your component helper class.
The used context needs to match the context you want to implement the fields in. An example of context could be com_content.article or com_weblinks.weblink. We’re using com_example.item here as example. Everything expect the context option need not be changed.

if (JComponentHelper::isEnabled('com_fields'))
{
	JHtmlSidebar::addEntry(
		JText::_('JGLOBAL_FIELDS'),
		'index.php?option=com_fields&context=com_example.item',
		$vName == 'fields.fields'
	);

	JHtmlSidebar::addEntry(
		JText::_('JGLOBAL_FIELD_GROUPS'),
		'index.php?option=com_fields&view=groups&context=com_example.item',
		$vName == 'fields.groups'
	);
}

Implement the ACL

Now the ACL part needs to be done. You have to add the following lines to your access xml file just before the closing </access> in that file. Here they are defined and will allow your users to choose the ACL settings in your implementation of com_fields.

	<section name="fieldgroup">
		<action name="core.create" title="JACTION_CREATE" description="COM_FIELDS_GROUP_PERMISSION_CREATE_DESC" />
		<action name="core.delete" title="JACTION_DELETE" description="COM_FIELDS_GROUP_PERMISSION_DELETE_DESC" />
		<action name="core.edit" title="JACTION_EDIT" description="COM_FIELDS_GROUP_PERMISSION_EDIT_DESC" />
		<action name="core.edit.state" title="JACTION_EDITSTATE" description="COM_FIELDS_GROUP_PERMISSION_EDITSTATE_DESC" />
		<action name="core.edit.own" title="JACTION_EDITOWN" description="COM_FIELDS_GROUP_PERMISSION_EDITOWN_DESC" />
		<action name="core.edit.value" title="JACTION_EDITVALUE" description="COM_FIELDS_GROUP_PERMISSION_EDITVALUE_DESC" />
	</section>
	<section name="field">
		<action name="core.delete" title="JACTION_DELETE" description="COM_FIELDS_FIELD_PERMISSION_DELETE_DESC" />
		<action name="core.edit" title="JACTION_EDIT" description="COM_FIELDS_FIELD_PERMISSION_EDIT_DESC" />
		<action name="core.edit.state" title="JACTION_EDITSTATE" description="COM_FIELDS_FIELD_PERMISSION_EDITSTATE_DESC" />
		<action name="core.edit.value" title="JACTION_EDITVALUE" description="COM_FIELDS_FIELD_PERMISSION_EDITVALUE_DESC" />
	</section>

There is one more entry setting in that file:

    <action name="core.edit.value" title="JACTION_EDITVALUE" description="JACTION_EDITVALUE_COMPONENT_DESC" />

This entry should be made under the normal settings in your component (and also in the access xml file) as it allows users in the group to edit any value of custom fields submitted in your component.

Result

If you completed these steps, your backend part for fields implementation is done. The users can now create fields and assign them to an item.

The Frontend Part

Now let's go to the frontend part. It is easy as the fields are rendered, through the Plugin/Events/Content events on the frontend.

To display fields on the frontend, you need to implement the content plugin events in your component. Important here is where you pass the same context that you used in the backend to the events.

See:

• onContentAfterTitle
• onContentBeforeDisplay
• onContentAfterDisplay
• onContentPrepare

After the onContentPrepare event is fired with the context you can find the attached fields in $item->jcfields property if you want to render the fields using in your layouts / views.

Tips, Tricks & Hidden Features

Here you can find some tips and tricks on what can be gone wrong with your implementation as well as some hidden features of com_fields.

The fields tab don’t show up in my component's edit view

In some components the edit views in backend and/or frontend are hardcoded and can't be changed / extended using plugins. But as the fields uses a plugin to add the fields to your component you need to support that in order to support fields. You can make sure that fields are rendered e.g. by implementing the following layout in your component edit view:

    <?php $this->ignore_fieldsets = array('general', 'info', 'detail', 'jmetadata', 'item_associations'); ?>
    <?php echo JLayoutHelper::render('joomla.edit.params', $this); ?>

The first line makes sure we ignore the (eventually hardcoded fieldsets) and than render the dynamic fields tab using the joomla.edit.params layout.

Public helper classes and API

The class FieldsHelper has some public API functions to work with fields.

    JLoader::register('FieldsHelper', JPATH_ADMINISTRATOR . '/components/com_fields/helpers/fields.php');
    $fields = FieldsHelper::getFields('com_example.item', $item, true);

The field model itself allows to get and store the value of a field.

    JModelLegacy::addIncludePath(JPATH_ADMINISTRATOR . '/components/com_fields/models', 'FieldsModel');
    $fieldModel = JModelLegacy::getInstance('Field', 'FieldsModel', array('ignore_request' => true));
    $fieldModel->setValue($fieldId, 'com_example.item', $item->id, ‘demo value’);

ACL support

• Every field has an access level
• Every field has a new permission edit.value

JFactory::getUser()->authorise('edit.value', ‘com_example.item.field.' . (int) $field->id);

More Informations

• https://www.youtube.com/watch?v=7ikOaOKyo6s | JAB16 - Custom Fields in Joomla for developers - English
• https://www.youtube.com/watch?v=F_Ni15icn1U | JD16AT - Custom fields since Joomla 3.7 - English
• https://joomla.digital-peak.com/images/blog/JDD16%20Custom%20fields%20in%20Joomla%20for%20developers.pdf

---

Developers

Introduction

If your extension can support association and you would like it to be available in the Associations Manager, you'll have to provide a helper class.

Basically, you need to create a file associations.php in your component administrator helper directory. If your component is named Example the helper class should be named ExampleAssociationsHelper and this class needs to extend JAssociationExtensionHelper.

Add three protected variables

	/**
	 * The extension name
	 *
	 * @var     array   $extension
	 *
	 * @since   3.7.0
	 */
	protected $extension = 'com_example';

	/**
	 * Array of item types
	 *
	 * @var     array   $itemTypes
	 *
	 * @since   3.7.0
	 */
	protected $itemTypes = array('item');

	/**
	 * Has the extension association support
	 *
	 * @var     boolean   $associationsSupport
	 *
	 * @since   3.7.0
	 */
	protected $associationsSupport = true;

Add three public functions

Method getAssociations

This function should return an array of associated items.

	/**
	 * Get the associated items for an item
	 *
	 * @param   string  $typeName  The item type
	 * @param   int     $id        The id of item for which we need the associated items
	 *
	 * @return  array
	 *
	 * @since   3.7.0
	 */
	public function getAssociations($typeName, $id)
	{
		// The code goes here.
	}

Method getItem

This function should return a JTable Object for the type and id. Don't forget something like JTable::addIncludePath(__DIR__ . '/../tables'); so that the class can be found.

	/**
	 * Get item information
	 *
	 * @param   string  $typeName  The item type
	 * @param   int     $id        The id of item for which we need the associated items
	 *
	 * @return  JTable|null
	 *
	 * @since   3.7.0
	 */
	public function getItem($typeName, $id)
	{
		// The code goes here.
	}

Method getType

This function should return an array of item types

	/**
	 * Get information about the type
	 *
	 * @param   string  $typeName  The item type
	 *
	 * @return  array  Array of item types
	 *
	 * @since   3.7.0
	 */
	public function getType($typeName = '')
	{
		// The code goes here.
	}

Here you set up information per type, the function returns an array

array(
	'fields'  => $fields,
	'support' => $support,
	'tables'  => $tables,
	'joins'   => $joins,
	'title'   => $title,
);

For fields and support we have a template function that set defaults so you only have to overwrite what is different in your extension. Please make sure that $fields['title'] and $fields['state'] are set correctly.

Example of Implementation

You can find an example for integrating multilingual associations in a component at GitHub.

• com_content
• com_contact
• com_newsfeeds
• com_menus
• com_weblinks

For more information about the feature itself please have a look into the Pull Request for this feature.