smd_bio

Configure additional user biographical information to be collected when authors are created, then show that info as bylines against your articles. A bit like custom fields for user info.

Features

• Define only the info you require to be collected about your authors — totally customisable
• Info is collected/edited on the Admin->Users tab beneath the existing user info
• Choose from a variety of types of content: text, radio buttons, select lists, checkboxes, images…
• Output any pieces of the biographical info in your article flow using a single, flexible tag
• Image thumbnail preview/selection on the Admin->Users tab
• Optional CSS to modify the layout of the Admin->Users tab

Author / Credits

Stef Dawson. The plugin is a logical extension of pvc_users_info by Peter V. Cook (the smd_bio_articles tag is essentially the same as pvc_author_articles). Thanks also to pieman for setting the wheels in motion and net-carver for his inimitable knack of making things better.

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 first visit the Extension->Bio Config page, the extra tables wil be installed automatically.

To uninstall, simply delete from the Admin -> Plugins page. But note the extra tables will remain until you delete them manually. A planned feature is to add buttons to the interface to allow deletion of all additional bio information and/or removal of the underlying tables.

Configuring bio items

Visit the Extensions->Bio config tab. Add bio items such as cell/work/fax numbers, department, mugshot, postal address, job title, whatever you wish. Just add one at a time and hit Save in between. The items will be listed below the form, and can be sorted at will. Each item comprises:

• Name : an internal name with which you wish to refer to your bio item. Avoid characters such as spaces and ‘weird’ characters here
• Title : a human-friendly name for your bio item. This is displayed to the left of the input control on the Admin->Users panel, and as a label on your article pages
• Type : the type of data you wish to collect. This will be the variety of input control you see on the Admin->Users tab
• Size : the dimensions of the chosen input control. Takes one or two comma-separated values, the interpretation of which depends on the item Type:
  • for text-based input fields, the first is the width of the box (in characters) and the second is the maximum number of characters a user can type (0 = leave at default)
  • for textareas, it is the width and height of the box in characters, respectively
  • for images, the two values are the x and y dimensions of the image/thumbnail on the Admin->Users tab. If only one value is given, the image will be square. If either value is omitted, the image or thumbnail dimensions (as stored in the database) are used instead
  • for other types, the Size is currently unused
• Value : depends on the item Type:
  • for text-based items, this is the default value that will be in the text box. You can use this to initialise an entry, or offer instructions like “Type your job description here”
  • for list, radio and checkbox items, this is used to configure the available options. Either put one item per line or use a comma to separate each item. If you just list items, they will be used as labels exactly as you define them. When referring to them in <txp:smd_bio_info /> their names will be all lower case, have ‘non-web-safe’ characters removed, and will have spaces converted to underscores. If you wish to define your own names and labels, use the syntax: option_name1 => option_label1, option_name2 => option_label2, .... For example a Departments dropdown list might be defined as sales => Sales, mktg => Marketing, eng => Engineering, qual => Quality assurance, it => Tech support or Sales, Marketing, Engineering, Quality assurance, Tech support — in which case you would refer to your new items with these names, respectively: sales, marketing, engineering, quality_assurance, tech_support. In select lists, you may put an empty item at the top if you wish. In select lists and radio sets you may also mark one label with [*] to indicate it is the default
  • for images, it can be used to specify the parent category name under which the desired images are stored. If omitted, all images are available in the image select list
• Position : the order in which the items appear on the Admin->Users tab. The lower the number the higher up the screen it will be. The numbers do not have to be sequential — it is advised you set them with a gap between them (e.g. 10 or 20) so you can alter the order fairly easily

Note that the Date/time Type is functionally identical to a Text box. This may change in future.

Entering user data

Your configured items will appear on the Admin->Users tab beneath the usual crop of data input controls. Simply enter data in them and it will be saved along with the existing user data. Hit Edit and any configured info will be retrieved for editing.

When choosing an image, you can either type its ID in the box or use the dropdown select list to choose an image. The chosen image will appear below the input controls.

If you wish to alter the layout of the input controls, you may create a standard stylesheet in Presentation->Style and name it smd_bio. It will be loaded automatically.

To view the extended bio information for a user, hover over the Edit link of an item in the list; a tooltip will appear showing some of the extended bio.

Displaying user bio info

<txp:smd_bio_info>

Use this tag to display pieces of info from the biography. One or more of these tags can be employed depending on how you prefer to work. It may also be used as a container (or via the form attribute) to allow you to embed other Texpattern tags and/or special replacement tags to format the output.

Use the following attributes to tweak the output:

• author : list of author login names you wish to display info from. If omitted, the current (individual article) author will be used. You may specify any item as SMD_PRIVS: and then colon-separate priv numbers. Any users with those matching level(s) will be displayed
• items : list of bio item names you wish to display, in the order you wish to display them. Defaults to all items. Note you can also use bio information from the standard TXP user info, i.e. you can use any of the following, (case sensitive) :
  • user_id
  • name (login name)
  • RealName
  • email
  • privs
  • last_access
• exclude : list of bio item names you do not wish to display. This overrides items
• form : the name of a TXP Form with which to process each item. If not specified, the tag’s container will be used instead. If the container is empty, default output is used
• itemwraptag : (X)HTML tag to wrap around each item
• itemclass : fixed CSS class name to add to each item. The default is to automatically assign smd_bio_name_of_item (e.g. smd_bio_cell, smd_bio_dept, etc)
• break : (X)HTML tag to put between each item
• wraptag : (X)HTML tag to wrap around each author’s record
• class : CSS class to apply to the wraptag
• labeltag : (X)HTML tag to wrap around the item’s label (if used)
• labelclass : CSS class to apply to the label. The default is to automatically assign smd_bio_name_of_item (e.g. smd_bio_phone, smd_bio_home_address, etc)
• label : whether to display a label or not for each item. Choose from:
  • 1 : (default) Display the Title of the item
  • 0 : Display the Name of the item
  • some label : Display the given text as a label
  • “” (i.e. empty) : Do not display any label

