Display Code Plugin Documentation

sed_display_code plugin, v0.5 (June 10th, 2006)

Takes a file—with a .txt extension—and formats it for output as a line-numbered list.
Highlights can be applied to entire lines.
However, no attempt is made at source code formatting of keywords of any kind, not even the recognition of comments.

v0.5 Additional features…

• Can now (optionally) use TXPs built-in file handling. This lets you…
  • Upload your code files from the TXP admin interface.
  • Assign TXP categories to your code files.
  • List your code files in your pages using a suitably categorized <txp:file_download_list/> tag.
  • Show the dowload count as part of the download link in the code listing itself.
• Removed the show_ver attribute.

TXP Upload Procedure

1. Create a category/categories for you code listing files.
2. Prepare your listing files—remember they need to have a .txt extension.
3. Use the TXP Admin interface to upload your files.
4. Put the <txp:sed_display_code/> tag in your articles/forms as needed and customize it’s attributes.
   1. You need to set the dir attribute to the files directory of your TXP installation. By default: dir=’files’.
   2. If you want a download link at the foot of the listing with the active download count then you need to add the show_count attribute. Set the value to the text you want to appear next to the count: show_count=’Copies Downloaded:’

Display Code Attributes.

The plugin can take the following attributes…

Attribute	Default Value	Status	Description
‘file’	None	Needed	Name of the file to process.
‘dir’	‘files’	Optional	Directory to use to look for file. *Note the change from the old default value of ‘code’. If you were relying on this old default value, please add ‘dir=”code”’ to your tag call. *
‘list_type’	‘table’	Optional	Choose which underlying structure will be used for your code listing. Valid values: ‘table’ or ‘ol’. The default value is ‘table’ because it has better browser support and validates in more doctypes than ordered lists with variable start/end lines.
‘list_text’	‘Listing’	Optional	Text used to tag the title of the listing. Set this to ‘’ to omit the title.
‘list_no’	‘’	Optional	Any non-empty value will be placed after the list_text variable in the title.
‘class’	’sed_dc_wrap’	Optional	Class to use in marking up the wraptag.
‘wraptag’	‘div’	Optional	Name of the tag to use to wrap the listing.
‘link_text’	‘Download this code.’	Optional	Text to use when printing the download option (set to ‘’ to disable download.)
‘link_title’	‘Downloads the above listing as a text file.’	Optional	Text used to title the download link (if enabled.)
‘show_count’	‘’	Optional	Omit or leave blank to prevent the download count from being shown. Otherwise, supply the string that will prefix the download count.
‘start’	‘1’	Optional	The line of the text file to start the listing from. (Omit to start from the beginning.)
‘end’	‘’	Optional	The last line of the text file to display. (Omit to list to the end of the file.)
‘highlight1’	’-1’	Optional	List of line numbers to tag with highlight class 1. (Omit to tag no lines).
‘highlight2’	’-1’	Optional	List of line numbers to tag with highlight class 1. (Omit to tag no lines).
‘highlight3’	’-1’	Optional	List of line numbers to tag with highlight class 1. (Omit to tag no lines).
‘sum_text’	‘This table lists the contents of the file’	Optional	The text used in the table’s summary attribute.
‘listclass’	‘sed_dc’	Optional	Class used to mark up the table.
‘errorclass’	‘sed_dc_error’	Optional	Class used to mark up any error messages generated by the plugin.
‘err_text’	‘was not found.’	Optional	Text used in the file not found message. (Goes after the filename).
‘showver’	‘0’	Optional	Displays the name of the plugin and it’s version and makes it a link to the plugin’s homepage.

Emphasized items have been added or changed since the last release.
Struck out items have been removed since the last release.

Examples

Basic use.

<txp:sed_display_code file='foo' />

Looks for ‘foo.txt’ in the default code directory (\code) from the site root. If it exists, it will display a <table> within a <div> with the default title line, the listing (table) body and the default download link.
NOTE: If the file is called ‘foo.txt’, don’t write file=”foo.txt”, do write file=”foo”.

If your file is called bar.c and is in ‘c files’ then simply prepare bar.c.txt (must have .txt at the end of the filename) in that directory and use:
<txp:sed_display_code dir='c files' file='bar.c' />

Wrap tag and class.

