utilitees

Simple Tags Documentation

• Requirements
• Upgrading from Simple Tags 1.0
• Upgrading from Simple Tags 1.6.2 to 1.6.3
• Upgrading from Simple Tags 1.6.3 to 1.6.x
• Installation
• Extension Settings
• Usage
• The Taglist Tag
• The Tagheader Tag
• Listing Tag-links for each entry
• Displaying a tag-cloud
• Listing tags and their popularity
• Displaying recently used tags
• Displaying related tags
• Displaying related tags as a cloud
• Listing related entries
• The Tagloop-Tag
• Displaying a WP-Cumulus Flash Tagcloud
• User Talk

 

Requirements

Simple Tags 1.7.2 or greater requires the jQuery for the Control Panel extension installed and enabled. This extension was introduced with 1.6.5 and if you carefully followed the update instructions you should have it.
If you don’t you can install it like outlined in the aforementioned instructions.

Upgrading from Simple Tags 1.0

If you’ve been using Simple Tags 1.0 first uninstall the old module and extension. Don’t worry - your existing tags won’t be lost.

1. In your Control Panel navigate to CP Home ›  Admin ›  Utilities ›  Extensions Manager, find the Simple Tags extension and click Disable?
2. In your Control Panel navigate to CP Home ›  Modules, find the Simple Tag module and click Remove.
3. Follow the normal installation instructions below. Be sure to overwrite the old files.
4. After you are finished go to CP Home ›  Modules › Simple Tag and re-tag all entries.

All template-tags are backward compatible.

Upgrading from Simple Tags 1.6.2 to 1.6.3

On installation the folder ext_simple_tags is copied from EE’s extensions-folder to EE’s themes-folder.
If you use the autosuggest-feature, please manually copy sita.js from extensions/ext_simple_tags/-folder to EE’s themes/ext_simple_tags/-folder.

Other than that you can just replace the old files with their new versions.

Upgrading from Simple Tags 1.6.3 to 1.6.x

Just replace the old files with their new versions.
After you are finished you may go to CP Home ›  Modules › Simple Tag and re-tag all entries.

Installation

1. Unzip the file.
2. Upload the file ext.simple_tags.php and the ext_simple_tags-folder to the extensions-folder inside your EE system directory.
3. Upload the folder simpletag and the contained files to the modules-folder inside your EE system directory.
4. Upload the files lang.simple_tags.php & lang.simpletag.php to the language/english-folder inside your EE system directory.
5. In your Control Panel navigate to CP Home ›  Admin ›  Utilities ›  Extensions Manager, find the Simple Tags extension and click Enable?
6. In your Control Panel navigate to CP Home ›  Modules, find the Simple Tag module and click Install.
7. Now you have access to the CP Interface of the module. There isn’t much to do there except batch-(re-)indexing all your existing weblog entries.
   If you installed the extension and already had a field containing comma-separated tags or if you at some point import entries that have such a field, the tagging-database table needs to be rebuild before the tags are available.
   This is as complicated as clicking the only button available until it’s gone

Extension settings

Go to the Extensions Manager and click the Settings-link of Simple-Tags extension.

There you’ll find a list of all Custom Weblog Fields that currently exist. You are supposed to select the field(s) that will contain your tags.

If you have no field for this purpose yet, first create one, then come back here to activate it.
Field Types can be Text Input or Textarea and Default Text Formatting must be ‘None’. Of course that field(s) must belong to the Field Group(s) assigned to the weblog(s) where you want to use tagging.

If you want to use AJAX auto-suggestion of tags, tick the appropriate checkbox. This will activate autosuggest for all tag-fields in the Contol Panel Publish Form as well as in Stand-Alone Entry Forms

Usage

As has been mentioned before, in order to use tagging in a weblog the weblog’s Field Group must contain a Custom Weblog Field with Formatting set to None and this field must designated as a tagging field in the extension’s settings.
When posting an entry you may enter your tags into that field. Separate the tags by commas.

The Taglist Tag

First thing you probably want to do is creating a template on which all related entries are shown once someone clicks on a Tag-link. I will call it site/taglist in this example.

Inside this template you can use a pretty standard exp:weblog:entries-tag to display whatever you like of the related entries, but you’ll have to wrap it inside {exp:simpletag:taglist}{/exp:simpletag:taglist}.

Parameters:

This parameter is mandatory. The Tag’s name will usually be passed in the URL. You have to specify the segment which contains it. Normally this will be the third segment.

You can of course also hardcode this value if you want to use the exp:simpletag:taglist-tag to output entries for a certain tag somewhere else.

Furthermore you can pipe several tags to this parameter using (or) or (and).
For example:

