smd_wrap

Wrap text with HTML, class, prefix, suffix, and apply tranforms to it in the process (linkify, format as date, trim, escape, sanitize, etc).

If the item you are intending to wrap is empty / non-existent then no wrap is applied and nothing is displayed. This makes it an ideal candidate for placing around other tags and saves having to do the “assign content to <txp:variable>, check if variable exists” dance. <txp:else /> is supported so you may take action if the contained content is empty.

Author / credits

Written by Stef Dawson. Thanks to the jakob for making a business case for creating this plugin, and of course the adi_wrap plugin for inspiration.

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.

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

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

Tag: <txp:smd_wrap>

Wrap the item or tag’s container with standard Txp wraptag paraphernalia. The content is parsed so you can include other Txp tags. If the results of the parse return nothing, the plugin does nothing, though you may fire an optional <txp:else /> if you wish. The following attributes configure the plugin:

item

The thing to wrap. Can be text, a tag-in-tag or some {replacement} from other smd_ plugins. If not specifed, the container is used as input.

wraptag

Wrap this HTML tag around the item. Specify it without angle brackets, e.g. wraptag="span"

class

Assign this CSS class to the wraptag. Unused if wraptag is empty.

html_id

Assign this HTML id value to the wraptag. Unused if wraptag is empty.

attr

Supply your own name=value pairs to add to the wraptag. For example, attr="rel|external, title|My useful popup title" would add rel="external" title="My useful popup title" as attributes to the wraptag.

label

Put this text as a heading / label before the item.

labeltag

Wrap the label with this HTML tag. Specify without angle brackets, e.g. labeltag="h4"

trim

Strip leading and trailing whitespace from the item before it has prefix and suffix applied. Use trim="0" to turn this feature off.

Default: 1

prefix

Put this text before the item. It is prepended prior to the item being passed through any transform chain.

suffix

Put this text after the item. It is appended prior to the item being passed through any transform chain.

transform

Apply transformations to the item. Transforms can be chained and are applied in order, each one separated by delim. Transform arguments are separated by param_delim. The following transforms are defined (see the examples for more information) :

add — append some text to the item. This is not the same as using prefix / suffix because the add transform can be inserted into the chain at any point. Use the second argument to determine in which position to add the new text; the text itself is the third argument. Here are the positional options:

before — add the text at the start of the item.

after — add the text at the end of the item.

both — add the text at both start and end of the item.

case — change the case of the item. You may chain case transforms in sequence, e.g. transform="case|lower|ucfirst". Choose from:

upper — upper case.

lower — lower case.

ucfirst — upper case first character of sentence.

ucwords — upper case first character of every word.

title — intelligent(ish) version of ucwords that ignores small words and tries to leave intentional first-lower-case words (e.g. iPhone) alone. Works best on English but does support Unicode up to a point. You can specify your own list of words by creating a hidden pref called smd_wrap_small_words. List each word separated by a pipe. You may use regex strings if you wish but no sanitization is done so be careful! The default list of ignored short words are: a|an|and|as|at|but|by|en|for|if|in|of|on|or|the|to|vs?[.]?|via

date — treat the item as a date and format it according to the strftime() compatible string given as the first argument. The item can either be a numeric (UNIX) timestamp or an English date string in an acceptable format. For datetime fields you could split the string first just to get the date portion.

escape — run the item through htmlspecialchars(). Use additional parameters to list optional flags or use any of the following special values:

no_quotes — ENT_NOQUOTES

double_quotes — ENT_COMPAT

all_quotes — ENT_QUOTES

fordb — run the item through Txp’s doSlash(). Always consider using this if you are posting the item back to the database (beware that other plugins may do this for you, so be careful not to duplicate it or you’ll get backslashes where there shouldn’t be backslashes).

form — pass the item through the nominated forms. Specify each form as an argument, and inside those forms place {smd_wrap_it} where you wish the item to be inserted.

link — turn the item into a clickable URL anchor. Without an argument, the link text will be the link itself. If you specify an argument, the link text will be set to whatever you choose.

no_widow — whether to allow the last word of the item to word-wrap to the next line. If you specify 0 as the argument, word-wrap will be allowed. Specifying 1 means the last word will never be allowed to wrap on its own. Without an argument, the Advanced Pref determines the behaviour.

