|
|
| (28 intermediate revisions by 3 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.
| |
| Ever wanted to show additional attributes on an your items, through custom fields, you have a seamlessly integrated way to show them on the backend and front end.
| |
| Custom fields offer 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 similiar tot he categories extension.
| |
| Basicly there are just 3 files you need to extend with the following code.
| |
| '''Note''' In the example code i will use for your componente name <code>com_example</code>.
| |
|
| |
| === The Backend Part ===
| |
|
| |
| ==== How to add fields to the backend lists ====
| |
| Similiar too com_categories the are are just a few lines involved to add the fields backend view.
| |
| Just add the following lines too the method <code>addSubmenu</code> in your component helper class.
| |
| '''Note''' We are checking here for a option we going to add in the next step.
| |
| The used context needs to match the context you want to implement fields in. An example context could be <code>com_content.article</code> or <code>com_weblinks.weblink</code> I’m using <code>com_example.item</code> here as example. Everything expected the context option and the first if don’t need to be changed.
| |
| <source lang="php">
| |
| if (JComponentHelper::isEnabled('com_fields') && JComponentHelper::getParams('com_example')->get('custom_fields_enable', '1'))
| |
| {
| |
| 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 a option to switch fields on and off ====
| |
| As you may don’t want fields enabled on any site or it should be allowed to disable it lets add a option to enable or disable this feature.
| |
| Just adding the following line to your configuration xml file.
| |
| <source lang="xml">
| |
| <field
| |
| name="custom_fields_enable"
| |
| type="radio"
| |
| label="JGLOBAL_CUSTOM_FIELDS_ENABLE_LABEL"
| |
| description="JGLOBAL_CUSTOM_FIELDS_ENABLE_DESC"
| |
| default="0"
| |
| class="btn-group btn-group-yesno"
| |
| >
| |
| <option value="1">JYES</option>
| |
| <option value="0">JNO</option>
| |
| </field>
| |
| </source>
| |
|
| |
| ==== Implement the needed ACL ====
| |
| Now the last part needs to be done and it is ACL. Just adding the following lines to your access xml file just before the closing <code></access></code> in that file. They are defiing and let your users choose the ACL settings for your implemention of com_fields.
| |
| <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>
| |
|
| |
| But there is on more setting entry 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 for 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 three steps you are done and have the backend part for fields implemented. The users can now create fields and assign them to your item.
| |
|
| |
|
| |
| === The Frontend Part ===
| |
|
| |
| Now we come to the frontend part. To display fields to the frontend you need to implement the following plugin events with your component.
| |
|
| |
| 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]]
| |
|
| |
| TBC (to be completed)
| |
|
| |
| -------
| |
|
| |
|
| |
| ==Developers==
| |
|
| |
| === Introducion ===
| |
| If your extension support association and you will make your extension available in the Associations Manager you have to provide a helper class.
| |
|
| |
| Basicly you need to create a file <code>associations.php</code> in your component administrator helper directory. If your component is named <code>Example</code> the helper class should be named <code>ExampleAssociationsHelper</code> and this class needs to extend <code>JAssociationExtensionHelper</code>.
| |
|
| |
| === 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 the you only have to overwrite what is different in your extension.
| |
| Please make sure that $fields['title'] and $fields['state'] are set right.
| |
|
| |
| === Example 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.
| |