tagname="software(or)browser(or)ftp" 

will retrieve all entries tagged with either software or with browser or with ftp.
Likewise

tagname="software(and)browser" 

will fetch entries that are both tagged with software AND browser.
The exp:simpletag:tagheader and exp:simpletag:related_tags will behave accordingliy.

This parameter is optional. If you want to limit the display to entries of (a) particular weblog(s) you can specifiy this here using the usual syntax.

Optional. You can specifiy multiple sites using the usual syntax. If not specified it defaults to the current site.

Example:

The Tagheader Tag

To account for special characters tags use url_titles much like weblog entries or categories. If you want to print the plaintext of a tagname passed in the URL there’s {exp:simpletag:tagheader}{/exp:simpletag:tagheader}.

It has one mandatory parameter and a single variable: {tag}.

Example:

This will translate the tagname passed in segment_3 into the plaintext tag.

Listing Tag-links for each entry

To display tags under your entries that are linked to the taglist we created above the {exp:simpletag:taglinks}-tag is used. This is single-tag with no closing element. It is supposed to be used inside an {exp:weblog:entries}-loop.

Example:

Parameters:

This parameter is mandatory. It will pass the ID of the entry whose tags are supposed to show up.

This parameter is mandatory. This will contain the URL to the taglist we created. You can use a {path}-variable here.

Optional. This can be any text-string you want to display between the single tags. If nothing is specified it defaults to one space character.
Notice: Since a parameter cannot start or end with a space character, you have to use an underscore (_) instead if your delimiter shall begin or end with blanks.

The taggify-tag is deprecated as of version 1.7. It does still work however.


To display tags under your entries that are linked to the taglist we created above you can wrap {exp:simpletag:taggify}{/exp:simpletag:taggify} around the variable of the custom field you designated to contain tags. This may be done everywhere you display weblog entries with the exp:weblog:entries-tag no matter whether it’s on a single- or multi-entry template.

Parameters:

path="" 

This parameter is mandatory. This will contain the URL to the taglist we created. You can use a {path}-variable here.

delimiter="" 

Optional. This can be any text-string you want to display between the single tags. If nothing is specified it defaults to one space character.
Notice: Since a parameter cannot start or end with a space character, you have to use an underscore (_) instead if your delimiter shall begin or end with blanks.

Example:

{exp:weblog:entries weblog="blog" limit="10"}
   <h1>{title}</h1>
  {body}
  <br />
   Tags: 
   {exp:simpletag:taggify path="{path=site/taglist}" delimiter="_-_"}
      {keywords}
   {/exp:simpletag:taggify}
{/exp:weblog:entries} 

This will display the tags from your field named keywords separated by ” - ” and linked to the taglist-template.

Displaying a tag-cloud

Then there is an EE-tag to display a tagcloud:

.

It’s a single EE tag with no closing element.

Parameters:

This parameter is mandatory. This will contain the URL to the taglist we created. You can use a {path}-variable here.

This parameter is optional. If you want to limit the display to entries of (a) particular weblog(s) you can specifiy this here using the usual syntax.

Optional. You can specifiy multiple sites using the usual syntax. If not specified it defaults to the current site.

Optional. This limits the cloud to the X most popular tags.

Optional. The font-size of the tags will be determined in %. This is the maximum size a popular tag can reach. Defaults to 250.

Optional. The font-size of the tags will be determined in %. This is the minimum size an unpopular tag can reach. Defaults to 100.

Optional. By default the tagcloud is ordered alphabetically. You can order it by popularity if you set this parameter.

Example:

This will produce a tagcloud with the top 20 tags linked to the template site/taglist and the most popular tag will have a font-size of 200%.

Listing tags and their popularity

A more generic way to list your tags is offered by the {exp:simpletag:tags}-tagpair.
You can use it to create your own clouds, lists or whatever comes to your mind.

Variables:

The plaintext representation of the tag.

The url_title of the tag.

The number of times the tag was used.
This value may also be normalized using the min & max parameters.

Parameters:

This parameter is optional. If you want to limit the display to entries of (a) particular weblog(s) you can specifiy this here using the usual syntax.

Optional. You can specifiy multiple sites using the usual syntax. If not specified it defaults to the current site.

Optional. This limits the cloud to the X most popular tags.

Optional. You must either set both or none of them.
If max & min are not set the {quantity} variable will return the total number of times a tag is used.
With max & min you can normalize the value by assigning, well, maximum and minimum values. This way you can translate the total numbers to be used with font-sizes or percentages.

Optional. By default the tagcloud is ordered alphabetically. You can order it by popularity if you set this parameter.

Example:

Displaying recently used tags

