Plugin: LMReplacementVars

Alternative implementations of some key Nucleus core skin and template variables for better plugin support.

General plugin info
Author:Leo
Current version:1.1.0
Download:NP_LMReplacementVars_v110.zip
Support: Plugin comments or forum thread
Compability:Nucleus CMS 3.60

Plugin overview

The NP_LMReplacementVars plugin is a plugin that gives alternative implementations of some key Nucleus core skin and template variables. These implementations increase the available events for other plugins to facilitate, and makes it possible for plugins to refine the behaviour of these skin and template variables without duplicating the core functionality in each plugin. It is also possible for more than one plugin to refine the behaviour of a skin and template variable without the plugins to know of each other.

This plugin was made because I need the functionality from the added events in some of my plugins. The hope is that events like these will be implemented in the Nucleus core some time in the future, and make this plugin obsolete.

Installation

  • Upload the NP_LMReplacementVars.php file and the lmreplacementvars 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.
  • Go to the Plugins page in the admin area and press the "Update subscription list" button.
  • If a plugin data upgrade is needed, will an upgrade plugin data option be available on the NP_LMReplacementVars 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_LMReplacementVars 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_LMReplacementVars plugin has no configration options.

Usage

Parameter handling in this plugin's implementation of the skin variables is somewhat different from the original skin and template variables. Some parameters are dynamic, and must be passed as parametername=value in the parameter list for the skin and template variable call. The order of dynamic parameters are insignificant. Dynamic parameters are labeled in the parameter lists for each skin and template variable.

Core skin variables and template variables that have alternative implementations in this plugin are listed in the following sections.

Archive (skin variable)

Inserts the archive for the selected year, month or day for the currently selected blog, using a given template. To use the alternative versions of these skin variable use the following:

<%LMReplacementVars(Archive, template, dynamic parameters)%> 

The parameters are as for the core skin variable:

  • template: Name of the template to use (required).
  • category: Name of the category to show (optional, dynamic).

Example use of the plugin skin variable with parameters:

<%LMReplacementVars(Archive,lm/index)%>
<%LMReplacementVars(Archive,lm/index,category=somename)%>

New and changed events this skin variable triggers:

  • LMReplacementVars_ArchiveExtraQuery: New event. Subscribing plugins can add SQL to be AND'ed to the WHERE part of the SQL statement used to select items. Parameters in $data:
    • blog - Blog object
    • skinvarparm - Associated array with dynamic skin variable parameters (parametername => value).
    • extraquery - Associated array with extra SQL (pluginname => sql). Add the extra SQL required by your plugin to this array.
      Example: $data['extraquery']['yourpluginnname'] = 'i.inumber=4';
  • LMReplacementVars_ArchiveOrderQuery: New event. Subscribing plugins can set the order items should be listed. Parameters in $data:
    • blog - Blog object
    • skinvarparm - Associated array with dynamic skin variable parameters (parametername => value).
    • orderquery - Column and direction that items are to be ordered by on archive pages. Available columns are TITLE and TIME. Avaiable directions are ASC (ascending) and DESC (descending). Plugins can only set this value if it's not already set by another plugin. If more than 1 plugin want to set this value, the plugin higher in the plugin list will get preference.
      Example: $data['orderquery'] = 'TITLE ASC';
  • PreBlogContent: Added parameters in $data:
    • templatename - Name of template.
    • extraquery - Associated array of extra SQL (pluginname => sql) returned by the LMReplacementVars_ArchiveExtraQuery event.
    • skinvarparm - Associated array of dynamic skin variable parameters (parametername => value).
    • orderquery - String with SQL to be added to ORDER BY returned by the LMReplacementVars_ArchiveOrderQuery event.
  • PostBlogContent: Added parameters in $data:
    • templatename - Name of template.
    • extraquery - Associated array of extra SQL (pluginname => sql) returned by the LMReplacementVars_ArchiveExtraQuery event.
    • skinvarparm - Associated array of dynamic skin variable parameters (parametername => value).
    • orderquery - String with SQL to be added to ORDER BY returned by the LMReplacementVars_ArchiveOrderQuery event.