replace — find a string or regex and replace it with something else. Additional parameters are:

1: type either string (or omitted) for a regular replace, or regex for a regular expression

2: from the string to search for. If using a regex, you MUST specify the regular expression delimiters as well or you’ll get an error

3: to the text with which to replace any found strings. If omited, the found strings will simply be removed

sanitize — clean the item either for:

url — address bar use.

file — filename use.

url_title — use as a URL title.

split — split the item at the given character(s) and return one or more parts, optionally joined by the given characters. Arguments:

1: split character(s)

2: join character(s)

3+: which pieces to return, each separated by param_delim. You can either use numeric indices to specify discrete parts, e.g. 1|4 returns the first and 4th parts. You can specify negative numbers to get parts starting from the end, e.g. -1|-2 returns the last and penultimate elements. last is a synonym for -1, all returns every piece, and rand chooses one piece at random. In addition you can also use greater-than and less-than symbols before a value to only return elements higher or lower than the given value, e.g. >2 returns the 3rd, 4th, 5th,… elements. See example 3 for details.

strip_tags — remove all HTML / PHP tags from the item.

textile — pass the item through the Textile processor.

trim — remove leading and trailing characters from the item. Specify a list of characters as the argument. Without an argument, whitespace will be removed.

delim

The plugin delimiter.

Default: comma (,)

param_delim

The argument delimiter.

Default: pipe (|)

debug

Display the item the tag is trying to wrap.

Examples

Example 1: Link anchor

<txp:variable name="wiki" value="http://textpattern.net/wiki" />
<txp:smd_wrap wraptag="div" class="external"
     transform="link|Textpattern documentation">
   <txp:variable name="wiki" />
</txp:smd_wrap>

Example 2: Date formatting

Notice that because we’re using a comma in the formatted string, the delim needs to be altered to some other (in this case arbitrary) string:

<txp:smd_wrap delim="@"
     transform="date|%A, %d %B, %Y %l:%M%p">
2011-9-12 05:30:00
</txp:smd_wrap>

Example 3: Split and join

Return a filename extension. Notice no join character is specified in the third argument (although it doesn’t hurt to include one; it won’t be used in this case):

<txp:smd_wrap transform="split|.||last"
     item="/path/to/some/really.big.file.name.jpg" />

Return the file path and filename extension, separated by colon (last is the same as -1) :

<txp:smd_wrap transform="split|.|:|1|-1">
/path/to/some/really.big.file.name.jpg
</txp:smd_wrap>

Split the date portion of a combined datetime and format it:

<txp:smd_wrap delim="@"
     transform="split| ||1 @ date|%A, %d %B, %Y">
2011-9-12 05:30:00
</txp:smd_wrap>

Make an HTML list from some other markup system:

<txp:smd_wrap wraptag="ul"
     transform="split|#|</li><li>|>1, add|before|<li>, add|after|</li>">
# First
# Second
# Third
# Fourth
</txp:smd_wrap>

A couple of things to note about this example:

• The add transform is used instead of prefix / suffix. This is because the latter pair become part of the item/container and are then split with the transform attribute. In this case we need to add the opening and closing tags afterwards.
• Splitting at ‘#’ renders an empty element before the “First” entry, so the transform is instructed to return items >1.

Example 4: with smd_query {replacements}

Wrap the custom_6 value with a div and sanitize it for use in a URL. If custom_6 is empty, nothing would be displayed.

<txp:smd_query query="SELECT * FROM wherever">
   <txp:smd_wrap item="{custom_6}" wraptag="div"
     transform="sanitize|url" />
</txp:smd_query>

If you wanted to trap the condition when custom_6 might be empty:

<txp:smd_query query="SELECT * FROM wherever">
   <txp:smd_wrap wraptag="div" transform="sanitize|url">
      {custom_6}
   <txp:else />
      <p>Sorry, custom_6 is empty</p>
   </txp:smd_wrap>
</txp:smd_query>

Example 5: find / replace

<txp:smd_wrap
     transform="replace||fox|badger">
Farewell my fox, it's been fun!
</txp:smd_wrap>

Note that the 2nd parameter (‘type’) has been omitted. You could specify ‘string’ here if you wished.

Changelog

22 Nov 2011 | 0.10 | Initial release