Replacement tags

Inside the smd_bio_info form or container you may utilise special replacement tags that allow you to display any pieces of content from the current item. The core replacement tags are:

• {smd_bio_info_item} : the given value of the current item
• {smd_bio_info_name} : the sanitized name of the column corresponding to this item
• {smd_bio_info_title} : the human-friendly title you assigned this item
• {smd_bio_info_itemclass} : the name of the class associated with this item
• {smd_bio_info_labelclass} : the name of the class associated with this item’s label
• {smd_bio_*name*} : the value of the named item (e.g. smd_bio_cell, smd_bio_department, etc)

If you have elected to extract a list item such as radio, list or checkbox you will have some more replacement tags in the following format:

• {smd_bio_*name*_item_N} : the value of each named item in turn, where N starts at 1 and increments
• {smd_bio_*name*_label_N} : the value of each named item’s label in turn. Again, N starts at 1 and counts up for every item in your list
• {smd_bio_*name*_chosen_N} : the value of each selected item in turn, where N starts at 1 and increments. For select and radio lists there will be only one; for checkbox groups there may be more
• {smd_bio_*name*_chosen_label_N} : the value of each selected item’s label in turn, where N starts at 1 and increments
• {smd_bio_*name*_count} : the total number of elements in the named list
• {smd_bio_*name*_chosen_count} : the total number of selected elements in the named list

Replacement tag notes

If you extract more than one item at once in your items attribute, the individual named replacement variable won’t be available until the plugin has discovered them. For example:

<txp:smd_bio_info items="cell, mug, dept">
{smd_bio_info_title}: {smd_bio_cell}<br />
{smd_bio_info_title}: {smd_bio_mug}<br />
{smd_bio_info_title}: {smd_bio_dept}<br />
</txp:smd_bio_info>

would output:

Mobile number: 555-SQUID
Mobile number: {smd_bio_mug}
Mobile number: {smd_bio_dept}
Mugshot: 555-SQUID
Mugshot: 2
Mugshot: {smd_bio_dept}
Dept: 555-SQUID
Dept: 2
Dept: eng

Not quite what you wanted! For this reason it is best to use the individual named items only when you are using a single item. See Example 4 for ways round this:

If you wish to see an entire list of available replacement tags as the plugin builds them up, add debug="1" to your smd_bio_info tag.

<txp:smd_bio_articles>

A simple convenience wrapper for <txp:article_custom /> that sets the author attribute to the person who wrote the current article. If you specify an author, that person will be used instead. In all other regards, the tag functions identically to article_custom and can be used as a container if you wish.

IMPORTANT: take care when using this tag inside your default form. If you do not specify your own container or a dedicated form, you will receive a circular reference error from TXP as it tries to call the default form, which calls the default form, which calls the default form…

Examples

Example 1: List bio fields

<txp:smd_bio_info
     items="jobtitle, extension, cell, department"
     labeltag="dt" wraptag="dl"
     itemwraptag="dd" class="record" />

Shows the job title, work’s extension number, cell phone number and department of the current author, as a definition list.

Example 2: List users by priv level

<txp:smd_bio_info
     author="mr_pub, SMD_PRIVS:4:3"
     items="name, RealName, department"
     labeltag="dt" wraptag="dl"
     itemwraptag="dd" />

Shows the name, real name and department of all Copy Editors and Staff Writers and the user ‘mr_pub’.

Example 3: Using smd_bio_articles

<txp:smd_bio_info items="photo" label="">
   <txp:image id="{smd_bio_photo}" />
</txp:smd_bio_info> Recent articles by
   <a href="/desks/<txp:smd_bio_info
        items='department' label="" />">
        <txp:smd_bio_info items="RealName"
           label="" />
     </a>:
<txp:smd_bio_articles limit="6"
     wraptag="ul" break="li">
   <txp:permlink><txp:title /></txp:permlink>
</txp:smd_bio_articles>

Displays the author photo, the author’s RealName linked to the section that explains about the department to which she belongs, then lists the 6 most recent articles by her. Note the use of label="" to suppress the automatic labelling of items and our use of a replacement tag to feed <txp:image /> with the ID of the selected photo.

Example 4: Nesting tags

<txp:smd_bio_info author="SMD_PRIVS:5" items="name">
   <!-- For each author's name -->
   <a class="image"
     href="/blog/<txp:smd_bio_info author="{smd_bio_info_item}"
       items="name" label="" />"
     title="browse other posts by this author">
      <img class="thumb"
        src="/images/<txp:smd_bio_info author='{smd_bio_info_item}'
        items='image' label='' />.jpg" />
   </a>
   <div class="summary">
      <txp:smd_bio_info author='{smd_bio_info_item}'
	     items='profile' label='' />
   </div>
</txp:smd_bio_info>

Note that we iterate over each author first and then plug the {smd_bio_info_item} (the author’s name) into each nested smd_bio_info tag. This pulls out individual items just for that author and inserts them in the markup, again using label="" to omit the label.

Changelog

• 14 Jul 09 | 0.1 | Initial (non-public) release
• 21 Aug 09 | 0.2 | First public release ; no image/thumb output ; experimental options attribute removed ; container/form accepts TXP tags ; fixed textbox size limit (thanks MattD)
• 31 Aug 09 | 0.3 | Removed item attribute ; fixed warning message if using single items ; hidden pref smd_bio_sanitize_name forces sanitized login names
• 08 Jun 10 | 0.31 | Javascript only appears on admin tab (thanks redbot/Gocom)