smd_featured

Pull one or more articles out of the regular article flow and pimp them — perhaps on a section landing page or your home page.

Features

• One-click selection of articles to feature
• Label your featured articles, allowing you to group them into areas like Featured, Teasers, etc
• Add an optional title/description to each article so you can use that as copy, instead of something from the article itself (supports Textile and some TXP tags)
• Search your featured articles by name or label; filtering in real-time if you wish
• Administrators can limit the articles available for pimpage from certain sections
• Display information from the featured articles using regular TXP article tags
• Keeps track of which articles have been seen already on the page so later featured (or unfeatured) articles aren’t duplicated

Installation / Uninstallation

Requires Textpattern 4.6.0+

Download the plugin from either textpattern.org, or the software page, paste the code into the TXP Admin -> Plugins pane, install and enable the plugin. Visit the forum thread for more info or to report on the success or otherwise of the plugin.

When you install the plugin, the necessary table is automatically installed for you. There’s currently no facility for removing it during plugin operation, but it will be deleted if the plugin is deleted from your system. Note that if you put the plugin in the cache dir and therefore don’t go though the normal installation procedure, the table is not installed automatically; visit the Content->Featured articles tab and click the Install table button.

To uninstall, simply delete the plugin from the Admin->Plugins page.

Unfortunately, when upgrading from v0.3x to v0.40, your Textile preferences will be lost. Please reset them by visiting the Featured articles tab with an administrator account and adjusting the prefs.

Configuring featured articles

Visit the Content->Featured articles tab. A list of all articles (from the admin-selected sections) are presented in a grid.

To feature an article

Click its name. It will be highlighted and (if permitted by the administrator) an [Edit] button appears beside it. If you choose not to edit the article information, it will be featured but unlabelled.

An arrow also appears in the lower right hand corner of the box. Click this to take you to the Write tab to view/edit the original article. The same link is available by clicking the article Title while editing an entry.

In the lower left corner of the box, a position input field appears. You can type anything in this box to specify a sort order for the featured item; as soon as the cursor leaves the box the value is saved. You are free to use whichever sort scheme works for you — numbers, alphanumerics, squiggles, anything. This does not alter the order of the items in the grid (use the Sort by value in the plugin’s control panel for that) but allows you to order the items as they appear on your site. You may leave this box empty if you wish. Note that sorting is performed on a per-label basis so you may reuse sort values under different labels.

Clicking [Edit] will display up to four input boxes, depending on the prefs:

• Label : allows you to label (group) the article with others of a similar featured status. For example, you could label some articles to go in a ‘teasers’ block on your home page by labelling each potential article with Teaser. Be careful: labels are case sensitive. To help, you may choose a label from the dropdown list of all currently defined labels or enter a new one.
• Title : allows you to store some Textile-aware title related to the article. This is different from the article’s actual Title and can be used for any purpose you see fit.
• Description : allows you to store some Textile-aware supporting information about the article. This could simply be additional information for your own use, or some copy that you may wish to display in your teasers block to entice people to read the article. It can be as simple or as complex as you like and can contain TXP tags (if they make sense to use at that point — article tags cannot be used, for example, but <txp:site_url /> can).
• Position : allows you to store some positioning text (up to 16 characters) that governs the order this item appears on your site. This is the same value as in the little box in the lower left corner of the article cell.

When you’re happy with your values, hit Save to store the entry. You can edit the information at any time by clicking the appropriate [Edit] button from the featured article list.

To unfeature an article

Click its name again. You may be offered a confirmation dialog box, in which case confirm that you are sure first. The article’s label, title and description are deleted, so be sure you really want to remove them, or have backed the information up somewhere.

Finding articles to feature

With large article lists it can become difficult to find the one you want. Above the grid is a control panel. Click it to reveal the plugin options. On the left is the Article search area and on the right are the plugin preferences. If you are in Display: All mode, simply start typing in the By name box and your article list will be reduced as you type to only those that match. Type multiple words to find articles that contain any of the given words. To quickly clear the box, hit the ESCape key.

Alternatively, you can use the select list to choose all articles with a particular label. The empty entry at the top of the list means “all articles”. If you have featured an article but don’t supply a label you can filter it by choosing the [unlabelled] item from the list. If you have labelled any articles, each label you have supplied will also be an option in the list. Remember that labels are case sensitive.

Note that filtering by name or by label are mutually exclusive actions: selecting something from the dropdown will clear the text box, and typing something in the text box will reset the dropdown.

Your search criteria are remembered between edit/list views so you won’t lose your place. If you are in Display: Paginated mode, the search works in exactly the same way but you have to hit Enter or click Go to submit the search criteria. This mode is handy for very long article lists or slow servers / computers.

Plugin preferences

Users of the Featured articles tab also have a few preferences at their disposal which can be altered at will:

1. Display : choose whether you wish to display all articles on one page (and use the live search to filter them) or choose a paginated view (and use the traditional search). The traditional search might be useful if you have a lot of articles (over 1000) because the live search might slow down significantly. Note that when you search for something in paginated mode, the results themselves aren’t paginated.
2. Sort by : define the sort order of the article list.
3. Box size : specify the width and height values in pixels of each cell in the grid. Default is 150x40.

Administrators can also alter the behaviour of the plugin by altering the following prefs:

1. Permit entry of: choose which featured elements users are permitted to enter/alter. If you disable all the checkboxes, the [Edit] links next to featured articles will not appear.
2. Apply textile to: choose the items to which you wish to apply Textile when you Edit and Save a featured article. Note this only affects featured articles saved from this point forward. Thus if you wish to apply a new Textile setting to existing articles you need to visit each one in turn by clicking [Edit] and then Save.
3. Articles from sections: define a comma-separated list of section names. These will be the only sections from which articles are allowed to be featured. If you leave this box empty you or your users may specify &section_list=list,of,sections,... in the smd_featured tab’s URL to limit the list to only articles in the given sections. This is handy if you wish to direct people to the smd_featured tab from a link in another tab.

In addition, if you create a hidden pref called smd_featured_privs you can limit the privilege levels of accounts that can access the Featured articles tab. Default: 1,2. If using smd_prefalizer to create this pref, set the name and value as above and set the following additional parameters:

• type : hidden
• event : smd_featured
• input control : text_input
• user : / empty /
• position: 0

Displaying featured articles

Once you have chosen your featured articles, you need a way to display them:

Tag: <txp:smd_featured />

Acts a bit like the standard <txp:article /> tag to display featured articles. Attributes:

• label : display featured articles with this label. Specify label="" to display unlabelled articles (which are not the same as unfeatured articles). If this attribute is omitted, all featured articles — irrespective of label — will be displayed.
• labeltag : the (X)HTML tag — without brackets — to apply to the label attribute. If this attribute is specified the label itself is displayed at the head of your featured article list. If you wish to display unlabelled articles you need to specify the unlabel attribute or you’ll see no label. Note that this tag differs from the TXP convention: you will only see the label if you specify the labeltag. You can display the label inside your articles using the <txp:featured_info /> tag.
• unlabel : when using label="" (to show unlabelled articles) this attribute specifies the label to use inside the labeltag. Default: “Featured”.
• time : limit the articles to those in the past, the future or any. Default: past.
• status : only display articles of the given status number(s). Default: 4,5 (a.k.a. live and sticky). Note that this attribute may be ignored if you are trying to view anything other live and sticky articles (since article_custom does the same).
• section : only display articles from the given section(s). If the section list is restricted using the plugin preferences, the sections used here must also be in that list.
• history : determines whether to remember previously seen articles and thus exclude them from future smd_featured / smd_unfeatured tags. If you are using the same featured tag multiple times on the same page and want it to always output the same list, set this attribute to 0. Default: 1.
• form : use this TXP form to display each article, instead of using the container contents.
• limit : maximum number of featured articles to display. Default: 10.
• sort : order the featured articles by id, label, Title, Posted, and so on. Add asc or desc to the attribute to alter the direction of the sort. You may also use rand() to sort the articles randomly. Default: feat_position asc, Posted desc. The same list available for the <txp:article /> tag is usable here. You may also use:
  • feat_position : your custom position
  • feat_title : your featured title content
  • description : your featured description content
• wraptag : the (X)HTML tag — without brackets — to wrap around the list of featured articles.
• break : the (X)HTML tag — without brackets — or text to put between each article.
• class : the CSS class name to apply to the wraptag.
• html_id : a DOM ID to apply to the wraptag.

You may use the tag as a container and any tags you specify will be displayed in each featured article. You can use standard article tags such as <txp:title />, <txp:excerpt />, <txp:permlink />, etc, although some articles are not displayable by Textpattern (e.g. hidden, pending and draft articles).

Note that you can’t use <txp:smd_featured> inside an article or an Article Form. Doing so will trigger a warning because it’s the same as putting another article tag inside an article. Use the tag only in Pages, or in a Form that is never directly used to display article content.

Each time you use <txp:smd_featured /> it makes a note of the articles it has displayed and will not duplicate articles in later tags. You can use <txp:else /> in your form / container to take action if the featured list is empty.

Tag: <txp:smd_featured_info />

Allows you to display the label or the description within your <txp:smd_featured /> form/container.

Has one attribute:

• item : the thing you want to display. Choose from:
  • label: the label.
  • title: the (possibly Textile-processed) title.
  • description: the (possibly Textile-processed) description.

Tag: <txp:smd_unfeatured />

Use this tag if you wish to show the ‘remaining’ articles — i.e. ones not already displayed by any preceding <txp:smd_featured /> tags. It acts very much like the built-in article_custom tag, and takes all the same attributes. Thus, by default, its context is “any articles from any section defined in the smd_featured plugin that have not been displayed already”. You can reduce this list by section, time or status.

Unlike article_custom, <txp:smd_unfeatured /> supports pagination and <txp:else /> (for when your unfeatured list returns nothing). You can also specify the history attribute and it works exactly the same way as it does for <txp:smd_featured />. Thus it can be a very useful, pageable direct replacement tag for article_custom if you use history="0".

Notes:

• to use pagination, remove any article tag and add the pageby attribute (and of course limit) to the smd_unfeatured tag. Note you may get a warning about no article tag on the page, but you can ignore it.
• if you wish the pageby attribute to track any limit you set, specify pageby="limit".
• if you have any other paging in effect on the page, unfeatured pagination will be ignored.

Tag: <txp:smd_if_featured>

This tag allows you to detect if the current (individual) article is featured and/or has a particular label. You may also use this outside an article context by supplying a list of article IDs.

Has two attributes:

• id : list of article IDs of which you wish to check the featured status. If omitted, defaults to the current article (if used inside a <txp:article /> container/form).
• label : list of labels to compare the given ID(s) with. Specify label="" to check for unlabelled articles, or use an empty item if specifying a list, e.g. label=", Featured, Teaser". Remember that labels are case sensitive.

If the article matches one of the given labels the contained content will be executed. If no label is given the article(s) will be checked if they are featured, irrespective of label.

Examples

Example 1: Complete directory of featured articles

<txp:smd_featured labeltag="h2" limit="20"
     wraptag="dl" sort="label">
   <txp:if_different>
      <h2><txp:smd_featured_info item="label" /></h2>
   </txp:if_different>
   <dt>
      <txp:permlink><txp:title /></txp:permlink>
   </dt>
   <dd>
      <txp:excerpt />
   </dd>
</txp:smd_featured>

Example 2: One featured article and six teasers on the home page

Select an article and label it feature. Select six others and label them teasers. Add some description text to your teaser articles.

In your default Page, put this:

<txp:smd_featured label="feature"
     wraptag="div" html_id="main_feature">
   <txp:permlink><txp:title /></txp:permlink>
   <txp:article_image class="feat_image" />
   <p class="leadin"><txp:excerpt /></p>
</txp:smd_featured>

<txp:smd_featured label="teasers"
     wraptag="ul" break="li" html_id="teaser_block">
   <txp:permlink><txp:title /></txp:permlink>
   <p class="leadin"><txp:excerpt /></p>
</txp:smd_featured>

If you wanted to have some other articles beneath those, but didn’t want any duplicates to appear you could use:

<txp:smd_unfeatured form="my_list" />

Example 3: Per-section landing page featured articles

If you had a zoo site with a section for primates, a section for mammals and a section for reptiles, when you set up your featured article list define their labels like this:

• Featured primates
• Featured mammals
• Featured reptiles

On your section landing page template you can then do this to display four articles from the relevant (current) section:

<h2>Look who's here:</h2>
<txp:smd_featured label='Featured <txp:section />'
     section='<txp:section />' limit="4"
     wraptag="div" html_id="feat_block">
   <div class="pimped_article">
      <txp:permlink><txp:title /></txp:permlink>
      <txp:smd_featured_info item="description" />
   </div>
</txp:smd_featured>

Example 4: Conditional check for featured-ness

If a site visitor has navigated away from your front page and is viewing an article, you may wish to highlight the fact the current article is a featured product. So, somewhere inside you article form add:

<txp:smd_if_featured>
   <p class="hilight">FEATURED PRODUCT</p>
</txp:smd_if_featured>

Or if you wanted to only highlight the article if it was a featured or on special offer:

<txp:smd_if_featured label="Featured, Special">
   <p class="hilight">As featured on the front page!</p>
</txp:smd_if_featured>

Author / Credits

Stef Dawson