Archivelist, archivedaylist and archiveyearlist (skin variable)

Inserts the list of available archives for the currently selected blog, using a given template. To use the alternative versions of these skin variable use the following:

<%LMReplacementVars(ArchiveList, template, dynamic parameters)%> 
<%LMReplacementVars(ArchiveDayList, template, dynamic parameters)%>
<%LMReplacementVars(ArchiveYearList, template, dynamic parameters)%>

The parameters are as for the core skin variable:

  • template: Name of the template to use (required).
  • category: Name of the category to show (optional, dynamic).
  • limit: Limits the amount of links shown (optional, dynamic).

Example use of the plugin skin variable with parameters:

<%LMReplacementVars(ArchiveList,lm/index)%>
<%LMReplacementVars(ArchiveDayList,lm/index,category=somename,limit=10)%>
<%LMReplacementVars(ArchiveYearList,lm/index,limit=5)%>

New and changed events these skin variable triggers:

  • LMReplacementVars_ArchListExtraQuery: New event. Subscribing plugins can add SQL to be AND'ed to the WHERE part of the SQL statement used to select items. Parameters in $data:
    • blog - Blog object
    • skinvarparm - Associated array with dynamic skin variable parameters (parametername => value).
    • extraquery - Associated array with extra SQL (pluginname => sql). Add the extra SQL required by your plugin to this array.
      Example: $data['extraquery']['yourpluginnname'] = 'i.inumber=4';
  • LMReplacementVars_ArchListItemLinkPar: New event. Subscribing plugins can add parameters to the archive links generated by the skin variable. Parameters in $data:
    • listitem - Associated array with information on the archive list item to be rendered. The array hs the following keys:
      • blogid - Id for the blog that the arcive list item is for.
      • day - Day number in month the arcive list item is for.
      • month - Month number the arcive list item is for.
      • year - Year the arcive list item is for.
      • linkparams - Associated array with archive link parameters. Add the extra archive link parameters required by your plugin to this array.
        Example: $data['listitem']['linkparams']['parametername'] = $value;
  • PreBlogContent: Added parameters in $data:
    • templatename - Name of template.
    • extraquery - Associated array of extra SQL (pluginname => sql) returned by the LMReplacementVars_ArchListExtraQuery event.
    • limit - Limit parameter from the skin variable call.
    • skinvarparm - Associated array of dynamic skin variable parameters (parametername => value).
  • PostBlogContent: Added parameters in $data:
    • templatename - Name of template.
    • extraquery - Associated array of extra SQL (pluginname => sql) returned by the LMReplacementVars_ArchListExtraQuery event.
    • limit - Limit parameter from the skin variable call.
    • skinvarparm - Associated array of dynamic skin variable parameters (parametername => value).

Blog (skin variable)

Inserts the most recently added items of the currently active blog, using a given template. To use the alternative versions of this skin variable use the following:

<%LMReplacementVars(Blog, template, dynamic parameters)%> 

The parameters are as for the core skin variable:

  • template: Name of the template to use (required).
  • amount: The amount of items to show (optional, dynamic). Can specify an offset to start at by adding a number in parenthesis after the amount of items to show.
  • category: Name of the category to show (optional, dynamic).

Example use of the plugin skin variable with parameters:

<%LMReplacementVars(Blog,lm/index)%>
<%LMReplacementVars(Blog,lm/index,category=somename,amount=10)%>
<%LMReplacementVars(Blog,lm/index,amount=10(5))%>

