Joomla! Documentation - User contributions [en]

J3.x:Using Tags in an Extension

2014-04-26T16:27:05Z

GreyHead: /* content_history_options */

{{copyedit}}

==Introduction==
Joomla's tagging system is used in all core content extensions and is designed to be be easy to integrate into other extensions that use standard Joomla design patterns.

Using tags in an extension is fairly straightforward. It requires these changes to a typical extension:

* Register a 'Content type' for the extension view(s)
* Add 'Observer methods' to the extension table class(es)
* Add 'Tag fields' to the extension edit forms
* Add 'Tag display' code to the extension view files
* Optionally, add a batch tagging method to the extension administration

== Register a content type for each view ==

In Joomla! 3 content types e.g. articles, weblinks, contacts, . . . are registered in the <tt>#__content_types</tt> table with a separate record for each content view e.g. article, weblink, article category, weblink category, . . .

Your extension installer needs to create a new record for each view.

Here is the structure of the <tt>#__content_types</tt> table; each column is described in the following sections.
{| class="wikitable"
|-
! Column name !! Column type !! Purpose
|-
| <tt>type_id</tt> || int(10) || Record key
|-
| <tt>type_title</tt>|| varchar(255)|| Type title e.g. <tt>Article</tt>
|-
| <tt>type_alias</tt> || varchar(255)|| Type alias e.g. <tt>com_content.article</tt>
|-
| <tt>table</tt> || varchar(255)|| Information about the Table class
|-
| <tt>rules</tt> || text || Not currently used
|-
| <tt>field_mappings</tt> || text || Maps the table column names to standard Joomla! names
|-
| <tt>router</tt> || varchar(255)|| Optional: name of a router method
|-
| <tt>content_history_options</tt> || varchar(5120)|| Optional: ????
|}

===type_id===
This is the auto-incremented record key, nothing to be done here.

===type_title===
The title for your Content Type e.g. Article, Contact, Weblink,
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.

===type_alias===
A string identifying the component and view (that would be in the page request, typically matching the model name) e.g. <tt>com_contact.contact</tt>, <tt>com_weblinks.weblink</tt>.

===table===
You need to identify which tables used by your component contain records to be tagged. For example the 'Contact' view of the Contacts component uses <tt>#__contact_details</tt> and similarly the 'Weblinks' view of the Weblinks component uses <tt>#__weblinks </tt>.

Each of these components uses a class to write to the table: <tt>ContactTableContact</tt> for the Contacts component and <tt>WeblinksTableWeblink</tt> for the Weblinks component. You will need the class prefixes e.g. <tt>ContactTable</tt>, <tt>WeblinksTable</tt>.

Note that Category types all use the <tt>#__categories</tt> table.

The <tt>type_table</tt> entry gives the complete table class information for the table class as a JSON object with two elements. The first element represents your "special" table and the second an optional common table (otherwise it will default the <tt>JTableCorecontent</tt>).

Here is the JSON entry for the Weblink content type:
<source lang="php">{
"special": {
"dbtable": "#__weblinks",
"key": "id",
"type": "Weblink",
"prefix": "WeblinksTable",
"config": "array()"
},
"common": {
"dbtable": "#__ucm_content",
"key": "ucm_id",
"type": "Corecontent",
"prefix": "JTable",
"config": "array()"
}
}</source>
The values to be included are:
{| class="wikitable"
|-
! Entry name !! Content
|-
| <tt>dbtable</tt> || Table name
|-
| <tt>key</tt>|| Primary key name
|-
| <tt>type</tt> || Content type
|-
| <tt>prefix</tt> || Class prefix
|-
| <tt>config</tt> || An option array, as used in your component constructor and getInstance() methods, may be empty
|}

This information 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.

====Notes====
* The table name for the common table is <tt>#__ucm_content</tt>; 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 <tt>type_title</tt> field would potentially be used for display although this is not implemented currently except in the contenttype field. Usually it should begin with an upper case letter if it is in English. See note about how to make this translatable. To make your type names translatable add <tt>COM_TAGS_CONTENT_TYPE_+type_title="Type Title"</tt> in both the ini and sys.ini files.

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

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

Here is the field_mappings entry for the Banner Content Type (chosen because it is a richer example than Article or WebLink). Note that 'common' mappings that have no equivalent are included as 'null' (leaving them blank may cause sql issues); and the names and values in the 'special' element all match as they are limited to this component.
<source lang="php">{
"common": {
"core_content_item_id": "id",
"core_title": "name",
"core_state": "published",
"core_alias": "alias",
"core_created_time": "created",
"core_modified_time": "modified",
"core_body": "description",
"core_hits": "null",
"core_publish_up": "publish_up",
"core_publish_down": "publish_down",
"core_access": "access",
"core_params": "params",
"core_featured": "null",
"core_metadata": "metadata",
"core_language": "language",
"core_images": "images",
"core_urls": "link",
"core_version": "version",
"core_ordering": "ordering",
"core_metakey": "metakey",
"core_metadesc": "metadesc",
"core_catid": "catid",
"core_xreference": "null",
"asset_id": "null"
},
"special": {
"imptotal": "imptotal",
"impmade": "impmade",
"clicks": "clicks",
"clickurl": "clickurl",
"custombannercode": "custombannercode",
"cid": "cid",
"purchase_type": "purchase_type",
"track_impressions": "track_impressions",
"track_clicks": "track_clicks"
}
}</source>
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. The special fields are optional.

====Note====
* The <tt>JHelperTags</tt> and JUcm APIs at 3.1.1 supported arrays for this field, but as of 3.1.4 either arrays or objects are supported; the default is objects.

===router===
This is an optional entry to include the name of a static helper router method for this type found in its front end helpers folder e.g. <tt>WeblinksHelperRoute::getWeblinkRoute</tt>.

If you do not have a custom router then Tags falls back to the rules in <tt>JHelperRoute</tt>.

If you only store data in <tt>#__ucm_content</tt> you will eventually be able to leave the router field blank although this option is not currently implemented.

===content_history_options===
This section was added in Joomla! 3.2 to link to the Content History component.

Here's the entry for the Banner Content Type:
<source lang="php">{
"formFile": "administrator\/components\/com_banners\/models\/forms\/banner.xml",
"hideFields": [
"checked_out",
"checked_out_time",
"version",
"reset"
],
"ignoreChanges": [
"modified_by",
"modified",
"checked_out",
"checked_out_time",
"version",
"imptotal",
"impmade",
"reset"
],
"convertToInt": [
"publish_up",
"publish_down",
"ordering"
],
"displayLookup": [
{
"sourceColumn": "catid",
"targetTable": "#__categories",
"targetColumn": "id",
"displayColumn": "title"
},
{
"sourceColumn": "cid",
"targetTable": "#__banner_clients",
"targetColumn": "id",
"displayColumn": "name"
},
{
"sourceColumn": "created_by",
"targetTable": "#__users",
"targetColumn": "id",
"displayColumn": "name"
},
{
"sourceColumn": "modified_by",
"targetTable": "#__users",
"targetColumn": "id",
"displayColumn": "name"
}
]
}</source>

