Plugin: LMLabels

Lets you add one or more labels to each item in a blog.

General plugin info
Author:Leo
Current version:1.0.1
Download:NP_LMLabels_v101.zip
Support: Plugin comments or forum thread
Compability:Nucleus CMS 3.60, NP_LMReplacementVars 1.0.0, NP_LMURLParts 1.1.1

Plugin overview

The NP_LMLabels plugin lets you add one or more labels to each item in a blog. The normal use for these labels is to categorize items. Labels can be used in addition to or instead of the built in category system in Nucleus. An other use for this plugin is to add words to the URL of an item.

To show the labels associated with an item on an item skin is the plugin template variable used. The template variable can be used in any item fields in a template. The HTML generated by the template variable used is fully customizable either by plugin options or by template fields.

Labels can be used to filter items shown on the index page, archive list page or archive pages of a blog. This is done by using the plugin skin variable to add a label cloud to the index, archive list or archive pages. All the labels used in the currently available items are shown in the label cloud. Each label shown in the label cloud has an URL thats adds the label to the current label filter. As labels are added to the label filter will the label cloud change to match the items available after filtering. The HTML generated by the label cloud skin variable is fully customizable either by plugin options or by template fields.

To show the current label filter for an index page, archive list page or archive page is the plugin skin variable used. Each label shown in the current label filter has an URL thats removes the label from the filter. An URL to remove all labels from the filter is also shown. The HTML generated by the current label filter skin variable is fully customizable either by plugin options or by template fields.

The current skin variables in Nucleus core for showing blog content on index, archive list and archive pages does not have the possibility to have plugins filter the items shown. Because of this the NP_LMLabels plugin uses a helper plugin for handling item filtering. This plugin is called NP_LMReplacementVars and gives alternative implementations of some key Nucleus core skin variables. It must be installed before the NP_LMLabels plugin can be installed. The NP_LMReplacementVars plugin can be downloaded from the NP_LMReplacementVars plugin page.

The NP_LMLabels plugin uses a helper plugin for handling the URL part values. This plugin is called NP_LMURLParts and is used to store and edit the URL part values to be used in the generated URLs. This plugin must be installed before the NP_LMLabels plugin can be installed. The NP_LMURLParts plugin can be downloaded from the NP_LMURLParts plugin page.

If the NP_LMFancierURL plugin is installed will label keywords be used in URLs. The NP_LMFancierURL plugin can be downloaded from the NP_LMFancierURL plugin page.

Installation

  • Before you can install the NP_LMLabels you must install the NP_LMURLParts and NP_LMReplacementVars helper plugins.
  • Upload the NP_LMLabel.php file and the lmlabels directory from the zip file to the Nucleus CMS plugins directory (nucleus/plugins) on your web server.
  • Go to the Plugins page in the admin area. You should be able to select the plugin in the dropdown list under the "Install New Plugin" section and press the "Install Plugin" button.

Upgrade

  • Take a backup of the current plugin files. You will need these if you want to rollback to the previous version after the upgrade.
  • Take a backup of the database used for you Nucleus installation.
  • Replace the old plugin files with the new ones. Do not uninstall the plugin.
  • If a plugin data upgrade is needed, will an upgrade plugin data option be available on the NP_LMLabels plugin admin page. Choose this option to upgrade the plugin data.
  • After the plugin data upgrade has been performed may a rollback option and a commit option be available on the NP_LMLabels plugin admin page. Not all upgrades support the rollback and commit option.
  • If you are not pleased with the new version of the plugin you may use the rollback option to rollback the plugin data upgrade. After the rollback of the plugin data upgrade you have to replace the new plugin files with the old plugin files.
  • If you are pleased with the new version of the plugin you should use the commit option to commit the plugin data upgrade. After the commit of the plugin data upgrade will any rollback and commit options disappear.

Configuration