You can output a list of recently used tags and link them to your taglist. You can see an example here in the upper right sidebar.

Parameters:

This parameter is optional. If you want to limit the display to entries of (a) particular weblog(s) you can specifiy this here using the usual syntax.

Optional. You can specifiy multiple sites using the usual syntax. If not specified it defaults to the current site.

Optional. This limits the number of tags returned. Defaults to 10 if not specified.

Backspacing removes characters from the last iteration of the loop. Details.

Variables:

The url_title of the tag.

The plaintext representation of the tag.

Displaying related tags

This function is intended to be used in the taglist-template. It will output tags that are related to the tag currently viewed.

Two tags are considered related when they are attached to the same entry. The more often two tags are found in conjunction the closer the relation is considered - the relation gains weight.

Let’s look at an example, three entries with tags and the relations (<->) they create:

ENTRY 1
Tags: Software, Freeware, Browser

Software <-> Freeware
Software <-> Browser
Freeware <-> Browser

ENTRY 2
Tags: Freeware, Browser, Internet

Freeware <-> Browser
Freeware <-> Internet
Browser <-> Internet

ENTRY 3
Tags: Freeware, Browser

Freeware <-> Browser

So, “Browser” is related to “Freeware”, “Software” and “Internet” as it turns up in conjunction with each of these terms.
The relation between “Browser” and “Software” has a weight of 1 because there is one entry tagged with both of them. The same is true for the relation between “Browser” and “Internet”.
The combination of “Browser” and “Freeware” however is found three times so their relation has a weight of 3.

Makes sense? Hopefully.

Example:

Parameters:

This parameter is mandatory. The tag’s name will usually be passed in the URL. You have to specify the segment which contains it. Normally this will be the third segment.

This parameter is optional. If you want to limit the related tags that are retrieved to (a) particular weblog(s) you can specifiy this here using the usual syntax.

Optional. You can specifiy multiple sites using the usual syntax. If not specified it defaults to the current site.

Optional. You can order the related tags either by their name (alphabetically) or by weight.

Optional. Limits the number of related tags that are returned.

Optional. Sort order of the output. Either ascending or descending. Defaults to “asc” if not specified.

Backspacing removes characters from the last iteration of the loop. For example, if you put a <br /> after each tag and don’t want don’t want a <br /> after the last tag, you’d set backspace to 6 as <br /> is 6 characters long.

would output something like

Variables:

The url_title of the tag.

The plaintext representation of the tag.

The ‘weight’ of the relation.

Displaying related tags as a cloud

The related tags as explained above can also be presented in a cloud view. The more weight the relation has the bigger the font of the tag.

This is a single EE tag with no closing element.

Parameters:

This parameter is mandatory. The tag’s name will usually be passed in the URL. You have to specify the segment which contains it. Normally this will be the third segment.

Optional. This will contain the URL to the taglist we created. You can use a {path}-variable here.
If the related-tags-function is used in the taglist-template, path can be omitted.

This parameter is optional. If you want to limit the related tags that are retrieved to (a) particular weblog(s) you can specifiy this here using the usual syntax.

Optional. You can specifiy multiple sites using the usual syntax. If not specified it defaults to the current site.

Optional. The font-size of the tags will be determined in %. This is the maximum size a tag can reach. Defaults to 250.

Optional. The font-size of the tags will be determined in %. This is the minimum size a tag can reach. Defaults to 100.

Listing related entries

You can output a list of entries which are related to the current entry. The relation is based on whether and how many tags the entries have in common. The exp:simpletag:related_entries-tag needs to be placed inside a exp:weblog:entries-tag in order to pass the entry ID. It may be used on single- and multi-entry-templates.

Parameters:

Mandatory. The ID of the entry for which related entries should be fetched.

Optional. If you want to limit the display to entries of (a) particular weblog(s) you can specifiy this here using the usual syntax.

Optional. You can specifiy multiple sites using the usual syntax. If not specified it defaults to the current site.

Optional. You can set a threshold that needs to be reached before two entries are considered related. This is the number of tags in common. Defaults to 1 if not specified.

Optional. You may order the related entries by title, entry date or weight (number of tags in common).

Optional. Sort order of the output. Either ascending or descending. If not specified it defaults to “asc” for title and “desc” for entry date and weight.

Optional. You can limit the number of related entries returned. Defaults to 5 if not specified.

Backspacing removes characters from the last iteration of the loop. Details.

Variables:

The variables of this tag should be known from the exp:weblog:entries-tag. They are just prefixed with rel_ to avoid conflicts.

Title of the related entry.

URL title of the related entry.

Entry ID of the related entry.

Entry date of the related entry.

The weight (number of tags in common) of the relation.