By default the list will be output in a <div> with class=”sed_dc_wrap”. However, you can change this using the wraptag and class attributes…
<txp:sed_display_code file='header.h' wraptag='p' class='my-class' />

NOTE: Using the default <div> is recommended but changing the class could be useful, but don’t forget to include the appropriate styles in your style sheet!

The class applied to the table defaults to ‘sed_dc’ but can be changed by setting the ‘listclass’ attribute to whatever you need.

Customising the title.

To turn off the title text line…
<txp:sed_display_code file='foo' list_text='' />

To give the listing an identifier…
<txp:sed_display_code file='foo' list_no='x' /> where ‘x’ is a number—or whatever string you would like.

To give the listing a different label, like ‘snippet 4’…
<txp:sed_display_code file='foo' list_text='snippet' list_no='4' />

Customising the download link.

To omit the download link totally…
<txp:sed_display_code file='foo' link_text='' />

To change the link text and the pop-up label that goes with it…

<txp:sed_display_code file='foo' link_text='Grab the code!' link_title='Right click and save as…' />

To use the Textpattern file manager, upload your .txt files through the admin interface.

<txp:sed_display_code file='snip.php' dir='files' link_text='Grab the code'/>

This will produce a download link via the TXP file handling functions so that the download count will be recorded. If you want to see the current download count as part of the download link then you will need to supply the new show_count attribute and set it to the string you want to describe the count. Like this:-

<txp:sed_display_code file='snip.php' dir='files' link_text='Grab the code' show_count='Downloads:'/>

Displaying a ‘chunk’ of a file.

To display line 20 onwards from file foo.txt use…
<txp:sed_display_code file='foo' start='20' />

To display from the start of bar.txt to line 30 use…
<txp:sed_display_code file='bar' end='30' />

To display lines 23 to 32 of file accounts.php.txt use…
<txp:sed_display_code file='accounts.php' start='23' end='32' />

Playing with highlights.

To list file baz.c.txt and to highlight lines 25, 30 and 32 with style ‘hi1’ use…
<txp:sed_display_code file='baz.c' highlight1='25,30,32' />

If you wanted to highlight with styles ‘hi2’ and ‘hi3’as well then add…
<txp:sed_display_code file='baz.c' highlight1='25,30,32' highlight2='5,10' highlight3='31'/>

NOTE: Simply use a comma seperated list of numbers in the highlight1/2/3 attributes to tag those rows as needed. Which highlight takes precedence will depend upon the order of the style rules in your style sheet.

Example CSS markup

Here is an example of usable CSS for this plugin.

NOTE The last line allows some browsers to highlight the line you are pointing at with the mouse.

To-Do and Feature Enhancements

Feature ideas (in sequence of likely implementation)…

• Convert code to use classes to build the underlying xhtml representations…
  • One for table based structure (cross browser layout consistency, validation)
  • One for ordered lists (better semantic match, less consistency and possible validation failures in strict DocTypes).

Version History.

v0.5 June 10th, 2006.

• Integrated support for uploads via the TXP admin interface.
• Added download counter via a new attribute

v0.4 April 23rd, 2006.

• Simplified the table markup.
• Added the summary attribute to the table declaration.
• Added new tag attributes to control classes and allow internationalisation of output text.

v0.3 April 22nd, 2006.

• Changed the markup generated for the colgroup columns from “id” to “class” so that the tag can be used many times on the same page without triggering a validation warning of multiple instances of the same id.

v0.2 March 28th, 2006.

• Added a way of only listing a certain span of lines from the given source file.
• Added a way of highlighting certain rows in the listing.
• Added highlighting of odd/even rows.
• Added highlighting of lines pointed at by mouse.
• Changed method of displaying data from an ordered list to tabular data in order to better support line wrapping for long source lines.

v0.1 Implemented the following features…

• Styled, unordered list from given input file.
• Lightweight markup.
• Correctly indents leading tabs.
• Strips leading and trailing whitespace.
• Preserves blank lines from the source file.
• Strips any tabs out of the middle of lines.
• Customisable title before the listing (can be ommited if not needed).
• Customisable download link after the listing (can be ommited if not needed).

Credits

This is (loosely) based on the glx_code v0.3 plugin which, in turn, was inspired by Dunstan’s website.