New and changed events this skin variable triggers:

  • LMReplacementVars_BlogExtraQuery: New event. Subscribing plugins can add SQL to be AND'ed to the WHERE part of the SQL statement used to select items. Parameters in $data:
    • blog - Blog object
    • skinvarparm - Associated array with dynamic skin variable parameters (parametername => value).
    • extraquery - Associated array with extra SQL (pluginname => sql). Add the extra SQL required by your plugin to this array.
      Example: $data['extraquery']['yourpluginnname'] = 'i.inumber=4';
  • LMReplacementVars_BlogOrderQuery: New event. Subscribing plugins can set the order items should be listed. Parameters in $data:
    • blog - Blog object
    • skinvarparm - Associated array with dynamic skin variable parameters (parametername => value).
    • orderquery - Column and direction that items are to be ordered by on index pages. Available columns are TITLE and TIME. Avaiable directions are ASC (ascending) and DESC (descending). Plugins can only set this value if it's not already set by another plugin. If more than 1 plugin want to set this value, the plugin higher in the plugin list will get preference.
      Example: $data['orderquery'] = 'TITLE ASC';
  • PreBlogContent: Added parameters in $data:
    • templatename - Name of template.
    • extraquery - Associated array of extra SQL (pluginname => sql) returned by the LMReplacementVars_BlogExtraQuery event.
    • limit - Limit part of the amount parameter from the skin variable call.
    • offset - Offset part of the amount parameter from the skin variable call.
    • startpos - Start position where the skin variable will start showing items. This value can be changed by subscribing plugins.
    • skinvarparm - Associated array of dynamic skin variable parameters (parametername => value).
    • orderquery - String with SQL to be added to ORDER BY returned by the LMReplacementVars_BlogOrderQuery event.
  • PostBlogContent: Added parameters in $data:
    • templatename - Name of template.
    • extraquery - Associated array of extra SQL (pluginname => sql) returned by the LMReplacementVars_BlogExtraQuery event.
    • limit - Limit part of the amount parameter from the skin variable call.
    • offset - Offset part of the amount parameter from the skin variable call.
    • startpos - Start position where the skin variable will start showing items.
    • skinvarparm - Associated array of dynamic skin variable parameters (parametername => value).
    • orderquery - String with SQL to be added to ORDER BY returned by the LMReplacementVars_BlogOrderQuery event.

Categorylist (skin variable)

Inserts a list of categories for a blog. To use the alternative version of the skin variable use the following:

<%LMReplacementVars(CategoryList, template, dynamic parameters)%> 

The parameters are as for the core skin variable:

  • template: Name of the template to use (required).
  • blogname: short name of the blog to use (optional, dynamic).

Example use of the plugin skin variable with parameters:

<%LMReplacementVars(CategoryList,lm/index)%>
<%LMReplacementVars(CategoryList,lm/index,blogname=somename)%>

New and changed events this skin variable triggers:

  • LMReplacementVars_CatListItemLinkPar: New event. Subscribing plugins can add parameters to the category links generated by the skin variable. Parameters in $data:
    • listitem - Associated array with information on the category list item to be rendered. The array has the following keys:
      • blogid - Id for the blog that the category list item is for.
      • catid - Category id the category list item is for. Is 0 for header and footer.
      • catiscurrent - Is the category list item for for the current category.
      • currentcat - Same as catiscurrent.
      • linkparams - Associated array with category link parameters. Add the extra category link parameters required by your plugin to this array.
        Example: $data['listitem']['linkparams']['parametername'] = $value;

Comments (skin variable)

Shows the comments for the currently selected item using a given template. To use the alternative version of the skin variable use the following:

<%LMReplacementVars(Comments, template, dynamic parameters)%> 

The parameters are as for the core skin variable:

  • template: Name of the template to use (required).

Example use of the plugin skin variable with parameters:

<%LMReplacementVars(Comments,lm/index)%>

