'''table''' gives the complete table class information for the table class stored as a JSON object in which the first element represents your "special" table and the second an optional common table (otherwise it will default the JTableCorecontent. This includes the name of the database table, the name of the primary key, the prefix, the name, an option array as used in your constructor and getInstance() methods. This enables the tagging system (and other APIs) to access your table easily.

'''table''' gives the complete table class information for the table class stored as a JSON object in which the first element represents your "special" table and the second an optional common table (otherwise it will default the JTableCorecontent. This includes the name of the database table, the name of the primary key, the prefix, the name, an option array as used in your constructor and getInstance() methods. This enables the tagging system (and other APIs) to access your table easily.

−

If you are using Joomla categories make sure to create a category type so that they can be tagged. In Joomla 3.1 and 3.1.1 there is an error where the tag field will show even if there is not a type, but this will be corrected in 3.1.2.

+

If you are using Joomla categories make sure to create a category type so that they can be tagged. In Joomla 3.1 and 3.1.1 there is an error where the tag field will show even if there is not a type, but this is corrected in 3.1.4.

−

'''Important note''' : Please note that the table name for the common table is #__ucm_content. This is INCORRECT in 3.1 and 3.1.1 data but is not currently used. The data will be updated in 3.1.2.

+

'''Important note''' : Please note that the table name for the common table is #__ucm_content. This is INCORRECT in 3.1 and 3.1.1 data but is not currently used. The data was updated in 3.1.4.

Line 55:

Line 55:

'''field_mappings''' maps the names of specific fields in your table to a set of standard names. This mapping is stored as a JSON array with the first element mapping to the common fields and the second one mapping the other fields from the table.

'''field_mappings''' maps the names of specific fields in your table to a set of standard names. This mapping is stored as a JSON array with the first element mapping to the common fields and the second one mapping the other fields from the table.

−

'''Important note''' The JHelperTags and JUcm APIS at 3.1.1 supported arrays for this field, but as of 3.1.2 either arrays or objects with a default of objects are suppored.

+

'''Important note''' The JHelperTags and JUcm APIS at 3.1.1 supported arrays for this field, but as of 3.1.4 either arrays or objects with a default of objects are supported.

Management of tagging and associated data is largely handled through the store() method. This provides maximum flexibility for the handling of tags across many extensions.

+

−

+

−

If you don't have a store() method you will need to add one. The assumption is that tables will inherit from JTable.

+

−

+

−

The handling involves preStoreProcess(), a call to the parent store() method, and then a postStoreProcess().

+

−

+

−

<source lang="php">

+

−

$this->tagsHelper->preStoreProcess($this);

+

−

$result = parent::store($updateNulls);

+

−

+

−

return $result && $this->tagsHelper->postStoreProcess($this);

+

−

</source>

+

−

+

−

It is important that this be in the correct order since completion of tag processing depends on having primary key data from the parent store() method.

+

−

+

−

Note that much of this code is designed to prevent storage in in #__ucm_content when items are not tagged. If you want to always store in #__ucm_content you should modify the handling appropriately.

+

−

+

−

=== Add or modify a delete() method ===

+

−

+

−

The basic structure:

+

−

+

−

+

−

<source lang="php">

+

−

/**

+

−

* Method to delete a row from the database table by primary key value.

+

−

*

+

−

* @param integer $pk Primary key to delete.

+

−

*

+

−

* @return boolean True on success.

+

−

*

+

−

* @since 3.1

+

−

* @throws UnexpectedValueException

+

−

*/

+

−

public function delete($pk = null)

+

−

{

+

−

$result = parent::delete($pk);

+

−

return $result && $this->tagsHelper->deleteTagData($this, $pk);

+

−

}

+

−

+

−

</source>

+

−

+

−

This manages the deletion of all related data if a content item is deleted.

+

== Add tags to the getItem() method of the model ==

== Add tags to the getItem() method of the model ==

−

In the getItem() (or similar) method of your model add

+

'''Note: this was only required in 3.1.0 and 3.1.1. It should not be used in 3.1.4 or later.''' Please read the history of this page if you need instructions for older versions.

−

<source lang="php">

+

−

// Load item tags

+

−

if (!empty($item->id))

+

−

{

+

−

$item->tags = new JHelperTags;

+

−

$item->tags->getTagIds($item->id, 'com_contact.contact');

+

−

$item->metadata['tags'] = $item->tags;

+

−

}

+

−

</source>

+

−

changing to your component and alias name, matching what is in the type table.and changing the name of id property to the name of your primary key.

+

−

Note: It is our intent to make the storage field a property so that alternative fields can be used.

== Add a tag field to edit screens ==

== Add a tag field to edit screens ==

−

In any edit layouts where you want to allow tagging, you need to add the field to the xml and the appropriate layouts if necessary.

+

In any edit layouts where you want to allow tagging, you need to add the field to the xml and the appropriate layouts if necessary. The core layouts us a JLayout to manage this and the same layout by any extension.

−

Update: Note that there is new handling of this in the core. Tags in the edit screen '''MUST''' be part of a metadata <fields></fields> group. The core provides two JLayouts to help you manage standard layouts, one (details) for the metadata and one for the sidebar that includes the tabs.

+

Update: Note that in '''3.1.1 only''' there is special handling of this in the core. Tags in the edit screen '''MUST''' be part of a metadata <fields></fields> group. The core provides two JLayouts to help you manage standard layouts, one (details) for the metadata and one for the sidebar that includes the tabs. In update an extension to 3.1.4 you may need to fix adjust your edit views.

+

In 3.1.4 or later this special handling is not necessary. Best practice is to use the standard JLayouts since this provides a consistent experience for users.

<source lang="xml">

<source lang="xml">

Line 196:

Line 129:

if it is not already there. Usually multiple should be true unless you have a specific reason for it not to be.

if it is not already there. Usually multiple should be true unless you have a specific reason for it not to be.

In the core components in administrator, the field is in the group shown on the right, below the language field.

In the core components in administrator, the field is in the group shown on the right, below the language field.

+

+

Note: As of 3.1.2 if you wish to use the field to designate parent tags you must add parent="parent" to the xml definition of the field.

For each table/option/view you will need to make an entry in #__content_types. You can do this either using sql or postflight by creating an instance of JTableContenttype. Don't forget a category type if you use the Joomla categories API.

A string giving component.view (that would be in the page request, typically matching the model name) goes in the **type_alias** field.

table gives the complete table class information for the table class stored as a JSON object in which the first element represents your "special" table and the second an optional common table (otherwise it will default the JTableCorecontent. This includes the name of the database table, the name of the primary key, the prefix, the name, an option array as used in your constructor and getInstance() methods. This enables the tagging system (and other APIs) to access your table easily.

If you are using Joomla categories make sure to create a category type so that they can be tagged. In Joomla 3.1 and 3.1.1 there is an error where the tag field will show even if there is not a type, but this is corrected in 3.1.4.

Important note : Please note that the table name for the common table is #__ucm_content. This is INCORRECT in 3.1 and 3.1.1 data but is not currently used. The data was updated in 3.1.4.

The type_title field would potentially be used for display although this is not implemented currently except in the contentttype field. Usually it should begin with an upper case letter if it is in English. See note about how to make this translatable.

note:
To make your type names translatable add

COM_TAGS_CONTENT_TYPE_ + the type_title

in both the ini and sys.ini files.

Rules is currently not used. It will likely be removed in favor of an asset_id for each type, but currently you can ignore this field which will be managed by JTable.

field_mappings maps the names of specific fields in your table to a set of standard names. This mapping is stored as a JSON array with the first element mapping to the common fields and the second one mapping the other fields from the table.

Important note The JHelperTags and JUcm APIS at 3.1.1 supported arrays for this field, but as of 3.1.4 either arrays or objects with a default of objects are supported.

is the field mapping for the Article type. Note that article uses the name attribs for the core field called params. If your table does not contain a field, put “null” instead. Leaving it blank may cause SQL issues. The special fields are optional. At a minimum for common fields you need to map: content_item_id, alias and title in order to successfully create urls in the tagged items list. You also will probably want: access, status, and language.

Router is an optional name of a static helper router method for this type found in its front end helpers folder. If you only store data in #__ucm_content you will eventually be able to leave the router field blank although this option is not currently implemented. If you do not have a custom router tags falls back to the rules found in JHelperRoute.

Add tags to the getItem() method of the model

Note: this was only required in 3.1.0 and 3.1.1. It should not be used in 3.1.4 or later. Please read the history of this page if you need instructions for older versions.

Add a tag field to edit screens

In any edit layouts where you want to allow tagging, you need to add the field to the xml and the appropriate layouts if necessary. The core layouts us a JLayout to manage this and the same layout by any extension.

Update: Note that in 3.1.1 only there is special handling of this in the core. Tags in the edit screen MUST be part of a metadata <fields></fields> group. The core provides two JLayouts to help you manage standard layouts, one (details) for the metadata and one for the sidebar that includes the tabs. In update an extension to 3.1.4 you may need to fix adjust your edit views.

In 3.1.4 or later this special handling is not necessary. Best practice is to use the standard JLayouts since this provides a consistent experience for users.

The field also includes an attribute to allow/deny the user to enter custom values. Currently this only works in AJAX mode. The attribute has to be added to the field definition like **custom="allow"** or **custom="deny"**

if it is not already there. Usually multiple should be true unless you have a specific reason for it not to be. In the core components in administrator, the field is in the group shown on the right, below the language field.

Note: As of 3.1.2 if you wish to use the field to designate parent tags you must add parent="parent" to the xml definition of the field.

Prepare the view

Add an appropriate version of this to your view.html.php file before loading the layout:

The first parameter should match a type in the types table. The second parameter is the primary key under which this record is stored in your table. This would be used in any display in any view where you want the tags associated with the item to display.

Set up the display

In any layout where you want to display the tags associated with an item add: