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 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 articles by title or label; filtering in real-time
• Hidden pref allows pre-filtering by an administrator so only articles from certain sections are available for pimpage
• 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

Author / Credits

Stef Dawson

Installation / Uninstallation

Requires Textpattern 4.2.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 removed from your system.

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

Configuring featured articles

Visit the Content->Featured articles config 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 an [Edit] button appears beside it. If you choose not to edit the article information, it will be featured but unlabelled.

Clicking [Edit] will display two input boxes:

• 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
• 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)

When you’re happy with your categorisation and/or description text, hit Save to store it. You can edit the information at any time by clicking the appropriate [Edit] button from the article list.

To unfeature an article

Click its name again. When you confirm that you are sure, the article’s label 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. In the top-left is an Article live search. Click it to reveal the search criteria. 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 click to feature an article but don’t supply a label you can display 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.

Plugin configuration

You can alter the behaviour of the plugin by creating some hidden preferences (the smd_prefalizer plugin can help here). There are a few prefs you may define:

1. smd_featured_privs : a comma-separated list of priv level numbers that can access the Featured articles tab. Default: 1,2
2. smd_featured_box_size : takes a width x height value and specifies the size in pixels of each cell in the grid. Default is 150x40
3. smd_featured_section_list: define a comma-separated list of section names. These will be the only sections from which articles are allowed to be featured
4. smd_featured_sort : defines the sort order of the article list. Use any valid database column name followed by either asc or desc to choose the sort direction. For example, Title asc. Defaut is Posted desc

If using smd_prefalizer to create the prefs, set the name and value as above and then 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:

<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)
• 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
• form : use this TXP form to display each article, instead of using the container contents
• limit : maximum number of featured articles to display
• sort : order the featured articles by id, label, Title, Posted, and so on. The same list available for the <txp:article /> tag are usable here. Add asc or desc to the attribute to alter the direction of the sort. You may also use rand() to sort the articles randomly
• 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

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.

<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
  • description: the Textile-processed description

<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 tag — and takes all the same attributes — but its context is “any articles from any section defined in the smd_featured plugin that have not been displayed already”.

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 teaaser 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 seciton for primates, a section for mammals and a section for reptiles, when you set up your featured article list define their names 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>