The NP_LMLabels plugin has the following options on the global level:

  • Delete NP_LMLabels data on uninstall? - Choose if all data should be deleted when the plugin is uninstalled.
  • Include marked labels in URLs for items? - Choose if any marked labels should be included in item URLs. See the usage section for more information on how to mark labels. Requires NP_LMFancierURL plugin installed if set to Yes.
  • Item Labels - Template for how to put together the label list generated by the <%LMLabels()%> template variable with the ItemLabels function. This template variable is meant to be used in the item section of a Nucleus template. The Item Labels template is build up by the following variables:
    • <%header%> - Inserts the content of the Item Labels Header option or template field.
    • <%body%> - Inserts the content of the Item Labels Body and Item Labels Body Last options or template fields. The content of Item Labels body is inserted for each label associated with the item except the the last label. For the last label is the content of Item Labels Body Last inserted. If there are no labels associated with the item, will nothing be inserted.
    • <%none%> - Inserts the content of the Item Labels None option or template field if no labels are associated with the item.
    • <%footer%> - Inserts the content of the Item Labels Footer option or template field.
  • Item Labels Header - The following variables are available: <%contexturl%> (URL to index or archive with an empty label filter).
  • Item Labels Body - The following variables are available: <%contexturl%> (URL to index or archive with the label added to the label filter) and <%labelname%>.
  • Item Labels Body Last - The following variables are available: <%contexturl%> (URL to index or archive with the label added to the label filter) and <%labelname%>.
  • Item Labels None - The following variables are available: <%contexturl%> (URL to index or archive with an empty label filter).
  • Item Labels Footer - The following variables are available: <%contexturl%> (URL to index or archive with an empty label filter).
  • Current Labels - Template for how to put together the label list generated by the <%LMLabels()%> skin variable with the CurrentLabels function. This variable is meant to be used in index, archive list and archive skins to show and manipulate the labels in the current label filter. The Current Labels template is build up by the following variables:
    • <%header%> - Inserts the content of the Current Labels Header option or template field.
    • <%body%> - Inserts the content of the Current Labels Body and Current Labels Body Last options or template fields. The content of Current Labels body is inserted for each label in the current label filter except the the last label. For the last label is the content of Current Labels Body Last inserted. If there are no labels in the current label filter, will nothing be inserted.
    • <%clear%> - Inserts the content of the Current Labels Clear option or template field if one or more labels is in the current label filter.
    • <%none%> - Inserts the content of the Current Labels None option or template field if no labels are in the current label filter.
    • <%footer%> - Inserts the content of the Current Labels Footer option or template field.
  • Current Labels Header - The following variables are available: <%contexturl%> (URL to index, archive list or archive with an empty label filter).
  • Current Labels Body - The following variables are available: <%contexturl%> (URL to index, archive list or archive with the label removed from the label filter) and <%labelname%>.
  • Current Labels Body Last - The following variables are available: <%contexturl%> (URL to index, archive list or archive with the label removed from the label filter) and <%labelname%>.
  • Current Labels Clear - The following variables are available: <%contexturl%> (URL to index, archive list or archive with an empty label filter).
  • Current Labels None - The following variables are available: <%contexturl%> (URL to index, archive list or archive with an empty label filter).
  • Current Labels Footer - The following variables are available: <%contexturl%> (URL to index, archive list or archive with an empty label filter).
  • Cloud Labels - Template for how to put together the label list generated by the <%LMLabels()%> skin variable with the CloudLabels function. This variable is meant to be used in index, archive list and archive skins to show a label cloud which includes the labels in the available items. The label cloud can be used to manipulate the labels in the current label filter. The Cloud Labels template is build up by the following variables:
    • <%header%> - Inserts the content of the Cloud Labels Header option or template field.
    • <%body%> - Inserts the content of the Cloud Labels Body and Cloud Labels Body Last options or template fields. The content of Cloud Labels body is inserted for each label in the cloud except the the last label. For the last label is the content of Cloud Labels Body Last inserted. If there are no labels in the label cloud, will nothing be inserted.
    • <%none%> - Inserts the content of the Cloud Labels None option or template field if no labels are in the label cloud.
    • <%footer%> - Inserts the content of the Cloud Labels Footer option or template field.
  • Cloud Labels Header - The following variables are available: <%contexturl%> (URL to index, archive list or archive with an empty label filter).
  • Cloud Labels Body - The following variables are available: <%contexturl%> (URL to index, archive list or archive with the label added to the label filter), <%labelname%>, <%count%> (The number of available items where the label is used) and <%size%> (Size to be used on label in the cloud: small, medium, large and xlarge).
  • Cloud Labels Body Last - The following variables are available: <%contexturl%> (URL to index, archive list or archive with the label added to the label filter), <%labelname%>, <%count%> (The number of available items where the label is used) and <%size%> (Size to be used on label in the cloud: small, medium, large and xlarge).
  • Cloud Labels None - The following variables are available: <%contexturl%> (URL to index, archive list or archive with an empty label filter).
  • Cloud Labels Footer - The following variables are available: <%contexturl%> (URL to index, archive list or archive with an empty label filter).