===Creating the record===
You can create records in the installer in one of three ways:
* in the [[J2.5:Managing_Component_Updates_(Script.php)#postflight|postflight]] method
* by creating a <tt>JTableContenttype</tt> instance and adding a row, or
* by using SQL to create a record directly

== Modify your component's table class (or classes if you have multiple tables) ==

Add the following to your JTable constructor:

$this->_observers = new JObserverUpdater($this);
JObserverMapper::attachAllObservers($this);

'''The addition material formerly located here is no longer needed after 3.1.4''' Please read the document history for this page if you are required to support 3.1.0 or 3.1.1.

'''For joomla 3.2 I needed this line:''' ( Dont forget to replace weblinks by your component name )

JObserverMapper::addObserverClassToClass('JTableObserverTags', 'WeblinksTableWeblink', array('typeAlias' => 'com_weblinks.weblink'));

== 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.

<source lang="xml">
<field name="tags" type="tag"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field></source>

The field loads all the Javascript libraries required. You don't need to worry about that.

The field supports two modes:
* '''Nested tags mode.''' Hierarchical tag list. Doesn't support on the fly tag creation.
* '''AJAX mode.''' Tags are searched while user types (3 min. chars required to launch the AJAX search). Custom tags are added by pressing ENTER or COMMA keys. Tags show the global route/path. Example: <code>grandpa/parent/tag</code>

The field mode can be forced or use the com_tags setting <code>Tag field mode</code> to determine its mode. To set/force the field mode we have to add '''mode="ajax"''' or '''mode="nested"''' to the tag field definition.

Example of forced AJAX mode:

<source lang="xml">
<field name="tags" type="tag" mode="ajax"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>
</source>
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"**

Example field definition with custom tags denied:

<source lang="xml">
<field name="tags" type="tag" mode="ajax" custom="denied"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>

</source>
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:

<source lang="php">
$item->tags = new JHelperTags;
$item->tags->getItemTags('com_newsfeeds.newsfeed.' , $this->item->id);
</source>

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:
<source lang="php">
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>

</source>
Changing the object and property names as appropriate.

You will most likely want to add the show_tags parameter to the item parameters, the menu item parameters and component configuration as appropriate for your use case.

<source lang="php">
<?php if ($this->params->get('show_tags', 1) && !empty($this->item->tags)) : ?>
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>
<?php endif; ?></source>

== Batch processing ==
If you want to add the ability to do batch tagging to a backend list view do the following.

Add tag to the default_batch layout

<source lang="php">
<div class="control-group">
<div class="controls">
<?php echo JHtml::_('batch.tag');?>
</div>
</div></source>

And add tag to the button class in the modal footer (Not totally necessary at this point, but good for potential future changes e.g. if unTag is added.)

<source lang="php">
<button class="btn" type="button" onclick="document.id('batch-category-id').value='';document.id('batch-access').value='';document.id('batch-language-id').value='';document.id('batch-user-id').value='';document.id('batch-tag-id)').value=''" data-dismiss="modal">
</source>

=== Add a batch method to your model if you are not extending JModelAdmin or overriding the batch method. ===

<source lang="php">
/**
* Batch tag a list of item.
*
* @param integer $value The value of the new tag.
* @param array $pks An array of row IDs.
* @param array $contexts An array of item contexts.
*
* @return void.
*
* @since 3.1
*/
protected function batchTag($value, $pks, $contexts)
{
$tagsHelper = new JHelperTags();
$tagsHelper->tagItems($value, $pks, $contexts);

return true;
}
</source>

And modify your batch method by adding
<source lang="php">
if (!empty($commands['tag']))
{
if (!$this->batchTag($commands['tag'], $pks, $contexts))
{
return false;
}

$done = true;
}

</source>

Pay attention to any JSON encoded strings that you need special handling for in batch processing -- remember that you are saving a copy of the core fields and you need save to work as expected.

That’s it, now create some tags, tag some items and you are set.

[[Category:Development]][[Category:Content Tags]]
[[Category:Tutorials]]

J3.x:Using Tags in an Extension

2014-04-26T16:03:34Z

GreyHead: /* Register a content type for each view */

{{copyedit}}

==Introduction==
Joomla's tagging system is used in all core content extensions and is designed to be be easy to integrate into other extensions that use standard Joomla design patterns.

Using tags in an extension is fairly straightforward. It requires these changes to a typical extension:

* Register a 'Content type' for the extension view(s)
* Add 'Observer methods' to the extension table class(es)
* Add 'Tag fields' to the extension edit forms
* Add 'Tag display' code to the extension view files
* Optionally, add a batch tagging method to the extension administration

== Register a content type for each view ==

In Joomla! 3 content types e.g. articles, weblinks, contacts, . . . are registered in the <tt>#__content_types</tt> table with a separate record for each content view e.g. article, weblink, article category, weblink category, . . .

Your extension installer needs to create a new record for each view.

Here is the structure of the <tt>#__content_types</tt> table; each column is described in the following sections.
{| class="wikitable"
|-
! Column name !! Column type !! Purpose
|-
| <tt>type_id</tt> || int(10) || Record key
|-
| <tt>type_title</tt>|| varchar(255)|| Type title e.g. <tt>Article</tt>
|-
| <tt>type_alias</tt> || varchar(255)|| Type alias e.g. <tt>com_content.article</tt>
|-
| <tt>table</tt> || varchar(255)|| Information about the Table class
|-
| <tt>rules</tt> || text || Not currently used
|-
| <tt>field_mappings</tt> || text || Maps the table column names to standard Joomla! names
|-
| <tt>router</tt> || varchar(255)|| Optional: name of a router method
|-
| <tt>content_history_options</tt> || varchar(5120)|| Optional: ????
|}

===type_id===
This is the auto-incremented record key, nothing to be done here.

===type_title===
The title for your Content Type e.g. Article, Contact, Weblink,
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.

===type_alias===
A string identifying the component and view (that would be in the page request, typically matching the model name) e.g. <tt>com_contact.contact</tt>, <tt>com_weblinks.weblink</tt>.

===table===
You need to identify which tables used by your component contain records to be tagged. For example the 'Contact' view of the Contacts component uses <tt>#__contact_details</tt> and similarly the 'Weblinks' view of the Weblinks component uses <tt>#__weblinks </tt>.

Each of these components uses a class to write to the table: <tt>ContactTableContact</tt> for the Contacts component and <tt>WeblinksTableWeblink</tt> for the Weblinks component. You will need the class prefixes e.g. <tt>ContactTable</tt>, <tt>WeblinksTable</tt>.

Note that Category types all use the <tt>#__categories</tt> table.

The <tt>type_table</tt> entry gives the complete table class information for the table class as a JSON object with two elements. The first element represents your "special" table and the second an optional common table (otherwise it will default the <tt>JTableCorecontent</tt>).

Here is the JSON entry for the Weblink content type:
<source lang="php">{
"special": {
"dbtable": "#__weblinks",
"key": "id",
"type": "Weblink",
"prefix": "WeblinksTable",
"config": "array()"
},
"common": {
"dbtable": "#__ucm_content",
"key": "ucm_id",
"type": "Corecontent",
"prefix": "JTable",
"config": "array()"
}
}</source>
The values to be included are:
{| class="wikitable"
|-
! Entry name !! Content
|-
| <tt>dbtable</tt> || Table name
|-
| <tt>key</tt>|| Primary key name
|-
| <tt>type</tt> || Content type
|-
| <tt>prefix</tt> || Class prefix
|-
| <tt>config</tt> || An option array, as used in your component constructor and getInstance() methods, may be empty
|}

This information 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.

====Notes====
* The table name for the common table is <tt>#__ucm_content</tt>; 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 <tt>type_title</tt> field would potentially be used for display although this is not implemented currently except in the contenttype field. Usually it should begin with an upper case letter if it is in English. See note about how to make this translatable. To make your type names translatable add <tt>COM_TAGS_CONTENT_TYPE_+type_title="Type Title"</tt> in both the ini and sys.ini files.

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

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

Here is the field_mappings entry for the Banner Content Type (chosen because it is a richer example than Article or WebLink). Note that 'common' mappings that have no equivalent are included as 'null' (leaving them blank may cause sql issues); and the names and values in the 'special' element all match as they are limited to this component.
<source lang="php">{
"common": {
"core_content_item_id": "id",
"core_title": "name",
"core_state": "published",
"core_alias": "alias",
"core_created_time": "created",
"core_modified_time": "modified",
"core_body": "description",
"core_hits": "null",
"core_publish_up": "publish_up",
"core_publish_down": "publish_down",
"core_access": "access",
"core_params": "params",
"core_featured": "null",
"core_metadata": "metadata",
"core_language": "language",
"core_images": "images",
"core_urls": "link",
"core_version": "version",
"core_ordering": "ordering",
"core_metakey": "metakey",
"core_metadesc": "metadesc",
"core_catid": "catid",
"core_xreference": "null",
"asset_id": "null"
},
"special": {
"imptotal": "imptotal",
"impmade": "impmade",
"clicks": "clicks",
"clickurl": "clickurl",
"custombannercode": "custombannercode",
"cid": "cid",
"purchase_type": "purchase_type",
"track_impressions": "track_impressions",
"track_clicks": "track_clicks"
}
}</source>
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. The special fields are optional.

====Note====
* The <tt>JHelperTags</tt> and JUcm APIs at 3.1.1 supported arrays for this field, but as of 3.1.4 either arrays or objects are supported; the default is objects.

===router===
This is an optional entry to include the name of a static helper router method for this type found in its front end helpers folder e.g. <tt>WeblinksHelperRoute::getWeblinkRoute</tt>.

If you do not have a custom router then Tags falls back to the rules in <tt>JHelperRoute</tt>.

If you only store data in <tt>#__ucm_content</tt> you will eventually be able to leave the router field blank although this option is not currently implemented.

===content_history_options===
?? What does this section do ??

Here's the entry for the Banner Content Type:
<source lang="php">{
"formFile": "administrator\/components\/com_banners\/models\/forms\/banner.xml",
"hideFields": [
"checked_out",
"checked_out_time",
"version",
"reset"
],
"ignoreChanges": [
"modified_by",
"modified",
"checked_out",
"checked_out_time",
"version",
"imptotal",
"impmade",
"reset"
],
"convertToInt": [
"publish_up",
"publish_down",
"ordering"
],
"displayLookup": [
{
"sourceColumn": "catid",
"targetTable": "#__categories",
"targetColumn": "id",
"displayColumn": "title"
},
{
"sourceColumn": "cid",
"targetTable": "#__banner_clients",
"targetColumn": "id",
"displayColumn": "name"
},
{
"sourceColumn": "created_by",
"targetTable": "#__users",
"targetColumn": "id",
"displayColumn": "name"
},
{
"sourceColumn": "modified_by",
"targetTable": "#__users",
"targetColumn": "id",
"displayColumn": "name"
}
]
}</source>

===Creating the record===
You can create records in the installer in one of three ways:
* in the [[J2.5:Managing_Component_Updates_(Script.php)#postflight|postflight]] method
* by creating a <tt>JTableContenttype</tt> instance and adding a row, or
* by using SQL to create a record directly

== Modify your component's table class (or classes if you have multiple tables) ==

Add the following to your JTable constructor:

$this->_observers = new JObserverUpdater($this);
JObserverMapper::attachAllObservers($this);

'''The addition material formerly located here is no longer needed after 3.1.4''' Please read the document history for this page if you are required to support 3.1.0 or 3.1.1.

'''For joomla 3.2 I needed this line:''' ( Dont forget to replace weblinks by your component name )

JObserverMapper::addObserverClassToClass('JTableObserverTags', 'WeblinksTableWeblink', array('typeAlias' => 'com_weblinks.weblink'));

== 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.

<source lang="xml">
<field name="tags" type="tag"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field></source>

The field loads all the Javascript libraries required. You don't need to worry about that.

The field supports two modes:
* '''Nested tags mode.''' Hierarchical tag list. Doesn't support on the fly tag creation.
* '''AJAX mode.''' Tags are searched while user types (3 min. chars required to launch the AJAX search). Custom tags are added by pressing ENTER or COMMA keys. Tags show the global route/path. Example: <code>grandpa/parent/tag</code>

The field mode can be forced or use the com_tags setting <code>Tag field mode</code> to determine its mode. To set/force the field mode we have to add '''mode="ajax"''' or '''mode="nested"''' to the tag field definition.

Example of forced AJAX mode:

<source lang="xml">
<field name="tags" type="tag" mode="ajax"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>
</source>
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"**

Example field definition with custom tags denied:

<source lang="xml">
<field name="tags" type="tag" mode="ajax" custom="denied"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>

</source>
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:

<source lang="php">
$item->tags = new JHelperTags;
$item->tags->getItemTags('com_newsfeeds.newsfeed.' , $this->item->id);
</source>

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:
<source lang="php">
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>

</source>
Changing the object and property names as appropriate.

You will most likely want to add the show_tags parameter to the item parameters, the menu item parameters and component configuration as appropriate for your use case.

<source lang="php">
<?php if ($this->params->get('show_tags', 1) && !empty($this->item->tags)) : ?>
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>
<?php endif; ?></source>

== Batch processing ==
If you want to add the ability to do batch tagging to a backend list view do the following.

Add tag to the default_batch layout

<source lang="php">
<div class="control-group">
<div class="controls">
<?php echo JHtml::_('batch.tag');?>
</div>
</div></source>

And add tag to the button class in the modal footer (Not totally necessary at this point, but good for potential future changes e.g. if unTag is added.)

<source lang="php">
<button class="btn" type="button" onclick="document.id('batch-category-id').value='';document.id('batch-access').value='';document.id('batch-language-id').value='';document.id('batch-user-id').value='';document.id('batch-tag-id)').value=''" data-dismiss="modal">
</source>

=== Add a batch method to your model if you are not extending JModelAdmin or overriding the batch method. ===

<source lang="php">
/**
* Batch tag a list of item.
*
* @param integer $value The value of the new tag.
* @param array $pks An array of row IDs.
* @param array $contexts An array of item contexts.
*
* @return void.
*
* @since 3.1
*/
protected function batchTag($value, $pks, $contexts)
{
$tagsHelper = new JHelperTags();
$tagsHelper->tagItems($value, $pks, $contexts);

return true;
}
</source>

And modify your batch method by adding
<source lang="php">
if (!empty($commands['tag']))
{
if (!$this->batchTag($commands['tag'], $pks, $contexts))
{
return false;
}

$done = true;
}

</source>

Pay attention to any JSON encoded strings that you need special handling for in batch processing -- remember that you are saving a copy of the core fields and you need save to work as expected.

That’s it, now create some tags, tag some items and you are set.

[[Category:Development]][[Category:Content Tags]]
[[Category:Tutorials]]

J3.x:Using Tags in an Extension

2014-04-26T15:56:00Z

GreyHead: /* Register a content type for each view */ Added Content History Options

{{copyedit}}

==Introduction==
Joomla's tagging system is used in all core content extensions and is designed to be be easy to integrate into other extensions that use standard Joomla design patterns.

Using tags in an extension is fairly straightforward. It requires these changes to a typical extension:

* Register a 'Content type' for the extension view(s)
* Add 'Observer methods' to the extension table class(es)
* Add 'Tag fields' to the extension edit forms
* Add 'Tag display' code to the extension view files
* Optionally, add a batch tagging method to the extension administration

== Register a content type for each view ==

In Joomla! 3 content types e.g. articles, weblinks, contacts, . . . are registered in the <tt>#__content_types</tt> table with a separate record for each content view e.g. article, weblink, article category, weblink category, . . .

Your extension installer needs to create a new record for each view.

You can create records in the installer in three different ways:
* in the [[J2.5:Managing_Component_Updates_(Script.php)#postflight|postflight]] method
* by creating a <tt>JTableContenttype</tt> instance and adding a row, or
* by using SQL to create a record directly

The structure of the <tt>#__content_types</tt> table is fairly straightforward:
{| class="wikitable"
|-
! Column name !! Column type !! Purpose
|-
| <tt>type_id</tt> || int(10) || Record key
|-
| <tt>type_title</tt>|| varchar(255)|| Type title e.g. <tt>Article</tt>
|-
| <tt>type_alias</tt> || varchar(255)|| Type alias e.g. <tt>com_content.article</tt>
|-
| <tt>table</tt> || varchar(255)|| Information about the Table class
|-
| <tt>rules</tt> || text || Not currently used
|-
| <tt>field_mappings</tt> || text || Maps the table column names to standard Joomla! names
|-
| <tt>router</tt> || varchar(255)|| Optional: name of a router method
|-
| <tt>content_history_options</tt> || varchar(5120)|| Optional: ????
|}

===Construct the Content Type entry===

For each table/option/view you will need to make an entry in <tt>#__content_types</tt> table (see above).

====type_id====
This is the auto-incremented record key, nothing to be done here.

====type_title====

The title for your Content Type e.g. Article, Contact, Weblink,
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.

====type_alias====

A string identifying the component and view (that would be in the page request, typically matching the model name) e.g. <tt>com_contact.contact</tt>, <tt>com_weblinks.weblink</tt>.

====table====

You need to identify which tables used by your component contain records to be tagged. For example the 'Contact' view of the Contacts component uses <tt>#__contact_details</tt> and similarly the 'Weblinks' view of the Weblinks component uses <tt>#__weblinks </tt>.

Each of these components uses a class to write to the table: <tt>ContactTableContact</tt> for the Contacts component and <tt>WeblinksTableWeblink</tt> for the Weblinks component. You will need the class prefixes e.g. <tt>ContactTable</tt>, <tt>WeblinksTable</tt>.

Note that Category types all use the <tt>#__categories</tt> table.

The <tt>type_table</tt> entry gives the complete table class information for the table class as a JSON object with two elements. The first element represents your "special" table and the second an optional common table (otherwise it will default the <tt>JTableCorecontent</tt>).

Here is the JSON entry for the Weblink content type:
<source lang="php">{
"special": {
"dbtable": "#__weblinks",
"key": "id",
"type": "Weblink",
"prefix": "WeblinksTable",
"config": "array()"
},
"common": {
"dbtable": "#__ucm_content",
"key": "ucm_id",
"type": "Corecontent",
"prefix": "JTable",
"config": "array()"
}
}</source>
The values to be included are:
{| class="wikitable"
|-
! Entry name !! Content
|-
| <tt>dbtable</tt> || Table name
|-
| <tt>key</tt>|| Primary key name
|-
| <tt>type</tt> || Content type
|-
| <tt>prefix</tt> || Class prefix
|-
| <tt>config</tt> || An option array, as used in your component constructor and getInstance() methods, may be empty
|}

This information 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.

=====Notes=====

* The table name for the common table is <tt>#__ucm_content</tt>; 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 <tt>type_title</tt> field would potentially be used for display although this is not implemented currently except in the contenttype field. Usually it should begin with an upper case letter if it is in English. See note about how to make this translatable. To make your type names translatable add <tt>COM_TAGS_CONTENT_TYPE_+type_title="Type Title"</tt> in both the ini and sys.ini files.

====rules====

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

====field_mappings====

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

Here is the field_mappings entry for the Banner Content Type (chosen because it is a richer example than Article or WebLink). Note that 'common' mappings that have no equivalent are included as 'null' (leaving them blank may cause sql issues); and the names and values in the 'special' element all match as they are limited to this component.

<source lang="php">{
"common": {
"core_content_item_id": "id",
"core_title": "name",
"core_state": "published",
"core_alias": "alias",
"core_created_time": "created",
"core_modified_time": "modified",
"core_body": "description",
"core_hits": "null",
"core_publish_up": "publish_up",
"core_publish_down": "publish_down",
"core_access": "access",
"core_params": "params",
"core_featured": "null",
"core_metadata": "metadata",
"core_language": "language",
"core_images": "images",
"core_urls": "link",
"core_version": "version",
"core_ordering": "ordering",
"core_metakey": "metakey",
"core_metadesc": "metadesc",
"core_catid": "catid",
"core_xreference": "null",
"asset_id": "null"
},
"special": {
"imptotal": "imptotal",
"impmade": "impmade",
"clicks": "clicks",
"clickurl": "clickurl",
"custombannercode": "custombannercode",
"cid": "cid",
"purchase_type": "purchase_type",
"track_impressions": "track_impressions",
"track_clicks": "track_clicks"
}
}</source>
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. The special fields are optional.

=====Note=====
* The <tt>JHelperTags</tt> and JUcm APIs at 3.1.1 supported arrays for this field, but as of 3.1.4 either arrays or objects are supported; the default is objects.

====router====

This is an optional entry to include the name of a static helper router method for this type found in its front end helpers folder e.g. <tt>WeblinksHelperRoute::getWeblinkRoute</tt>.

If you do not have a custom router then Tags falls back to the rules in <tt>JHelperRoute</tt>.

If you only store data in <tt>#__ucm_content</tt> you will eventually be able to leave the router field blank although this option is not currently implemented.

====content_history_options====

????

Here's the entry for the Banner Content Type:
<source lang="php">{
"formFile": "administrator\/components\/com_banners\/models\/forms\/banner.xml",
"hideFields": [
"checked_out",
"checked_out_time",
"version",
"reset"
],
"ignoreChanges": [
"modified_by",
"modified",
"checked_out",
"checked_out_time",
"version",
"imptotal",
"impmade",
"reset"
],
"convertToInt": [
"publish_up",
"publish_down",
"ordering"
],
"displayLookup": [
{
"sourceColumn": "catid",
"targetTable": "#__categories",
"targetColumn": "id",
"displayColumn": "title"
},
{
"sourceColumn": "cid",
"targetTable": "#__banner_clients",
"targetColumn": "id",
"displayColumn": "name"
},
{
"sourceColumn": "created_by",
"targetTable": "#__users",
"targetColumn": "id",
"displayColumn": "name"
},
{
"sourceColumn": "modified_by",
"targetTable": "#__users",
"targetColumn": "id",
"displayColumn": "name"
}
]
}</source>

== Modify your component's table class (or classes if you have multiple tables) ==

Add the following to your JTable constructor:

$this->_observers = new JObserverUpdater($this);
JObserverMapper::attachAllObservers($this);

'''The addition material formerly located here is no longer needed after 3.1.4''' Please read the document history for this page if you are required to support 3.1.0 or 3.1.1.

'''For joomla 3.2 I needed this line:''' ( Dont forget to replace weblinks by your component name )

JObserverMapper::addObserverClassToClass('JTableObserverTags', 'WeblinksTableWeblink', array('typeAlias' => 'com_weblinks.weblink'));

== 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.

<source lang="xml">
<field name="tags" type="tag"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field></source>

The field loads all the Javascript libraries required. You don't need to worry about that.

The field supports two modes:
* '''Nested tags mode.''' Hierarchical tag list. Doesn't support on the fly tag creation.
* '''AJAX mode.''' Tags are searched while user types (3 min. chars required to launch the AJAX search). Custom tags are added by pressing ENTER or COMMA keys. Tags show the global route/path. Example: <code>grandpa/parent/tag</code>

The field mode can be forced or use the com_tags setting <code>Tag field mode</code> to determine its mode. To set/force the field mode we have to add '''mode="ajax"''' or '''mode="nested"''' to the tag field definition.

Example of forced AJAX mode:

<source lang="xml">
<field name="tags" type="tag" mode="ajax"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>
</source>
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"**

Example field definition with custom tags denied:

<source lang="xml">
<field name="tags" type="tag" mode="ajax" custom="denied"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>

</source>
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:

<source lang="php">
$item->tags = new JHelperTags;
$item->tags->getItemTags('com_newsfeeds.newsfeed.' , $this->item->id);
</source>

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:
<source lang="php">
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>

</source>
Changing the object and property names as appropriate.

You will most likely want to add the show_tags parameter to the item parameters, the menu item parameters and component configuration as appropriate for your use case.

<source lang="php">
<?php if ($this->params->get('show_tags', 1) && !empty($this->item->tags)) : ?>
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>
<?php endif; ?></source>

== Batch processing ==
If you want to add the ability to do batch tagging to a backend list view do the following.

Add tag to the default_batch layout

<source lang="php">
<div class="control-group">
<div class="controls">
<?php echo JHtml::_('batch.tag');?>
</div>
</div></source>

And add tag to the button class in the modal footer (Not totally necessary at this point, but good for potential future changes e.g. if unTag is added.)

<source lang="php">
<button class="btn" type="button" onclick="document.id('batch-category-id').value='';document.id('batch-access').value='';document.id('batch-language-id').value='';document.id('batch-user-id').value='';document.id('batch-tag-id)').value=''" data-dismiss="modal">
</source>

=== Add a batch method to your model if you are not extending JModelAdmin or overriding the batch method. ===

<source lang="php">
/**
* Batch tag a list of item.
*
* @param integer $value The value of the new tag.
* @param array $pks An array of row IDs.
* @param array $contexts An array of item contexts.
*
* @return void.
*
* @since 3.1
*/
protected function batchTag($value, $pks, $contexts)
{
$tagsHelper = new JHelperTags();
$tagsHelper->tagItems($value, $pks, $contexts);

return true;
}
</source>

And modify your batch method by adding
<source lang="php">
if (!empty($commands['tag']))
{
if (!$this->batchTag($commands['tag'], $pks, $contexts))
{
return false;
}

$done = true;
}

</source>

Pay attention to any JSON encoded strings that you need special handling for in batch processing -- remember that you are saving a copy of the core fields and you need save to work as expected.

That’s it, now create some tags, tag some items and you are set.

[[Category:Development]][[Category:Content Tags]]
[[Category:Tutorials]]

J3.x:Using Tags in an Extension

2014-04-26T15:49:46Z

GreyHead: /* Note */

{{copyedit}}

==Introduction==
Joomla's tagging system is used in all core content extensions and is designed to be be easy to integrate into other extensions that use standard Joomla design patterns.

Using tags in an extension is fairly straightforward. It requires these changes to a typical extension:

* Register a 'Content type' for the extension view(s)
* Add 'Observer methods' to the extension table class(es)
* Add 'Tag fields' to the extension edit forms
* Add 'Tag display' code to the extension view files
* Optionally, add a batch tagging method to the extension administration

== Register a content type for each view ==

In Joomla! 3 content types e.g. articles, weblinks, contacts, . . . are registered in the <tt>#__content_types</tt> table with a separate record for each content view e.g. article, weblink, article category, weblink category, . . .

Your extension installer needs to create a new record for each view.

You can create records in the installer in three different ways:
* in the [[J2.5:Managing_Component_Updates_(Script.php)#postflight|postflight]] method
* by creating a <tt>JTableContenttype</tt> instance and adding a row, or
* by using SQL to create a record directly

The structure of the <tt>#__content_types</tt> table is fairly straightforward:
{| class="wikitable"
|-
! Column name !! Column type !! Purpose
|-
| <tt>type_id</tt> || int(10) || Record key
|-
| <tt>type_title</tt>|| varchar(255)|| Type title e.g. <tt>Article</tt>
|-
| <tt>type_alias</tt> || varchar(255)|| Type alias e.g. <tt>com_content.article</tt>
|-
| <tt>table</tt> || varchar(255)|| Information about the Table class
|-
| <tt>rules</tt> || text || Not currently used
|-
| <tt>field_mappings</tt> || text || Maps the table column names to standard Joomla! names
|-
| <tt>router</tt> || varchar(255)|| Optional: name of a router method
|}

===Construct the Content Type entry===

For each table/option/view you will need to make an entry in <tt>#__content_types</tt> table (see above).

====type_id====
This is the auto-incremented record key, nothing to be done here.

====type_title====

The title for your Content Type e.g. Article, Contact, Weblink,
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.

====type_alias====

A string identifying the component and view (that would be in the page request, typically matching the model name) e.g. <tt>com_contact.contact</tt>, <tt>com_weblinks.weblink</tt>.

====table====

You need to identify which tables used by your component contain records to be tagged. For example the 'Contact' view of the Contacts component uses <tt>#__contact_details</tt> and similarly the 'Weblinks' view of the Weblinks component uses <tt>#__weblinks </tt>.

Each of these components uses a class to write to the table: <tt>ContactTableContact</tt> for the Contacts component and <tt>WeblinksTableWeblink</tt> for the Weblinks component. You will need the class prefixes e.g. <tt>ContactTable</tt>, <tt>WeblinksTable</tt>.

Note that Category types all use the <tt>#__categories</tt> table.

The <tt>type_table</tt> entry gives the complete table class information for the table class as a JSON object with two elements. The first element represents your "special" table and the second an optional common table (otherwise it will default the <tt>JTableCorecontent</tt>).

Here is the JSON entry for the Weblink content type:
<source lang="php">{
"special": {
"dbtable": "#__weblinks",
"key": "id",
"type": "Weblink",
"prefix": "WeblinksTable",
"config": "array()"
},
"common": {
"dbtable": "#__ucm_content",
"key": "ucm_id",
"type": "Corecontent",
"prefix": "JTable",
"config": "array()"
}
}</source>
The values to be included are:
{| class="wikitable"
|-
! Entry name !! Content
|-
| <tt>dbtable</tt> || Table name
|-
| <tt>key</tt>|| Primary key name
|-
| <tt>type</tt> || Content type
|-
| <tt>prefix</tt> || Class prefix
|-
| <tt>config</tt> || An option array, as used in your component constructor and getInstance() methods, may be empty
|}

This information 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.

=====Notes=====

* The table name for the common table is <tt>#__ucm_content</tt>; 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 <tt>type_title</tt> field would potentially be used for display although this is not implemented currently except in the contenttype field. Usually it should begin with an upper case letter if it is in English. See note about how to make this translatable. To make your type names translatable add <tt>COM_TAGS_CONTENT_TYPE_+type_title="Type Title"</tt> in both the ini and sys.ini files.

====rules====

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

====field_mappings====

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

Here is the field_mappings entry for the Banner Content Type (chosen because it is a richer example than Article or WebLink). Note that 'common' mappings that have no equivalent are included as 'null' (leaving them blank may cause sql issues); and the names and values in the 'special' element all match as they are limited to this component.

<source lang="php">{
"common": {
"core_content_item_id": "id",
"core_title": "name",
"core_state": "published",
"core_alias": "alias",
"core_created_time": "created",
"core_modified_time": "modified",
"core_body": "description",
"core_hits": "null",
"core_publish_up": "publish_up",
"core_publish_down": "publish_down",
"core_access": "access",
"core_params": "params",
"core_featured": "null",
"core_metadata": "metadata",
"core_language": "language",
"core_images": "images",
"core_urls": "link",
"core_version": "version",
"core_ordering": "ordering",
"core_metakey": "metakey",
"core_metadesc": "metadesc",
"core_catid": "catid",
"core_xreference": "null",
"asset_id": "null"
},
"special": {
"imptotal": "imptotal",
"impmade": "impmade",
"clicks": "clicks",
"clickurl": "clickurl",
"custombannercode": "custombannercode",
"cid": "cid",
"purchase_type": "purchase_type",
"track_impressions": "track_impressions",
"track_clicks": "track_clicks"
}
}</source>
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. The special fields are optional.

=====Note=====
* The <tt>JHelperTags</tt> and JUcm APIs at 3.1.1 supported arrays for this field, but as of 3.1.4 either arrays or objects are supported; the default is objects.

====router====

This is an optional entry to include the name of a static helper router method for this type found in its front end helpers folder e.g. <tt>WeblinksHelperRoute::getWeblinkRoute</tt>.

If you do not have a custom router then Tags falls back to the rules in <tt>JHelperRoute</tt>.

If you only store data in <tt>#__ucm_content</tt> you will eventually be able to leave the router field blank although this option is not currently implemented.

== Modify your component's table class (or classes if you have multiple tables) ==

Add the following to your JTable constructor:

$this->_observers = new JObserverUpdater($this);
JObserverMapper::attachAllObservers($this);

'''The addition material formerly located here is no longer needed after 3.1.4''' Please read the document history for this page if you are required to support 3.1.0 or 3.1.1.

'''For joomla 3.2 I needed this line:''' ( Dont forget to replace weblinks by your component name )

JObserverMapper::addObserverClassToClass('JTableObserverTags', 'WeblinksTableWeblink', array('typeAlias' => 'com_weblinks.weblink'));

== 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.

<source lang="xml">
<field name="tags" type="tag"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field></source>

The field loads all the Javascript libraries required. You don't need to worry about that.

The field supports two modes:
* '''Nested tags mode.''' Hierarchical tag list. Doesn't support on the fly tag creation.
* '''AJAX mode.''' Tags are searched while user types (3 min. chars required to launch the AJAX search). Custom tags are added by pressing ENTER or COMMA keys. Tags show the global route/path. Example: <code>grandpa/parent/tag</code>

The field mode can be forced or use the com_tags setting <code>Tag field mode</code> to determine its mode. To set/force the field mode we have to add '''mode="ajax"''' or '''mode="nested"''' to the tag field definition.

Example of forced AJAX mode:

<source lang="xml">
<field name="tags" type="tag" mode="ajax"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>
</source>
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"**

Example field definition with custom tags denied:

<source lang="xml">
<field name="tags" type="tag" mode="ajax" custom="denied"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>

</source>
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:

<source lang="php">
$item->tags = new JHelperTags;
$item->tags->getItemTags('com_newsfeeds.newsfeed.' , $this->item->id);
</source>

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:
<source lang="php">
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>

</source>
Changing the object and property names as appropriate.

You will most likely want to add the show_tags parameter to the item parameters, the menu item parameters and component configuration as appropriate for your use case.

<source lang="php">
<?php if ($this->params->get('show_tags', 1) && !empty($this->item->tags)) : ?>
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>
<?php endif; ?></source>

== Batch processing ==
If you want to add the ability to do batch tagging to a backend list view do the following.

Add tag to the default_batch layout

<source lang="php">
<div class="control-group">
<div class="controls">
<?php echo JHtml::_('batch.tag');?>
</div>
</div></source>

And add tag to the button class in the modal footer (Not totally necessary at this point, but good for potential future changes e.g. if unTag is added.)

<source lang="php">
<button class="btn" type="button" onclick="document.id('batch-category-id').value='';document.id('batch-access').value='';document.id('batch-language-id').value='';document.id('batch-user-id').value='';document.id('batch-tag-id)').value=''" data-dismiss="modal">
</source>

=== Add a batch method to your model if you are not extending JModelAdmin or overriding the batch method. ===

<source lang="php">
/**
* Batch tag a list of item.
*
* @param integer $value The value of the new tag.
* @param array $pks An array of row IDs.
* @param array $contexts An array of item contexts.
*
* @return void.
*
* @since 3.1
*/
protected function batchTag($value, $pks, $contexts)
{
$tagsHelper = new JHelperTags();
$tagsHelper->tagItems($value, $pks, $contexts);

return true;
}
</source>

And modify your batch method by adding
<source lang="php">
if (!empty($commands['tag']))
{
if (!$this->batchTag($commands['tag'], $pks, $contexts))
{
return false;
}

$done = true;
}

</source>

Pay attention to any JSON encoded strings that you need special handling for in batch processing -- remember that you are saving a copy of the core fields and you need save to work as expected.

That’s it, now create some tags, tag some items and you are set.

[[Category:Development]][[Category:Content Tags]]
[[Category:Tutorials]]

J3.x:Using Tags in an Extension

2014-04-26T15:48:24Z

GreyHead: /* router */

{{copyedit}}

==Introduction==
Joomla's tagging system is used in all core content extensions and is designed to be be easy to integrate into other extensions that use standard Joomla design patterns.

Using tags in an extension is fairly straightforward. It requires these changes to a typical extension:

* Register a 'Content type' for the extension view(s)
* Add 'Observer methods' to the extension table class(es)
* Add 'Tag fields' to the extension edit forms
* Add 'Tag display' code to the extension view files
* Optionally, add a batch tagging method to the extension administration

== Register a content type for each view ==

In Joomla! 3 content types e.g. articles, weblinks, contacts, . . . are registered in the <tt>#__content_types</tt> table with a separate record for each content view e.g. article, weblink, article category, weblink category, . . .

Your extension installer needs to create a new record for each view.

You can create records in the installer in three different ways:
* in the [[J2.5:Managing_Component_Updates_(Script.php)#postflight|postflight]] method
* by creating a <tt>JTableContenttype</tt> instance and adding a row, or
* by using SQL to create a record directly

The structure of the <tt>#__content_types</tt> table is fairly straightforward:
{| class="wikitable"
|-
! Column name !! Column type !! Purpose
|-
| <tt>type_id</tt> || int(10) || Record key
|-
| <tt>type_title</tt>|| varchar(255)|| Type title e.g. <tt>Article</tt>
|-
| <tt>type_alias</tt> || varchar(255)|| Type alias e.g. <tt>com_content.article</tt>
|-
| <tt>table</tt> || varchar(255)|| Information about the Table class
|-
| <tt>rules</tt> || text || Not currently used
|-
| <tt>field_mappings</tt> || text || Maps the table column names to standard Joomla! names
|-
| <tt>router</tt> || varchar(255)|| Optional: name of a router method
|}

===Construct the Content Type entry===

For each table/option/view you will need to make an entry in <tt>#__content_types</tt> table (see above).

====type_id====
This is the auto-incremented record key, nothing to be done here.

====type_title====

The title for your Content Type e.g. Article, Contact, Weblink,
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.

====type_alias====

A string identifying the component and view (that would be in the page request, typically matching the model name) e.g. <tt>com_contact.contact</tt>, <tt>com_weblinks.weblink</tt>.

====table====

You need to identify which tables used by your component contain records to be tagged. For example the 'Contact' view of the Contacts component uses <tt>#__contact_details</tt> and similarly the 'Weblinks' view of the Weblinks component uses <tt>#__weblinks </tt>.

Each of these components uses a class to write to the table: <tt>ContactTableContact</tt> for the Contacts component and <tt>WeblinksTableWeblink</tt> for the Weblinks component. You will need the class prefixes e.g. <tt>ContactTable</tt>, <tt>WeblinksTable</tt>.

Note that Category types all use the <tt>#__categories</tt> table.

The <tt>type_table</tt> entry gives the complete table class information for the table class as a JSON object with two elements. The first element represents your "special" table and the second an optional common table (otherwise it will default the <tt>JTableCorecontent</tt>).

Here is the JSON entry for the Weblink content type:
<source lang="php">{
"special": {
"dbtable": "#__weblinks",
"key": "id",
"type": "Weblink",
"prefix": "WeblinksTable",
"config": "array()"
},
"common": {
"dbtable": "#__ucm_content",
"key": "ucm_id",
"type": "Corecontent",
"prefix": "JTable",
"config": "array()"
}
}</source>
The values to be included are:
{| class="wikitable"
|-
! Entry name !! Content
|-
| <tt>dbtable</tt> || Table name
|-
| <tt>key</tt>|| Primary key name
|-
| <tt>type</tt> || Content type
|-
| <tt>prefix</tt> || Class prefix
|-
| <tt>config</tt> || An option array, as used in your component constructor and getInstance() methods, may be empty
|}

This information 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.

=====Notes=====

* The table name for the common table is <tt>#__ucm_content</tt>; 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 <tt>type_title</tt> field would potentially be used for display although this is not implemented currently except in the contenttype field. Usually it should begin with an upper case letter if it is in English. See note about how to make this translatable. To make your type names translatable add <tt>COM_TAGS_CONTENT_TYPE_+type_title="Type Title"</tt> in both the ini and sys.ini files.

====rules====

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

====field_mappings====

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

Here is the field_mappings entry for the Banner Content Type (chosen because it is a richer example than Article or WebLink). Note that 'common' mappings that have no equivalent are included as 'null' (leaving them blank may cause sql issues); and the names and values in the 'special' element all match as they are limited to this component.

<source lang="php">{
"common": {
"core_content_item_id": "id",
"core_title": "name",
"core_state": "published",
"core_alias": "alias",
"core_created_time": "created",
"core_modified_time": "modified",
"core_body": "description",
"core_hits": "null",
"core_publish_up": "publish_up",
"core_publish_down": "publish_down",
"core_access": "access",
"core_params": "params",
"core_featured": "null",
"core_metadata": "metadata",
"core_language": "language",
"core_images": "images",
"core_urls": "link",
"core_version": "version",
"core_ordering": "ordering",
"core_metakey": "metakey",
"core_metadesc": "metadesc",
"core_catid": "catid",
"core_xreference": "null",
"asset_id": "null"
},
"special": {
"imptotal": "imptotal",
"impmade": "impmade",
"clicks": "clicks",
"clickurl": "clickurl",
"custombannercode": "custombannercode",
"cid": "cid",
"purchase_type": "purchase_type",
"track_impressions": "track_impressions",
"track_clicks": "track_clicks"
}
}</source>
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. The special fields are optional.

=====Note=====
* The <tt>JHelperTags</tt> and JUcm APIS at 3.1.1 supported arrays for this field, but as of 3.1.4 either arrays or objects are supported; the default is objects.

====router====

This is an optional entry to include the name of a static helper router method for this type found in its front end helpers folder e.g. <tt>WeblinksHelperRoute::getWeblinkRoute</tt>.

If you do not have a custom router then Tags falls back to the rules in <tt>JHelperRoute</tt>.

If you only store data in <tt>#__ucm_content</tt> you will eventually be able to leave the router field blank although this option is not currently implemented.

== Modify your component's table class (or classes if you have multiple tables) ==

Add the following to your JTable constructor:

$this->_observers = new JObserverUpdater($this);
JObserverMapper::attachAllObservers($this);

'''The addition material formerly located here is no longer needed after 3.1.4''' Please read the document history for this page if you are required to support 3.1.0 or 3.1.1.

'''For joomla 3.2 I needed this line:''' ( Dont forget to replace weblinks by your component name )

JObserverMapper::addObserverClassToClass('JTableObserverTags', 'WeblinksTableWeblink', array('typeAlias' => 'com_weblinks.weblink'));

== 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.

<source lang="xml">
<field name="tags" type="tag"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field></source>

The field loads all the Javascript libraries required. You don't need to worry about that.

The field supports two modes:
* '''Nested tags mode.''' Hierarchical tag list. Doesn't support on the fly tag creation.
* '''AJAX mode.''' Tags are searched while user types (3 min. chars required to launch the AJAX search). Custom tags are added by pressing ENTER or COMMA keys. Tags show the global route/path. Example: <code>grandpa/parent/tag</code>

The field mode can be forced or use the com_tags setting <code>Tag field mode</code> to determine its mode. To set/force the field mode we have to add '''mode="ajax"''' or '''mode="nested"''' to the tag field definition.

Example of forced AJAX mode:

<source lang="xml">
<field name="tags" type="tag" mode="ajax"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>
</source>
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"**

Example field definition with custom tags denied:

<source lang="xml">
<field name="tags" type="tag" mode="ajax" custom="denied"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>

</source>
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:

<source lang="php">
$item->tags = new JHelperTags;
$item->tags->getItemTags('com_newsfeeds.newsfeed.' , $this->item->id);
</source>

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:
<source lang="php">
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>

</source>
Changing the object and property names as appropriate.

You will most likely want to add the show_tags parameter to the item parameters, the menu item parameters and component configuration as appropriate for your use case.

<source lang="php">
<?php if ($this->params->get('show_tags', 1) && !empty($this->item->tags)) : ?>
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>
<?php endif; ?></source>

== Batch processing ==
If you want to add the ability to do batch tagging to a backend list view do the following.

Add tag to the default_batch layout

<source lang="php">
<div class="control-group">
<div class="controls">
<?php echo JHtml::_('batch.tag');?>
</div>
</div></source>

And add tag to the button class in the modal footer (Not totally necessary at this point, but good for potential future changes e.g. if unTag is added.)

<source lang="php">
<button class="btn" type="button" onclick="document.id('batch-category-id').value='';document.id('batch-access').value='';document.id('batch-language-id').value='';document.id('batch-user-id').value='';document.id('batch-tag-id)').value=''" data-dismiss="modal">
</source>

=== Add a batch method to your model if you are not extending JModelAdmin or overriding the batch method. ===

<source lang="php">
/**
* Batch tag a list of item.
*
* @param integer $value The value of the new tag.
* @param array $pks An array of row IDs.
* @param array $contexts An array of item contexts.
*
* @return void.
*
* @since 3.1
*/
protected function batchTag($value, $pks, $contexts)
{
$tagsHelper = new JHelperTags();
$tagsHelper->tagItems($value, $pks, $contexts);

return true;
}
</source>

And modify your batch method by adding
<source lang="php">
if (!empty($commands['tag']))
{
if (!$this->batchTag($commands['tag'], $pks, $contexts))
{
return false;
}

$done = true;
}

</source>

Pay attention to any JSON encoded strings that you need special handling for in batch processing -- remember that you are saving a copy of the core fields and you need save to work as expected.

That’s it, now create some tags, tag some items and you are set.

[[Category:Development]][[Category:Content Tags]]
[[Category:Tutorials]]

J3.x:Using Tags in an Extension

2014-04-26T15:46:03Z

GreyHead: /* field_mappings */ Updated and edited

{{copyedit}}

==Introduction==
Joomla's tagging system is used in all core content extensions and is designed to be be easy to integrate into other extensions that use standard Joomla design patterns.

Using tags in an extension is fairly straightforward. It requires these changes to a typical extension:

* Register a 'Content type' for the extension view(s)
* Add 'Observer methods' to the extension table class(es)
* Add 'Tag fields' to the extension edit forms
* Add 'Tag display' code to the extension view files
* Optionally, add a batch tagging method to the extension administration

== Register a content type for each view ==

In Joomla! 3 content types e.g. articles, weblinks, contacts, . . . are registered in the <tt>#__content_types</tt> table with a separate record for each content view e.g. article, weblink, article category, weblink category, . . .

Your extension installer needs to create a new record for each view.

You can create records in the installer in three different ways:
* in the [[J2.5:Managing_Component_Updates_(Script.php)#postflight|postflight]] method
* by creating a <tt>JTableContenttype</tt> instance and adding a row, or
* by using SQL to create a record directly

The structure of the <tt>#__content_types</tt> table is fairly straightforward:
{| class="wikitable"
|-
! Column name !! Column type !! Purpose
|-
| <tt>type_id</tt> || int(10) || Record key
|-
| <tt>type_title</tt>|| varchar(255)|| Type title e.g. <tt>Article</tt>
|-
| <tt>type_alias</tt> || varchar(255)|| Type alias e.g. <tt>com_content.article</tt>
|-
| <tt>table</tt> || varchar(255)|| Information about the Table class
|-
| <tt>rules</tt> || text || Not currently used
|-
| <tt>field_mappings</tt> || text || Maps the table column names to standard Joomla! names
|-
| <tt>router</tt> || varchar(255)|| Optional: name of a router method
|}

===Construct the Content Type entry===

For each table/option/view you will need to make an entry in <tt>#__content_types</tt> table (see above).

====type_id====
This is the auto-incremented record key, nothing to be done here.

====type_title====

The title for your Content Type e.g. Article, Contact, Weblink,
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.

====type_alias====

A string identifying the component and view (that would be in the page request, typically matching the model name) e.g. <tt>com_contact.contact</tt>, <tt>com_weblinks.weblink</tt>.

====table====

You need to identify which tables used by your component contain records to be tagged. For example the 'Contact' view of the Contacts component uses <tt>#__contact_details</tt> and similarly the 'Weblinks' view of the Weblinks component uses <tt>#__weblinks </tt>.

Each of these components uses a class to write to the table: <tt>ContactTableContact</tt> for the Contacts component and <tt>WeblinksTableWeblink</tt> for the Weblinks component. You will need the class prefixes e.g. <tt>ContactTable</tt>, <tt>WeblinksTable</tt>.

Note that Category types all use the <tt>#__categories</tt> table.

The <tt>type_table</tt> entry gives the complete table class information for the table class as a JSON object with two elements. The first element represents your "special" table and the second an optional common table (otherwise it will default the <tt>JTableCorecontent</tt>).

Here is the JSON entry for the Weblink content type:
<source lang="php">{
"special": {
"dbtable": "#__weblinks",
"key": "id",
"type": "Weblink",
"prefix": "WeblinksTable",
"config": "array()"
},
"common": {
"dbtable": "#__ucm_content",
"key": "ucm_id",
"type": "Corecontent",
"prefix": "JTable",
"config": "array()"
}
}</source>
The values to be included are:
{| class="wikitable"
|-
! Entry name !! Content
|-
| <tt>dbtable</tt> || Table name
|-
| <tt>key</tt>|| Primary key name
|-
| <tt>type</tt> || Content type
|-
| <tt>prefix</tt> || Class prefix
|-
| <tt>config</tt> || An option array, as used in your component constructor and getInstance() methods, may be empty
|}

This information 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.

=====Notes=====

* The table name for the common table is <tt>#__ucm_content</tt>; 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 <tt>type_title</tt> field would potentially be used for display although this is not implemented currently except in the contenttype field. Usually it should begin with an upper case letter if it is in English. See note about how to make this translatable. To make your type names translatable add <tt>COM_TAGS_CONTENT_TYPE_+type_title="Type Title"</tt> in both the ini and sys.ini files.

====rules====

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

====field_mappings====

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

Here is the field_mappings entry for the Banner Content Type (chosen because it is a richer example than Article or WebLink). Note that 'common' mappings that have no equivalent are included as 'null' (leaving them blank may cause sql issues); and the names and values in the 'special' element all match as they are limited to this component.

<source lang="php">{
"common": {
"core_content_item_id": "id",
"core_title": "name",
"core_state": "published",
"core_alias": "alias",
"core_created_time": "created",
"core_modified_time": "modified",
"core_body": "description",
"core_hits": "null",
"core_publish_up": "publish_up",
"core_publish_down": "publish_down",
"core_access": "access",
"core_params": "params",
"core_featured": "null",
"core_metadata": "metadata",
"core_language": "language",
"core_images": "images",
"core_urls": "link",
"core_version": "version",
"core_ordering": "ordering",
"core_metakey": "metakey",
"core_metadesc": "metadesc",
"core_catid": "catid",
"core_xreference": "null",
"asset_id": "null"
},
"special": {
"imptotal": "imptotal",
"impmade": "impmade",
"clicks": "clicks",
"clickurl": "clickurl",
"custombannercode": "custombannercode",
"cid": "cid",
"purchase_type": "purchase_type",
"track_impressions": "track_impressions",
"track_clicks": "track_clicks"
}
}</source>
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. The special fields are optional.

=====Note=====
* The <tt>JHelperTags</tt> and JUcm APIS at 3.1.1 supported arrays for this field, but as of 3.1.4 either arrays or objects are supported; the default is objects.

====<tt>router</tt>====

'''Router''' is an optional entry to include the name of a static helper router method for this type found in its front end helpers folder.

If you only store data in <tt>#__ucm_content</tt> 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 <tt>JHelperRoute</tt>.

== Modify your component's table class (or classes if you have multiple tables) ==

Add the following to your JTable constructor:

$this->_observers = new JObserverUpdater($this);
JObserverMapper::attachAllObservers($this);

'''The addition material formerly located here is no longer needed after 3.1.4''' Please read the document history for this page if you are required to support 3.1.0 or 3.1.1.

'''For joomla 3.2 I needed this line:''' ( Dont forget to replace weblinks by your component name )

JObserverMapper::addObserverClassToClass('JTableObserverTags', 'WeblinksTableWeblink', array('typeAlias' => 'com_weblinks.weblink'));

== 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.

<source lang="xml">
<field name="tags" type="tag"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field></source>

The field loads all the Javascript libraries required. You don't need to worry about that.

The field supports two modes:
* '''Nested tags mode.''' Hierarchical tag list. Doesn't support on the fly tag creation.
* '''AJAX mode.''' Tags are searched while user types (3 min. chars required to launch the AJAX search). Custom tags are added by pressing ENTER or COMMA keys. Tags show the global route/path. Example: <code>grandpa/parent/tag</code>

The field mode can be forced or use the com_tags setting <code>Tag field mode</code> to determine its mode. To set/force the field mode we have to add '''mode="ajax"''' or '''mode="nested"''' to the tag field definition.

Example of forced AJAX mode:

<source lang="xml">
<field name="tags" type="tag" mode="ajax"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>
</source>
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"**

Example field definition with custom tags denied:

<source lang="xml">
<field name="tags" type="tag" mode="ajax" custom="denied"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>

</source>
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:

<source lang="php">
$item->tags = new JHelperTags;
$item->tags->getItemTags('com_newsfeeds.newsfeed.' , $this->item->id);
</source>

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:
<source lang="php">
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>

</source>
Changing the object and property names as appropriate.

You will most likely want to add the show_tags parameter to the item parameters, the menu item parameters and component configuration as appropriate for your use case.

<source lang="php">
<?php if ($this->params->get('show_tags', 1) && !empty($this->item->tags)) : ?>
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>
<?php endif; ?></source>

== Batch processing ==
If you want to add the ability to do batch tagging to a backend list view do the following.

Add tag to the default_batch layout

<source lang="php">
<div class="control-group">
<div class="controls">
<?php echo JHtml::_('batch.tag');?>
</div>
</div></source>

And add tag to the button class in the modal footer (Not totally necessary at this point, but good for potential future changes e.g. if unTag is added.)

<source lang="php">
<button class="btn" type="button" onclick="document.id('batch-category-id').value='';document.id('batch-access').value='';document.id('batch-language-id').value='';document.id('batch-user-id').value='';document.id('batch-tag-id)').value=''" data-dismiss="modal">
</source>

=== Add a batch method to your model if you are not extending JModelAdmin or overriding the batch method. ===

<source lang="php">
/**
* Batch tag a list of item.
*
* @param integer $value The value of the new tag.
* @param array $pks An array of row IDs.
* @param array $contexts An array of item contexts.
*
* @return void.
*
* @since 3.1
*/
protected function batchTag($value, $pks, $contexts)
{
$tagsHelper = new JHelperTags();
$tagsHelper->tagItems($value, $pks, $contexts);

return true;
}
</source>

And modify your batch method by adding
<source lang="php">
if (!empty($commands['tag']))
{
if (!$this->batchTag($commands['tag'], $pks, $contexts))
{
return false;
}

$done = true;
}

</source>

Pay attention to any JSON encoded strings that you need special handling for in batch processing -- remember that you are saving a copy of the core fields and you need save to work as expected.

That’s it, now create some tags, tag some items and you are set.

[[Category:Development]][[Category:Content Tags]]
[[Category:Tutorials]]

J3.x:Using Tags in an Extension

2014-04-26T15:35:30Z

GreyHead: /* rules */

{{copyedit}}

==Introduction==
Joomla's tagging system is used in all core content extensions and is designed to be be easy to integrate into other extensions that use standard Joomla design patterns.

Using tags in an extension is fairly straightforward. It requires these changes to a typical extension:

* Register a 'Content type' for the extension view(s)
* Add 'Observer methods' to the extension table class(es)
* Add 'Tag fields' to the extension edit forms
* Add 'Tag display' code to the extension view files
* Optionally, add a batch tagging method to the extension administration

== Register a content type for each view ==

In Joomla! 3 content types e.g. articles, weblinks, contacts, . . . are registered in the <tt>#__content_types</tt> table with a separate record for each content view e.g. article, weblink, article category, weblink category, . . .

Your extension installer needs to create a new record for each view.

You can create records in the installer in three different ways:
* in the [[J2.5:Managing_Component_Updates_(Script.php)#postflight|postflight]] method
* by creating a <tt>JTableContenttype</tt> instance and adding a row, or
* by using SQL to create a record directly

The structure of the <tt>#__content_types</tt> table is fairly straightforward:
{| class="wikitable"
|-
! Column name !! Column type !! Purpose
|-
| <tt>type_id</tt> || int(10) || Record key
|-
| <tt>type_title</tt>|| varchar(255)|| Type title e.g. <tt>Article</tt>
|-
| <tt>type_alias</tt> || varchar(255)|| Type alias e.g. <tt>com_content.article</tt>
|-
| <tt>table</tt> || varchar(255)|| Information about the Table class
|-
| <tt>rules</tt> || text || Not currently used
|-
| <tt>field_mappings</tt> || text || Maps the table column names to standard Joomla! names
|-
| <tt>router</tt> || varchar(255)|| Optional: name of a router method
|}

===Construct the Content Type entry===

For each table/option/view you will need to make an entry in <tt>#__content_types</tt> table (see above).

====type_id====
This is the auto-incremented record key, nothing to be done here.

====type_title====

The title for your Content Type e.g. Article, Contact, Weblink,
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.

====type_alias====

A string identifying the component and view (that would be in the page request, typically matching the model name) e.g. <tt>com_contact.contact</tt>, <tt>com_weblinks.weblink</tt>.

====table====

You need to identify which tables used by your component contain records to be tagged. For example the 'Contact' view of the Contacts component uses <tt>#__contact_details</tt> and similarly the 'Weblinks' view of the Weblinks component uses <tt>#__weblinks </tt>.

Each of these components uses a class to write to the table: <tt>ContactTableContact</tt> for the Contacts component and <tt>WeblinksTableWeblink</tt> for the Weblinks component. You will need the class prefixes e.g. <tt>ContactTable</tt>, <tt>WeblinksTable</tt>.

Note that Category types all use the <tt>#__categories</tt> table.

The <tt>type_table</tt> entry gives the complete table class information for the table class as a JSON object with two elements. The first element represents your "special" table and the second an optional common table (otherwise it will default the <tt>JTableCorecontent</tt>).

Here is the JSON entry for the Weblink content type:
<source lang="php">{
"special": {
"dbtable": "#__weblinks",
"key": "id",
"type": "Weblink",
"prefix": "WeblinksTable",
"config": "array()"
},
"common": {
"dbtable": "#__ucm_content",
"key": "ucm_id",
"type": "Corecontent",
"prefix": "JTable",
"config": "array()"
}
}</source>
The values to be included are:
{| class="wikitable"
|-
! Entry name !! Content
|-
| <tt>dbtable</tt> || Table name
|-
| <tt>key</tt>|| Primary key name
|-
| <tt>type</tt> || Content type
|-
| <tt>prefix</tt> || Class prefix
|-
| <tt>config</tt> || An option array, as used in your component constructor and getInstance() methods, may be empty
|}

This information 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.

=====Notes=====

* The table name for the common table is <tt>#__ucm_content</tt>; 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 <tt>type_title</tt> field would potentially be used for display although this is not implemented currently except in the contenttype field. Usually it should begin with an upper case letter if it is in English. See note about how to make this translatable. To make your type names translatable add <tt>COM_TAGS_CONTENT_TYPE_+type_title="Type Title"</tt> in both the ini and sys.ini files.

====rules====

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

====<tt>field_mappings</tt>====

This entry 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.

<source lang="php">
'{"common":[{"core_content_item_id":"id","core_title":"title","core_state":"published","core_alias":"alias","core_created_time":"created_time","core_modified_time":"modified_time","core_body":"description", "core_hits":"hits","core_publish_up":"null","core_publish_down":"null","core_access":"access", "core_params":"params", "core_featured":"null", "core_metadata":"metadata", "core_language":"language", "core_images":"null", "core_urls":"null", "core_version":"version", "core_ordering":"null", "core_metakey":"metakey", "core_metadesc":"metadesc", "core_catid":"parent_id", "core_xreference":"null", "asset_id":"asset_id"}], "special": [{"parent_id":"parent_id","lft":"lft","rgt":"rgt","level":"level","path":"path","extension":"extension","note":"note"}]}'
</source>

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.

====<tt>router</tt>====

'''Router''' is an optional entry to include the name of a static helper router method for this type found in its front end helpers folder.

If you only store data in <tt>#__ucm_content</tt> 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 <tt>JHelperRoute</tt>.

== Modify your component's table class (or classes if you have multiple tables) ==

Add the following to your JTable constructor:

$this->_observers = new JObserverUpdater($this);
JObserverMapper::attachAllObservers($this);

'''The addition material formerly located here is no longer needed after 3.1.4''' Please read the document history for this page if you are required to support 3.1.0 or 3.1.1.

'''For joomla 3.2 I needed this line:''' ( Dont forget to replace weblinks by your component name )

JObserverMapper::addObserverClassToClass('JTableObserverTags', 'WeblinksTableWeblink', array('typeAlias' => 'com_weblinks.weblink'));

== 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.

<source lang="xml">
<field name="tags" type="tag"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field></source>

The field loads all the Javascript libraries required. You don't need to worry about that.

The field supports two modes:
* '''Nested tags mode.''' Hierarchical tag list. Doesn't support on the fly tag creation.
* '''AJAX mode.''' Tags are searched while user types (3 min. chars required to launch the AJAX search). Custom tags are added by pressing ENTER or COMMA keys. Tags show the global route/path. Example: <code>grandpa/parent/tag</code>

The field mode can be forced or use the com_tags setting <code>Tag field mode</code> to determine its mode. To set/force the field mode we have to add '''mode="ajax"''' or '''mode="nested"''' to the tag field definition.

Example of forced AJAX mode:

<source lang="xml">
<field name="tags" type="tag" mode="ajax"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>
</source>
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"**

Example field definition with custom tags denied:

<source lang="xml">
<field name="tags" type="tag" mode="ajax" custom="denied"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>

</source>
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:

<source lang="php">
$item->tags = new JHelperTags;
$item->tags->getItemTags('com_newsfeeds.newsfeed.' , $this->item->id);
</source>

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:
<source lang="php">
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>

</source>
Changing the object and property names as appropriate.

You will most likely want to add the show_tags parameter to the item parameters, the menu item parameters and component configuration as appropriate for your use case.

<source lang="php">
<?php if ($this->params->get('show_tags', 1) && !empty($this->item->tags)) : ?>
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>
<?php endif; ?></source>

== Batch processing ==
If you want to add the ability to do batch tagging to a backend list view do the following.

Add tag to the default_batch layout

<source lang="php">
<div class="control-group">
<div class="controls">
<?php echo JHtml::_('batch.tag');?>
</div>
</div></source>

And add tag to the button class in the modal footer (Not totally necessary at this point, but good for potential future changes e.g. if unTag is added.)

<source lang="php">
<button class="btn" type="button" onclick="document.id('batch-category-id').value='';document.id('batch-access').value='';document.id('batch-language-id').value='';document.id('batch-user-id').value='';document.id('batch-tag-id)').value=''" data-dismiss="modal">
</source>

=== Add a batch method to your model if you are not extending JModelAdmin or overriding the batch method. ===

<source lang="php">
/**
* Batch tag a list of item.
*
* @param integer $value The value of the new tag.
* @param array $pks An array of row IDs.
* @param array $contexts An array of item contexts.
*
* @return void.
*
* @since 3.1
*/
protected function batchTag($value, $pks, $contexts)
{
$tagsHelper = new JHelperTags();
$tagsHelper->tagItems($value, $pks, $contexts);

return true;
}
</source>

And modify your batch method by adding
<source lang="php">
if (!empty($commands['tag']))
{
if (!$this->batchTag($commands['tag'], $pks, $contexts))
{
return false;
}

$done = true;
}

</source>

Pay attention to any JSON encoded strings that you need special handling for in batch processing -- remember that you are saving a copy of the core fields and you need save to work as expected.

That’s it, now create some tags, tag some items and you are set.

[[Category:Development]][[Category:Content Tags]]
[[Category:Tutorials]]

J3.x:Using Tags in an Extension

2014-04-26T15:34:43Z

GreyHead: /* table */

{{copyedit}}

==Introduction==
Joomla's tagging system is used in all core content extensions and is designed to be be easy to integrate into other extensions that use standard Joomla design patterns.

Using tags in an extension is fairly straightforward. It requires these changes to a typical extension:

* Register a 'Content type' for the extension view(s)
* Add 'Observer methods' to the extension table class(es)
* Add 'Tag fields' to the extension edit forms
* Add 'Tag display' code to the extension view files
* Optionally, add a batch tagging method to the extension administration

== Register a content type for each view ==

In Joomla! 3 content types e.g. articles, weblinks, contacts, . . . are registered in the <tt>#__content_types</tt> table with a separate record for each content view e.g. article, weblink, article category, weblink category, . . .

Your extension installer needs to create a new record for each view.

You can create records in the installer in three different ways:
* in the [[J2.5:Managing_Component_Updates_(Script.php)#postflight|postflight]] method
* by creating a <tt>JTableContenttype</tt> instance and adding a row, or
* by using SQL to create a record directly

The structure of the <tt>#__content_types</tt> table is fairly straightforward:
{| class="wikitable"
|-
! Column name !! Column type !! Purpose
|-
| <tt>type_id</tt> || int(10) || Record key
|-
| <tt>type_title</tt>|| varchar(255)|| Type title e.g. <tt>Article</tt>
|-
| <tt>type_alias</tt> || varchar(255)|| Type alias e.g. <tt>com_content.article</tt>
|-
| <tt>table</tt> || varchar(255)|| Information about the Table class
|-
| <tt>rules</tt> || text || Not currently used
|-
| <tt>field_mappings</tt> || text || Maps the table column names to standard Joomla! names
|-
| <tt>router</tt> || varchar(255)|| Optional: name of a router method
|}

===Construct the Content Type entry===

For each table/option/view you will need to make an entry in <tt>#__content_types</tt> table (see above).

====type_id====
This is the auto-incremented record key, nothing to be done here.

====type_title====

The title for your Content Type e.g. Article, Contact, Weblink,
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.

====type_alias====

A string identifying the component and view (that would be in the page request, typically matching the model name) e.g. <tt>com_contact.contact</tt>, <tt>com_weblinks.weblink</tt>.

====table====

You need to identify which tables used by your component contain records to be tagged. For example the 'Contact' view of the Contacts component uses <tt>#__contact_details</tt> and similarly the 'Weblinks' view of the Weblinks component uses <tt>#__weblinks </tt>.

Each of these components uses a class to write to the table: <tt>ContactTableContact</tt> for the Contacts component and <tt>WeblinksTableWeblink</tt> for the Weblinks component. You will need the class prefixes e.g. <tt>ContactTable</tt>, <tt>WeblinksTable</tt>.

Note that Category types all use the <tt>#__categories</tt> table.

The <tt>type_table</tt> entry gives the complete table class information for the table class as a JSON object with two elements. The first element represents your "special" table and the second an optional common table (otherwise it will default the <tt>JTableCorecontent</tt>).

Here is the JSON entry for the Weblink content type:
<source lang="php">{
"special": {
"dbtable": "#__weblinks",
"key": "id",
"type": "Weblink",
"prefix": "WeblinksTable",
"config": "array()"
},
"common": {
"dbtable": "#__ucm_content",
"key": "ucm_id",
"type": "Corecontent",
"prefix": "JTable",
"config": "array()"
}
}</source>
The values to be included are:
{| class="wikitable"
|-
! Entry name !! Content
|-
| <tt>dbtable</tt> || Table name
|-
| <tt>key</tt>|| Primary key name
|-
| <tt>type</tt> || Content type
|-
| <tt>prefix</tt> || Class prefix
|-
| <tt>config</tt> || An option array, as used in your component constructor and getInstance() methods, may be empty
|}

This information 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.

=====Notes=====

* The table name for the common table is <tt>#__ucm_content</tt>; 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 <tt>type_title</tt> field would potentially be used for display although this is not implemented currently except in the contenttype field. Usually it should begin with an upper case letter if it is in English. See note about how to make this translatable. To make your type names translatable add <tt>COM_TAGS_CONTENT_TYPE_+type_title="Type Title"</tt> in both the ini and sys.ini files.

====<tt>rules</tt>====

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.

====<tt>field_mappings</tt>====

This entry 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.

<source lang="php">
'{"common":[{"core_content_item_id":"id","core_title":"title","core_state":"published","core_alias":"alias","core_created_time":"created_time","core_modified_time":"modified_time","core_body":"description", "core_hits":"hits","core_publish_up":"null","core_publish_down":"null","core_access":"access", "core_params":"params", "core_featured":"null", "core_metadata":"metadata", "core_language":"language", "core_images":"null", "core_urls":"null", "core_version":"version", "core_ordering":"null", "core_metakey":"metakey", "core_metadesc":"metadesc", "core_catid":"parent_id", "core_xreference":"null", "asset_id":"asset_id"}], "special": [{"parent_id":"parent_id","lft":"lft","rgt":"rgt","level":"level","path":"path","extension":"extension","note":"note"}]}'
</source>

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.

====<tt>router</tt>====

'''Router''' is an optional entry to include the name of a static helper router method for this type found in its front end helpers folder.

If you only store data in <tt>#__ucm_content</tt> 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 <tt>JHelperRoute</tt>.

== Modify your component's table class (or classes if you have multiple tables) ==

Add the following to your JTable constructor:

$this->_observers = new JObserverUpdater($this);
JObserverMapper::attachAllObservers($this);

'''The addition material formerly located here is no longer needed after 3.1.4''' Please read the document history for this page if you are required to support 3.1.0 or 3.1.1.

'''For joomla 3.2 I needed this line:''' ( Dont forget to replace weblinks by your component name )

JObserverMapper::addObserverClassToClass('JTableObserverTags', 'WeblinksTableWeblink', array('typeAlias' => 'com_weblinks.weblink'));

== 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.

<source lang="xml">
<field name="tags" type="tag"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field></source>

The field loads all the Javascript libraries required. You don't need to worry about that.

The field supports two modes:
* '''Nested tags mode.''' Hierarchical tag list. Doesn't support on the fly tag creation.
* '''AJAX mode.''' Tags are searched while user types (3 min. chars required to launch the AJAX search). Custom tags are added by pressing ENTER or COMMA keys. Tags show the global route/path. Example: <code>grandpa/parent/tag</code>

The field mode can be forced or use the com_tags setting <code>Tag field mode</code> to determine its mode. To set/force the field mode we have to add '''mode="ajax"''' or '''mode="nested"''' to the tag field definition.

Example of forced AJAX mode:

<source lang="xml">
<field name="tags" type="tag" mode="ajax"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>
</source>
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"**

Example field definition with custom tags denied:

<source lang="xml">
<field name="tags" type="tag" mode="ajax" custom="denied"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>

</source>
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:

<source lang="php">
$item->tags = new JHelperTags;
$item->tags->getItemTags('com_newsfeeds.newsfeed.' , $this->item->id);
</source>

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:
<source lang="php">
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>

</source>
Changing the object and property names as appropriate.

You will most likely want to add the show_tags parameter to the item parameters, the menu item parameters and component configuration as appropriate for your use case.

<source lang="php">
<?php if ($this->params->get('show_tags', 1) && !empty($this->item->tags)) : ?>
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>
<?php endif; ?></source>

== Batch processing ==
If you want to add the ability to do batch tagging to a backend list view do the following.

Add tag to the default_batch layout

<source lang="php">
<div class="control-group">
<div class="controls">
<?php echo JHtml::_('batch.tag');?>
</div>
</div></source>

And add tag to the button class in the modal footer (Not totally necessary at this point, but good for potential future changes e.g. if unTag is added.)

<source lang="php">
<button class="btn" type="button" onclick="document.id('batch-category-id').value='';document.id('batch-access').value='';document.id('batch-language-id').value='';document.id('batch-user-id').value='';document.id('batch-tag-id)').value=''" data-dismiss="modal">
</source>

=== Add a batch method to your model if you are not extending JModelAdmin or overriding the batch method. ===

<source lang="php">
/**
* Batch tag a list of item.
*
* @param integer $value The value of the new tag.
* @param array $pks An array of row IDs.
* @param array $contexts An array of item contexts.
*
* @return void.
*
* @since 3.1
*/
protected function batchTag($value, $pks, $contexts)
{
$tagsHelper = new JHelperTags();
$tagsHelper->tagItems($value, $pks, $contexts);

return true;
}
</source>

And modify your batch method by adding
<source lang="php">
if (!empty($commands['tag']))
{
if (!$this->batchTag($commands['tag'], $pks, $contexts))
{
return false;
}

$done = true;
}

</source>

Pay attention to any JSON encoded strings that you need special handling for in batch processing -- remember that you are saving a copy of the core fields and you need save to work as expected.

That’s it, now create some tags, tag some items and you are set.

[[Category:Development]][[Category:Content Tags]]
[[Category:Tutorials]]

J3.x:Using Tags in an Extension

2014-04-26T15:34:12Z

GreyHead: /* Notes */

{{copyedit}}

==Introduction==
Joomla's tagging system is used in all core content extensions and is designed to be be easy to integrate into other extensions that use standard Joomla design patterns.

Using tags in an extension is fairly straightforward. It requires these changes to a typical extension:

* Register a 'Content type' for the extension view(s)
* Add 'Observer methods' to the extension table class(es)
* Add 'Tag fields' to the extension edit forms
* Add 'Tag display' code to the extension view files
* Optionally, add a batch tagging method to the extension administration

== Register a content type for each view ==

In Joomla! 3 content types e.g. articles, weblinks, contacts, . . . are registered in the <tt>#__content_types</tt> table with a separate record for each content view e.g. article, weblink, article category, weblink category, . . .

Your extension installer needs to create a new record for each view.

You can create records in the installer in three different ways:
* in the [[J2.5:Managing_Component_Updates_(Script.php)#postflight|postflight]] method
* by creating a <tt>JTableContenttype</tt> instance and adding a row, or
* by using SQL to create a record directly

The structure of the <tt>#__content_types</tt> table is fairly straightforward:
{| class="wikitable"
|-
! Column name !! Column type !! Purpose
|-
| <tt>type_id</tt> || int(10) || Record key
|-
| <tt>type_title</tt>|| varchar(255)|| Type title e.g. <tt>Article</tt>
|-
| <tt>type_alias</tt> || varchar(255)|| Type alias e.g. <tt>com_content.article</tt>
|-
| <tt>table</tt> || varchar(255)|| Information about the Table class
|-
| <tt>rules</tt> || text || Not currently used
|-
| <tt>field_mappings</tt> || text || Maps the table column names to standard Joomla! names
|-
| <tt>router</tt> || varchar(255)|| Optional: name of a router method
|}

===Construct the Content Type entry===

For each table/option/view you will need to make an entry in <tt>#__content_types</tt> table (see above).

====type_id====
This is the auto-incremented record key, nothing to be done here.

====type_title====

The title for your Content Type e.g. Article, Contact, Weblink,
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.

====type_alias====

A string identifying the component and view (that would be in the page request, typically matching the model name) e.g. <tt>com_contact.contact</tt>, <tt>com_weblinks.weblink</tt>.

====<tt>table</tt>====

You need to identify which tables used by your component contain records to be tagged. For example the 'Contact' view of the Contacts component uses <tt>#__contact_details</tt> and similarly the 'Weblinks' view of the Weblinks component uses <tt>#__weblinks </tt>.

Each of these components uses a class to write to the table: <tt>ContactTableContact</tt> for the Contacts component and <tt>WeblinksTableWeblink</tt> for the Weblinks component. You will need the class prefixes e.g. <tt>ContactTable</tt>, <tt>WeblinksTable</tt>.

Note that Category types all use the <tt>#__categories</tt> table.

The <tt>type_table</tt> entry gives the complete table class information for the table class as a JSON object with two elements. The first element represents your "special" table and the second an optional common table (otherwise it will default the <tt>JTableCorecontent</tt>).

Here is the JSON entry for the Weblink content type:
<source lang="php">{
"special": {
"dbtable": "#__weblinks",
"key": "id",
"type": "Weblink",
"prefix": "WeblinksTable",
"config": "array()"
},
"common": {
"dbtable": "#__ucm_content",
"key": "ucm_id",
"type": "Corecontent",
"prefix": "JTable",
"config": "array()"
}
}</source>
The values to be included are:
{| class="wikitable"
|-
! Entry name !! Content
|-
| <tt>dbtable</tt> || Table name
|-
| <tt>key</tt>|| Primary key name
|-
| <tt>type</tt> || Content type
|-
| <tt>prefix</tt> || Class prefix
|-
| <tt>config</tt> || An option array, as used in your component constructor and getInstance() methods, may be empty
|}

This information 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.

=====Notes=====

* The table name for the common table is <tt>#__ucm_content</tt>; 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 <tt>type_title</tt> field would potentially be used for display although this is not implemented currently except in the contenttype field. Usually it should begin with an upper case letter if it is in English. See note about how to make this translatable. To make your type names translatable add <tt>COM_TAGS_CONTENT_TYPE_+type_title="Type Title"</tt> in both the ini and sys.ini files.

====<tt>rules</tt>====

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.

====<tt>field_mappings</tt>====

This entry 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.

<source lang="php">
'{"common":[{"core_content_item_id":"id","core_title":"title","core_state":"published","core_alias":"alias","core_created_time":"created_time","core_modified_time":"modified_time","core_body":"description", "core_hits":"hits","core_publish_up":"null","core_publish_down":"null","core_access":"access", "core_params":"params", "core_featured":"null", "core_metadata":"metadata", "core_language":"language", "core_images":"null", "core_urls":"null", "core_version":"version", "core_ordering":"null", "core_metakey":"metakey", "core_metadesc":"metadesc", "core_catid":"parent_id", "core_xreference":"null", "asset_id":"asset_id"}], "special": [{"parent_id":"parent_id","lft":"lft","rgt":"rgt","level":"level","path":"path","extension":"extension","note":"note"}]}'
</source>

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.

====<tt>router</tt>====

'''Router''' is an optional entry to include the name of a static helper router method for this type found in its front end helpers folder.

If you only store data in <tt>#__ucm_content</tt> 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 <tt>JHelperRoute</tt>.

== Modify your component's table class (or classes if you have multiple tables) ==

Add the following to your JTable constructor:

$this->_observers = new JObserverUpdater($this);
JObserverMapper::attachAllObservers($this);

'''The addition material formerly located here is no longer needed after 3.1.4''' Please read the document history for this page if you are required to support 3.1.0 or 3.1.1.

'''For joomla 3.2 I needed this line:''' ( Dont forget to replace weblinks by your component name )

JObserverMapper::addObserverClassToClass('JTableObserverTags', 'WeblinksTableWeblink', array('typeAlias' => 'com_weblinks.weblink'));

== 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.

<source lang="xml">
<field name="tags" type="tag"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field></source>

The field loads all the Javascript libraries required. You don't need to worry about that.

The field supports two modes:
* '''Nested tags mode.''' Hierarchical tag list. Doesn't support on the fly tag creation.
* '''AJAX mode.''' Tags are searched while user types (3 min. chars required to launch the AJAX search). Custom tags are added by pressing ENTER or COMMA keys. Tags show the global route/path. Example: <code>grandpa/parent/tag</code>

The field mode can be forced or use the com_tags setting <code>Tag field mode</code> to determine its mode. To set/force the field mode we have to add '''mode="ajax"''' or '''mode="nested"''' to the tag field definition.

Example of forced AJAX mode:

<source lang="xml">
<field name="tags" type="tag" mode="ajax"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>
</source>
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"**

Example field definition with custom tags denied:

<source lang="xml">
<field name="tags" type="tag" mode="ajax" custom="denied"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>

</source>
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:

<source lang="php">
$item->tags = new JHelperTags;
$item->tags->getItemTags('com_newsfeeds.newsfeed.' , $this->item->id);
</source>

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:
<source lang="php">
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>

</source>
Changing the object and property names as appropriate.

You will most likely want to add the show_tags parameter to the item parameters, the menu item parameters and component configuration as appropriate for your use case.

<source lang="php">
<?php if ($this->params->get('show_tags', 1) && !empty($this->item->tags)) : ?>
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>
<?php endif; ?></source>

== Batch processing ==
If you want to add the ability to do batch tagging to a backend list view do the following.

Add tag to the default_batch layout

<source lang="php">
<div class="control-group">
<div class="controls">
<?php echo JHtml::_('batch.tag');?>
</div>
</div></source>

And add tag to the button class in the modal footer (Not totally necessary at this point, but good for potential future changes e.g. if unTag is added.)

<source lang="php">
<button class="btn" type="button" onclick="document.id('batch-category-id').value='';document.id('batch-access').value='';document.id('batch-language-id').value='';document.id('batch-user-id').value='';document.id('batch-tag-id)').value=''" data-dismiss="modal">
</source>

=== Add a batch method to your model if you are not extending JModelAdmin or overriding the batch method. ===

<source lang="php">
/**
* Batch tag a list of item.
*
* @param integer $value The value of the new tag.
* @param array $pks An array of row IDs.
* @param array $contexts An array of item contexts.
*
* @return void.
*
* @since 3.1
*/
protected function batchTag($value, $pks, $contexts)
{
$tagsHelper = new JHelperTags();
$tagsHelper->tagItems($value, $pks, $contexts);

return true;
}
</source>

And modify your batch method by adding
<source lang="php">
if (!empty($commands['tag']))
{
if (!$this->batchTag($commands['tag'], $pks, $contexts))
{
return false;
}

$done = true;
}

</source>

Pay attention to any JSON encoded strings that you need special handling for in batch processing -- remember that you are saving a copy of the core fields and you need save to work as expected.

That’s it, now create some tags, tag some items and you are set.

[[Category:Development]][[Category:Content Tags]]
[[Category:Tutorials]]

J3.x:Using Tags in an Extension

2014-04-26T15:33:41Z

GreyHead: /* type_alias */

{{copyedit}}

==Introduction==
Joomla's tagging system is used in all core content extensions and is designed to be be easy to integrate into other extensions that use standard Joomla design patterns.

Using tags in an extension is fairly straightforward. It requires these changes to a typical extension:

* Register a 'Content type' for the extension view(s)
* Add 'Observer methods' to the extension table class(es)
* Add 'Tag fields' to the extension edit forms
* Add 'Tag display' code to the extension view files
* Optionally, add a batch tagging method to the extension administration

== Register a content type for each view ==

In Joomla! 3 content types e.g. articles, weblinks, contacts, . . . are registered in the <tt>#__content_types</tt> table with a separate record for each content view e.g. article, weblink, article category, weblink category, . . .

Your extension installer needs to create a new record for each view.

You can create records in the installer in three different ways:
* in the [[J2.5:Managing_Component_Updates_(Script.php)#postflight|postflight]] method
* by creating a <tt>JTableContenttype</tt> instance and adding a row, or
* by using SQL to create a record directly

The structure of the <tt>#__content_types</tt> table is fairly straightforward:
{| class="wikitable"
|-
! Column name !! Column type !! Purpose
|-
| <tt>type_id</tt> || int(10) || Record key
|-
| <tt>type_title</tt>|| varchar(255)|| Type title e.g. <tt>Article</tt>
|-
| <tt>type_alias</tt> || varchar(255)|| Type alias e.g. <tt>com_content.article</tt>
|-
| <tt>table</tt> || varchar(255)|| Information about the Table class
|-
| <tt>rules</tt> || text || Not currently used
|-
| <tt>field_mappings</tt> || text || Maps the table column names to standard Joomla! names
|-
| <tt>router</tt> || varchar(255)|| Optional: name of a router method
|}

===Construct the Content Type entry===

For each table/option/view you will need to make an entry in <tt>#__content_types</tt> table (see above).

====type_id====
This is the auto-incremented record key, nothing to be done here.

====type_title====

The title for your Content Type e.g. Article, Contact, Weblink,
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.

====type_alias====

A string identifying the component and view (that would be in the page request, typically matching the model name) e.g. <tt>com_contact.contact</tt>, <tt>com_weblinks.weblink</tt>.

====<tt>table</tt>====

You need to identify which tables used by your component contain records to be tagged. For example the 'Contact' view of the Contacts component uses <tt>#__contact_details</tt> and similarly the 'Weblinks' view of the Weblinks component uses <tt>#__weblinks </tt>.

Each of these components uses a class to write to the table: <tt>ContactTableContact</tt> for the Contacts component and <tt>WeblinksTableWeblink</tt> for the Weblinks component. You will need the class prefixes e.g. <tt>ContactTable</tt>, <tt>WeblinksTable</tt>.

Note that Category types all use the <tt>#__categories</tt> table.

The <tt>type_table</tt> entry gives the complete table class information for the table class as a JSON object with two elements. The first element represents your "special" table and the second an optional common table (otherwise it will default the <tt>JTableCorecontent</tt>).

Here is the JSON entry for the Weblink content type:
<source lang="php">{
"special": {
"dbtable": "#__weblinks",
"key": "id",
"type": "Weblink",
"prefix": "WeblinksTable",
"config": "array()"
},
"common": {
"dbtable": "#__ucm_content",
"key": "ucm_id",
"type": "Corecontent",
"prefix": "JTable",
"config": "array()"
}
}</source>
The values to be included are:
{| class="wikitable"
|-
! Entry name !! Content
|-
| <tt>dbtable</tt> || Table name
|-
| <tt>key</tt>|| Primary key name
|-
| <tt>type</tt> || Content type
|-
| <tt>prefix</tt> || Class prefix
|-
| <tt>config</tt> || An option array, as used in your component constructor and getInstance() methods, may be empty
|}

This information 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.

=====Notes=====

* The table name for the common table is <tt>#__ucm_content</tt>; 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 <tt>type_title</tt> field would potentially be used for display although this is not implemented currently except in the contenttype field. Usually it should begin with an upper case letter if it is in English. See note about how to make this translatable. To make your type names translatable add <tt>COM_TAGS_CONTENT_TYPE_+type_title="Type Title"</tt> in both the ini and sys.ini files.

====<tt>rules</tt>====

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.

====<tt>field_mappings</tt>====

This entry 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.

<source lang="php">
'{"common":[{"core_content_item_id":"id","core_title":"title","core_state":"published","core_alias":"alias","core_created_time":"created_time","core_modified_time":"modified_time","core_body":"description", "core_hits":"hits","core_publish_up":"null","core_publish_down":"null","core_access":"access", "core_params":"params", "core_featured":"null", "core_metadata":"metadata", "core_language":"language", "core_images":"null", "core_urls":"null", "core_version":"version", "core_ordering":"null", "core_metakey":"metakey", "core_metadesc":"metadesc", "core_catid":"parent_id", "core_xreference":"null", "asset_id":"asset_id"}], "special": [{"parent_id":"parent_id","lft":"lft","rgt":"rgt","level":"level","path":"path","extension":"extension","note":"note"}]}'
</source>

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.

====<tt>router</tt>====

'''Router''' is an optional entry to include the name of a static helper router method for this type found in its front end helpers folder.

If you only store data in <tt>#__ucm_content</tt> 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 <tt>JHelperRoute</tt>.

== Modify your component's table class (or classes if you have multiple tables) ==

Add the following to your JTable constructor:

$this->_observers = new JObserverUpdater($this);
JObserverMapper::attachAllObservers($this);

'''The addition material formerly located here is no longer needed after 3.1.4''' Please read the document history for this page if you are required to support 3.1.0 or 3.1.1.

'''For joomla 3.2 I needed this line:''' ( Dont forget to replace weblinks by your component name )

JObserverMapper::addObserverClassToClass('JTableObserverTags', 'WeblinksTableWeblink', array('typeAlias' => 'com_weblinks.weblink'));

== 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.

<source lang="xml">
<field name="tags" type="tag"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field></source>

The field loads all the Javascript libraries required. You don't need to worry about that.

The field supports two modes:
* '''Nested tags mode.''' Hierarchical tag list. Doesn't support on the fly tag creation.
* '''AJAX mode.''' Tags are searched while user types (3 min. chars required to launch the AJAX search). Custom tags are added by pressing ENTER or COMMA keys. Tags show the global route/path. Example: <code>grandpa/parent/tag</code>

The field mode can be forced or use the com_tags setting <code>Tag field mode</code> to determine its mode. To set/force the field mode we have to add '''mode="ajax"''' or '''mode="nested"''' to the tag field definition.

Example of forced AJAX mode:

<source lang="xml">
<field name="tags" type="tag" mode="ajax"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>
</source>
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"**

Example field definition with custom tags denied:

<source lang="xml">
<field name="tags" type="tag" mode="ajax" custom="denied"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>

</source>
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:

<source lang="php">
$item->tags = new JHelperTags;
$item->tags->getItemTags('com_newsfeeds.newsfeed.' , $this->item->id);
</source>

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:
<source lang="php">
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>

</source>
Changing the object and property names as appropriate.

You will most likely want to add the show_tags parameter to the item parameters, the menu item parameters and component configuration as appropriate for your use case.

<source lang="php">
<?php if ($this->params->get('show_tags', 1) && !empty($this->item->tags)) : ?>
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>
<?php endif; ?></source>

== Batch processing ==
If you want to add the ability to do batch tagging to a backend list view do the following.

Add tag to the default_batch layout

<source lang="php">
<div class="control-group">
<div class="controls">
<?php echo JHtml::_('batch.tag');?>
</div>
</div></source>

And add tag to the button class in the modal footer (Not totally necessary at this point, but good for potential future changes e.g. if unTag is added.)

<source lang="php">
<button class="btn" type="button" onclick="document.id('batch-category-id').value='';document.id('batch-access').value='';document.id('batch-language-id').value='';document.id('batch-user-id').value='';document.id('batch-tag-id)').value=''" data-dismiss="modal">
</source>

=== Add a batch method to your model if you are not extending JModelAdmin or overriding the batch method. ===

<source lang="php">
/**
* Batch tag a list of item.
*
* @param integer $value The value of the new tag.
* @param array $pks An array of row IDs.
* @param array $contexts An array of item contexts.
*
* @return void.
*
* @since 3.1
*/
protected function batchTag($value, $pks, $contexts)
{
$tagsHelper = new JHelperTags();
$tagsHelper->tagItems($value, $pks, $contexts);

return true;
}
</source>

And modify your batch method by adding
<source lang="php">
if (!empty($commands['tag']))
{
if (!$this->batchTag($commands['tag'], $pks, $contexts))
{
return false;
}

$done = true;
}

</source>

Pay attention to any JSON encoded strings that you need special handling for in batch processing -- remember that you are saving a copy of the core fields and you need save to work as expected.

That’s it, now create some tags, tag some items and you are set.

[[Category:Development]][[Category:Content Tags]]
[[Category:Tutorials]]

J3.x:Using Tags in an Extension

2014-04-26T15:33:20Z

GreyHead: /* type_title */

{{copyedit}}

==Introduction==
Joomla's tagging system is used in all core content extensions and is designed to be be easy to integrate into other extensions that use standard Joomla design patterns.

Using tags in an extension is fairly straightforward. It requires these changes to a typical extension:

* Register a 'Content type' for the extension view(s)
* Add 'Observer methods' to the extension table class(es)
* Add 'Tag fields' to the extension edit forms
* Add 'Tag display' code to the extension view files
* Optionally, add a batch tagging method to the extension administration

== Register a content type for each view ==

In Joomla! 3 content types e.g. articles, weblinks, contacts, . . . are registered in the <tt>#__content_types</tt> table with a separate record for each content view e.g. article, weblink, article category, weblink category, . . .

Your extension installer needs to create a new record for each view.

You can create records in the installer in three different ways:
* in the [[J2.5:Managing_Component_Updates_(Script.php)#postflight|postflight]] method
* by creating a <tt>JTableContenttype</tt> instance and adding a row, or
* by using SQL to create a record directly

The structure of the <tt>#__content_types</tt> table is fairly straightforward:
{| class="wikitable"
|-
! Column name !! Column type !! Purpose
|-
| <tt>type_id</tt> || int(10) || Record key
|-
| <tt>type_title</tt>|| varchar(255)|| Type title e.g. <tt>Article</tt>
|-
| <tt>type_alias</tt> || varchar(255)|| Type alias e.g. <tt>com_content.article</tt>
|-
| <tt>table</tt> || varchar(255)|| Information about the Table class
|-
| <tt>rules</tt> || text || Not currently used
|-
| <tt>field_mappings</tt> || text || Maps the table column names to standard Joomla! names
|-
| <tt>router</tt> || varchar(255)|| Optional: name of a router method
|}

===Construct the Content Type entry===

For each table/option/view you will need to make an entry in <tt>#__content_types</tt> table (see above).

====type_id====
This is the auto-incremented record key, nothing to be done here.

====type_title====

The title for your Content Type e.g. Article, Contact, Weblink,
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.

====<tt>type_alias</tt>====

A string identifying the component and view (that would be in the page request, typically matching the model name) e.g. <tt>com_contact.contact</tt>, <tt>com_weblinks.weblink</tt>.

====<tt>table</tt>====

You need to identify which tables used by your component contain records to be tagged. For example the 'Contact' view of the Contacts component uses <tt>#__contact_details</tt> and similarly the 'Weblinks' view of the Weblinks component uses <tt>#__weblinks </tt>.

Each of these components uses a class to write to the table: <tt>ContactTableContact</tt> for the Contacts component and <tt>WeblinksTableWeblink</tt> for the Weblinks component. You will need the class prefixes e.g. <tt>ContactTable</tt>, <tt>WeblinksTable</tt>.

Note that Category types all use the <tt>#__categories</tt> table.

The <tt>type_table</tt> entry gives the complete table class information for the table class as a JSON object with two elements. The first element represents your "special" table and the second an optional common table (otherwise it will default the <tt>JTableCorecontent</tt>).

Here is the JSON entry for the Weblink content type:
<source lang="php">{
"special": {
"dbtable": "#__weblinks",
"key": "id",
"type": "Weblink",
"prefix": "WeblinksTable",
"config": "array()"
},
"common": {
"dbtable": "#__ucm_content",
"key": "ucm_id",
"type": "Corecontent",
"prefix": "JTable",
"config": "array()"
}
}</source>
The values to be included are:
{| class="wikitable"
|-
! Entry name !! Content
|-
| <tt>dbtable</tt> || Table name
|-
| <tt>key</tt>|| Primary key name
|-
| <tt>type</tt> || Content type
|-
| <tt>prefix</tt> || Class prefix
|-
| <tt>config</tt> || An option array, as used in your component constructor and getInstance() methods, may be empty
|}

This information 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.

=====Notes=====

* The table name for the common table is <tt>#__ucm_content</tt>; 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 <tt>type_title</tt> field would potentially be used for display although this is not implemented currently except in the contenttype field. Usually it should begin with an upper case letter if it is in English. See note about how to make this translatable. To make your type names translatable add <tt>COM_TAGS_CONTENT_TYPE_+type_title="Type Title"</tt> in both the ini and sys.ini files.

====<tt>rules</tt>====

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.

====<tt>field_mappings</tt>====

This entry 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.

<source lang="php">
'{"common":[{"core_content_item_id":"id","core_title":"title","core_state":"published","core_alias":"alias","core_created_time":"created_time","core_modified_time":"modified_time","core_body":"description", "core_hits":"hits","core_publish_up":"null","core_publish_down":"null","core_access":"access", "core_params":"params", "core_featured":"null", "core_metadata":"metadata", "core_language":"language", "core_images":"null", "core_urls":"null", "core_version":"version", "core_ordering":"null", "core_metakey":"metakey", "core_metadesc":"metadesc", "core_catid":"parent_id", "core_xreference":"null", "asset_id":"asset_id"}], "special": [{"parent_id":"parent_id","lft":"lft","rgt":"rgt","level":"level","path":"path","extension":"extension","note":"note"}]}'
</source>

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.

====<tt>router</tt>====

'''Router''' is an optional entry to include the name of a static helper router method for this type found in its front end helpers folder.

If you only store data in <tt>#__ucm_content</tt> 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 <tt>JHelperRoute</tt>.

== Modify your component's table class (or classes if you have multiple tables) ==

Add the following to your JTable constructor:

$this->_observers = new JObserverUpdater($this);
JObserverMapper::attachAllObservers($this);

'''The addition material formerly located here is no longer needed after 3.1.4''' Please read the document history for this page if you are required to support 3.1.0 or 3.1.1.

'''For joomla 3.2 I needed this line:''' ( Dont forget to replace weblinks by your component name )

JObserverMapper::addObserverClassToClass('JTableObserverTags', 'WeblinksTableWeblink', array('typeAlias' => 'com_weblinks.weblink'));

== 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.

<source lang="xml">
<field name="tags" type="tag"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field></source>

The field loads all the Javascript libraries required. You don't need to worry about that.

The field supports two modes:
* '''Nested tags mode.''' Hierarchical tag list. Doesn't support on the fly tag creation.
* '''AJAX mode.''' Tags are searched while user types (3 min. chars required to launch the AJAX search). Custom tags are added by pressing ENTER or COMMA keys. Tags show the global route/path. Example: <code>grandpa/parent/tag</code>

The field mode can be forced or use the com_tags setting <code>Tag field mode</code> to determine its mode. To set/force the field mode we have to add '''mode="ajax"''' or '''mode="nested"''' to the tag field definition.

Example of forced AJAX mode:

<source lang="xml">
<field name="tags" type="tag" mode="ajax"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>
</source>
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"**

Example field definition with custom tags denied:

<source lang="xml">
<field name="tags" type="tag" mode="ajax" custom="denied"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>

</source>
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:

<source lang="php">
$item->tags = new JHelperTags;
$item->tags->getItemTags('com_newsfeeds.newsfeed.' , $this->item->id);
</source>

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:
<source lang="php">
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>

</source>
Changing the object and property names as appropriate.

You will most likely want to add the show_tags parameter to the item parameters, the menu item parameters and component configuration as appropriate for your use case.

<source lang="php">
<?php if ($this->params->get('show_tags', 1) && !empty($this->item->tags)) : ?>
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>
<?php endif; ?></source>

== Batch processing ==
If you want to add the ability to do batch tagging to a backend list view do the following.

Add tag to the default_batch layout

<source lang="php">
<div class="control-group">
<div class="controls">
<?php echo JHtml::_('batch.tag');?>
</div>
</div></source>

And add tag to the button class in the modal footer (Not totally necessary at this point, but good for potential future changes e.g. if unTag is added.)

<source lang="php">
<button class="btn" type="button" onclick="document.id('batch-category-id').value='';document.id('batch-access').value='';document.id('batch-language-id').value='';document.id('batch-user-id').value='';document.id('batch-tag-id)').value=''" data-dismiss="modal">
</source>

=== Add a batch method to your model if you are not extending JModelAdmin or overriding the batch method. ===

<source lang="php">
/**
* Batch tag a list of item.
*
* @param integer $value The value of the new tag.
* @param array $pks An array of row IDs.
* @param array $contexts An array of item contexts.
*
* @return void.
*
* @since 3.1
*/
protected function batchTag($value, $pks, $contexts)
{
$tagsHelper = new JHelperTags();
$tagsHelper->tagItems($value, $pks, $contexts);

return true;
}
</source>

And modify your batch method by adding
<source lang="php">
if (!empty($commands['tag']))
{
if (!$this->batchTag($commands['tag'], $pks, $contexts))
{
return false;
}

$done = true;
}

</source>

Pay attention to any JSON encoded strings that you need special handling for in batch processing -- remember that you are saving a copy of the core fields and you need save to work as expected.

That’s it, now create some tags, tag some items and you are set.

[[Category:Development]][[Category:Content Tags]]
[[Category:Tutorials]]

J3.x:Using Tags in an Extension

2014-04-26T15:33:00Z

GreyHead: /* type_id */

{{copyedit}}

==Introduction==
Joomla's tagging system is used in all core content extensions and is designed to be be easy to integrate into other extensions that use standard Joomla design patterns.

Using tags in an extension is fairly straightforward. It requires these changes to a typical extension:

* Register a 'Content type' for the extension view(s)
* Add 'Observer methods' to the extension table class(es)
* Add 'Tag fields' to the extension edit forms
* Add 'Tag display' code to the extension view files
* Optionally, add a batch tagging method to the extension administration

== Register a content type for each view ==

In Joomla! 3 content types e.g. articles, weblinks, contacts, . . . are registered in the <tt>#__content_types</tt> table with a separate record for each content view e.g. article, weblink, article category, weblink category, . . .

Your extension installer needs to create a new record for each view.

You can create records in the installer in three different ways:
* in the [[J2.5:Managing_Component_Updates_(Script.php)#postflight|postflight]] method
* by creating a <tt>JTableContenttype</tt> instance and adding a row, or
* by using SQL to create a record directly

The structure of the <tt>#__content_types</tt> table is fairly straightforward:
{| class="wikitable"
|-
! Column name !! Column type !! Purpose
|-
| <tt>type_id</tt> || int(10) || Record key
|-
| <tt>type_title</tt>|| varchar(255)|| Type title e.g. <tt>Article</tt>
|-
| <tt>type_alias</tt> || varchar(255)|| Type alias e.g. <tt>com_content.article</tt>
|-
| <tt>table</tt> || varchar(255)|| Information about the Table class
|-
| <tt>rules</tt> || text || Not currently used
|-
| <tt>field_mappings</tt> || text || Maps the table column names to standard Joomla! names
|-
| <tt>router</tt> || varchar(255)|| Optional: name of a router method
|}

===Construct the Content Type entry===

For each table/option/view you will need to make an entry in <tt>#__content_types</tt> table (see above).

====type_id====
This is the auto-incremented record key, nothing to be done here.

====<tt>type_title</tt>====

The title for your Content Type e.g. Article, Contact, Weblink,
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.

====<tt>type_alias</tt>====

A string identifying the component and view (that would be in the page request, typically matching the model name) e.g. <tt>com_contact.contact</tt>, <tt>com_weblinks.weblink</tt>.

====<tt>table</tt>====

You need to identify which tables used by your component contain records to be tagged. For example the 'Contact' view of the Contacts component uses <tt>#__contact_details</tt> and similarly the 'Weblinks' view of the Weblinks component uses <tt>#__weblinks </tt>.

Each of these components uses a class to write to the table: <tt>ContactTableContact</tt> for the Contacts component and <tt>WeblinksTableWeblink</tt> for the Weblinks component. You will need the class prefixes e.g. <tt>ContactTable</tt>, <tt>WeblinksTable</tt>.

Note that Category types all use the <tt>#__categories</tt> table.

The <tt>type_table</tt> entry gives the complete table class information for the table class as a JSON object with two elements. The first element represents your "special" table and the second an optional common table (otherwise it will default the <tt>JTableCorecontent</tt>).

Here is the JSON entry for the Weblink content type:
<source lang="php">{
"special": {
"dbtable": "#__weblinks",
"key": "id",
"type": "Weblink",
"prefix": "WeblinksTable",
"config": "array()"
},
"common": {
"dbtable": "#__ucm_content",
"key": "ucm_id",
"type": "Corecontent",
"prefix": "JTable",
"config": "array()"
}
}</source>
The values to be included are:
{| class="wikitable"
|-
! Entry name !! Content
|-
| <tt>dbtable</tt> || Table name
|-
| <tt>key</tt>|| Primary key name
|-
| <tt>type</tt> || Content type
|-
| <tt>prefix</tt> || Class prefix
|-
| <tt>config</tt> || An option array, as used in your component constructor and getInstance() methods, may be empty
|}

This information 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.

=====Notes=====

* The table name for the common table is <tt>#__ucm_content</tt>; 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 <tt>type_title</tt> field would potentially be used for display although this is not implemented currently except in the contenttype field. Usually it should begin with an upper case letter if it is in English. See note about how to make this translatable. To make your type names translatable add <tt>COM_TAGS_CONTENT_TYPE_+type_title="Type Title"</tt> in both the ini and sys.ini files.

====<tt>rules</tt>====

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.

====<tt>field_mappings</tt>====

This entry 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.

<source lang="php">
'{"common":[{"core_content_item_id":"id","core_title":"title","core_state":"published","core_alias":"alias","core_created_time":"created_time","core_modified_time":"modified_time","core_body":"description", "core_hits":"hits","core_publish_up":"null","core_publish_down":"null","core_access":"access", "core_params":"params", "core_featured":"null", "core_metadata":"metadata", "core_language":"language", "core_images":"null", "core_urls":"null", "core_version":"version", "core_ordering":"null", "core_metakey":"metakey", "core_metadesc":"metadesc", "core_catid":"parent_id", "core_xreference":"null", "asset_id":"asset_id"}], "special": [{"parent_id":"parent_id","lft":"lft","rgt":"rgt","level":"level","path":"path","extension":"extension","note":"note"}]}'
</source>

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.

====<tt>router</tt>====

'''Router''' is an optional entry to include the name of a static helper router method for this type found in its front end helpers folder.

If you only store data in <tt>#__ucm_content</tt> 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 <tt>JHelperRoute</tt>.

== Modify your component's table class (or classes if you have multiple tables) ==

Add the following to your JTable constructor:

$this->_observers = new JObserverUpdater($this);
JObserverMapper::attachAllObservers($this);

'''The addition material formerly located here is no longer needed after 3.1.4''' Please read the document history for this page if you are required to support 3.1.0 or 3.1.1.

'''For joomla 3.2 I needed this line:''' ( Dont forget to replace weblinks by your component name )

JObserverMapper::addObserverClassToClass('JTableObserverTags', 'WeblinksTableWeblink', array('typeAlias' => 'com_weblinks.weblink'));

== 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.

<source lang="xml">
<field name="tags" type="tag"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field></source>

The field loads all the Javascript libraries required. You don't need to worry about that.

The field supports two modes:
* '''Nested tags mode.''' Hierarchical tag list. Doesn't support on the fly tag creation.
* '''AJAX mode.''' Tags are searched while user types (3 min. chars required to launch the AJAX search). Custom tags are added by pressing ENTER or COMMA keys. Tags show the global route/path. Example: <code>grandpa/parent/tag</code>

The field mode can be forced or use the com_tags setting <code>Tag field mode</code> to determine its mode. To set/force the field mode we have to add '''mode="ajax"''' or '''mode="nested"''' to the tag field definition.

Example of forced AJAX mode:

<source lang="xml">
<field name="tags" type="tag" mode="ajax"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>
</source>
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"**

Example field definition with custom tags denied:

<source lang="xml">
<field name="tags" type="tag" mode="ajax" custom="denied"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>

</source>
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:

<source lang="php">
$item->tags = new JHelperTags;
$item->tags->getItemTags('com_newsfeeds.newsfeed.' , $this->item->id);
</source>

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:
<source lang="php">
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>

</source>
Changing the object and property names as appropriate.

You will most likely want to add the show_tags parameter to the item parameters, the menu item parameters and component configuration as appropriate for your use case.

<source lang="php">
<?php if ($this->params->get('show_tags', 1) && !empty($this->item->tags)) : ?>
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>
<?php endif; ?></source>

== Batch processing ==
If you want to add the ability to do batch tagging to a backend list view do the following.

Add tag to the default_batch layout

<source lang="php">
<div class="control-group">
<div class="controls">
<?php echo JHtml::_('batch.tag');?>
</div>
</div></source>

And add tag to the button class in the modal footer (Not totally necessary at this point, but good for potential future changes e.g. if unTag is added.)

<source lang="php">
<button class="btn" type="button" onclick="document.id('batch-category-id').value='';document.id('batch-access').value='';document.id('batch-language-id').value='';document.id('batch-user-id').value='';document.id('batch-tag-id)').value=''" data-dismiss="modal">
</source>

=== Add a batch method to your model if you are not extending JModelAdmin or overriding the batch method. ===

<source lang="php">
/**
* Batch tag a list of item.
*
* @param integer $value The value of the new tag.
* @param array $pks An array of row IDs.
* @param array $contexts An array of item contexts.
*
* @return void.
*
* @since 3.1
*/
protected function batchTag($value, $pks, $contexts)
{
$tagsHelper = new JHelperTags();
$tagsHelper->tagItems($value, $pks, $contexts);

return true;
}
</source>

And modify your batch method by adding
<source lang="php">
if (!empty($commands['tag']))
{
if (!$this->batchTag($commands['tag'], $pks, $contexts))
{
return false;
}

$done = true;
}

</source>

Pay attention to any JSON encoded strings that you need special handling for in batch processing -- remember that you are saving a copy of the core fields and you need save to work as expected.

That’s it, now create some tags, tag some items and you are set.

[[Category:Development]][[Category:Content Tags]]
[[Category:Tutorials]]

J3.x:Using Tags in an Extension

2014-04-26T15:31:42Z

GreyHead: /* Register a content type for each view */

{{copyedit}}

==Introduction==
Joomla's tagging system is used in all core content extensions and is designed to be be easy to integrate into other extensions that use standard Joomla design patterns.

Using tags in an extension is fairly straightforward. It requires these changes to a typical extension:

* Register a 'Content type' for the extension view(s)
* Add 'Observer methods' to the extension table class(es)
* Add 'Tag fields' to the extension edit forms
* Add 'Tag display' code to the extension view files
* Optionally, add a batch tagging method to the extension administration

== Register a content type for each view ==

In Joomla! 3 content types e.g. articles, weblinks, contacts, . . . are registered in the <tt>#__content_types</tt> table with a separate record for each content view e.g. article, weblink, article category, weblink category, . . .

Your extension installer needs to create a new record for each view.

You can create records in the installer in three different ways:
* in the [[J2.5:Managing_Component_Updates_(Script.php)#postflight|postflight]] method
* by creating a <tt>JTableContenttype</tt> instance and adding a row, or
* by using SQL to create a record directly

The structure of the <tt>#__content_types</tt> table is fairly straightforward:
{| class="wikitable"
|-
! Column name !! Column type !! Purpose
|-
| <tt>type_id</tt> || int(10) || Record key
|-
| <tt>type_title</tt>|| varchar(255)|| Type title e.g. <tt>Article</tt>
|-
| <tt>type_alias</tt> || varchar(255)|| Type alias e.g. <tt>com_content.article</tt>
|-
| <tt>table</tt> || varchar(255)|| Information about the Table class
|-
| <tt>rules</tt> || text || Not currently used
|-
| <tt>field_mappings</tt> || text || Maps the table column names to standard Joomla! names
|-
| <tt>router</tt> || varchar(255)|| Optional: name of a router method
|}

===Construct the Content Type entry===

For each table/option/view you will need to make an entry in <tt>#__content_types</tt> table (see above).

====<tt>type_id</tt>====
This is the auto-incremented record key, nothing to be done here.

====<tt>type_title</tt>====

The title for your Content Type e.g. Article, Contact, Weblink,
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.

====<tt>type_alias</tt>====

A string identifying the component and view (that would be in the page request, typically matching the model name) e.g. <tt>com_contact.contact</tt>, <tt>com_weblinks.weblink</tt>.

====<tt>table</tt>====

You need to identify which tables used by your component contain records to be tagged. For example the 'Contact' view of the Contacts component uses <tt>#__contact_details</tt> and similarly the 'Weblinks' view of the Weblinks component uses <tt>#__weblinks </tt>.

Each of these components uses a class to write to the table: <tt>ContactTableContact</tt> for the Contacts component and <tt>WeblinksTableWeblink</tt> for the Weblinks component. You will need the class prefixes e.g. <tt>ContactTable</tt>, <tt>WeblinksTable</tt>.

Note that Category types all use the <tt>#__categories</tt> table.

The <tt>type_table</tt> entry gives the complete table class information for the table class as a JSON object with two elements. The first element represents your "special" table and the second an optional common table (otherwise it will default the <tt>JTableCorecontent</tt>).

Here is the JSON entry for the Weblink content type:
<source lang="php">{
"special": {
"dbtable": "#__weblinks",
"key": "id",
"type": "Weblink",
"prefix": "WeblinksTable",
"config": "array()"
},
"common": {
"dbtable": "#__ucm_content",
"key": "ucm_id",
"type": "Corecontent",
"prefix": "JTable",
"config": "array()"
}
}</source>
The values to be included are:
{| class="wikitable"
|-
! Entry name !! Content
|-
| <tt>dbtable</tt> || Table name
|-
| <tt>key</tt>|| Primary key name
|-
| <tt>type</tt> || Content type
|-
| <tt>prefix</tt> || Class prefix
|-
| <tt>config</tt> || An option array, as used in your component constructor and getInstance() methods, may be empty
|}

This information 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.

=====Notes=====

* The table name for the common table is <tt>#__ucm_content</tt>; 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 <tt>type_title</tt> field would potentially be used for display although this is not implemented currently except in the contenttype field. Usually it should begin with an upper case letter if it is in English. See note about how to make this translatable. To make your type names translatable add <tt>COM_TAGS_CONTENT_TYPE_+type_title="Type Title"</tt> in both the ini and sys.ini files.

====<tt>rules</tt>====

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.

====<tt>field_mappings</tt>====

This entry 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.

<source lang="php">
'{"common":[{"core_content_item_id":"id","core_title":"title","core_state":"published","core_alias":"alias","core_created_time":"created_time","core_modified_time":"modified_time","core_body":"description", "core_hits":"hits","core_publish_up":"null","core_publish_down":"null","core_access":"access", "core_params":"params", "core_featured":"null", "core_metadata":"metadata", "core_language":"language", "core_images":"null", "core_urls":"null", "core_version":"version", "core_ordering":"null", "core_metakey":"metakey", "core_metadesc":"metadesc", "core_catid":"parent_id", "core_xreference":"null", "asset_id":"asset_id"}], "special": [{"parent_id":"parent_id","lft":"lft","rgt":"rgt","level":"level","path":"path","extension":"extension","note":"note"}]}'
</source>

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.

====<tt>router</tt>====

'''Router''' is an optional entry to include the name of a static helper router method for this type found in its front end helpers folder.

If you only store data in <tt>#__ucm_content</tt> 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 <tt>JHelperRoute</tt>.

== Modify your component's table class (or classes if you have multiple tables) ==

Add the following to your JTable constructor:

$this->_observers = new JObserverUpdater($this);
JObserverMapper::attachAllObservers($this);

'''The addition material formerly located here is no longer needed after 3.1.4''' Please read the document history for this page if you are required to support 3.1.0 or 3.1.1.

'''For joomla 3.2 I needed this line:''' ( Dont forget to replace weblinks by your component name )

JObserverMapper::addObserverClassToClass('JTableObserverTags', 'WeblinksTableWeblink', array('typeAlias' => 'com_weblinks.weblink'));

== 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.

<source lang="xml">
<field name="tags" type="tag"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field></source>

The field loads all the Javascript libraries required. You don't need to worry about that.

The field supports two modes:
* '''Nested tags mode.''' Hierarchical tag list. Doesn't support on the fly tag creation.
* '''AJAX mode.''' Tags are searched while user types (3 min. chars required to launch the AJAX search). Custom tags are added by pressing ENTER or COMMA keys. Tags show the global route/path. Example: <code>grandpa/parent/tag</code>

The field mode can be forced or use the com_tags setting <code>Tag field mode</code> to determine its mode. To set/force the field mode we have to add '''mode="ajax"''' or '''mode="nested"''' to the tag field definition.

Example of forced AJAX mode:

<source lang="xml">
<field name="tags" type="tag" mode="ajax"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>
</source>
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"**

Example field definition with custom tags denied:

<source lang="xml">
<field name="tags" type="tag" mode="ajax" custom="denied"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>

</source>
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:

<source lang="php">
$item->tags = new JHelperTags;
$item->tags->getItemTags('com_newsfeeds.newsfeed.' , $this->item->id);
</source>

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:
<source lang="php">
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>

</source>
Changing the object and property names as appropriate.

You will most likely want to add the show_tags parameter to the item parameters, the menu item parameters and component configuration as appropriate for your use case.

<source lang="php">
<?php if ($this->params->get('show_tags', 1) && !empty($this->item->tags)) : ?>
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>
<?php endif; ?></source>

== Batch processing ==
If you want to add the ability to do batch tagging to a backend list view do the following.

Add tag to the default_batch layout

<source lang="php">
<div class="control-group">
<div class="controls">
<?php echo JHtml::_('batch.tag');?>
</div>
</div></source>

And add tag to the button class in the modal footer (Not totally necessary at this point, but good for potential future changes e.g. if unTag is added.)

<source lang="php">
<button class="btn" type="button" onclick="document.id('batch-category-id').value='';document.id('batch-access').value='';document.id('batch-language-id').value='';document.id('batch-user-id').value='';document.id('batch-tag-id)').value=''" data-dismiss="modal">
</source>

=== Add a batch method to your model if you are not extending JModelAdmin or overriding the batch method. ===

<source lang="php">
/**
* Batch tag a list of item.
*
* @param integer $value The value of the new tag.
* @param array $pks An array of row IDs.
* @param array $contexts An array of item contexts.
*
* @return void.
*
* @since 3.1
*/
protected function batchTag($value, $pks, $contexts)
{
$tagsHelper = new JHelperTags();
$tagsHelper->tagItems($value, $pks, $contexts);

return true;
}
</source>

And modify your batch method by adding
<source lang="php">
if (!empty($commands['tag']))
{
if (!$this->batchTag($commands['tag'], $pks, $contexts))
{
return false;
}

$done = true;
}

</source>

Pay attention to any JSON encoded strings that you need special handling for in batch processing -- remember that you are saving a copy of the core fields and you need save to work as expected.

That’s it, now create some tags, tag some items and you are set.

[[Category:Development]][[Category:Content Tags]]
[[Category:Tutorials]]

J3.x:Using Tags in an Extension

2014-04-26T15:13:13Z

GreyHead: /* Register a content type for each view */ Amplify table section

{{copyedit}}

==Introduction==
Joomla's tagging system is used in all core content extensions and is designed to be be easy to integrate into other extensions that use standard Joomla design patterns.

Using tags in an extension is fairly straightforward. It requires these changes to a typical extension:

* Register a 'Content type' for the extension view(s)
* Add 'Observer methods' to the extension table class(es)
* Add 'Tag fields' to the extension edit forms
* Add 'Tag display' code to the extension view files
* Optionally, add a batch tagging method to the extension administration

== Register a content type for each view ==

In Joomla! 3 content types e.g. articles, weblinks, contacts, . . . are registered in the <tt>#__content_types</tt> table with a separate record for each content view e.g. article, weblink, article category, weblink category, . . .

Your extension installer needs to create a new record for each view.

You can create records in the installer in three different ways:
* in the [[J2.5:Managing_Component_Updates_(Script.php)#postflight|postflight]] method
* by creating a <tt>JTableContenttype</tt> instance and adding a row, or
* by using SQL to create a record directly

The structure of the <tt>#__content_types</tt> table is fairly straightforward:
{|
|-
! Column name !! Column type !! Purpose
|-
| <tt>type_id</tt> || int(10) || Record key
|-
| <tt>type_title</tt>|| varchar(255)|| Type title e.g. <tt>Article</tt>
|-
| <tt>type_alias</tt> || varchar(255)|| Type alias e.g. <tt>com_content.article</tt>
|-
| <tt>table</tt> || varchar(255)|| Information about the Table class
|-
| <tt>rules</tt> || text || Not currently used
|-
| <tt>field_mappings</tt> || text || Maps the table column names to standard Joomla! names
|-
| <tt>router</tt> || varchar(255)|| Optional: name of a router method
|}

===Construct the Content Type entry===

For each table/option/view you will need to make an entry in <tt>#__content_types</tt> table (see above).

====type_id====
This is the auto-incremented record key, nothing to be done here.

====type_title====

The title for your Content Type e.g. Article, Contact, Weblink,
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.

====type_alias====

A string identifying the component and view (that would be in the page request, typically matching the model name) e.g. <tt>com_contact.contact</tt>, <tt>com_weblinks.weblink</tt>.

====table====

You need to identify which tables used by your component contain records to be tagged. For example the 'Contact' view of the Contacts component uses <tt>#__contact_details</tt> and similarly the 'Weblinks' view of the Weblinks component uses <tt>#__weblinks </tt>.

Each of these components uses a class to write to the table: <tt>ContactTableContact</tt> for the Contacts component and <tt>WeblinksTableWeblink</tt> for the Weblinks component. You will need the class prefixes e.g. <tt>ContactTable</tt>, <tt>WeblinksTable</tt>.

Note that Category types all use the <tt>#__categories</tt> table.

The <tt>type_table</tt> entry gives the complete table class information for the table class as a JSON object with two elements. The first element represents your "special" table and the second an optional common table (otherwise it will default the <tt>JTableCorecontent</tt>).

Here is the JSON entry for the Weblink content type:
<source lang="php">{
"special": {
"dbtable": "#__weblinks",
"key": "id",
"type": "Weblink",
"prefix": "WeblinksTable",
"config": "array()"
},
"common": {
"dbtable": "#__ucm_content",
"key": "ucm_id",
"type": "Corecontent",
"prefix": "JTable",
"config": "array()"
}
}</source>

{|
|-
! Entry name !! Content
|-
| <tt>dbtable</tt> || Table name
|-
| <tt>key</tt>|| Primary key name
|-
| <tt>type</tt> || Content type
|-
| <tt>prefix</tt> || Class prefix
|-
| <tt>config</tt> || An option array, may be empty
|}
The option array is as used in your component constructor and getInstance() methods.

This information 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
<source lang="php">
COM_TAGS_CONTENT_TYPE_ + the type_title
</source>
in both the ini and sys.ini files.

====table====

'''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.

<source lang="php">
'{"common":[{"core_content_item_id":"id","core_title":"title","core_state":"published","core_alias":"alias","core_created_time":"created_time","core_modified_time":"modified_time","core_body":"description", "core_hits":"hits","core_publish_up":"null","core_publish_down":"null","core_access":"access", "core_params":"params", "core_featured":"null", "core_metadata":"metadata", "core_language":"language", "core_images":"null", "core_urls":"null", "core_version":"version", "core_ordering":"null", "core_metakey":"metakey", "core_metadesc":"metadesc", "core_catid":"parent_id", "core_xreference":"null", "asset_id":"asset_id"}], "special": [{"parent_id":"parent_id","lft":"lft","rgt":"rgt","level":"level","path":"path","extension":"extension","note":"note"}]}'
</source>

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====

'''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.

== Modify your component's table class (or classes if you have multiple tables) ==

Add the following to your JTable constructor:

$this->_observers = new JObserverUpdater($this);
JObserverMapper::attachAllObservers($this);

'''The addition material formerly located here is no longer needed after 3.1.4''' Please read the document history for this page if you are required to support 3.1.0 or 3.1.1.

'''For joomla 3.2 I needed this line:''' ( Dont forget to replace weblinks by your component name )

JObserverMapper::addObserverClassToClass('JTableObserverTags', 'WeblinksTableWeblink', array('typeAlias' => 'com_weblinks.weblink'));

== 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.

<source lang="xml">
<field name="tags" type="tag"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field></source>

The field loads all the Javascript libraries required. You don't need to worry about that.

The field supports two modes:
* '''Nested tags mode.''' Hierarchical tag list. Doesn't support on the fly tag creation.
* '''AJAX mode.''' Tags are searched while user types (3 min. chars required to launch the AJAX search). Custom tags are added by pressing ENTER or COMMA keys. Tags show the global route/path. Example: <code>grandpa/parent/tag</code>

The field mode can be forced or use the com_tags setting <code>Tag field mode</code> to determine its mode. To set/force the field mode we have to add '''mode="ajax"''' or '''mode="nested"''' to the tag field definition.

Example of forced AJAX mode:

<source lang="xml">
<field name="tags" type="tag" mode="ajax"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>
</source>
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"**

Example field definition with custom tags denied:

<source lang="xml">
<field name="tags" type="tag" mode="ajax" custom="denied"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>

</source>
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:

<source lang="php">
$item->tags = new JHelperTags;
$item->tags->getItemTags('com_newsfeeds.newsfeed.' , $this->item->id);
</source>

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:
<source lang="php">
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>

</source>
Changing the object and property names as appropriate.

You will most likely want to add the show_tags parameter to the item parameters, the menu item parameters and component configuration as appropriate for your use case.

<source lang="php">
<?php if ($this->params->get('show_tags', 1) && !empty($this->item->tags)) : ?>
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>
<?php endif; ?></source>

== Batch processing ==
If you want to add the ability to do batch tagging to a backend list view do the following.

Add tag to the default_batch layout

<source lang="php">
<div class="control-group">
<div class="controls">
<?php echo JHtml::_('batch.tag');?>
</div>
</div></source>

And add tag to the button class in the modal footer (Not totally necessary at this point, but good for potential future changes e.g. if unTag is added.)

<source lang="php">
<button class="btn" type="button" onclick="document.id('batch-category-id').value='';document.id('batch-access').value='';document.id('batch-language-id').value='';document.id('batch-user-id').value='';document.id('batch-tag-id)').value=''" data-dismiss="modal">
</source>

=== Add a batch method to your model if you are not extending JModelAdmin or overriding the batch method. ===

<source lang="php">
/**
* Batch tag a list of item.
*
* @param integer $value The value of the new tag.
* @param array $pks An array of row IDs.
* @param array $contexts An array of item contexts.
*
* @return void.
*
* @since 3.1
*/
protected function batchTag($value, $pks, $contexts)
{
$tagsHelper = new JHelperTags();
$tagsHelper->tagItems($value, $pks, $contexts);

return true;
}
</source>

And modify your batch method by adding
<source lang="php">
if (!empty($commands['tag']))
{
if (!$this->batchTag($commands['tag'], $pks, $contexts))
{
return false;
}

$done = true;
}

</source>

Pay attention to any JSON encoded strings that you need special handling for in batch processing -- remember that you are saving a copy of the core fields and you need save to work as expected.

That’s it, now create some tags, tag some items and you are set.

[[Category:Development]][[Category:Content Tags]]
[[Category:Tutorials]]

J3.x:Using Tags in an Extension

2014-04-24T17:19:14Z

GreyHead: /* Create a content type for each view */ clarified table struture

{{copyedit}}

==Introduction==
Joomla's tagging system is used in all core content extensions and is designed to be be easy to integrate into other extensions that use standard Joomla design patterns.

Using tags in an extension is fairly straightforward. It requires these changes to a typical extension:

* Register a 'Content type' for the extension view(s)
* Add 'Observer methods' to the extension table class(es)
* Add 'Tag fields' to the extension edit forms
* Add 'Tag display' code to the extension view files
* Optionally, add a batch tagging method to the extension administration

== Register a content type for each view ==

In Joomla! 3 content types e.g. articles, weblinks, contacts, . . . are registered in the <tt>#__content_types</tt> table with a separate record for each content view e.g. article, weblink, article category, weblink category, . . .

Your extension installer needs to create a new record for each view.

You can create records in the installer in three different ways:
* in the [[J2.5:Managing_Component_Updates_(Script.php)#postflight|postflight]] method
* by creating a <tt>JTableContenttype</tt> instance and adding a row, or
* by using SQL to create a record directly

The structure of the <tt>#__content_types</tt> table is fairly straightforward:
{|
|-
! Column name !! Column type !! Purpose
|-
| <tt>type_id</tt> || int(10) || Record key
|-
| <tt>type_title</tt>|| varchar(255)|| Type title e.g. <tt>Article</tt>
|-
| <tt>type_alias</tt> || varchar(255)|| Type alias e.g. <tt>com_content.article</tt>
|-
| <tt>table</tt> || varchar(255)|| Information about the Table class
|-
| <tt>rules</tt> || text || Not currently used
|-
| <tt>field_mappings</tt> || text || Maps the table column names to standard Joomla! names
|-
| <tt>router</tt> || varchar(255)|| Optional: name of a router method
|}

First identify which tables contain data that will be tagged and what the name of the single item view displaying each of these tables. For example:
* #__contact_details is the table displayed in the view contact of component com_contact with table class ContactTableContact.
* #__weblinks is the table displayed in the view weblink of com_weblinks so WeblinksTableWeblink.

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.

<source lang="php">
{"special":{"dbtable":"#__content","key":"id","type":"Content","prefix":"JTable","config":"array()"},"common":{"dbtable":"#__ucm_content","key":"ucm_id","type":"Corecontent","prefix":"JTable","config":"array()"}}
</source>

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
<source lang="php">
COM_TAGS_CONTENT_TYPE_ + the type_title
</source>
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.

<source lang="php">
'{"common":[{"core_content_item_id":"id","core_title":"title","core_state":"published","core_alias":"alias","core_created_time":"created_time","core_modified_time":"modified_time","core_body":"description", "core_hits":"hits","core_publish_up":"null","core_publish_down":"null","core_access":"access", "core_params":"params", "core_featured":"null", "core_metadata":"metadata", "core_language":"language", "core_images":"null", "core_urls":"null", "core_version":"version", "core_ordering":"null", "core_metakey":"metakey", "core_metadesc":"metadesc", "core_catid":"parent_id", "core_xreference":"null", "asset_id":"asset_id"}], "special": [{"parent_id":"parent_id","lft":"lft","rgt":"rgt","level":"level","path":"path","extension":"extension","note":"note"}]}'
</source>

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.

== Modify your component's table class (or classes if you have multiple tables) ==

Add the following to your JTable constructor:

$this->_observers = new JObserverUpdater($this);
JObserverMapper::attachAllObservers($this);

'''The addition material formerly located here is no longer needed after 3.1.4''' Please read the document history for this page if you are required to support 3.1.0 or 3.1.1.

'''For joomla 3.2 I needed this line:''' ( Dont forget to replace weblinks by your component name )

JObserverMapper::addObserverClassToClass('JTableObserverTags', 'WeblinksTableWeblink', array('typeAlias' => 'com_weblinks.weblink'));

== 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.

<source lang="xml">
<field name="tags" type="tag"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field></source>

The field loads all the Javascript libraries required. You don't need to worry about that.

The field supports two modes:
* '''Nested tags mode.''' Hierarchical tag list. Doesn't support on the fly tag creation.
* '''AJAX mode.''' Tags are searched while user types (3 min. chars required to launch the AJAX search). Custom tags are added by pressing ENTER or COMMA keys. Tags show the global route/path. Example: <code>grandpa/parent/tag</code>

The field mode can be forced or use the com_tags setting <code>Tag field mode</code> to determine its mode. To set/force the field mode we have to add '''mode="ajax"''' or '''mode="nested"''' to the tag field definition.

Example of forced AJAX mode:

<source lang="xml">
<field name="tags" type="tag" mode="ajax"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>
</source>
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"**

Example field definition with custom tags denied:

<source lang="xml">
<field name="tags" type="tag" mode="ajax" custom="denied"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>

</source>
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:

<source lang="php">
$item->tags = new JHelperTags;
$item->tags->getItemTags('com_newsfeeds.newsfeed.' , $this->item->id);
</source>

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:
<source lang="php">
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>

</source>
Changing the object and property names as appropriate.

You will most likely want to add the show_tags parameter to the item parameters, the menu item parameters and component configuration as appropriate for your use case.

<source lang="php">
<?php if ($this->params->get('show_tags', 1) && !empty($this->item->tags)) : ?>
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>
<?php endif; ?></source>

== Batch processing ==
If you want to add the ability to do batch tagging to a backend list view do the following.

Add tag to the default_batch layout

<source lang="php">
<div class="control-group">
<div class="controls">
<?php echo JHtml::_('batch.tag');?>
</div>
</div></source>

And add tag to the button class in the modal footer (Not totally necessary at this point, but good for potential future changes e.g. if unTag is added.)

<source lang="php">
<button class="btn" type="button" onclick="document.id('batch-category-id').value='';document.id('batch-access').value='';document.id('batch-language-id').value='';document.id('batch-user-id').value='';document.id('batch-tag-id)').value=''" data-dismiss="modal">
</source>

=== Add a batch method to your model if you are not extending JModelAdmin or overriding the batch method. ===

<source lang="php">
/**
* Batch tag a list of item.
*
* @param integer $value The value of the new tag.
* @param array $pks An array of row IDs.
* @param array $contexts An array of item contexts.
*
* @return void.
*
* @since 3.1
*/
protected function batchTag($value, $pks, $contexts)
{
$tagsHelper = new JHelperTags();
$tagsHelper->tagItems($value, $pks, $contexts);

return true;
}
</source>

And modify your batch method by adding
<source lang="php">
if (!empty($commands['tag']))
{
if (!$this->batchTag($commands['tag'], $pks, $contexts))
{
return false;
}

$done = true;
}

</source>

Pay attention to any JSON encoded strings that you need special handling for in batch processing -- remember that you are saving a copy of the core fields and you need save to work as expected.

That’s it, now create some tags, tag some items and you are set.

[[Category:Development]][[Category:Content Tags]]
[[Category:Tutorials]]

J3.x:Using Tags in an Extension

2014-04-24T16:56:36Z

GreyHead: Added and edited introduction section

{{copyedit}}

==Introduction==
Joomla's tagging system is used in all core content extensions and is designed to be be easy to integrate into other extensions that use standard Joomla design patterns.

Using tags in an extension is fairly straightforward. It requires these changes to a typical extension:

* Register a 'Content type' for the extension view(s)
* Add 'Observer methods' to the extension table class(es)
* Add 'Tag fields' to the extension edit forms
* Add 'Tag display' code to the extension view files
* Optionally, add a batch tagging method to the extension administration

== Create a content type for each view ==

Note: Types can be added using either sql or [[J2.5:Managing_Component_Updates_(Script.php)#postflight|postflight]] by creating a JTableContenttype instance and adding a row.

First identify which tables contain data that will be tagged and what the name of the single item view displaying each of these tables. For example:
* #__contact_details is the table displayed in the view contact of component com_contact with table class ContactTableContact.
* #__weblinks is the table displayed in the view weblink of com_weblinks so WeblinksTableWeblink.

<source lang="sql">
CREATE TABLE IF NOT EXISTS `#__content_types` (
`type_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`type_title` varchar(255) NOT NULL DEFAULT '',
`type_alias` varchar(255) NOT NULL DEFAULT '',
`table` varchar(255) NOT NULL DEFAULT '',
`rules` text NOT NULL,
`field_mappings` text NOT NULL,
`router` varchar(255) NOT NULL DEFAULT '',

</source>

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.

<source lang="php">
{"special":{"dbtable":"#__content","key":"id","type":"Content","prefix":"JTable","config":"array()"},"common":{"dbtable":"#__ucm_content","key":"ucm_id","type":"Corecontent","prefix":"JTable","config":"array()"}}
</source>

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
<source lang="php">
COM_TAGS_CONTENT_TYPE_ + the type_title
</source>
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.

<source lang="php">
'{"common":[{"core_content_item_id":"id","core_title":"title","core_state":"published","core_alias":"alias","core_created_time":"created_time","core_modified_time":"modified_time","core_body":"description", "core_hits":"hits","core_publish_up":"null","core_publish_down":"null","core_access":"access", "core_params":"params", "core_featured":"null", "core_metadata":"metadata", "core_language":"language", "core_images":"null", "core_urls":"null", "core_version":"version", "core_ordering":"null", "core_metakey":"metakey", "core_metadesc":"metadesc", "core_catid":"parent_id", "core_xreference":"null", "asset_id":"asset_id"}], "special": [{"parent_id":"parent_id","lft":"lft","rgt":"rgt","level":"level","path":"path","extension":"extension","note":"note"}]}'
</source>

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.

== Modify your component's table class (or classes if you have multiple tables) ==

Add the following to your JTable constructor:

$this->_observers = new JObserverUpdater($this);
JObserverMapper::attachAllObservers($this);

'''The addition material formerly located here is no longer needed after 3.1.4''' Please read the document history for this page if you are required to support 3.1.0 or 3.1.1.

'''For joomla 3.2 I needed this line:''' ( Dont forget to replace weblinks by your component name )

JObserverMapper::addObserverClassToClass('JTableObserverTags', 'WeblinksTableWeblink', array('typeAlias' => 'com_weblinks.weblink'));

== 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.

<source lang="xml">
<field name="tags" type="tag"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field></source>

The field loads all the Javascript libraries required. You don't need to worry about that.

The field supports two modes:
* '''Nested tags mode.''' Hierarchical tag list. Doesn't support on the fly tag creation.
* '''AJAX mode.''' Tags are searched while user types (3 min. chars required to launch the AJAX search). Custom tags are added by pressing ENTER or COMMA keys. Tags show the global route/path. Example: <code>grandpa/parent/tag</code>

The field mode can be forced or use the com_tags setting <code>Tag field mode</code> to determine its mode. To set/force the field mode we have to add '''mode="ajax"''' or '''mode="nested"''' to the tag field definition.

Example of forced AJAX mode:

<source lang="xml">
<field name="tags" type="tag" mode="ajax"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>
</source>
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"**

Example field definition with custom tags denied:

<source lang="xml">
<field name="tags" type="tag" mode="ajax" custom="denied"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>

</source>
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:

<source lang="php">
$item->tags = new JHelperTags;
$item->tags->getItemTags('com_newsfeeds.newsfeed.' , $this->item->id);
</source>

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:
<source lang="php">
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>

</source>
Changing the object and property names as appropriate.

You will most likely want to add the show_tags parameter to the item parameters, the menu item parameters and component configuration as appropriate for your use case.

<source lang="php">
<?php if ($this->params->get('show_tags', 1) && !empty($this->item->tags)) : ?>
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>
<?php endif; ?></source>

== Batch processing ==
If you want to add the ability to do batch tagging to a backend list view do the following.

Add tag to the default_batch layout

<source lang="php">
<div class="control-group">
<div class="controls">
<?php echo JHtml::_('batch.tag');?>
</div>
</div></source>

And add tag to the button class in the modal footer (Not totally necessary at this point, but good for potential future changes e.g. if unTag is added.)

<source lang="php">
<button class="btn" type="button" onclick="document.id('batch-category-id').value='';document.id('batch-access').value='';document.id('batch-language-id').value='';document.id('batch-user-id').value='';document.id('batch-tag-id)').value=''" data-dismiss="modal">
</source>

=== Add a batch method to your model if you are not extending JModelAdmin or overriding the batch method. ===

<source lang="php">
/**
* Batch tag a list of item.
*
* @param integer $value The value of the new tag.
* @param array $pks An array of row IDs.
* @param array $contexts An array of item contexts.
*
* @return void.
*
* @since 3.1
*/
protected function batchTag($value, $pks, $contexts)
{
$tagsHelper = new JHelperTags();
$tagsHelper->tagItems($value, $pks, $contexts);

return true;
}
</source>

And modify your batch method by adding
<source lang="php">
if (!empty($commands['tag']))
{
if (!$this->batchTag($commands['tag'], $pks, $contexts))
{
return false;
}

$done = true;
}

</source>

Pay attention to any JSON encoded strings that you need special handling for in batch processing -- remember that you are saving a copy of the core fields and you need save to work as expected.

That’s it, now create some tags, tag some items and you are set.

[[Category:Development]][[Category:Content Tags]]
[[Category:Tutorials]]

J3.x:Using Tags in an Extension

2014-04-24T16:48:09Z

GreyHead: // added link to postflight

{{copyedit}}

Joomla's tagging system is used in all core content extensions and is designed to be be easy to integrate into other extensions that use standard Joomla design patterns.

Using tags in an extension is relatively straightforward but it requires small changes in a number of specific places.

== Create a content type for each view ==

Note: Types can be added using either sql or [[J2.5:Managing_Component_Updates_(Script.php)#postflight|postflight]] by creating a JTableContenttype instance and adding a row.

First identify which tables contain data that will be tagged and what the name of the single item view displaying each of these tables. For example:
* #__contact_details is the table displayed in the view contact of component com_contact with table class ContactTableContact.
* #__weblinks is the table displayed in the view weblink of com_weblinks so WeblinksTableWeblink.

<source lang="sql">
CREATE TABLE IF NOT EXISTS `#__content_types` (
`type_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`type_title` varchar(255) NOT NULL DEFAULT '',
`type_alias` varchar(255) NOT NULL DEFAULT '',
`table` varchar(255) NOT NULL DEFAULT '',
`rules` text NOT NULL,
`field_mappings` text NOT NULL,
`router` varchar(255) NOT NULL DEFAULT '',

</source>

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.

<source lang="php">
{"special":{"dbtable":"#__content","key":"id","type":"Content","prefix":"JTable","config":"array()"},"common":{"dbtable":"#__ucm_content","key":"ucm_id","type":"Corecontent","prefix":"JTable","config":"array()"}}
</source>

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
<source lang="php">
COM_TAGS_CONTENT_TYPE_ + the type_title
</source>
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.

<source lang="php">
'{"common":[{"core_content_item_id":"id","core_title":"title","core_state":"published","core_alias":"alias","core_created_time":"created_time","core_modified_time":"modified_time","core_body":"description", "core_hits":"hits","core_publish_up":"null","core_publish_down":"null","core_access":"access", "core_params":"params", "core_featured":"null", "core_metadata":"metadata", "core_language":"language", "core_images":"null", "core_urls":"null", "core_version":"version", "core_ordering":"null", "core_metakey":"metakey", "core_metadesc":"metadesc", "core_catid":"parent_id", "core_xreference":"null", "asset_id":"asset_id"}], "special": [{"parent_id":"parent_id","lft":"lft","rgt":"rgt","level":"level","path":"path","extension":"extension","note":"note"}]}'
</source>

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.

== Modify your component's table class (or classes if you have multiple tables) ==

Add the following to your JTable constructor:

$this->_observers = new JObserverUpdater($this);
JObserverMapper::attachAllObservers($this);

'''The addition material formerly located here is no longer needed after 3.1.4''' Please read the document history for this page if you are required to support 3.1.0 or 3.1.1.

'''For joomla 3.2 I needed this line:''' ( Dont forget to replace weblinks by your component name )

JObserverMapper::addObserverClassToClass('JTableObserverTags', 'WeblinksTableWeblink', array('typeAlias' => 'com_weblinks.weblink'));

== 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.

<source lang="xml">
<field name="tags" type="tag"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field></source>

The field loads all the Javascript libraries required. You don't need to worry about that.

The field supports two modes:
* '''Nested tags mode.''' Hierarchical tag list. Doesn't support on the fly tag creation.
* '''AJAX mode.''' Tags are searched while user types (3 min. chars required to launch the AJAX search). Custom tags are added by pressing ENTER or COMMA keys. Tags show the global route/path. Example: <code>grandpa/parent/tag</code>

The field mode can be forced or use the com_tags setting <code>Tag field mode</code> to determine its mode. To set/force the field mode we have to add '''mode="ajax"''' or '''mode="nested"''' to the tag field definition.

Example of forced AJAX mode:

<source lang="xml">
<field name="tags" type="tag" mode="ajax"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>
</source>
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"**

Example field definition with custom tags denied:

<source lang="xml">
<field name="tags" type="tag" mode="ajax" custom="denied"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>

</source>
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:

<source lang="php">
$item->tags = new JHelperTags;
$item->tags->getItemTags('com_newsfeeds.newsfeed.' , $this->item->id);
</source>

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:
<source lang="php">
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>

</source>
Changing the object and property names as appropriate.

You will most likely want to add the show_tags parameter to the item parameters, the menu item parameters and component configuration as appropriate for your use case.

<source lang="php">
<?php if ($this->params->get('show_tags', 1) && !empty($this->item->tags)) : ?>
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>
<?php endif; ?></source>

== Batch processing ==
If you want to add the ability to do batch tagging to a backend list view do the following.

Add tag to the default_batch layout

<source lang="php">
<div class="control-group">
<div class="controls">
<?php echo JHtml::_('batch.tag');?>
</div>
</div></source>

And add tag to the button class in the modal footer (Not totally necessary at this point, but good for potential future changes e.g. if unTag is added.)

<source lang="php">
<button class="btn" type="button" onclick="document.id('batch-category-id').value='';document.id('batch-access').value='';document.id('batch-language-id').value='';document.id('batch-user-id').value='';document.id('batch-tag-id)').value=''" data-dismiss="modal">
</source>

=== Add a batch method to your model if you are not extending JModelAdmin or overriding the batch method. ===

<source lang="php">
/**
* Batch tag a list of item.
*
* @param integer $value The value of the new tag.
* @param array $pks An array of row IDs.
* @param array $contexts An array of item contexts.
*
* @return void.
*
* @since 3.1
*/
protected function batchTag($value, $pks, $contexts)
{
$tagsHelper = new JHelperTags();
$tagsHelper->tagItems($value, $pks, $contexts);

return true;
}
</source>

And modify your batch method by adding
<source lang="php">
if (!empty($commands['tag']))
{
if (!$this->batchTag($commands['tag'], $pks, $contexts))
{
return false;
}

$done = true;
}

</source>

Pay attention to any JSON encoded strings that you need special handling for in batch processing -- remember that you are saving a copy of the core fields and you need save to work as expected.

That’s it, now create some tags, tag some items and you are set.

[[Category:Development]][[Category:Content Tags]]
[[Category:Tutorials]]

J3.x:Using Tags in an Extension

2014-04-24T15:33:08Z

GreyHead: // copyedit

{{copyedit}}

Joomla's tagging system is used in all core content extensions and is designed to be be easy to integrate into other extensions that use standard Joomla design patterns.

Using tags in an extension is relatively straightforward but it requires small changes in a number of specific places.

== Create a content type for each view ==

Note: Types can be added using either sql or postflight by creating a JTableContenttype instance and adding a row.

First identify which tables contain data that will be tagged and what the name of the single item view displaying each of these tables. For example:
* #__contact_details is the table displayed in the view contact of component com_contact with table class ContactTableContact.
* #__weblinks is the table displayed in the view weblink of com_weblinks so WeblinksTableWeblink.

<source lang="sql">
CREATE TABLE IF NOT EXISTS `#__content_types` (
`type_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`type_title` varchar(255) NOT NULL DEFAULT '',
`type_alias` varchar(255) NOT NULL DEFAULT '',
`table` varchar(255) NOT NULL DEFAULT '',
`rules` text NOT NULL,
`field_mappings` text NOT NULL,
`router` varchar(255) NOT NULL DEFAULT '',

</source>

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.

<source lang="php">
{"special":{"dbtable":"#__content","key":"id","type":"Content","prefix":"JTable","config":"array()"},"common":{"dbtable":"#__ucm_content","key":"ucm_id","type":"Corecontent","prefix":"JTable","config":"array()"}}
</source>

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
<source lang="php">
COM_TAGS_CONTENT_TYPE_ + the type_title
</source>
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.

<source lang="php">
'{"common":[{"core_content_item_id":"id","core_title":"title","core_state":"published","core_alias":"alias","core_created_time":"created_time","core_modified_time":"modified_time","core_body":"description", "core_hits":"hits","core_publish_up":"null","core_publish_down":"null","core_access":"access", "core_params":"params", "core_featured":"null", "core_metadata":"metadata", "core_language":"language", "core_images":"null", "core_urls":"null", "core_version":"version", "core_ordering":"null", "core_metakey":"metakey", "core_metadesc":"metadesc", "core_catid":"parent_id", "core_xreference":"null", "asset_id":"asset_id"}], "special": [{"parent_id":"parent_id","lft":"lft","rgt":"rgt","level":"level","path":"path","extension":"extension","note":"note"}]}'
</source>

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.

== Modify your component's table class (or classes if you have multiple tables) ==

Add the following to your JTable constructor:

$this->_observers = new JObserverUpdater($this);
JObserverMapper::attachAllObservers($this);

'''The addition material formerly located here is no longer needed after 3.1.4''' Please read the document history for this page if you are required to support 3.1.0 or 3.1.1.

'''For joomla 3.2 I needed this line:''' ( Dont forget to replace weblinks by your component name )

JObserverMapper::addObserverClassToClass('JTableObserverTags', 'WeblinksTableWeblink', array('typeAlias' => 'com_weblinks.weblink'));

== 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.

<source lang="xml">
<field name="tags" type="tag"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field></source>

The field loads all the Javascript libraries required. You don't need to worry about that.

The field supports two modes:
* '''Nested tags mode.''' Hierarchical tag list. Doesn't support on the fly tag creation.
* '''AJAX mode.''' Tags are searched while user types (3 min. chars required to launch the AJAX search). Custom tags are added by pressing ENTER or COMMA keys. Tags show the global route/path. Example: <code>grandpa/parent/tag</code>

The field mode can be forced or use the com_tags setting <code>Tag field mode</code> to determine its mode. To set/force the field mode we have to add '''mode="ajax"''' or '''mode="nested"''' to the tag field definition.

Example of forced AJAX mode:

<source lang="xml">
<field name="tags" type="tag" mode="ajax"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>
</source>
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"**

Example field definition with custom tags denied:

<source lang="xml">
<field name="tags" type="tag" mode="ajax" custom="denied"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>

</source>
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:

<source lang="php">
$item->tags = new JHelperTags;
$item->tags->getItemTags('com_newsfeeds.newsfeed.' , $this->item->id);
</source>

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:
<source lang="php">
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>

</source>
Changing the object and property names as appropriate.

You will most likely want to add the show_tags parameter to the item parameters, the menu item parameters and component configuration as appropriate for your use case.

<source lang="php">
<?php if ($this->params->get('show_tags', 1) && !empty($this->item->tags)) : ?>
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>
<?php endif; ?></source>

== Batch processing ==
If you want to add the ability to do batch tagging to a backend list view do the following.

Add tag to the default_batch layout

<source lang="php">
<div class="control-group">
<div class="controls">
<?php echo JHtml::_('batch.tag');?>
</div>
</div></source>

And add tag to the button class in the modal footer (Not totally necessary at this point, but good for potential future changes e.g. if unTag is added.)

<source lang="php">
<button class="btn" type="button" onclick="document.id('batch-category-id').value='';document.id('batch-access').value='';document.id('batch-language-id').value='';document.id('batch-user-id').value='';document.id('batch-tag-id)').value=''" data-dismiss="modal">
</source>

=== Add a batch method to your model if you are not extending JModelAdmin or overriding the batch method. ===

<source lang="php">
/**
* Batch tag a list of item.
*
* @param integer $value The value of the new tag.
* @param array $pks An array of row IDs.
* @param array $contexts An array of item contexts.
*
* @return void.
*
* @since 3.1
*/
protected function batchTag($value, $pks, $contexts)
{
$tagsHelper = new JHelperTags();
$tagsHelper->tagItems($value, $pks, $contexts);

return true;
}
</source>

And modify your batch method by adding
<source lang="php">
if (!empty($commands['tag']))
{
if (!$this->batchTag($commands['tag'], $pks, $contexts))
{
return false;
}

$done = true;
}

</source>

Pay attention to any JSON encoded strings that you need special handling for in batch processing -- remember that you are saving a copy of the core fields and you need save to work as expected.

That’s it, now create some tags, tag some items and you are set.

[[Category:Development]][[Category:Content Tags]]
[[Category:Tutorials]]

J3.x talk:Using Tags in an Extension

2014-04-24T15:28:54Z

GreyHead: /* Page contents */

== Page contents ==

The page contents as currently written are substantially incomprehensible.
It requires not so much copy-editing as re-interpretation into every day English. [[User:GreyHead|GreyHead]] ([[User talk:GreyHead|talk]]) 10:28, 24 April 2014 (CDT)

== ??? ==
Also bind() on component's table class on JTable should be overridden. Metadata should be json encoded before preStoreProcess.
<source lang="php">
public function bind($array, $ignore = '')
{
if (isset($array['metadata']) && is_array($array['metadata']))
{
$registry = new JRegistry;
$registry->loadArray($array['metadata']);
$array['metadata'] = (string) $registry;
}
return parent::bind($array, $ignore);
}
</source>
([[User:Kasiopi|Kasiopi]] ([[User talk:Kasiopi|talk]]) 05:42, 25 June 2013 (CDT))

J3.x talk:Using Tags in an Extension

2014-04-24T15:28:29Z

GreyHead: Contents incomprehensible

== Page contents ==

The page contents as currently written are substantially incomprehensible.
It requires not so much copy-editing as re-interpretation into every day English.

== ??? ==
Also bind() on component's table class on JTable should be overridden. Metadata should be json encoded before preStoreProcess.
<source lang="php">
public function bind($array, $ignore = '')
{
if (isset($array['metadata']) && is_array($array['metadata']))
{
$registry = new JRegistry;
$registry->loadArray($array['metadata']);
$array['metadata'] = (string) $registry;
}
return parent::bind($array, $ignore);
}
</source>
([[User:Kasiopi|Kasiopi]] ([[User talk:Kasiopi|talk]]) 05:42, 25 June 2013 (CDT))

JDOC:Local wiki templates

2014-04-24T15:23:59Z

GreyHead: /* Copyedit */

<p style="text-align:center;border:1px solid #ccc">[[JDOC:Local wiki templates|Local wiki templates]] • [[JDOC:Local wiki extensions|Local wiki extensions]] • [[JDOC:Local interwiki links|Local interwiki links]]</p>
[[:Category:Wiki Templates|MediaWiki templates]] should not to be confused with Joomla! templates! MediaWiki templates are "boiler-plate" items that can be included in your wiki pages by inserting a simple reference.

==Incomplete Content Notice==
Use this notice to indicate a page or section is incomplete and missing key information. The {{tl|incomplete}} or {{tl|underconstruction}} are different. The {{tl|underconstruction}} template is used to note the page is not finished, but a contributor will be completing the page in the very near future.
Insert {{tl|incomplete}} to obtain the following notice:
{{incomplete}}

==Page In Use Notice==
Use this notice should be used during '''Doc Sprints''' or if you will be editing a page for an extended period of time, e.g. more than 30 minutes. Please don't forget to remove it when you are done.
Insert {{tl|inuse}} at the top of the page to obtain the following notice:
{{inuse|category=no}}

==Under Construction Notice==
The {{tl|underconstruction}} template is used to note the page is not finished, but a contributor will be completing the page in the very near future.
Insert {{tl|underconstruction}} to obtain the following notice:
{{underconstruction}}

==Copyedit==
Use: <nowiki>{{copyedit}}</nowiki>

{{copyedit}}

==Article Reviews and Needs==
Once you're done with editing please replace {{tl|underconstruction}} and {{tl|inuse}} with {{tl|review}}. This will add your document to the [[:Category:Needs review]].
{{review}}
You can also use the {{tl|page}} notice if the page needs review or something other than a review.<br/>
Examples are:'''<nowiki>{{page|needs more content}}</nowiki>''' which would add the article to the [[:Category:Needs more content]].
{{page|needs more content}}Or use, '''<nowiki>{{page|needs images}}</nowiki>''' which would add the article to the [[:Category:Needs images]].
{{page|needs images}}
==Joomla Version Icons==
To indicate availability of a class, method or some piece of functionality in or from a particular version of Joomla, you can use the {{tl|JVer}} template. Only certain specific version numbers are supported:
{|class="prettytable parameters"
|-
!Version
!Short icon
!Long icon
|-
|CMS 1.0
|<nowiki>{{JVer|1.0}}</nowiki>: {{JVer|1.0}}
|<nowiki>{{JVer|1.0|Joomla 1.0|long}}</nowiki>: {{JVer|1.0|Joomla 1.0|long}}
|-
|CMS 1.5
|<nowiki>{{JVer|1.5}}</nowiki>: {{JVer|1.5}}
|<nowiki>{{JVer|1.5|Joomla 1.5|long}}</nowiki>: {{JVer|1.5|Joomla 1.5|long}}
|-
|CMS 1.6
|<nowiki>{{JVer|1.6}}</nowiki>: {{JVer|1.6}}
|<nowiki>{{JVer|1.6|Joomla 1.6|long}}</nowiki>: {{JVer|1.6|Joomla 1.6|long}}
|-
|CMS 1.7
|<nowiki>{{JVer|1.7}}</nowiki>: {{JVer|1.7}}
|<nowiki>{{JVer|1.7|Joomla 1.7|long}}</nowiki>: {{JVer|1.7|Joomla 1.7|long}}
|-
|CMS 2.5
|<nowiki>{{JVer|2.5}}</nowiki>: {{JVer|2.5}}
|<nowiki>{{JVer|2,5|Joomla 2.5|long}}</nowiki>: {{JVer|2.5|Joomla 2.5|long}}
|-
|CMS 3.x
|<nowiki>{{JVer|3.x}}</nowiki>: {{JVer|3.x}}
|<nowiki>{{JVer|3.x|Joomla 3.x|long}}</nowiki>: {{JVer|3.x|Joomla 3.x|long}}
|-
|CMS 3.0
|<nowiki>{{JVer|3.0}}</nowiki>: {{JVer|3.0}}
|<nowiki>{{JVer|3.0|Joomla 3.0|long}}</nowiki>: {{JVer|3.0|Joomla 3.0|long}}
|-
|CMS 3.1
|<nowiki>{{JVer|3.1}}</nowiki>: {{JVer|3.1}}
|<nowiki>{{JVer|3.1|Joomla 3.1|long}}</nowiki>: {{JVer|3.1|Joomla 3.1|long}}
|-
|Platform
|<nowiki>{{JVer|Platform}}</nowiki>: {{JVer|Platform}}
|Not available
|-
|Platform 11.1
|<nowiki>{{JVer|11.1}}</nowiki>: {{JVer|11.1}}
|Not available
|-
|Platform 11.2
|<nowiki>{{JVer|11.2}}</nowiki>: {{JVer|11.2}}
|Not available
|-
|Platform 11.3
|<nowiki>{{JVer|11.3}}</nowiki>: {{JVer|11.3}}
|Not available
|}

By default the ''alt'' tag generated will be the same as the version number, prefixed with the word "Joomla". You can override this default by adding a second parameter. For example, to get an ''alt'' tag of "Only available in Joomla 1.5" you should use <nowiki>{{JVer|1.5|Only available in Joomla 1.5}}</nowiki> which produces this: {{JVer|1.5|Only available in Joomla 1.5}}

Full documentation on the JVer template can be found [[Template:JVer/doc|here]].

You can also use the {{tl|JVer/multi}} Template to place multiple version icons.

{|class="prettytable parameters"
|-
!Versions
!Short icon
!Long icon
|-
|CMS Versions
|<nowiki>{{JVer/multi|1.0,1.5}}</nowiki>: {{JVer/multi|1.0,1.5}}
|<nowiki>{{JVer/multi|1.6,1.7,2.5|Joomla Version|long}}</nowiki>: {{JVer/multi|1.6,1.7,2.5|Joomla Version|long}}
|-
|Platform
|<nowiki>{{JVer/multi|11.1,11.2}}</nowiki>: {{JVer/multi|11.1,11.2}}
| '''Not Available'''
|-
|Mix CMS/Platform
|<nowiki>{{JVer/multi|1.7,11.2}}</nowiki>: {{JVer/multi|1.7,11.2}}
| '''Not Available'''
|}

For more information on use, specifically the long version icon use, please see, {{tl|JVer/multi}}

==Table of Contents==
You will get a table of contents(TOC) box on each page by default as soon as you make 4 or more headings and subheadings on the page. As an example, please look at the one you see on this page. The default table of contents box is located on the right and text will flow around it.
*You can force the table of contents in the location you add the text: '''<nowiki>__TOC__</nowiki>'''
*Alternatively, you can suppress the table of contents box by adding anywhere on the page: '''<nowiki>__NOTOC__</nowiki>'''

==Organisational Templates==
Used to mark articles for deletion, merging or version splitting.

===Delete===
Use the template {{tlx|delete|<reason text>}} on the very top of the page.
{{delete|This marker is just an example of use.}}

===Merge===
Use the template {{tlx|merge||title of target page}} on the very top of the page.
{{merge|JDOC:Local wiki templates}}

===JSplit===
Use the template {{tl|JSplit}} on the very top of the page.
{{JSplit}}

===Split===
Use the template {{tlx|split|<reason for splitting>}} on the very top of the page.
{{split|This page is too long and hard to follow.}}

==Version Notice==
If an article is written for a specific Joomla! Version, please use the {{tl|version}} template. It should be placed at the very top(first of all wiki markup) of an article so a person will see what version the page is relevant to. For example: '''<nowiki>{{version|1.6,1.7,2.5}}</nowiki>''' will place this:<br/>

{{version|1.6,1.7,2.5}}

If the article is a tutorial or part of a Tutorial Series, please use the '''<nowiki>{{version/tutor|1.5}}</nowiki>''' template, which will show this:<br/>

{{version/tutor|1.5}}

This helps readers know what version the information references and aids in version icon(s) inclusion in lists of articles and tutorials. For more information and how to use extended features of this template, please see {{tl|version}} template documentation.

==Standard License Notice==
Insert {{tl|license}} to obtain the following notice:
{{1}}{{license}}

==Shortcuts, Links & Navigation==
Some URLs can become utterly long, some are ugly, and some are just tedious to type over and over again. Adding categories to a page can become equally annoying.

To simplify your job try some of the following templates. Similar to the interwikis, they're true [[:Category:Typing-aid templates|keystroke-savers]]:
* {{tlx|jsite|keyword}}, for example:
: <nowiki>{{jsite}}</nowiki> = {{jsite}}
: <nowiki>{{jsite|forum}}</nowiki> = {{jsite|forum}}
: <nowiki>{{jsite|ext}}</nowiki> = {{jsite|ext}}. For more see {{tl|jsite}}.
* {{tlx|jforum|keyword}}, shortcuts for the many Working Group fora, i.e.
: <nowiki>{{jforum}}</nowiki> = {{jforum}}
: <nowiki>{{jforum|doc}}</nowiki> = {{jforum|doc}}
: <nowiki>{{jforum|devdoc}}</nowiki> = {{jforum|devdoc}}. For more see {{tl|jforum}}.

See also:
* [[:Category:Typing-aid templates]]
* [[:Category:Wiki Templates]] for the ''big list''

[[Category:Style guides|{{PAGENAME}}]]

J3.x:Using Tags in an Extension

2014-04-23T15:21:42Z

GreyHead:

Joomla's tagging system is used in all core content extensions and is designed to be be easy to integrate into other extensions that use standard Joomla design patterns.

Using tags in an extension is relatively straightforward but it requires small changes in a number of specific places.

'''!!! This document is mostly incomprehensible, please provide a translation into everyday English !!!'''

== Create a content type for each view ==
Note: Types can be added using either sql or postflight by creating a JTableContenttype instance and adding a row.

First identify which tables contain data that will be tagged and what the name of the single item view displaying each of these tables. For example:
* #__contact_details is the table displayed in the view contact of component com_contact with table class ContactTableContact.
* #__weblinks is the table displayed in the view weblink of com_weblinks so WeblinksTableWeblink.

<source lang="sql">
CREATE TABLE IF NOT EXISTS `#__content_types` (
`type_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`type_title` varchar(255) NOT NULL DEFAULT '',
`type_alias` varchar(255) NOT NULL DEFAULT '',
`table` varchar(255) NOT NULL DEFAULT '',
`rules` text NOT NULL,
`field_mappings` text NOT NULL,
`router` varchar(255) NOT NULL DEFAULT '',

</source>

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.

<source lang="php">
{"special":{"dbtable":"#__content","key":"id","type":"Content","prefix":"JTable","config":"array()"},"common":{"dbtable":"#__ucm_content","key":"ucm_id","type":"Corecontent","prefix":"JTable","config":"array()"}}
</source>

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
<source lang="php">
COM_TAGS_CONTENT_TYPE_ + the type_title
</source>
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.

<source lang="php">
'{"common":[{"core_content_item_id":"id","core_title":"title","core_state":"published","core_alias":"alias","core_created_time":"created_time","core_modified_time":"modified_time","core_body":"description", "core_hits":"hits","core_publish_up":"null","core_publish_down":"null","core_access":"access", "core_params":"params", "core_featured":"null", "core_metadata":"metadata", "core_language":"language", "core_images":"null", "core_urls":"null", "core_version":"version", "core_ordering":"null", "core_metakey":"metakey", "core_metadesc":"metadesc", "core_catid":"parent_id", "core_xreference":"null", "asset_id":"asset_id"}], "special": [{"parent_id":"parent_id","lft":"lft","rgt":"rgt","level":"level","path":"path","extension":"extension","note":"note"}]}'
</source>

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.

== Modify your component's table class (or classes if you have multiple tables) ==
Add the following to your JTable constructor:

$this->_observers = new JObserverUpdater($this);
JObserverMapper::attachAllObservers($this);

'''The addition material formerly located here is no longer needed after 3.1.4''' Please read the document history for this page if you are required to support 3.1.0 or 3.1.1.

'''For joomla 3.2 I needed this line:''' ( Dont forget to replace weblinks by your component name )

JObserverMapper::addObserverClassToClass('JTableObserverTags', 'WeblinksTableWeblink', array('typeAlias' => 'com_weblinks.weblink'));

== 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.

<source lang="xml">
<field name="tags" type="tag"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field></source>

The field loads all the Javascript libraries required. You don't need to worry about that.

The field supports two modes:
* '''Nested tags mode.''' Hierarchical tag list. Doesn't support on the fly tag creation.
* '''AJAX mode.''' Tags are searched while user types (3 min. chars required to launch the AJAX search). Custom tags are added by pressing ENTER or COMMA keys. Tags show the global route/path. Example: <code>grandpa/parent/tag</code>

The field mode can be forced or use the com_tags setting <code>Tag field mode</code> to determine its mode. To set/force the field mode we have to add '''mode="ajax"''' or '''mode="nested"''' to the tag field definition.

Example of forced AJAX mode:

<source lang="xml">
<field name="tags" type="tag" mode="ajax"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>
</source>
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"**

Example field definition with custom tags denied:

<source lang="xml">
<field name="tags" type="tag" mode="ajax" custom="denied"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>

</source>
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:

<source lang="php">
$item->tags = new JHelperTags;
$item->tags->getItemTags('com_newsfeeds.newsfeed.' , $this->item->id);
</source>

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:
<source lang="php">
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>

</source>
Changing the object and property names as appropriate.

You will most likely want to add the show_tags parameter to the item parameters, the menu item parameters and component configuration as appropriate for your use case.

<source lang="php">
<?php if ($this->params->get('show_tags', 1) && !empty($this->item->tags)) : ?>
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>
<?php endif; ?></source>

== Batch processing ==
If you want to add the ability to do batch tagging to a backend list view do the following.

Add tag to the default_batch layout

<source lang="php">
<div class="control-group">
<div class="controls">
<?php echo JHtml::_('batch.tag');?>
</div>
</div></source>

And add tag to the button class in the modal footer (Not totally necessary at this point, but good for potential future changes e.g. if unTag is added.)

<source lang="php">
<button class="btn" type="button" onclick="document.id('batch-category-id').value='';document.id('batch-access').value='';document.id('batch-language-id').value='';document.id('batch-user-id').value='';document.id('batch-tag-id)').value=''" data-dismiss="modal">
</source>

=== Add a batch method to your model if you are not extending JModelAdmin or overriding the batch method. ===

<source lang="php">
/**
* Batch tag a list of item.
*
* @param integer $value The value of the new tag.
* @param array $pks An array of row IDs.
* @param array $contexts An array of item contexts.
*
* @return void.
*
* @since 3.1
*/
protected function batchTag($value, $pks, $contexts)
{
$tagsHelper = new JHelperTags();
$tagsHelper->tagItems($value, $pks, $contexts);

return true;
}
</source>

And modify your batch method by adding
<source lang="php">
if (!empty($commands['tag']))
{
if (!$this->batchTag($commands['tag'], $pks, $contexts))
{
return false;
}

$done = true;
}

</source>

Pay attention to any JSON encoded strings that you need special handling for in batch processing -- remember that you are saving a copy of the core fields and you need save to work as expected.

That’s it, now create some tags, tag some items and you are set.

[[Category:Development]][[Category:Content Tags]]
[[Category:Tutorials]]

Accessing the database using JDatabase

2013-09-09T15:04:39Z

GreyHead: Re-added link to the really useful information

{{version/tutor|1.5,2.5,3.1}}
==Useful information==
This tutorial is split into two independent parts:
* [[Inserting, Updating and Removing data using JDatabase|Inserting, updating and removing data from the database]]. It also touches on transactions.
* [[Selecting data using JDatabase|Selecting data from one or more tables]] and retrieving it in a variety of different forms

Note: If you are looking for practical information about accessing the database it has been moved to the [[J1.5:Accessing_the_database_using_JDatabase|Joomla! 1.5 page here]]

==Supported Storage Connectors==

The table below outlines the database and storage connectors available for Joomla! as well as which version of Joomla they became available in.

To make a connector available in Joomla's installer or global configuration manager, you will need to ensure the PHP library is installed (E.g. for PHP5 and MySQL the php5-mysql library would need to be installed).

{| class="wikitable"
! scope="col" | Database
! scope="col" | Joomla Versions
|-
| MySQL || {{JVer|1.5}}{{JVer|2.5}}{{JVer|3.0}}
|-
| Postgresql || {{JVer|3.0}}
|-
| Microsoft SQL Server || {{JVer|2.5}}{{JVer|3.0}}
|-
| Microsoft SQL Azure || {{JVer|2.5}}{{JVer|3.0}}
|-
| Oracle DB || {{JVer|3.0}}
|-
| SQL Lite || {{JVer|3.0}}
|-
| PHP Data Objects (PDO)* || {{JVer|3.0}}
|}

* PHP Data Objects is a database abstraction layer and is shipped with PHP 5.1+.

J1.5:Accessing the database using JDatabase

2013-01-08T10:12:16Z

GreyHead:

Accessing the database using JDatabase

2013-01-08T10:10:32Z

GreyHead:

==Useful information==
If you are looking for practical information about accessing the database it has been moved to the Joomla! 1.5 page linked below

{{underconstruction}}

{{version/tutor|1.5,2.5,3.0}}{{multiversion|The '''{{PAGENAME}}''' Tutorial is available in these versions:-|version|pages=no}}

==Supported Storage Connectors==

The table below outlines the database and storage connectors available for Joomla! as well as which version of Joomla they became available in.

To make a connector available in Joomla's installer or global configuration manager, you will need to ensure the PHP library is installed (E.g. for PHP5 and MySQL the php5-mysql library would need to be installed).

{| class="wikitable"
! scope="col" | Database
! scope="col" | Joomla Versions
|-
| MySQL || {{JVer|1.5}}{{JVer|2.5}}{{JVer|3.0}}
|-
| Postgresql || {{JVer|3.0}}
|-
| Microsoft SQL Server || {{JVer|2.5}}{{JVer|3.0}}
|-
| Microsoft SQL Azure || {{JVer|2.5}}{{JVer|3.0}}
|-
| Oracle DB || {{JVer|3.0}}
|-
| SQL Lite || {{JVer|3.0}}
|-
| PHP Data Objects (PDO)* || {{JVer|3.0}}
|}

* PHP Data Objects is a database abstraction layer and is shipped with PHP 5.1+.

Talk:Accessing the database using JDatabase

2010-03-06T10:48:53Z

GreyHead: /* Merging the 2 suggested articles */

Can anyone provide more info regarding insertObject()?
I just have no idea of how to insert a row into a table. I tried to do the following but it just doesn't work:

$db = & JFactory::getDBO();
$query = "insert into #__my_table(field1, field2) values ('".$value1."','".$value2."')";
echo $query;
$db->setQuery( $query );
return($db->Query());

Any ideas?

Thanks!

<source lang="php">
/**
*
* $object->fieldname1 = 'value1';
* $object->fieldname2 = 'value2';
* $object->fieldname3 = 'value3';
* $object->fieldname4 = 'value4';
* $object->fieldname5 = 'value5';
*
* $table = '#__tablename';
*
*/

$db = JFactory::getDBO();

$db->insertObject($table, $object, 'id');

/**
*
* The query will be generated:
*
* INSERT INTO `#__tablename` ( 'fieldname1', 'fieldname2', 'fieldname3', 'fieldname4', 'fieldname5' ) VALUES ( 'value1', 'value2', 'value3', 'value4', 'value5' );
*
* and executed
*
*/

echo $object->id; // will output the last insert ID
</source>

If you wanna use "your" syntax:

<source lang="php">
$db = JFactory::getDOB();

$query = "INSERT INTO `#__tablename` ( 'field1', 'field2' ) VALUES ( '".$value1."', '".$value2."')";

/**
*
* $db->setQuery($query);
*
* if ($dump) {
* echo $db->getQuery();
* }
*
* $db->Query();
*
*/

$db->Execute($query);

</source>

But it's recommend to use a controller/model/table construct:

<source lang="php">

// controller

$model = $this->getModel('modelname')
$model->store($data);

// Model

public function store($data) {

[...]

$row = JTable::getInstance('KomponentNameTableName');

//save it in the db
if (!$row->save($data)) {
JError::raiseError( 500, $row->_db->getError() );
return false;
}

[...]

}

// table/komponentnametablename.php

class JTableKomponentNameTableName extends JTable {

/**
* Primary Key
* @var int
*/
var $id = null;
/** @var int */
var $field1 = null;
/** @var char */
var $field2 = null;

public function __construct(& $db) {
parent::__construct('#__tablename', 'id', $db);
}

public function check () {

// Check all fields $this->fieldname
return true;

}

}
</source>
-- [[User:Bembelimen|Bembelimen]] 12:34, 16 March 2009 (UTC)

----

I think, you can '''not''' repeat the call to loadAssoc to get further rows, because
loadAssoc runs the query unconditionally, I got a infinite recursion using it this way:
<source lang="php">
while($row = $db->loadAssoc()){
// do something...
}
</source>
See: [http://api.joomla.org/__filesource/fsource_Joomla-Framework_Database_joomladatabasedatabasemysql.php.html#a390]
line: 392

== Merging the 2 suggested articles ==

* Article 1:[[How to use the database classes in your script]]
* Article 2:[[Tutorial:How to use the database classes in your script]]
Discuss here ([[User:E-builds|E-builds]] 17:38, 11 January 2010 (UTC))

While they have the same name one is 'supposed' to be a reference and the other a 'how to' tutorial. Given that I think that the two should be complementary and linked but not merged. [[User:GreyHead|GreyHead]]

Talk:Accessing the database using JDatabase

2010-03-06T10:47:37Z

GreyHead: /* Merging the 2 suggested articles */

Can anyone provide more info regarding insertObject()?
I just have no idea of how to insert a row into a table. I tried to do the following but it just doesn't work:

$db = & JFactory::getDBO();
$query = "insert into #__my_table(field1, field2) values ('".$value1."','".$value2."')";
echo $query;
$db->setQuery( $query );
return($db->Query());

Any ideas?

Thanks!

<source lang="php">
/**
*
* $object->fieldname1 = 'value1';
* $object->fieldname2 = 'value2';
* $object->fieldname3 = 'value3';
* $object->fieldname4 = 'value4';
* $object->fieldname5 = 'value5';
*
* $table = '#__tablename';
*
*/

$db = JFactory::getDBO();

$db->insertObject($table, $object, 'id');

/**
*
* The query will be generated:
*
* INSERT INTO `#__tablename` ( 'fieldname1', 'fieldname2', 'fieldname3', 'fieldname4', 'fieldname5' ) VALUES ( 'value1', 'value2', 'value3', 'value4', 'value5' );
*
* and executed
*
*/

echo $object->id; // will output the last insert ID
</source>

If you wanna use "your" syntax:

<source lang="php">
$db = JFactory::getDOB();

$query = "INSERT INTO `#__tablename` ( 'field1', 'field2' ) VALUES ( '".$value1."', '".$value2."')";

/**
*
* $db->setQuery($query);
*
* if ($dump) {
* echo $db->getQuery();
* }
*
* $db->Query();
*
*/

$db->Execute($query);

</source>

But it's recommend to use a controller/model/table construct:

<source lang="php">

// controller

$model = $this->getModel('modelname')
$model->store($data);

// Model

public function store($data) {

[...]

$row = JTable::getInstance('KomponentNameTableName');

//save it in the db
if (!$row->save($data)) {
JError::raiseError( 500, $row->_db->getError() );
return false;
}

[...]

}

// table/komponentnametablename.php

class JTableKomponentNameTableName extends JTable {

/**
* Primary Key
* @var int
*/
var $id = null;
/** @var int */
var $field1 = null;
/** @var char */
var $field2 = null;

public function __construct(& $db) {
parent::__construct('#__tablename', 'id', $db);
}

public function check () {

// Check all fields $this->fieldname
return true;

}

}
</source>
-- [[User:Bembelimen|Bembelimen]] 12:34, 16 March 2009 (UTC)

----

I think, you can '''not''' repeat the call to loadAssoc to get further rows, because
loadAssoc runs the query unconditionally, I got a infinite recursion using it this way:
<source lang="php">
while($row = $db->loadAssoc()){
// do something...
}
</source>
See: [http://api.joomla.org/__filesource/fsource_Joomla-Framework_Database_joomladatabasedatabasemysql.php.html#a390]
line: 392

== Merging the 2 suggested articles ==

* Article 1:[[How to use the database classes in your script]]
* Article 2:[[Tutorial:How to use the database classes in your script]]
Discuss here ([[User:E-builds|E-builds]] 17:38, 11 January 2010 (UTC))

While thaty have the same name one is 'supposed' to be a reference and the other a 'how to' tutorial. Given that I think that the two should be complementary and linked but not merged.

J1.5:Developing a MVC Component/Using the Database

2009-03-07T16:08:57Z

GreyHead: Added Category:Database

== Introduction ==

In the first two tutorials, we showed you how to build a simple model-view-controller component. We had one view which retrieved data from a model (which was created in the 2nd tutorial). In this tutorial, we will be working with the model. Instead of the data being hard coded in the model, the model will retrieve the data from a table in the database.

This tutorial will demonstrate how to use the JDatabase class to retrieve data from the database.

== Retrieving the Data ==

Our model currently has one method: getGreeting(). This method is very simple - all it does is return the hard-coded greeting.

To make things more interesting, we will load the greeting from a database table. We will demonstrate later how to create an SQL file and add the appropriate code to the XML manifest file so that the table and some sample data will be created when the component is installed. For now, we will simply replace our return statement with some code that will retrieve the greeting from the database and return it.

The first step is to obtain a reference to a database object. Since Joomla! uses the database for its normal operation, a database connection already exists; therefore, it is not necessary to create your own. A reference to the existing database can be obtained using:

<source lang="php">$db =& JFactory::getDBO();</source>

JFactory is a static class that is used to retrieve references to many of the system objects. More information about this class can be found in the API documentation.

The method name (getDBO) stands for get DataBase Object, and is easy and important to remember.

Now that we have obtained a reference to the database object, we can retrieve our data. We do this in two steps:

* store our query in the database object
* load the result

Our new getGreeting() method will therefore look like:

<source lang="php">function getGreeting()
{
$db =& JFactory::getDBO();

$query = 'SELECT greeting FROM #__hello';
$db->setQuery( $query );
$greeting = $db->loadResult();

return $greeting;
}</source>

hello is the name of the table that we will create later, and greeting is the name of the field that stores the greetings. If you are not familiar with SQL, it would be helpful to take a tutorial or a lesson to get yourself up to speed. One such tutorial can be found at [http://www.w3schools.com/sql/default.asp w3schools].

The $db->loadResult() method will execute the stored database query and return the first field of the first row of the result. See [http://api.joomla.org/Joomla-Framework/Database/JDatabase.html JDatabase API reference] for more information about other load methods in the JDatabase class.

== Creating the Installation SQL File ==

The Joomla! installer has built-in support for executing queries during component installation. These queries are all stored in a standard text file.

We will have three queries in our install file: the first will drop the table in case it already exists, the second will create the table with the appropriate fields, and the third will insert the data.

Here are our queries:

<source lang="php">DROP TABLE IF EXISTS `#__hello`;

CREATE TABLE `#__hello` (
`id` int(11) NOT NULL auto_increment,
`greeting` varchar(25) NOT NULL,
PRIMARY KEY (`id`)
) ENGINE=MyISAM AUTO_INCREMENT DEFAULT CHARSET=utf8;

INSERT INTO `#__hello` (`greeting`) VALUES ('Hello, World!'),
('Bonjour, Monde!'),
('Ciao, Mondo!');</source>

You might find the prefix on the table names rather odd. Joomla! will replace this prefix with the prefix used by the current install. For most installs, this table will become jos_hello. This allows multiple installs of Joomla! to use the same database, and prevents collisions with other applications using the same table names (i.e. two applications might share a database, but might both require a 'users' table. This convention avoids problems.)

We have specified two fields in our database. The first field is id, and is called the 'primary key'. The primary key of a database table is a field that is used to uniquely identify a record. This is often used to lookup rows in the database. The other field is greeting. This is the field that stores the greeting that is returned from the query that we used above.

We will save our queries in a file called install.utf.sql.

=== Creating the Uninstall SQL File ===

Though we might hope that people will never want to uninstall our component, it is important that if they do, we don't leave anything behind. Joomla! will look after deleting the files and directories that were created during install, but you must manually include queries that will remove any tables that have been added to the database. Since we have only created one table, we only need one query:

<source lang="php">DROP TABLE IF EXISTS `#__hello`;</source>

We will save this query in a file called uninstall.utf.sql.

== Updating our Install File ==

We need to change a few things in our install file. First, we need to add our two new files to the list of files to install. SQL install file have to go in the admin directory. Second, we need to tell the installer to execute the queries in our files on install and uninstall.

Our new file looks like this:

<source lang="xml"><?xml version="1.0" encoding="utf-8"?>
<install type="component" version="1.5.0">
<name>Hello</name>

<creationDate>2007-02-22</creationDate>
<author>John Doe</author>
<authorEmail>john.doe@example.org</authorEmail>
<authorUrl>http://www.example.org</authorUrl>
<copyright>Copyright Info</copyright>
<license>License Info</license>

<version>3.01</version>

<description>Description of the component ...</description>



<files folder="site">
<filename>controller.php</filename>
<filename>hello.php</filename>
<filename>index.html</filename>
<filename>models/hello.php</filename>
<filename>models/index.html</filename>
<filename>views/index.html</filename>
<filename>views/hello/index.html</filename>
<filename>views/hello/view.html.php</filename>
<filename>views/hello/tmpl/default.php</filename>
<filename>views/hello/tmpl/index.html</filename>
</files>

<install>
<sql>
<file charset="utf8" driver="mysql">install.sql</file>
</sql>
</install>
<uninstall>
<sql>
<file charset="utf8" driver="mysql">uninstall.sql</file>
</sql>
</uninstall>

<administration>

<menu>Hello World!</menu>


<files folder="admin">
<filename>hello.php</filename>
<filename>index.html</filename>
<filename>install.sql</filename>
<filename>uninstall.sql</filename>
</files>

</administration>
</install></source>

You will notice two attributes present on the <file> tags within the <install> and <uninstall> sections: charset and driver. The charset is the type of charset to use. The only valid charset is utf8. If you want to create install files for non-utf8 databases (for older version of MySQL), you should omit this attribute.

The driver attribute specifies which database the queries were written for. Currently, this can only be mysql, but in future versions of Joomla! there may be more database drivers available.

== Conclusion ==

We now have a component that takes advantage of both the Joomla! MVC framework classes and the JDatabase classes. You are now able to write MVC components that interact with the database and can use the Joomla! installer to create and populate database tables.

== Other Articles in this Series ==
[[Developing a Model-View-Controller Component - Part 1]]

[[Developing a Model-View-Controller Component - Part 2 - Adding a Model]]

[[Developing a Model-View-Controller Component - Part 4 - Creating an Administrator Interface]]

== Contributors ==
* staalanden

== Download ==

The component can be downloaded at: [http://joomlacode.org/gf/download/frsrelease/8110/29435/com_hello3_01.zip com_hello3_01]
[[Category:Database]]

Accessing the database using JDatabase

2009-03-07T16:08:28Z

GreyHead: Added Category:Database

How to determine your database prefix

2009-03-07T16:05:00Z

GreyHead: Added Category:Database

The database prefix can be found in the file configuration.php or in the admin panel under the menu "Site - Configuration File - Global Configuration - Server"

[[Category:Database]]

How to apply a .sql file to a database

2009-03-07T16:04:29Z

GreyHead: Added Category:Database

==Using phpMyAdmin==
Login to your MySQL database via phpMyAdmin [http://www.phpmyadmin.net]. Select your database. Choose the SQL tab. Enter the code lines into the text box and press Go. You will be provided with the results of the command on this screen.

==Using MySQL Query Browser==
Login to your MySQL database via MySQL Query Browser [http://www.mysql.com/products/tools/query-browser/]. Double click on your database on the right hand side to select it. Create a new "script" tab and enter the code lines into the text box provided and press "Execute".

==Using the command line MySQL client (advanced!)==
MySQL by default ships with a command line client [http://dev.mysql.com/doc/refman/5.0/en/mysql.html] that enables access to MySQL databases.
# Change to the directory containing a copy of the script file. For example,
#:<source lang="bash">cd /public_html/installation/sql/mysql</source>
# Use the tool to connect to your Joomla! database and use a redirection operator ("<") to take commands from the .sql file. For example,
#:<source lang="bash">mysql --user=name joomla_database_name < diff_rc3_to_rc4.sql</source>
#: You will be prompted to enter the password before the command is carried out. Do not use the "--password" option to enter your password on the command line as this is not secure (potentially anyone else logged in to your system can see the password).

[[Category:Database]]

J1.5:Database structure

2009-03-07T16:03:40Z

GreyHead: added Category:Database

{{stub}}
{{inuse}}
==Structure==
The J! 1.5.x database structure includes 36 Tables
Tables listing w/out prefix_
#banner
#bannerclient
#bannertrack
#categories
#components
#contact_details
#content
#content_frontpage
#content_rating
#core_acl_aro
#core_acl_aro_groups
#core_acl_aro_map
#core_acl_aro_sections
#core_acl_aro_groups_aro_map
#core_log_items
#core_log_searches
#groups
#menu
#menu_types
#messages
#messages_cfg
#migration_backlinks
#modules
#modules_menu
#newsfeeds
#plugins
#polls
#poll_data
#poll_date
#poll_menu
#sections
#sessions
#stats_agents
#templates_menu
#users
#weblinks

'''API table Relationships joomla 1.5'''

#Lien : http://www.torkiljohnsen.com/wp-content/uploads/2006/04/joomla_15_database_schema.png

#[[Detailed list of fields]] [[Category:Database]]

Connecting to an external database

2009-03-07T15:57:33Z

GreyHead: Added database category

If you need to access tables within the same database as your Joomla! installation then you can simply use the [[JFactory/getDBO|JFactory->getDBO]] method. This uses the already established connection that Joomla! uses to connect to the database. For example:

<source lang="php">
<?php
$db = JFactory::getDBO();
?>
</source>

$db is now an object of type [[JDatabase]] and you can perform database operations on it using the usual methods.

But what if you want to connect to a completely different database from the one used by Joomla!?. This might be a different database on the same machine as your Joomla! site or it might be on a different host and perhaps even require a different database driver. Well, you can do this using the [[JDatabase/getInstance|JDatabase->getInstance]] method.

<source lang="php">
<?php
$option = array(); //prevent problems

$option['driver'] = 'mysql'; // Database driver name
$option['host'] = 'db.myhost.com'; // Database host name
$option['user'] = 'fredbloggs'; // User for database authentication
$option['password'] = 's9(39s£h[%dkFd'; // Password for database authentication
$option['database'] = 'bigdatabase'; // Database name
$option['prefix'] = 'abc_'; // Database prefix (may be empty)

$db = & JDatabase::getInstance( $option );
?>
</source>

$db is now an object of type [[JDatabase]] and you can perform database operations on it using the usual methods.

Note that if the database uses a non-standard port number then this can be specified by adding it to the end of the host name. For example, you might have your MySQL database running on port 3307 (the default is port 3306), in which case your host name might be 'db.myhost.com:3307'.

One feature of using [[JDatabase/getInstance|JDatabase->getInstance]] is that if another call is made with the same parameters it will return the previously created object rather than creating a fresh one.

Note, however, that the parameters must match exactly for this to happen. For example, if two calls were made to a MySQL database using [[JDatabase/getInstance|JDatabase->getInstance]], with the first using a host name of 'db.myhost.com' and the second using 'db.myhost.com:3306', then two separate connections would be made, even though port 3306 is the default port for MySQL and so the parameters are logically the same.
<noinclude>[[Category:Development]] [[Category:Database]]</noinclude>

Accessing the database using JDatabase

2009-02-23T20:04:48Z

GreyHead: /* loadResultArray() */

Accessing the database using JDatabase

2009-02-23T19:15:27Z

GreyHead: /* loadResultArray($index) */

Accessing the database using JDatabase

2009-02-23T19:12:41Z

GreyHead: /* Single Column Results */ added loadResultArray($index)

Accessing the database using JDatabase

2009-02-10T16:05:38Z

GreyHead: Moved $setQuery and added () to method titles

Accessing the database using JDatabase

2009-02-10T16:02:09Z

GreyHead: /* Basic Query Execution */ added setQuery content

Accessing the database using JDatabase

2009-02-10T15:52:31Z

GreyHead: /* Basic Query Execution */ added content

Accessing the database using JDatabase

2009-02-07T16:18:25Z

GreyHead: /* loadObjectList('key') */

Accessing the database using JDatabase

2009-02-07T16:17:53Z

GreyHead: /* loadObjectList('key') */

Accessing the database using JDatabase

2009-02-07T16:17:15Z

GreyHead: /* loadObjectList */ added loadObjectList('key')

Accessing the database using JDatabase

2009-02-07T16:12:12Z

GreyHead: /* loadAssocList */

Accessing the database using JDatabase

2009-02-07T15:55:05Z

GreyHead: /* getNumRows */

Accessing the database using JDatabase

2009-02-07T15:53:40Z

GreyHead: /* Misc Result Set Methods */ added content

Accessing the database using JDatabase

2009-02-07T08:48:47Z

GreyHead: /* loadObjectList */ updated results

Accessing the database using JDatabase

2009-02-07T08:47:08Z

GreyHead: /* loadAssocList */ updated results

Accessing the database using JDatabase

2009-02-07T08:45:21Z

GreyHead: /* loadRowList */ updated results

Accessing the database using JDatabase

2009-02-07T08:43:14Z

GreyHead: /* loadResultArray */

Accessing the database using JDatabase

2009-02-07T08:42:31Z

GreyHead: /* loadResultArray */ updated results