smd_prefalizer

With the advent of per-user preferences, your prefs table could become rather large. Keep it under control with this plugin. Also useful if you have uninstalled plugins you no longer use that have left prefs behind.

Features

• Add, edit or remove TXP preferences set in your database
• Filter prefs by name / value / user / type to help find the ones you want
• Create regular or hidden prefs, for all or specific users
• Create, display or delete prefs from your public site

Installation / uninstallation

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.

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

Usage — admin side

Visit the Admin => Prefalizer page to see a list of all defined preferences in your Textpattern database.

Each row has actions in the last column that allow you to edit or delete any preference. Some (system) prefs cannot be deleted because that would potentially hurt your site; the plugin tries to limit you to only being able to delete per-user or plugin prefs, but you should still exercise caution.

The columns are as follows:

• Name : The name of the preference
• Value : The stored contents of the preference
• Visibility : Whether the preference appears on the Basic Prefs or Advanced Prefs subtab. If it does not appear anywhere at all, it is Hidden and is usually used by TXP or a plugin to keep track of things
• Event : The event (or admin-side tab) to which this pref is associated. Useful for grouping pref values together on-screen
• Input control : If the preference is rendered on-screen then this governs which UI widget is drawn or how the control will behave. Common entries in this column are:
  • text_input : (default) A standard text box
  • custom_set : A custom field
  • dateformats : Some kind of date formatting string
  • yesnoradio : A yes or no radio button set
• User : Login name to whom the preference belongs
• Position : When listing preferences on-screen, the position dictates their order. Lowest numbered values are displayed first. It is common practice to assign positions in increments of 10 or 20 so there is room to easily insert values later
• Actions : Actions to perform on each preference:
  • [Edit] : Edit the various details of the preference. Input controls appear inline for you to alter the values. When you are done, click Save
  • [Delete] : Permanently remove the preference value from your database. You will have a chance to confirm your intentions. Be careful!

Use the search feature to limit the list to the matched items. When searching by Visibility you can either use basic, advanced or hidden, or use their numeric counterparts 0, 1 or 2 respectively.

Click New pref to add a preference value to the database. A row of input controls will slide down allowing you to enter your desired values. Click Add to commit the new preference.

Notes

• If you try to edit a preference and rename it to that of an existing preference owned by someone else, the plugin will warn you and your edit will be reverted to its original state
• If you try to create a preference value that would clobber an existing setting, the plugin will warn you. If you click New pref again though, your most recently entered values will still be available. The name and user will be reset, however
• If you really, really, know what you are doing and want to delete a ‘protected’ pref setting (e.g. rvm_css_dir is one such entry) then simply add &expose=all to the URL. The delete button will become available for all pref settings. Be careful! As a precaution, when you change page or alter the search/sort criteria the plugin will revert to ‘safe’ mode and you will have to add &expose=all to the URL again to notify the plugin of your intentions

Usage — tags

<txp:smd_pref_set />

Set a preference value. Attributes:

• name : the name of the preference you wish to set. If it exists it will be updated, if it doesn’t exist it will be created. Note that you cannot create or update a preference with the same name as one of the system preferences — use the admin interface for that
• value : the value to assign to the named preference
• event¹ : a group to which you wish to assign your preference. It could be the event of an admin-side tab (e.g. ‘file’) or an entry of your own choosing. It is recommended you stay away from the name of existing events unless you know what you’re doing! You can leave this blank, but it’s advisable to set it to something
• visibility¹ : one of basic, advanced or hidden. Default: hidden. If you set it to basic or advanced, your preference value will appear on the relevant basic/advanced Preferences page
• input_ctrl¹ : the type of input control your preference requires. text_input is the default but you can set this to whatever makes sense for your app (e.g. TXP uses yesnoradio for yes/no radio choices)
• position¹ : the position (order) you want your pref to appear in. Takes an integer value and the prefs will be displayed in ascending order, grouped by event
• private¹ : by default this is 0 which means the preference is available to everyone. If you set this to 1 then the plugin will attempt to make a private (per-user) preference. If you’re not logged in it won’t have any effect and the preference will not be created

¹ Note that these attributes can only be set when the preference is created for the first time. Once the pref is made, these attributes will be ignored and you can only update the value of the pref.

The tag works with <txp:else /> so you can, for example, report the success or failure of the set operation.

<txp:smd_pref_get />

Retrieve one or more preference values. Attributes:

• name : a comma separated list of preference names to retrieve
• value : a list of preference values to extract. Useful if using one name to check if the preference is set to this particular value
• event : a list of preference events to retrieve
• visibility : one of either basic, advanced or hidden to retrieve that type of preference
• input_ctrl : filter by this list of input controls
• position : only show preferences that are set to appear at this list of positions in the table
• author : list of author (login) names from which you wish to retrieve (per-user) preferences. If you specify the special value SMD_PREF_LOGGED_IN then the current logged in user’s name (if available) will be considered. You can use this to your advantage to only display a user’s preferences when they’re logged in and visit the public site
• sort : order the returned prefs by these columns and sort directions. Default: name asc. Choose from:
  • name : pref name
  • val : pref value. NOTE: it’s val not value
  • event : pref event group
  • type : pref type (visibility)
  • html : input control
  • position : list position
  • user_name : pref owner’s login name
• form : use this form to display each preference value. If unset, the container will be used. If both are empty the plugin will display nothing. Note that if you use the tag as a self-closing tag, the value(s) will be displayed
• wraptag : the HTML tag (without <> brackets) in which to wrap the displayed list of preferences
• break : the HTML tag (without <> brackets) in which to wrap each preference
• class : the CSS class name to apply to the wraptag
• html_id : the HTML DOM node ID to apply to the wraptag

The tag works with <txp:else /> so you can, for example, detect if a preference exists or has a certain value and then update or create it if it doesn’t match.

Replacement variables

In your container or form you may use the following replacement variables to display the various values from each returned preference:

• {smd_pref_name} : the preference name
• {smd_pref_value} : the preference value
• {smd_pref_event} : the event to which the pref belongs
• {smd_pref_visibility} : the numeric preference flavour (0 = basic; 1=advanced; 2=hidden)
• {smd_pref_input_ctrl} : the html input control type assigned to the pref
• {smd_pref_position} : the order / position of the current pref
• {smd_pref_author} : the owner (author login name) of the preference. Will be empty for global prefs
• {smd_pref_total} : the total number of preference values that matched the criteria
• {smd_pref_index} : the current pref count value, counting from 0
• {smd_pref_counter} : the current pref count value, counting from 1

<txp:smd_pref_delete />

Remove one or more preference values. You may not remove a system preference using this tag: you can only do this if you use the admin interface and indicate that you know what you’re doing with the expose URL variable.

Tag attributes:

• name : a comma separated list of preference names to remove
• event : a list of preference events to remove
• author : remove prefs belonging to this list of author (login) names. If you specify the special value SMD_PREF_LOGGED_IN then the current logged in user’s name (if available) will be considered

The tag supports <txp:else /> so you can indicate the success or otherwise of the delete operation on each preference. Inside your container you can use any of the replacement variables as given for the <txp:smd_pref_get> tag. There is one additional replacement: {smd_pref_del_result} is a numeric value indicating the outcome of the delete, as follows:

• -1: disallowed (it’s a system pref)
• 0: failed (for some other reason)
• 1: successfully deleted

Examples

Example 1: list of preferences by event

<txp:smd_pref_get event="my_event"
     wraptag="ul" break="li">
   {smd_pref_value}
</txp:smd_pref_get>

Example 2: set pref if it doesn’t exist; display otherwise

<txp:smd_pref_get name="kermit">
  Current setting of {smd_pref_name} is {smd_pref_value}
<txp:else />
   <txp:smd_pref_set name="kermit" value="a frog"
     event="muppets" />
</txp:smd_pref_get>

Example 3: set per-user pref if logged in

<txp:smd_pref_set name="list_order"
     value="asc" event="control_sys" private="1" />

If the user is logged in, the list_order will be set. If they are not logged in, nothing will happen. This could be wrapped in a <txp:rvm_if_privileged> call. It could also be wrapepd in an smd_pref_get so it was created only if it didn’t exist.

Example 4: toggle per-user pref

<txp:smd_pref_get name="list_order"
     author="SMD_PREF_LOGGED_IN">
   <txp:variable name="the_order">{smd_pref_value}</txp:variable>
   <txp:if_variable name="the_order" value="asc">
      <txp:smd_pref_set name="list_order" value="desc" />
   <txp:else />
      <txp:smd_pref_set name="list_order" value="asc" />
   </txp:if_variable>
</txp:smd_pref_get>

If the user is logged in and the list_order is asc, swap it to desc, and vice-versa. If the user’s not logged in, nothing happens.

Author / credits

Written by Stef Dawson.

Changelog

• 06 Nov 2009 | 0.10 | Initial release
• 07 Nov 2009 | 0.11 | Added heading row above row being edited (thanks Uli)
• 13 Nov 2009 | 0.12 | Added expose URL override parameter
• 27 Jun 2010 | 0.20 | Added smd_pref_get, smd_pref_set and smd_pref_delete ; fixed pageby typo (thanks speeke) ; pref types > 2 now considered Hidden ; removed unused code
• 24 Sep 2013 | 0.30 | For Txp 4.5.x