The NP_LMLabels plugin has the following options on the blog level. The default value for the blog options is to use the value of the globally defined options. See the global options description for a description of the options values. Available blog options are:

  • Include marked labels in URLs for items? - Choose if any marked labels should be included in item URLs.

The NP_LMLabels plugin has fields that can be set in Nucleus templates. These fields can be used to override the value of the plugin option with the same names. The purpose of the plugin template fields is to be able do differentiate the layout by the different NP_LMLabels plugin variables on a Nucleus site by specifying a Nucleus template as a parameter to the plugin variable. The default value for the template fields (when empty) is to use the value of the corresponding plugin option. If you want to force a template field to produce a empty string add the value #empty# to the Nucleus template field.

Usage

Labels for an item are registered on the Add Item page, and can be updated on the Edit Item page. The field for the labels is in the Extra Plugin Options section.

The labels for an item are registered as a comma separated list. Label names can have spaces, but any spaces are trimmed from the begining and end of a label. If labels are prepended with a *, will the label be marked for inclusion in generated item URLs. For any inclusion to be performed must inclusion also be turned on in plugin or blog options. The * is not included in the label. If you need a label to start with a *, prepend the label with a '.

If you want to change the name of a label, is it best to use the NP_LMLabels plugin admin page. When you use the NP_LMLabels plugin admin page to change a label name, will you change the label name for all items that the label is associated with.

You can also use the NP_LMURLParts plugin admin page to edit the label URL part keywords that NP_LMFancierURL should use. See the NP_LMURLPart plugin help page for more information on using the NP_LMURLParts plugin admin page.

To be able to display labels in your blog you need to use the skin and template variable for this plugin. The first parameter for the skin and template variable is always the function to perform. For some of the functions is it defined dynamic parameters. Dynamic parameters are given like parametername=parametervalue. If more than one dynamic parameter are used, must they be comma separated. The available functions are listed in the following sections.

ItemLabels

Inserts the labels associated with an item. Is used in the item part of an Nuclues template. Uses the template defined in the Item Labels plugin option or Nucleus template field.

<%LMLabels(ItemLabels, template)%>

The parameters are:

  • template - Name of the template to use (can be blank).

CurrentLabels

Inserts the labels in the current label filter. Is used in index, archive list and archive pages. Uses the template defined in the Current Labels plugin option or Nucleus template field.

<%LMLabels(CurrentLabels, template)%>

The parameters are:

  • template - Name of the template to use (can be blank).

CloudLabels

Inserts a label cloud. Is used in index, archive list and archive pages. Uses the template defined in the Cloud Labels plugin option or Nucleus template field.

<%LMLabels(CloudLabels, template, dynamic parameters)%>

The parameters are:

  • template - Name of the template to use (can be blank).
  • mediumpercent - The limit in percent of the available labels to start using the medium label size, default value: 50 (optional, dynamic).
  • largepercent - The limit in percent of the available labels to start using the large label size, default value: 80 (optional, dynamic).
  • xlargepercent - The limit in percent of the available labels to start using the xlarge label size, default value: 95 (optional, dynamic).