New and changed events this skin variables triggers:

  • LMReplacementVars_CommentsExtraQuery: New event. Subscribing plugins can add to the SQL statement used to select comments. Parameters in $data:
    • blog - Blog object
    • item - Item object
    • skinvarparm - Associated array with dynamic skin variable parameters (parametername => value).
    • extraquery - Associated array with SQL to add the the SQL statement used to select comments. The array has the following keys:
      • select - Associated array (pluginname => sql). Add the columns your plugin needs to be included in the SELECT part of the statement to this array.
        Example: $data['extraquery']['select']['yourpluginname'] = 'somecolumn, someothercolumn';
      • from - Associated array (pluginname => sql). Add the tables your plugin needs to be included in the FROM part of the statement to this array.
        Example: $data['extraquery']['from']['yourpluginname'] = 'sometable as somealias';
      • where - Associated array (pluginname => sql). Add the conditions your plugin needs to be AND'ed to the WHERE part of the statement to this array.
        Example: $data['extraquery']['where']['yourpluginname'] = 'somealias.somecolumn IN ("X", "Y")';
      • orderby - Associated array (pluginname => sql). Add the sort order your plugin needs to be included in the ORDER BY part of the statement to this array. If no plugins add elements to this array will the default sort order (c.ctime ASC) be used for comments.
        Example: $data['extraquery']['orderby']['yourpluginname'] = 'somealias.somecolumn ASC';

Comments (template variable)

Shows the comments for the currently selected item inside a template. To use the alternative version of the template variable use the following:

<%LMReplacementVars(Comments, dynamic parameters)%> 

The parameters are as for the core template variable:

  • maxtoshow: Amount of comments to show (when set, this overrides the max. comments blogsetting) (optional, dynamic).

Example use of the plugin template variable with parameters:

<%LMReplacementVars(Comments,maxtoshow=0)%>

This template variable uses the same new events as the Comments skin variable.

CommentForm (skin variable)

Shows the comment form on an item page. To use the alternative version of the skin variable use the following:

<%LMReplacementVars(CommentForm, template, dynamic parameters)%> 

The parameters are as for the core skin variable:

  • destinationurl: Sets the URL to where Nucleus needs to redirect after adding the comment (default is to redirect to the comment on the item page) (optional, dynamic).

If no destination URL is given as parameter is the user redirected to the comment after a comment is added. For this redirection to work must a id attribute identifing the comment be added to the first HTML element for each comment shown. A comment is identified by the word comment followed by the comment id. In the comment template can the id attribute be generated by the following code:

id="comment<%commentid%>"

Example use of the plugin skin variable with parameters:

<%LMReplacementVars(CommentForm,lm/index,destinationurl=http://host/thanks.html)%>

New and changed events this skin variables triggers:

  • LMReplacementVars_PreForm: New event. This event is triggered before a comment form is shown. Parameters in $data:
    • type - The type of commentform.
    • formdata - Associated array with formdata. The formdata is used by the <%formdata(key)%> formvar. The contents of the array can be altered. The array has the following keys:
      • destinationurl - Destination URL.
      • actionurl - Action URL.
      • itemid - Item id.
      • user - User name.
      • userid - User id.
      • email - Email.
      • body - Body of comment.
      • membername - Member name.
      • rememberchecked - Remeber checkmark
      • ticket - Ticket.
    • contents - Alternate content for the form that can be supplied by a subscribing plugin. Only update the contents if it's empty.
    • retry - True if this is a retry after a failure to add a comment.
    • commentid - Comment id if the form is shown in a comment. See CommentForm template variable.
    • templatename - Name of template in use.

CommentForm (template variable)

Shows the comment form on an item page inside a comment. The commentform can only be shown once for each item. This template variable is used in all comments for an item, but plugins subscribing to the LMReplacementVars_CommentFormInComment event decides if a comment form is to be shown for a comment. To use the alternative version of the skin variable use the following:

<%LMReplacementVars(CommentForm, template, dynamic parameters)%> 

The parameters are as for the core skin variable:

  • destinationurl: Sets the URL to where Nucleus needs to redirect after adding the comment (default is to redirect to the comment on the item page) (optional, dynamic).

Example use of the plugin skin variable with parameters:

<%LMReplacementVars(CommentForm,lm/index,destinationurl=http://host/thanks.html)%>

New and changed events this skin variables triggers:

  • LMReplacementVars_PreForm: New event. See CommentForm skin variable for a description of this event.
  • LMReplacementVars_CommentFormInComment: New event. Ask plugins if the CommentForm should be shown for a comment. Parameters in $data:
    • item - Associated array with the attributes of the item to show comment form for.
    • comment - Associated array with the attributes of the comment to show.
    • continue - Set to TRUE if the comment form be shown for this comment.

Item (skin variable)

Shows the currently selected item using a given template. To use the alternative version of the skin variable use the following:

<%LMReplacementVars(Item, template)%> 

Example use of the plugin skin variable with parameters:

<%LMReplacementVars(Item,lm/index)%>

New and changed events this skin variables triggers:

  • PreBlogContent: Added parameters in $data:
    • templatename - Name of template.
    • skinvarparm - Associated array of dynamic skin variable parameters (parametername => value).
    • itemid - Id for the item to be shown.
  • PostBlogContent: Added parameters in $data:
    • templatename - Name of template.
    • skinvarparm - Associated array of dynamic skin variable parameters (parametername => value).
    • itemid - Id for the item that has been.

Previtem, Previtemtitle, Prevlink, Nextitem, Nextitemtitle and Nextlink (skin variable)

These are skin variables for making next item and previous item linking on item pages. This plugin has not any new skin variables for these skin variables, as the behaviour of the old ones can ble modified without making a new implementation of the skin variables.

New events that are triggered to configure how the system should use these skin variables:

  • LMReplacementVars_PreNextExtraQuery: New event. Subscribing plugins can add SQL to be AND'ed to the WHERE part of the SQL statement used to select items for the previous item and next item skin variables on item pages. Parameters in $data:
    • blog - Blog object
    • extraquery - Associated array with extra SQL (pluginname => sql). Add the extra SQL required by your plugin to this array.
      Example: $data['extraquery']['yourpluginnname'] = 'i.inumber=4';
  • LMReplacementVars_PreNextOrderQuery: New event. Subscribing plugins can set the order items should listed for the next item and previous item linking on item pages. Parameters in $data:
    • blog - Blog object
    • orderquery - Column and direction that items are to be ordered by. Available columns are TITLE and TIME. Avaiable directions are ASC (ascending) and DESC (descending). Plugins can only set this value if it's not already set by another plugin. If more than 1 plugin want to set this value, the plugin higher in the plugin list will get preference.
      Example: $data['orderquery'] = 'TITLE ASC';

Events not related to skin variables or template variables

  • LMReplacementVars_EditCommentFormExtras: New event. Triggered when a comment is edited in the admin area. Here plugins can add their comment custom fields. Parameters in $data:
    • comment - Associated array with comment data

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_LMReplacementVars is tested against version 3.66 of LMNucleus CMS. The minimum version of Nucleus CMS needed for using this plugin is 3.60.

Version History

  • v1.0.0 2013-01-27: by Leo (http://nucleus.slightlysome.net/leo)
    • Initial release.
  • v1.0.1 2013-05-20: by Leo (http://nucleus.slightlysome.net/leo)
    • Changes for PHP 5.4.
  • v1.1.0 2014-04-13: by Leo (http://nucleus.slightlysome.net/leo)
    • Replacement for Comments skin and template variable.
    • Replacement for CommentForm skin variable.
    • Replacement for Item skin variable.
    • New events:
      • LMReplacementVars_CommentsExtraQuery
      • LMReplacementVars_PreForm
      • LMReplacementVars_CommentFormInComment
      • LMReplacementVars_EditCommentFormExtras.

Download

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


Add Comment

Spam and off topic comments will be deleted.

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