The “count” out of the current related entries being displayed. If five entries are being displayed, then for the fourth entry the {rel_count} variable would have a value of “4”.

These are common path-variables that can be used to link to your related entries.

Tagloop-Tag

For the sake of completeness I should mention that there’s also a method called with exp:simpletag:tagloop. It is not designed for any special purpose but may be of interest for developing some custom functionality like populating a select-box or just putting out a list of linked tags (comparable to exp:weblog:categories) .

All it does is returning all tags that exist for the given weblog(s). 

Parameters:

Optional. If you want to limit the display to entries of (a) particular weblog(s) you can specifiy this here using the usual syntax.

Optional. You can specifiy multiple sites using the usual syntax. If not specified it defaults to the current site.

Backspacing removes characters from the last iteration of the loop. Details.

Variables:

The url_title of the tag.

The plaintext representation of the tag.

Application example:

I put together a little example how this could be used. In the right column of the weblog there’s the box labeled Dynamic RSS. It lets you select multiple tags and produces a link to a dynamic RSS-template.

It uses exp:simpletag:tagloop to populate the select-list. That little javascript then stitches the tagnames toghether using either (or) or (and) and redirects to the RSS-template passing the tags in the URL.

Inside the RSS-template there’s of course an exp:simpletag:taglist-tag that takes the tags from Segment 3 and returns weblog entries accordingly.

Here’s the code:

Displaying a WP-Cumulus Flash Tagcloud

For those who want a more fancy tagcloud I added support for WP-Cumulus. An example can be seen in the weblog.

Installation
To use it you need to download the Wordpress-Plugin here. Unpack the archive and upload the folder wp-cumulus to your ExpressionEngine themes-folder. You only need the files swfobject.js and tagcloud.swf. You can and probably should delete the other files.

The tag to display the cumulus-cloud is similiar to the tagcloud-tag but has additional parameters to control the flash-movie.

Note: It’s a single EE tag with no closing element.

Parameters:

This parameter is mandatory. This will contain the URL to the taglist we created. Use a {path}-variable here.

This parameter is optional. If you want to limit the display to entries of (a) particular weblog(s) you can specifiy this here using the usual syntax.

Optional. You can specifiy multiple sites using the usual syntax. If not specified it defaults to the current site.

Optional. This limits the cloud to the X most popular tags.

Optional. The font-size of the tags will be determined in pt. This is the maximum size a popular tag can reach. Defaults to 25.

Optional. The font-size of the tags will be determined in pt. This is the minimum size an unpopular tag can reach. Defaults to 10.

Optional. Defaults to 400.
The movie will scale itself to fit inside whatever dimensions you decide to give it. If you make it really small, chances are people will not be able to read less-used tags that are further away. Anything up from 300 will work fine in most cases.

Optional. Defaults to 300.
Ideally, the height should be something like 3/4 of the width. This will make the rotating cloud fit nicely, while the extra width allows for the tags to be displayed without cropping. Western text is horizontal by nature, which is why the ideal aspect is slightly landscape even though the cloud is circular.

Optional. The background-color of the movie. Defaults to #000000 (black).
This options has no effect when you set the trans-parameter to ‘true’.

Optional. Color of the tags. Default to #ffffff (white).
Type the HTML color value you’d like to use for the tags, with or without the ‘#’. Black (000000) will obviously work well with light backgrounds, white (ffffff) is recommended for use on dark backgrounds. Optionally, you can use the tcolor2-parameter to specify a different color. When two colors are available, each tag’s color will be from a gradient between the two. This allows you to create a multi-colored tag cloud.

Optional . Mouseover highlight color. Defaults to #ff0000 (red).

Optional. Defaults to ‘false’.
If you set this to ‘true’ the movie will attempt to distribute the tags evenly over the surface of the sphere.

Optional. Defaults to 100.
This allows you to change the speed of the sphere. Options between 25 and 500 work best.

Optional. Defaults to ‘false’.
Set to ‘true’ or ‘false’ to turn on/off background transparency. Enabling this might cause issues with some (mostly older) browsers. Under Linux, transparency doesn’t work in at all due to a known limitation in the Flash player.

Example:

{exp:simpletag:cumulus weblog=“blog” path=”{path=notes/tag}” width=“600” height=“450” font_max=“25” font_min=“10” tcolor=”#004080” tcolor2=”#88ABEC” bgcolor=”#ffffff” hicolor=”#ff0000” distr=“true”}

Questions / bug reports

For general comments, brickbats & bouquets please use the form over here.

Name:

Email:

URL:

	Remember my personal information
	Notify me of follow-up comments?

Page 1 of 14 pages  1 2 3 >  Last »

User Talk