When the plugin assigns size to a label is the labels sorted by usage count. The labels with the lowest usage count gets the small size, and up to the labels whith the highest usage count get the xlarge size. How many labels that get each size is determined by the mediumpercent, largepercent and xlargepercent parameters. When there are few labels in the label cloud, may some of the sizes not be used.

Example use:

<%LMLabels(CloudLabels, lm/index)%>
<%LMLabels(CloudLabels, lm/index, mediumpercent=55, largepercent=75, xlargepercent=90)%>
<%LMLabels(CloudLabels, lm/index, xlargepercent=87)%>

Example CSS to set the size of labelnames in a label cloud when using the default values for the Cloud Labels Body and Cloud Labels Body Last options.

.lmlabelscloudsmall {
	font-size: 10px;
}

.lmlabelscloudmedium {
	font-size: 11px;
}

.lmlabelscloudlarge {
	font-size: 12px;
}

.lmlabelscloudxlarge {
	font-size: 14px;
	font-weight: bold;
}

MetaNoIndex

Inserts a noindex meta tag on index, archive list and archive page if the items on the page is filtered by a label filter or a choosen category. Will also set the noindex meta tag on search results pages. The skinvar must be used in the head part of the page.

<%LMLabels(MetaNoIndex)%>

There are no parameters for this function.

The text inserted is:

<meta name="robots" content="noindex" />

The purpose of the MetaNoIndex skinvar function is to avoid that search engines indexes pages that contain filtered content. You don't need to get filtered pages indexed, because all the content is available from the unfiltered pages. You may also add the rel="nofollow" attribute to all URLs that points to filtered content.

NP_LMReplacementVars

The replacement skin variables in the NP_LMReplacementVars plugin must be used by your blog if you want the current label filter to function. This includes all replacement skinvars for archive, archiveList, archivedaylist, archiveyearlist, blog and categorylist. See the documentation for the NP_LMReplacementVars plugin for further information on how to use the replacement skinvars.

The NP_LMLabels plugin recognize the following dynamic parameter used by the NP_LMReplacementVars replacement for the archive, archivelist, archivedaylist, archiveyearlist and blog skin variables:

  • lmlabelsfilter - When set to disable will the current label filter be disabled for this skin variable.

Support and Bug reports

For additional support and/or bug reports please use the Nucleus forum plugin announce thread or the plugin page comment section.

Compability

This version of the NP_LMLabels is tested against version 3.64 of Nucleus CMS. The minimum version of Nucleus CMS needed for using this plugin is 3.50, the minimum version of the NP_LMURLParts plugin needed by this plugin is version 1.1.1 and the minimum version of the NP_LMReplacementVars plugin needed by this plugin is version 1.0.0. If the NP_LMFancierURL plugin is installed is the minimum version of the NP_LMFancierURL plugin needed by this plugin version 3.0.0.

Version History

  • v1.0.0 2013-01-27: by Leo (http://www.slightlysome.net)
    • Initial release.
  • v1.0.1 2013-05-20: by Leo (http://www.slightlysome.net)
    • Changes for PHP 5.4.

Download

Download NP_LMLabels v1.0.1. The latest version of the NP_LMLabels plugin can be downloaded from the NP_LMLabels plugin page.

The latest version of the NP_LMReplacementVars plugin can be downloaded from the NP_LMReplacementVars plugin page.

The latest version of the NP_LMURLParts plugin can be downloaded from the NP_LMURLParts plugin page.


Comments

  • Posted by Lord Matt on 17/09-14 18:00.

    Is it possible to use Labels with LMFancierURL to get templates such as
    example.com/%label%/%cat%/%title%.html

  • Posted by Leo on 17/09-14 23:51.

    Lord Matt: Is it possible to use Labels with LMFancierURL to get templates such as
    Labels can not be used in freeform item URL part templates.

    If you use standard item urls with LMFancierURL you can add labels to the generated item url. This is done by listing the labels you want to include with a * infront of them in the item edit form. See the usage section in the plugin documentation above for more information on this.

Add Comment

Spam and off topic comments will be deleted.

Allowed BBCode:[b] [i] [u] [s] [color=] [size=] [quote] [code] [email] [url]