Opus 2.27 Publisher's Manual: Template Merge Fields

Remember that you insert a merge field into a template using the <opusfield> tag thus:

<opusfield name="article" [optional parameters]/>

or thus if you want to embed a tag within an HTML tag (as using the form above can confuse some HTML editors):

{opusfield name="article" [optional parameters]/}

The available merge field names given below. Where a field has parameters these are detailed against the field however there is one parameter which is valid for any field. This is code. If it's present it indicates to Opus that this field is to be taken from another article. Valid values are:

code= Contents

number The article with this article number

N The navbar article (as defined in the paper set up)

C The copyright article (as defined in the paper set up)

M The contact article (as defined in the paper set up)

P The privacy article (as defined in the paper set up)

L L:sect[[|sect...]] L:sect[[|sect...]]:offset L::offset The latest news article. In its simplest form L this is the latest news article from any section.
If you include the :sect suffix then it will be the latest article from that section. You can ask for the latest article in a list of sections by separating each section by a "|", e.g. L:1|2|5 which indicates the latest article from sections 1, 2 and 5.
You can also select the latest but N article by specifying an offset. An offset of 0 is the lastest article, so L::0 is just like using L on its own.

code=	Contents
number	The article with this article number
`N`	The navbar article (as defined in the paper set up)
`C`	The copyright article (as defined in the paper set up)
`M`	The contact article (as defined in the paper set up)
`P`	The privacy article (as defined in the paper set up)
`L L:sect[[\|sect`...`]] L:sect[[\|sect`...`]]:offset L::offset`	The latest news article. In its simplest form `L` this is the latest news article from any section. If you include the `:sect` suffix then it will be the latest article from that section. You can ask for the latest article in a list of sections by separating each section by a "\|", e.g. `L:1\|2\|5` which indicates the latest article from sections 1, 2 and 5. You can also select the latest but N article by specifying an offset. An offset of 0 is the lastest article, so `L::0` is just like using `L` on its own.

The list of valid merge fields is as follows:

name= Contents

include Contents of the template specified by the parameter file. The file must be in the paper's directory. The file is treated as a template and can include merge fields.

paper Name of the paper.

headline Article headline. For datacards this is the "title" of the datacard type.
You can also use this field to include the headline of other articles, typically because you want to include a news article but perhaps for other reasons.

title Article headline. Note that for datacards this is a composite field consisting of xdb| followed by the type of datacard, another | and the contents of the first field in the datacard so you may prefer to use the field "headline" above.

article The text of the article, processed appropriately to turn it into HTML.
An option "format" parameter lets you format it different ways:

format= Effect

short Only display the text up to the first blank line or {...} marker and then adds a "read more ..." link. This is what is used by the news page to generate the short articles

rss As about but without the "read more ..." link, making it more suitable for generating RSS feeds.

footnotes With all hyperlinks replaced with footnote numbers, as used in the default template for the printable version of the article. If you use this you must also use the merge field "footnotes" to place them somewhere on your page.

raw The text with no processing at all, so Opus tags are not expanded and implicit anchor tags from email addresses and URLs aren't created.

As discussed above you can also use this field to include the text of other articles, typically because you have made the site navigation an article, by using the code parameter.

url The URL of the article. You would normally use this field to include the URL of other articles rather than the current article by using the code parameter.

httphost The domain name of the server which you are using to host the server e.g. "www.miltonvillage.org.uk" or "opus.cx".

baseurl The URL of the directory where Opus is installed. Note that this includes a trailing "/" so if it's installed in the directory opus then this field will contain "/opus/".

cssurl The URL of the style sheet paperstyle.css either from the paper's directory or, if there isn't one, then from ./def.

templatepath The path of the template being used to generate the page. This is used in as a comment in the default templates as it's useful for debugging and we suggest that you retain it in your bespoke templates.

authormenuurl The URL of the author menu for this paper.

copyrighturl The URL of the copyright article for this paper.

printableurl The URL of the printable version of the current article if the article is printable, otherwise empty.

cologo An <img> tag for logo.gif, logo.jpg or logo.png (in that preference order) in the paper's directory, if one exists, and otherwise an <img> tag for the Opus image.

authoropts If the user is an author this will expand to a list of author options: "Write article, Add datacard, Author menu"; otherwise empty.

datewritten Date on which article was written. By default this is in dd/mm/yy format but you can specify a different format using the "format" parameter thus:

format= How date is formatted

iso ISO format (yyyy-mm-dd)

dmy european style (dd/mm/yy)

mdy american style (mm/dd/yy)

date(format) Using format. See below.

format is a string of characters specifying the format in the style used by the PHP date() function. So if, for example, you have a merge field:
<opusfield name="datewritten" format="date(F jS, Y)"/>
and you wrote the article on 2003-07-02 it will appear in your page as "July 2nd, 2003".

timewritten Time at which the article was written. By default this is in twelve hour date format e.g. 9:30am but you can specify a different format using the "format" parameter thus:

format= How date is formatted

iso ISO format (hh:mm:ss)

hma twelve hour format e.g. 9:30am

hmsa twelve hour format with seconds e.g. 9:30:15am

hma twenty four hour format e.g. 13:30

hmsa twenty four hour format with seconds e.g. 13:30:15

date(format)
time(format) Using format. See below.

format is a string of characters specifying the format in the style used by the PHP date() function. So if, for example, you have a merge field:
<opusfield name="datewritten" format="time(H.i)"/>
and you wrote the article at 2:30pm it will appear in your page as "14.30".

datereleased Date article released (the later of the date written and the date the article embargo finishes), with same format options as "datewritten".

timereleased Time article released, with same format options as "timewritten".

dateexpires Date article will expire. It has the same format options as "datewritten". If the article is not set to expire then its expiry date will be set to 9999-12-31 in whatever format you have set, either implicitly or explicitly.
If you want to use some other date for unexpired articles you can do this by setting including a ifnull parameter. This is a string not a date. So you can set it to "" or "never expires" or "2010-12-31" as appropriate to your application.

timeexpires Time article expires, with same format options as "timewritten".

datedated Date article was dated (if this is enabled for the section the article is in) otherwise the date that the article was written, with same format options as "datewritten".

authorcode The article author's code (1 being the publisher).

authorsig
authorforename
authorsurname
authoremail The article author's signature, encoded as an anchor tag.
The article author's forename.
The article author's surname.
The article author's email address.
You can modify all four of these to return details for another author by specifying their authorcode using the optional authorcode parameter. A value of "E" will return details of the paper's editor. A value of "U" will return details of the author if the reader is a logged in author, or a null string if not.

auxfield1
auxfield2
auxfield3
auxfield4 Contents of the relevant auxiliary field. If the auxiliary field is a select pull down or radio button then the value shown is the one displayed during data entry rather than the code stored in the database (e.g. so if you had "Y","Yes" in your CSV file and the article had "Y" in the field then "Yes" then this merge field would be "Yes"). If it is empty you can set a default value to be used in such cases by including a ifnull parameter.

articlecode The article number.

sectioncode The article's section number.

papercode The article's papercode number.

documentname
documenttype
documentsize For document articles returns the document file name, type and size. The type is a text string determined by the description in ./cfg/document_types.txt if that's present, otherwise it return "MS/Word", "Adobe/PDF" or "Postscript". Size is in human readable format, sizes below 1MB are returned as "nnnKB", over 1MB as "n.nnMB".

object Inserts the Opus object named by the parameter object.

nav Automatically generated navigation. This field has a mandatory type parameter which defines what sort of navigation is to be produced. This is generated by an include file nav_type.inc in either the ./def directory or the paper's directory.
Valid values for type currently are:

type= Contents

folders Navigation in the style of Windows 3.1 file manager, with articles in a tree format with folders. It relies on you setting parent article codes when creating articles. The optional parameter deftop lets you define a top article if the current article being displayed has no parent article.

linkline Link of hyperlinks from current article back to ultimate parent, separated by ">". Again it relies on you setting parent article codes when creating articles. The optional parameter deftop lets you define a top article if the current article being displayed has no parent article.

released "Y" if the article has been released, "N" if not. This can be useful if you're writing some JavaScript and need to test for this before deciding to take an action.

textbox This field simplifies the generation of boxes around text using simple graphics. The field has two mandatory parameters: a scheme parameter which defines what type of boxes are being made and a part parameter which defines which part of the box you want Opus to render. There are two basic types of textbox, with and without a title. To generate using textbox the "lightblue" scheme without a title you include this text:

<opusfield name="textbox" scheme="lightblue" part="top"/> your text to go within the box here <opusfield name="textbox" scheme="lightblue" part="bottom"/>

... and to generate a textbox with a title you include this text:

<opusfield name="textbox" scheme="lightblue" part="titletop"/> your title goes here <opusfield name="textbox" scheme="lightblue" part="titlemiddle"/> your text to go within the box here <opusfield name="textbox"scheme="lightblue" part="bottom"/>

If you want the text to have a coloured background then you need to include the optional parameter colbg="Y" in each of your [opusfield] tags.
Whichever type of textbox you use (with the exception of the "html-*" schemes) you also need to include the style sheet for the scheme in the [head] part of your template thus (for the scheme "lightblue"):

