Add category dropdowns to Txp

n: smd_browse_by | v: 0.11 | f: /

Documentation for the Textpattern plugin smd_browse_by by Stef Dawson follows this short message from our sponsor ;-)

Plugin list button Plugin download button Compressed plugin download button

smd_browse_by

Browse your articles/images/files/links via a quick dropdown menu of category (or in the case of articles: section as well). Just install, activate, done.

Author / credits

Written by Stef Dawson. Original plugin by Steve Lam.

Installation / uninstallation

Requires TXP 4.4.1+

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.

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

Visit the forum thread for more info or to report on the success or otherwise of the plugin.

Configuration

The plugin can be controlled with a few hidden preference values (the smd_prefalizer plugin can help here). Any prefs you create should have the following items set, in addition to the preference-specific name and value given later:

  • Visibility: Hidden
  • Event: smd_browse
  • User: your login name if you wish the preference to only apply to your login, or leave it empty to apply it for all users

The preferences are:

Browse using

By default you can browse by category on all main content types and additionally by section with articles. If you wish to only offer browsing on certain tabs, set this preference. Comma-separate any of the following values to build the interface to your choosing:

  • Name: smd_browse_by
  • Value:
    • empty : none (!) : remove all browsable lists added by the plugin
    • SMD_ALL : browse on every tab — this has the same effect as completely removing the preference value
    • article: browse by category and section lists on the Articles tab
    • article_cat: browse by category on the Articles tab
    • article_sec: browse by section on the Articles tab
    • image: browse by category on the Images tab
    • file: browse by category on the Files tab
    • link: browse by category on the Links tab

Go button

By default the select lists submit automatically when the entry is changed. If you wish to add a ‘Go’ button next to the lists, set this preference:

  • Name: smd_browse_by_go_button
  • Value:
    • 0 (auto-submit)
    • 1 (Go button)

API

If you wish to alter the output of any of the lists that appear on the screen you may do so by registering a callback to be notified when one or all of the select lists are displayed. Here are the relevant events and steps you can use:

  • Event: smd_browse_by_ui
  • Step: call your plugin at the following times:
    • empty : all select lists
    • article_cat: when the Article category list is displayed
    • article_sec: when the Article section list is displayed
    • image: when the Image category list is displayed
    • file: when the File category list is displayed
    • link: when the Link category list is displayed

An example:

if (@txpinterface == 'admin') {
   register_callback('my_custom_browser', 'smd_browse_by_ui', 'image');
}

function my_custom_browser($evt, $stp, $data, $rs, $val) {
   // $evt is always 'smd_browse_by_ui'
   // $stp is the current step
   //    (article_cat, article_sec, image, file, or link)
   // $data holds the fully rendered default select list HTML
   //    so you can search/replace/manipulate it
   // $rs is the raw array containing the list of items
   //    so you can iterate over them
   // $val is the currently chosen value from the list
   // if you return anything from this function,
   //    that will be what is displayed in place of the
   //    default select list
}

Changelog

  • 31 Aug 2011 | 0.10 | Initial release
  • 04 Mar 2012 | 0.11 | Added hidden pref to control which dropdowns to use ; category tree now displayed (thanks pieman) ; pluggable_ui() implemented so other plugins can alter the lists (thanks tye) ; more consistent layout (thanks philwareham) ; sections ordered by title

Source code

If you’d rather wander aimlessly through thousands of lines of PHP source code, you’ll need to step into the view source page.

Legacy software

If, for some inexplicable reason, you need a prior version of a plugin, it can probably be found on the plugin archive page.

Experimental software

If you’re feeling brave, or fancy skateboarding into volcanos, you can test out some of my beta code. It can be found on the plugin beta page.