|
|
| (17 intermediate revisions by 2 users not shown) |
| Line 7: |
Line 7: |
| * https://github.com/zero-24 | | * https://github.com/zero-24 |
| * https://volunteers.joomla.org/joomlers/tobias-zulauf | | * https://volunteers.joomla.org/joomlers/tobias-zulauf |
|
| |
|
| |
|
| |
| ------
| |
|
| |
| == Implement fields into your component ==
| |
|
| |
| This is an article on how to do a basic implemention of the custom fields feature into your custom component. <br />
| |
|
| |
| Ever wanted to show additional attributes in your items? Through custom fields, you have a seamlessly integrated way to show them on the backend and frontend. <br />
| |
| Custom fields offer 15 different types, if you need more you can create your own plugin (different tutorial).<br />
| |
| The custom fields extension is placed in core and can be used similar to the categories extension.
| |
| Basically there are just 2 files you need to extend with the following code for the basic backend part.<br />
| |
| '''Note!''' In the example code we will use for your component the name <tt>com_example</tt>.
| |
|
| |
| === The Backend Part ===
| |
|
| |
| ==== How to add fields to the backend lists ====
| |
|
| |
| Similar to <tt>com_categories</tt> there are just a few lines involved to add the fields in the backend view.
| |
| Just add the following lines to the method <code>addSubmenu</code> in your component helper class.<br />
| |
| The used context needs to match the context you want to implement the fields in. An example of context could be <tt>com_content.article</tt> or <tt>com_weblinks.weblink</tt>. We’re using <tt>com_example.item</tt> here as example. Everything expect the context option don’t need to be changed.
| |
|
| |
| <source lang="php">
| |
| 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'
| |
| );
| |
| }
| |
| </source>
| |
|
| |
| ==== Implement the ACL ====
| |
|
| |
| Now the ACL part which needs to be done. You have to add the following lines to your access xml file just before the closing <code></access></code> in that file. They are defined and so will allow your users to choose the ACL settings in your implemention of <tt>com_fields</tt>.
| |
|
| |
| <source lang=xml>
| |
| <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>
| |
| </source>
| |
|
| |
| There is one more entry setting in that file:
| |
| <source lang=xml>
| |
| <action name="core.edit.value" title="JACTION_EDITVALUE" description="JACTION_EDITVALUE_COMPONENT_DESC" />
| |
| </source>
| |
|
| |
| This entry should be made under the normal settings in your component (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 this steps, you are done and have the backend part for fields implementation. The users can now create fields and assign them to item.
| |
|
| |
| === The Frontend Part ===
| |
|
| |
| Now let's go to the frontend part. It is easy as the fields are rendered, through the [[S:MyLanguage/Plugin/Events/Content|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 that you pass the same context as you used in the backend to that events.
| |
|
| |
| See:
| |
| *[[S:MyLanguage/Plugin/Events/Content#onContentAfterTitle|onContentAfterTitle]]
| |
| *[[S:MyLanguage/Plugin/Events/Content#onContentBeforeDisplay|onContentBeforeDisplay]]
| |
| *[[S:MyLanguage/Plugin/Events/Content#onContentAfterDisplay|onContentAfterDisplay]]
| |
| *[[S:MyLanguage/Plugin/Events/Content#onContentPrepare|onContentPrepare]]
| |
|
| |
| After the onContentPrepare event is fired with the context you can find the attached fields in <code>$item->jcfields</code> property.
| |
|
| |
| === Tips, Tricks & Hidden Features ===
| |
|
| |
| Here you can find some tips and tricks about what can be gone wrong on implemention as well as some hidden features of com_fields.
| |
|
| |
| ==== The fields tab don’t show up in my componente 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 fiels are renderd e.g. by implementing the following layout in your compontent edit view:
| |
|
| |
| <source lang=php>
| |
| <?php $this->ignore_fieldsets = array('general', 'info', 'detail', 'jmetadata', 'item_associations'); ?>
| |
| <?php echo JLayoutHelper::render('joomla.edit.params', $this); ?>
| |
| </source>
| |
|
| |
| The first line makes sure we ignore the (eventualy hardcoded fieldsets) and than render the dynamic fields tab using the <code>joomla.edit.params</code> layout.
| |
|
| |
|
| |
| ==== Multiple contexts ====
| |
|
| |
| If your component has multiple contexts, for example Contacts has item and E-Mail form fields, add a filter form file to administrator/com_example/models/forms/filter_fields.xml.
| |
|
| |
| <source lang=xml>
| |
| <?xml version="1.0" encoding="utf-8"?>
| |
| <form>
| |
| <fields name="custom">
| |
| <fieldset name="custom">
| |
| <field
| |
| name="section"
| |
| type="section"
| |
| default="com_example.item"
| |
| >
| |
| <option value="com_example.item">COM_EXAMPLE_FILTER_ITEM />
| |
| <option value="com_example.mail">COM_EXAMPLE_FILTER_ITEM />
| |
| </field>
| |
| </fieldset>
| |
| </fields>
| |
| <form>
| |
| </source>
| |
|
| |
| ==== Public helper classes and API ====
| |
| The class FieldsHelper has some public API functions to work with fields.
| |
|
| |
| <source lang=php>
| |
| JLoader::register('FieldsHelper', JPATH_ADMINISTRATOR . '/components/com_fields/helpers/fields.php');
| |
| $fields = FieldsHelper::getFields(‘com_example.item’, $item, true);
| |
| </source>
| |
|
| |
| The field model itself allows to get and store the value of a field.
| |
|
| |
| <source lang=php>
| |
| 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’);
| |
| </source>
| |
|
| |
| ==== ACL support ====
| |
|
| |
| * Every field has an access level
| |
| * Every field has a new permission edit.value
| |
|
| |
| <code>JFactory::getUser()->authorise('edit.value', ‘com_example.item.field.' . (int) $field->id);<code>
| |
|
| |
| === More Informations ===
| |
| * https://www.youtube.com/watch?v=7ikOaOKyo6s | JAB16 - Custom Fields in Joomla for developers - englisch
| |
| * https://www.youtube.com/watch?v=F_Ni15icn1U | JD16AT - Custom fields since Joomla 3.7 - englisch
| |
| * 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 <tt>associations.php</tt> in your component administrator helper directory. If your component is named <tt>Example</tt> the helper class should be named <tt>ExampleAssociationsHelper</tt> and this class needs to extend <tt>JAssociationExtensionHelper</tt>.
| |
|
| |
| === Add three protected variables ===
| |
|
| |
| <source lang=php>
| |
| /**
| |
| * 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;
| |
| </source>
| |
|
| |
|
| |
| === Add three public functions ===
| |
|
| |
| ==== Method <code>getAssociations</code> ====
| |
|
| |
| This function should return an array of associated items.
| |
|
| |
| <source lang=php>
| |
| /**
| |
| * 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.
| |
| }
| |
| </source>
| |
|
| |
| ==== Method <code>getItem</code> ====
| |
|
| |
| This function should return a JTable Object for the type and id. Don't forget something like <code>JTable::addIncludePath(__DIR__ . '/../tables');</code> so that the class can be found.
| |
|
| |
| <source lang=php>
| |
| /**
| |
| * 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.
| |
| }
| |
| </source>
| |
|
| |
| ==== Method <code>getType</code> ====
| |
|
| |
| This function should return an array of item types
| |
|
| |
| <source lang=php>
| |
| /**
| |
| * 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.
| |
| }
| |
| </source>
| |
|
| |
| Here you set up information per type, the function returns an array
| |
|
| |
| <source lang=php>
| |
| array(
| |
| 'fields' => $fields,
| |
| 'support' => $support,
| |
| 'tables' => $tables,
| |
| 'joins' => $joins,
| |
| 'title' => $title,
| |
| );
| |
| </source>
| |
|
| |
| 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.
| |
|
| |
| * [https://github.com/joomla/joomla-cms/blob/staging/administrator/components/com_content/helpers/associations.php com_content]
| |
| * [https://github.com/joomla/joomla-cms/blob/staging/administrator/components/com_contact/helpers/associations.php com_contact]
| |
| * [https://github.com/joomla/joomla-cms/blob/staging/administrator/components/com_newsfeeds/helpers/associations.php com_newsfeeds]
| |
| * [https://github.com/joomla/joomla-cms/blob/staging/administrator/components/com_menus/helpers/associations.php com_menus]
| |
| * [https://github.com/joomla-extensions/weblinks/blob/master/src/administrator/components/com_weblinks/helpers/associations.php com_weblinks]
| |
|
| |
| For more information about the feature itself please have a look into the [https://github.com/joomla/joomla-cms/pull/13537 Pull Request] for this feature.
| |