<link rel=stylesheet href="/php/img/textbox/lightblue/style.css" type="text/css">

Valid values for scheme currently are:

scheme= Contents
lightblue Line drawn boxes with rounded corners in light blue, with option to put in a title in white on a light blue background and/or to show the text in black on a pale blue background. This scheme is currently used on Paul Oldham's web site.

navy Same style of boxes as lightblue but with navy blue lines, with option to put in a title in white on a navy blue background and/or to show the text in black on a pale yellow background. This scheme was contributed by Jeremy Rogers and is currently used on the Bognor Regis web site.

deeppurple Same style of boxes as lightblue but with purple lines, with option to put in a title in white on a purple background and/or to show the text in black on a magenta background. This scheme was contributed by Jeremy Rogers and was at one time used on the Bognor Regis web site.

brownbear Thicker line drawn boxes with rounded corners in brown, with option to put in a title in white on a brown background and/or to show the text on a pale brown background. This scheme is currently used on The Hug's commercial web site.

pushpurple 3D purple (#663399) rounded corner boxes which appear to be pushing out of the screen, illuminated top right. Text appear in white. The images use transparent backgrounds so they can be used on a white or purple background (you can see this in use on the Action for Prisoners' Families web site. This scheme does not support titles but can be used with coloured backgrounds.

dropround
dropsquare These schemes both produce drop shadow boxes (illuminated from top right) with black text on a white background. The boxes either have rounded or square corners depending on the scheme selected. These schemes do not support titles or coloured backgrounds.

html-* Schemes done using HTML only (i.e. no graphics) to create boxes with coloured borders, headings and backgrounds. It is very easy to add new schemes by adding new files to ./php/img/textbox/html and we're currently shipping Opus with three html- schemes defined to start you off:

html- border title colbg

cambridge black black text on light blue yes

manu red white text on red no

oxford black white text on blue yes

Note that "html-*" schemes do not require a style sheet.

You can add new schemes by duplicating the images you will find in ./img/textbox/[scheme] in a new directory under ./img/textbox/. To avoid naming problems please start the name of your new directory with "z_" e.g. ./img/textbox/z_myscheme or else consider contributing your scheme to The Hug for incorporation into the next mainstream release.

newslink This field lets you insert hyperlinks into the news page template and into individual news article templates. There are several types of hyperlink.
Valid values for type currently are:

type= Contents
newer A link to another page of newer news

older A link to another page of older news

nextold A link to the next oldest news article

nextnew A link to the next newest news article

This field is empty unless the hyperlink will resolve to another page. So if you are currently on the newest news page then an <opusfield> with name="newslink" and type="newer" will be empty.
You can see this in use in the Opus default news page.
The hyperlink can be presented either as a text or image hyperlink. To use a text hyperlink include the parameter textlink. To use an image hyperlink include the parameter imagelink containing the URL of an image to use. If you use an imagelink parameter you can, if you wish, also include a textlink parameter, which will then be used as the alt attribute for the image (this is good practice from an accessibility viewpoint).
Normally these links look only at the same news section in which the article currently being displayed is found. If you want to let this work across multiple sections then use the optional sectioncode parameter listing one or more section codes, separated by "|".

editlink If the author is logged on and can edit the article then this merge field produces the "eNNN" hyperlink. Normally you don't need to use this as it will be appended to the end of the article merge field.

blog
A "blog" section for the article. This is only shown if blogging is enabled for the article's section and this field is built using the blog comments template defined for the section. This template typically includes some the fields below.

blog_addcomment
This is only shown if blogging is enabled for the article's section and is a hyperlink to a page allowing the reader to add a comment. If the parameter textlink is used then its value is used as the hyperlink text, otherwise it appears as "Add your comment to this article".

blog_comments
All the comments for this article constructed using multiple applications of the blog comment template defined for the section.

blog_author
blog_comment
blog_datewritten
blog_timewritten
The name of the author of the current comment or the text "someone anonymous" (or the value of the parameter anon if set), their comment, and the date and time written. The last two can use the parameter "format" with the same options as "datewritten" and "timewritten".
These merge fields are only valid within the blog comment template.

blog_edit
This is only shown if blogging is enabled for the article's section and the viewer has permission to edit the article. It is a hyperlink to a page allowing the author to edit the comments. If the parameter textlink is given then its value is used as the hyperlink text, otherwise it appears as "edit comments".

Previous comments about this page:

On 25/10/06 at 10:51am Paul Oldham wrote:

The "textbox" merge field relies heavily on the use of tables. I think this is something we're going to have to tackle in a future release as it should be possible to do this with CSS now.

Comment on this page