How to Read the Reference Guide

Dispatch tags are presented in the following format:

<dpHeadline
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

The above syntax format should be read as follows:

• The tag is <dpHeadline>.

• All of the tag's possible tag attributes and all of their possible values are listed.

• Attribute values are separated by a pipe character "|" for readability only. The pipe character is not intended to be used in coding and should not be used. If you wanted to code a headline tag that was uppercase and spaced, you would code it like this:

  Right: <dpHeadline style="upper" style="spaced">

  Wrong: <dpHeadline style="upper|spaced">
  

• Attributes can be used multiple times as in the above example, and you can use as many or as few attributes as you want.

• Default values are in bold. If their isn't a default value, it is assumed that the attribute is equal to "" (no effect). It would be correct to say that <dpHeadline> is the same as <dpHeadline default="" style="" link="off" start="begin" stop="end" length="">

For comparison reference. The HTML <img> tag would be documented like this. Only a portion of the attributes are being used for this example.

<img
  src = "URL"
  align = "left|right|top|middle|bottom"
  alt = "default text"
  width = "#"
  height = "#"
>

Usually after the syntax of a tag is listed, its unique attributes are then defined. Frequently you will see a comment that says: "Please refer to the common attributes page for common attribute descriptions." The common attributes have been combined to a separate page to conserve space throughout the reference guide. To read about these attributes, follow the link as suggested.

D I S P A T C H   T A G   S Y N T A X   R U L E S

Dispatch tags have similar syntax rules to HTML. If you can do it with HTML, you can probably do it with Dispatch tags.

Rules similar to HTML

• Dispatch tags must be enclosed within less than < and greater than > signs.

• Dispatch tags are NOT case sensitive. You may mix the case however you want. All of our examples use a style of case we prefer, but you may develop your own style as well.

• White space and carriage returns don't matter. You can develop whatever style you wish, lots of white space or very little.

• Attributes to a tag should be quote encapsulated. For example: <dpHeadline case="lower"> as opposed to <dpHeadline case=lower>. You can break this rule, but we recommend using quotes on all of your attributes. You may also use 'single quotes' as well as "double quotes", as long as they are symmetrical.

• Dispatch tags may be combined with any HTML and can be used exactly like an HTML tag. For example, you can wrap bold tags around a headline: <b><dpHeadline></b>

Additional Rules

• If a tag fails, meaning it returns no results (null), then the tag is stripped from the template, and nothing is left in its place.

• Dispatch tags may be nested within HTML tags or other Dispatch tags. You can put a tag within a tag. This may look odd, but it is perfectly legal and often used within queries, variables, and conditional tests. Examples:

  <meta name="keywords" content="<dpMetaKeywords>">

  <a href="<dpPageForwardUrl>">Page Forward</a>

Common Attributes

The common attributes are attributes that are common to most Dispatch tags. These attributes are: default, style, link, start, stop and length

default = "default text"

The "default" attribute allows you to set a default value for a Dispatch tag. You can use the default attribute to define what should happen if a tag has no value, such as a story without an author or headline.

Examples:

If a story has an author, the <dpAuthor> tag will display it as usual. You can also use the default attribute for the scenario of a story without an author.

<dpAuthor default="Staff Writer">	Staff Writer
<dpAuthor default="Anonymous">	Anonymous

An example of the default attribute used within the <dpHeadline> tag. Notice the use of nesting a tag within a tag.

<dpHeadline default="<dpColumn>">

Cinema Review

In the following example, if the story has a summary, it is displayed as usual. If the story doesn't have a summary the default value is used. In this case the default value is the first two sentences of the story, followed by an ellipses.

<dpSummary default="<dpStory length="2s">...">

What's left to be said about Woody Allen? Or maybe the question is, "What does Woody have left to say?"...

style = "lower|upper|title|spaced|roman|decimal|noHtml|noHtmlStyle|identifier|scriptEncode|uriEncode"

The style attribute allows you to change the formatting style of a tag. You can change the style to lower case, upper case, title case, spaced, roman decimal, decimal, remove or encode HTML, or any combination of styles.

style="lower" - converts to "lower case".

style="upper" - converts to "UPPER CASE".

style="title" - converts to "Title Case". Note: use title case with caution. Due to the complexities of the English language, it may not always be 100% accurate.

style="spaced" - adds a space between each character. "s p a c e d"

style="roman" - converts to roman numeral: IX

style="decimal" - converts to decimal: 9

style="noHtml" - removes all HTML.

style="noHtmlStyle" - removes all HTML except paragraphs <p> and breaks <br>.

style="identifier" - converts to lower case letters with no spaces. This is primarily used for creating file names.

style="scriptEncode" - converts quotes, commas, and apostrophes to their numeric ASCII values. Primarily used within JavaScript or other scripting languages.

style="uriEncode" - encodes the text so it can be passed through a URL. This is often used for passing a query string on to an external search engine or commerce site.

style="chef", style="cockney", style="fudd", style="jive", style="kraut", style="newspeak", style="valspeak" - dialect translator Easter eggs. Read more about these here

Examples:

<dpHeadline>	Censored stories, 1998
<dpHeadline style="lower">	censored stories, 1998
<dpHeadline style="upper">	CENSORED STORIES, 1998
<dpHeadline style="title">	Censored Stories, 1998
<dpHeadline style="spaced">	C e n s o r e d   s t o r i e s ,   1 9 9 8
<dpHeadline style="roman">	Censored stories, MCMXCVIII
<dpHeadline style="decimal">	Censored stories, 1998
<dpHeadline style="spaced" style="upper">	C E N S O R E D   S T O R I E S ,   1 9 9 8
<dpHeadline style="uriEncode">	Censored+stories,+1998

link = "on|off|email|homepage"

The link attribute provides shorthand for creating a link around a tag, and is most commonly used within queries.

link="on" - creates a link to the story associated with the tag.

link="off" - no link is created. This is the default value for most tags.

link="email" - creates an email link. Note: this is only available on the <dpAuthor> and <dpImageArtist> tag.

link="homepage" - creates a link to a homepage. Note: this is only available on the <dpAuthor> and <dpImageArtist> tag.

Examples:

<dpHeadline>	Dolled Up Dreck
<dpHeadline link="on">	Dolled Up Dreck
<dpHeadline link="off">	Dolled Up Dreck
<dpQuery author="this" max="3">    <dpHeadline link="on"><br> </dpQuery>	Dolled Up Dreck Ashes to Ashes Tucci Feely
<dpAuthor>	Wil Gerken
<dpAuthor link="email">	Wil Gerken
<dpAuthor link="homepage">	Wil Gerken

start = "#p|#s|#w|#c|begin|end|resume"

stop = "#p|#s|#w|#c|begin|end|resume"

length = "#p|#s|#w|#c|begin|end"

Start, stop, and length manipulate the text returned by a tag, and are best described as a set of attributes.

The text that is returned by a tag is known as a "string". By default, the entire string is returned, and these attributes are not used. However, if you would like to return only a portion of the string, or manipulate the string in any way, you will need to use some or all of these attributes.

start - where to begin within the string

stop - where to end within the string

length - the length to return, most commonly used by itself or in conjunction with start.

#p - number of paragraphs. 1p = one paragraph, 2p = two paragraphs, etc.

#s - number of sentences. 1s = one sentence, 4s = four sentences, etc.

#w - number of words. 1w = one word, 5w = five words, etc.

#c - number of characters. 1c = one character, 10c = ten characters, etc.

begin - the beginning of the string

end - the end of the string

resume - continue from where you just left off. "Resume" will be equal to "begin" on the first call, and then equal to where you ended for the next call.

Examples:

Note: Spaces are counted as characters, but consecutive spaces are counted as only one character.

<dpHeadline>	All Fired Up
<dpHeadline length="1w">	All
<dpHeadline length="2w">	All Fired
<dpHeadline length="3w">	All Fired Up
<dpHeadline length="3c">	All
<dpHeadline length="5c">	All F

Note: "Start" always begins after what you specify as the starting position, as in these examples below:

<dpHeadline start="begin">	All Fired Up
<dpHeadline start="1w">	Fired Up
<dpHeadline start="2w">	Up
<dpHeadline start="2c">	l Fired Up
<dpHeadline start="8c">	d Up

Note: "Stop" specifies what position to stop at, unlike "length" which specifies how much to return.

<dpHeadline start="4c" stop="5c">	F
<dpHeadline start="5c" stop="7c">	ir
<dpHeadline start="2w" stop="3w">	Up

Display Tags

The display tags are the Dispatch tags that specifically relate to the fields in your publication's database, be it the headline, author, story or a user defined field. They are the most common of the Dispatch tags, and are primarily used to retrieve, manipulate and display information on a page.

<dpAuthor>

D E F I N I T I O N:

The author of the story currently being built or queried. By default <dpAuthor> will always return all of the authors of the story.

<dpAuthor
  format="standard|initials|fmlast|firstlast|lastfirst|first|middle|last"
  number="#|all"
  return="value|count"
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off|email|homepage"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

format="standard|initials|fmlast|firstlast|lastfirst|first|last|middle"

Using "Kay Anne Sather" as an example:

<dpAuthor format="standard"> - Kay Anne Sather
<dpAuthor format="initials"> - KAS
<dpAuthor format="fmlast"> - K A Sather
<dpAuthor format="firstlast"> - Kay Sather
<dpAuthor format="lastfirst"> - Sather, Kay
<dpAuthor format="first"> - Kay
<dpAuthor format="middle"> - Anne
<dpAuthor format="last"> - Sather

number="#|all"

If their are multiple authors of a story, you may optionally reference the individual authors using the number attribute. For example number="1" would return the first author and number="2" would return the second author.

number="all" is the default and will always return all the authors of a story, be it one or many.

return="value|count"

By default all author(s) names are returned (return="value"). You may optionally return the count which tells you how many authors an individual story has, and then loop through the authors one by one using the number attribute.

For example:

<dpIf <dpAuthor return="count"> = 1>
     {do the regular author layout}
<dpElseIf <dpAuthor return="count"> gt 1>
     {do the multi author layout and loop through the authors}
</dpIf>

The following expands on this concept and creates a link to the author's archive page. If there are multiple authors, it will create a link to each author's individual archive page by looping through them.

<dpIf <dpAuthor return="count"> = 1>
   <dpAuthorCredit> <a href="../authors/<dpAuthorID>.html"><dpAuthor></a>
<dpElseIf <dpAuthor return="count"> gt 1>
   <dpAuthorCredit>
   <dpLoop var="i" from="1" to="<dpAuthor return="count">">
      <a href="../authors/<dpAuthorID number="<dpVar i>">.html">
      <dpAuthor number="<dpVar i>"></a>
      <dpIf <dpVar i> lt <dpAuthor return="count">>
        ,
      </dpIf>
    </dpLoop>
</dpIf>

The idea is to loop through however many authors you have (from="1" to="<dpAuthor return="count">"), and then process each one individually, using the number attribute and the loop variable (<dpVar i>).

An additional test is performed to see if it is the last author or not. If it isn't a comma is displayed.

Please refer to the common attributes page for the common attribute descriptions.

E X A M P L E S:

<dpAuthor>	Jeff Smith
<dpAuthor link="email">	Jeff Smith
<dpAuthor format="initials">	JS
<dpIf <dpAuthor>>   <i><dpAuthorCredit> <dpAuthor></i> </dpIf>	By Jeff Smith

<dpAuthorCredit>

D E F I N I T I O N:

Returns the credit type for the author, such as "By" or "Edited By".

<dpAuthorCredit
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

Please refer to the common attributes page for the common attribute descriptions.

E X A M P L E S:

<dpAuthorCredit> <dpAuthor>

would return: By Neil Gaiman

A more common use would be to test to see if the story has an author first:

<dpIf <dpAuthor>>
  <dpAuthorCredit> <dpAuthor>
</dpIf>

<dpAuthorID>

D E F I N I T I O N:

The author ID of the story currently being built or queried. ID's are always in lowercase and contain no spaces. They are most commonly used to reference images or files.

<dpAuthorID
  default="default text"
  number="#"
  return="value|count"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

Please refer to the common attributes page for the common attribute descriptions.

E X A M P L E S:

<dpAuthorID>

jeffsmith

<dpColumn>

D E F I N I T I O N:

The column that the story belongs to which is currently being built or queried.

<dpColumn
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

Please refer to the common attributes page for the common attribute descriptions.

E X A M P L E S:

<dpColumn>	Music Feature
<dpColumn style="lower">	music feature
You're viewing: <dpColumn>	You're viewing: Music Feature

<dpColumnID>

D E F I N I T I O N:

The column ID that the story belongs to which is currently being built or queried. ID's are always in lowercase and contain no spaces. They are most commonly used to reference image names or files.

<dpColumnID
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

Please refer to the common attributes page for the common attribute descriptions.

E X A M P L E S:

<dpColumnID>	smith
<dpIf <dpColumnID> = "smith">   You're reading smith! <dpElse>   You should really check out <a href="smith.html">Smith</a>. </dpIf>	You're reading smith!

<dpFile>

D E F I N I T I O N:

The file name of the story currently being built or queried.

<dpFile
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

Please refer to the common attributes page for the common attribute descriptions.

E X A M P L E S:

<dpFile>

smith.html

<dpFileID>

D E F I N I T I O N:

The file ID of the story that is currently being built or queried. <dpFileID> always returns the base file name, as in "cinema" or "cinema4", whereas <dpFile> would return "cinema.html" or "cinema4.html".

<dpFileID
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

Please refer to the common attributes page for the common attribute descriptions.

E X A M P L E S:

<dpFileID>

smith

<dpHeadline>

D E F I N I T I O N:

The headline of the story currently being built or queried.

<dpHeadline
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

Please refer to the common attributes page for the common attribute descriptions.

E X A M P L E S:

<dpHeadline>	All Fired Up
<dpHeadline style="upper" style="spaced">	A L L   F I R E D   U P
<b><dpHeadline link="on"></b><br> <dpSummary>	All Fired Up The Steak-Out, home of the $30 steak with no potato, burned down a week ago last Saturday.

<dpHeadlineDefault>

D E F I N I T I O N:

This tag will return the headline value you have set for this column's default headline.

<dpHeadlineDefault
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

Please refer to the common attributes page for the common attribute descriptions.

<dpIssue>

D E F I N I T I O N:

The issue of the story currently being built or queried. This is also the directory name of the issue.

<dpIssue
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

Please refer to the common attributes page for the common attribute descriptions.

E X A M P L E S:

<dpIssue>	1998-06-25
<dpIssue style="roman">	MCMXCVIII-VI-XXV

<dpIssueID>

D E F I N I T I O N:

The issue ID of the story currently being built or queried. ID's are always in lowercase and contain no spaces. They are most commonly used to reference image names.

<dpIssueID
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

Please refer to the common attributes page for the common attribute descriptions.

E X A M P L E S:

<dpIssueID>

1998-06-25

<dpIssueDate>

D E F I N I T I O N:

The issue date of the issue currently being built or queried.

<dpIssueDate
  begin="strftime()"
  separator="default text"
  end="strftime()"
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

The default format for <dpIssueDate> is: <dpIssueDate begin="%B %e - " begin="%B %e, %Y">, which returns a date in this format: "June 25 - July 1, 1999"

A T T R I B U T E S:

begin = "strftime()"

The beginning run date of the issue being built or queried. This attribute takes strftime() syntax, as well as text. Please see table below.

end = "strftime()"

The ending run date of the issue being built or queried. This attribute takes strftime() syntax, as well as text. Please see table below.

separator = "default text"

This attribute takes any text. Common values are " - " and " to ". Please see examples below.

Please refer to the common attributes page for the common attribute descriptions.

strftime() values:

%A	Thursday	National representation of the full weekday name.
%a	Thu	National representation of the abbreviated weekday name, where the abbreviation is the first three characters.
%B	January	National representation of the full month name.
%b	Jan	National representation of the abbreviated month name, where the abbreviation is the first three characters.
%m	01	Month as a decimal number (01-12).
%d	07	Day of the month as a decimal number (01-31).
%e	7	Day of the month as a decimal number (1-31); single digits are preceded by a blank.
%Y	1998	Year with century as a decimal number.
%y	98	Year without century as a decimal number (00-99).
%D	01/07/98	Equivalent to "%m/%d/%y".

Additional strftime() values can be found here.

E X A M P L E S:

<dpIssueDate>	June 25 - July 1, 1998
<dpIssueDate begin="%A" separator=" through " end="%A">	Thursday through Wednesday
<dpIssueDate begin="%A through " end="%A">	Thursday through Wednesday
<dpIssueDate begin="%B %e, %Y">	June 25, 1998
<dpIssueDate end="%B %e, %Y">	July 1, 1998
<dpIssueDate begin="%Y-%m-%d">	1998-06-25
<dpIssueDate begin="%B %e, %Y" style="upper">	JUNE 25, 1998
<dpIssueDate begin="%Y" style="roman">	MCMXCVIII

<dpIssueNumber>

D E F I N I T I O N:

The issue number of the issue currently being built or queried.

<dpIssueNumber
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

Please refer to the common attributes page for the common attribute descriptions.

E X A M P L E S:

<dpIssueNumber>	18
<dpIssueNumber style="roman">	XVIII
<dpIssueNumber style="roman" style="lower">	xviii
Volume <dpVolumeNumber> Issue <dpIssueNumber>	Volume 15 Issue 18

<dpMetaDescription>

D E F I N I T I O N:

This tag will return the column's default meta description. You set this in column defaults.

<dpMetaDescription
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|
         noHtml|noHtmlStyle|identifier|scriptEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

Notice that style="noHtml" is the default for this tag. This will prevent potential HTML from side effecting meta tags.

Please refer to the common attributes page for the common attribute descriptions.

E X A M P L E S:

<meta name="description" content="<dpMetaDescription>">

or better yet, use the summary if it exists and then fall back (default=) to the meta description if no summary exists:

<meta name="description" content="<dpSummary style="noHTML" default="<dpMetaDescription>">">

<dpMetaKeywords>

D E F I N I T I O N:

This tag will return the column's default meta keywords. You set this in column defaults.

<dpMetaKeywords
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

Notice that style="noHtml" is the default for this tag. This will prevent potential HTML from side effecting meta tags.

Please refer to the common attributes page for the common attribute descriptions.

<dpSection>

D E F I N I T I O N:

The name of the section currently being built or queried. For example, if the story currently being built is within a section named "Music", <dpSection> would return Music.

<dpSection
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

Please refer to the common attributes page for the common attribute descriptions.

E X A M P L E S:

<dpSection>	Currents
<tt><dpSection style="upper" style="spaced"></tt>	C U R R E N T S
<dpIf <dpSection> = "music">   You're in the music section <dpElse>   You're NOT in the music section </dpIf>	You're NOT in the music section

<dpSectionID>

D E F I N I T I O N:

The section ID of the story currently being built or queried. ID's are always in lowercase and contain no spaces. They are most commonly used to reference image names.

<dpSectionID
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

Please refer to the common attributes page for the common attribute descriptions.

E X A M P L E S:

<dpSectionID>	currents
<img src="../images/<dpSectionID>.gif">

<dpStory>

D E F I N I T I O N:

The story currently being built or queried.

<dpStory
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
  images="on|all|off|#|# to #|#,#"
  imageStart="#p" (default is 0p)
  imageStop="#p" (default is 3/4 way through story)
  imageAlign="left|right|toggleLeft|toggleRight|center|none"
  imageMacro="macro name"
>

A T T R I B U T E S:

images="on|all|off|#|# to #|#,#"

Tells the story to display images or not. You may simply say on or all to display all of the images, or you may reference a single image, multiple images or a range of images.

<dpStory images="on">
<dpStory images="1, 3">
<dpStory images="2 to 4">
<dpStory images="2 to 4, 6">
<dpStory images="3 to <dpImageCount>">

imageAlign="left|right|toggleLeft|toggleRight|center|none"

Defines how you want your images aligned within the story.

right - all images align to the right.
left - all images align to the left
toggleLeft - images toggle left to right, back and forth
toggleRight - images toggle right to left, back and forth
center - centers image and follows it with a <p>
none

imageStart="#p"

Defines the starting position for the first image. The default is 0p, meaning before the first paragraph. <dpStory imageStart="3p"> would display the first image after the 3rd paragraph.

imageStop="#p"

Defines the ending position for the last image. This is only relevant if there is more then one image to be displayed. This is usually used in conjunction with <dpImageStart> to define a range where images should be displayed. The default is 3/4 through the story, meaning the last image will display at that position.

Examples:

<dpStory imageStart="2p" imageStop="10p">
This would put the first image after the second paragraph, and the last image after the 10th paragraph. All of the remaining images would be equidistantly dispersed within this range.

<dpStory imageStop="14p">
If this story had three images, the first image would be before the first paragraph (default). The middle image would be after the 7th paragraph, and the last image would be after the 14th paragraph. If there was only one image, it would still be before the first paragraph and the imageStop attribute would be ignored.

imageMacro="macro name"

The <dpStory> image shorthand is quite flexible and easy to use, but it always uses a pre-defined table that is hard coded into Dispatch. The imageMacro attribute allows you to override this table format and use a layout of your choosing.

When defining this layout, you can use any HTML you want and image tags "without" the number attribute. Dispatch will handle advancing the number values for the appropriate images. You may also use other Dispatch tags like conditional statements.

For example:

<dpMacro myImageLayout>
  <table border=1 align="<dpImageAlign>" width="<dpImageWidth>">
    <tr>
      <td>
        Image Table<br>
        <dpImage><br>
        <i><dpImageCaption></i><br>
        <font size=2><dpImageArtist></font>
      </td>
    </tr>
  </table>
</dpMacro>

Note: Like all macros, this macro needs to be declared before it is used, meaning it must be above whatever references it within your template.

Usage would be as follows:

<dpStory images="all" imageMacro="myImageLayout">

Please refer to the common attributes page for the common attribute descriptions.

<dpSubheadline>

D E F I N I T I O N:

The subheadline of the story currently being built or queried.

<dpSubheadline
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

Please refer to the common attributes page for the common attribute descriptions.

E X A M P L E S:

<dpSubHeadline>	Sonoita's Locals Lose An Institution Of Sorts.
<i><dpSubHeadline></i>	Sonoita's Locals Lose An Institution Of Sorts.
<dpSubHeadline style="lower">	sonoita's locals lose an institution of sorts.

<dpSubheadlineDefault>

D E F I N I T I O N:

This tag will return the subheadline value you have set for this column's default subheadline.

<dpSubheadlineDefault
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

Please refer to the common attributes page for the common attribute descriptions.

<dpSummary>

D E F I N I T I O N:

The summary of the story currently being built or queried.

<dpSummary
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

Please refer to the common attributes page for the common attribute descriptions.

E X A M P L E S:

<dpSummary>	The Steak-Out, home of the $30 steak with no potato, burned down a week ago last Saturday.
<b><dpHeadline link="on"></b><br> <dpSummary start="begin" length="9w">...	All Fired Up The Steak-Out, home of the $30 steak with no...

<dpSummaryDefault>

D E F I N I T I O N:

This tag will return the summary you have set for this column's default summary.

<dpSummaryDefault
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

Please refer to the common attributes page for the common attribute descriptions.

<dpUserField>

D E F I N I T I O N:

Returns the value contained in a user defined field (UDF) or the number (count) of values in a user defined field.

<dpUserField
  name="(UDFname)"
  number="#|all"
  return="value|count"
  realm="story|column|issue|all"
  squeeze="no|yes"
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

Please refer to the common attributes page for the common attribute descriptions.

<dpVolumeNumber>

D E F I N I T I O N:

The volume number of the issue currently being built or queried.

<dpVolumeNumber
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

Please refer to the common attributes page for the common attribute descriptions.

E X A M P L E S:

<dpVolumeNumber>	15
<dpVolumeNumber style="roman">	XV
Volume <dpVolumeNumber style="roman"> Issue <dpIssueNumber style="roman">	Volume XV Issue XVIII

Flow Control

Flow control tags relate to conditional statements, and looping constructs. The most common use of a flow control tag is a <dpIf> statement. Using <dpIf> you can perform tests within your template to decide how you want your page to render. For example, testing the character count of a story to decide how to present the images, ads, suggested links, or even if you want to split the story into multiple pages.

<dpIf>

D E F I N I T I O N:

Conditional tests allow you to make comparisons within your templates. For example, you can calculate how many characters are in a story, and provide a special layout for each circumstance.

Simple Condition Syntax

<dpIf (comparison statement)>
   action
</dpIf>

Complete Condition Syntax

<dpIf (comparison statement)>
   action
<dpElseIf (comparison statement)>
   action
<dpElse>
   action
</dpIf>

C O M P A R I S O N   O P E R A T O R S:

=	equal
!=	not equal
in	is in set
not	not in set
gt	greater than
lt	less than

E X A M P L E S:

The following can be read as "If the section for this story is music, then display the message You're in the music section":

<dpIf <dpSection>="music">
   You're in the music section
</dpIf>

The following can be read as "If the section for this story is music, then display the message You're in the music section, else (otherwise) display You're not in the music section":

<dpIf <dpSection>="music">
   You're in the music section
<dpElse>
   You're not in the music section
</dpIf>

The following can be read as "If the section for this story is music, then display the message 'You're in the music section', else if the section for this story is film, then display the message 'You're in the film section', else (otherwise) display 'You're not in the music or film section' ."

<dpIf <dpSection>="music">
   You're in the music section
<dpElseIf <dpSection>="film">
   You're in the film section
<dpElse>
   You're not in the music or film section
</dpIf>

The following can be read as "If you're not in the film section, display the message Go to the film section":

<dpIf <dpSection> != "film">
   Go to the film section.
</dpIf>

<dpLoop>

D E F I N I T I O N:

Looping is most commonly used to step through a story, headline or other display tag by paragraph or font. However you can use it for whatever you want.

<dpLoop var="variable" from="#" to="#" step="#|-#">
   Instructions to repeat.
</dpLoop>

A T T R I B U T E S:

var=(variable name)

Defines the name of a variable. This variable should be considered a counter and will always have the current value you can use.

from="#"

Defines the starting number of the loop.

to="#"

Defines the ending number of the loop.

step="#"

Allows you to step through the loop by a value other than one. The default value is one.

E X A M P L E S:

<dpLoop var="i" from="1" to="10">
   <dpVar i>
</dpLoop>

would create: 1 2 3 4 5 6 7 8 9 10

<dpLoop var="i" from="2" to="10" step=2>
   <dpVar i>
</dpLoop>

would create: 2 4 6 8 10

<dpLoop var="x" from="1" to="<dpImageCount>">
   <dpImage number="<dpVar x>">
</dpLoop>

would list all of the images in the story

<dpLoop var="x" from="1" to="<dpLength unit="p"><dpStory></dpLength>">
   Paragraph #<dpVar x><p>
   <dpStory start="resume" length="<dpVar x>p"><p>
</dpLoop>

would loop through the story one paragraph at a time from the first paragraph to the last paragraph. It would display the paragraph number followed by the paragraph itself.

Image Tags

The image tags allow you to get to access all the given information on a particular image or series of images. They are most commonly used to define an image macro, but can also be used independently for precision image placement and manipulation. For more information on image macros, see <dpStory>.

<dpImage>

D E F I N I T I O N:

Returns <img src="file.gif" width="100" height="220" alt="alt value">. In addition, you can push through any other values you want. The image tag will ignore everything but the number attribute and will just send your extras along.

<dpImage
  number="#"
>

E X A M P L E S:

<dpImage number="#" align="right">
returns
<img src="file.gif" width="100" height="220" alt="alt value" align="right">

<dpImage number="#" align="left" onmouseover="doSomething()">
returns
<img src="file.gif" width="100" height="220" alt="alt value" align="left" onmouseover="doSomething()">

You can also override values as follows:
<dpImage number="#" width="5">
returns <img src="file.gif" width="5" height="220" alt="alt value">

<dpImageAlt>

D E F I N I T I O N:

Returns the alt value of the specified image.

<dpImageAlt
  number="#"
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

Please refer to the common attributes page for the common attribute descriptions.

<dpImageArtist>

D E F I N I T I O N:

Returns the artist of a specific image referenced by the number. For example, if a story had three images, you would reference the second image's artist as follows: <dpImageArtist number="2">.

<dpImageArtist
  default="default text"
  number="#|all"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

Please refer to the common attributes page for the common attribute descriptions.

<dpImageCaption>

D E F I N I T I O N:

Returns the caption of a specific image referenced by the number. For example, if a story had three images, you would reference the second image's caption as follows: <dpImageCaption number="2">.

<dpImageCaption
  number="#"
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

Please refer to the common attributes page for the common attribute descriptions.

<dpImageCount>

D E F I N I T I O N:

Returns the number of images the story has associated with it. For example, if a story had three images, <dpImageCount> would return "3".

<dpImageCount
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

Please refer to the common attributes page for the common attribute descriptions.

<dpImageCredit>

D E F I N I T I O N:

Returns the credit type of the artist, for the specific image referenced by the number. Example return values include "Photo by" and "Illustration by".

<dpImageCredit
  number="#"
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

Please refer to the common attributes page for the common attribute descriptions.

<dpImageHeight>

D E F I N I T I O N:

Returns the height of the specified image.

<dpImageHeight
  number="#"
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

Please refer to the common attributes page for the common attribute descriptions.

<dpImageID>

D E F I N I T I O N:

Returns the base file name of the image. No suffix.

<dpImageID
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

Please refer to the common attributes page for the common attribute descriptions.

E X A M P L E S:

<dpImageURL>     returns feature1-2.gif

<dpImageID>     returns feature1-2

<dpImageNumber>

D E F I N I T I O N:

Returns the number of the "current" image. This would most commonly be used in an image macro to test for a specific image. For example, if it was the first image you may want to do something specific, or the last image.

<dpImageNumber
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

Please refer to the common attributes page for the common attribute descriptions.

E X A M P L E S:

<dpIf <dpImageNumber> = 1>
   tests if it is the first image
   special treatment for the first image
<dpElseIf <dpImageNumber> = <dpImageCount>>
   tests if it is the last image
   special treatment for the last image
<dpElse>
   default treatment (not the first or last image)
</dpIf>

<dpImageURL>

D E F I N I T I O N:

Returns the URL of the specified image. For example <dpImageURL number="1"> would return "feature2-1.gif".

<dpImageURL
  number="#"
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

Please refer to the common attributes page for the common attribute descriptions.

<dpImageWidth>

D E F I N I T I O N:

Returns the width of the specified image.

<dpImageWidth
  number="#"
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

Please refer to the common attributes page for the common attribute descriptions.

Miscellaneous Tags

The miscellaneous tags consist primarily of functions, like <dpLength> which calculates the length of a tag value or string by character, word, sentence or paragraph. Other miscellaneous tags include <dpMath> which allows you to perform mathematical operations, and <dpSpawn> which allows a template to create other pages within your site, most commonly used for server side includes or micro sites, like author archive pages.

<dpArray>

D E F I N I T I O N:

<dpArray> allows you to sort and display values you set in an array using <dpArrayElement>. It is most commonly used to display unique and sorted lists of authors in your database.

<dpArray
  name="arrayName"
  sort="ascending|descending|asc|desc"
  number="all|#"
  return="value|count"
>

A T T R I B U T E S:

name="arrayName"

The name attribute is used for the name of the array you are referencing. It should be the same name you used when defining your array with <dpArrayElement></dpArrayElement>

sort="ascending|descending|asc|desc"

The sort attribute lets you sort the array either ascending or descending. Asc and Desc are aliases to ascending and descending. The default sort is ascending.

number="all|#"

By default <dpArray> will return "all" elements in the array. You may also optionally choose to loop through an array or request a specific element by using the number attribute.

return="value|count"

By default <dpArray> will return all the elements in the array. You may also optionally choose to get just a count of elements in the array. This is most commonly used in conjunction of looping through an array or checking the size of an array before displaying it.

E X A M P L E S:

<dpArray name="myList" sort="ascending">

myList has <dpArray name="myList" return="count"> values.

<dpLoop var="i" from="1" to="<dpArray name="myList" return="count">">
    <dpArray name="myList" number="<dpVar i>" sort="ascending">
</dpLoop>

D E T A I L S:

• <dpArray> can be used as a stand alone tag which will perform the requested sort and display the entire array (each element). It can also be used interactively in conjunction with <dpLoop> to traverse through the array.

• name is required. All other values are optional and have default settings.

• The name is the same name you used to set each array element.

• sorting can be ascending or descending, with ascending as the default.

• by default, <dpArray> will return the whole array, but you may request an individual element number as well, by using number="#"

• return="count" will return the number of elements the array holds.

<dpArrayElement>

D E F I N I T I O N:

<dpArrayElement> lets you define elements within an array. It is always used in conjunction with <dpArray>.

<dpArrayElement name="arrayName" key="sort value">
  Value
</dpArrayElement>

A T T R I B U T E S:

name="arrayName"

The name attribute is used for the name of the array you want to create. You should use the same array name for each element you add to the array.

key="sort key"

The key attribute is used for sorting. For example, if you set a value of "Alfred E. Neuman", you would probably want a key of "neuman, alfred e."

value

The value is whatever value you want to assign to that array elemnt. It usually contains all the HTML formatting you will want when you display the array.

D E T A I L S:

• <dpArrayElement> requires a name, key and a close tag </dpArrayElement>. The value is technically optional, but it is fairly unlikely you would not set a value.

• The name value is the name of the array, such as "myList", "authorArray", etc. Make sure you use the same name for all of the elements you want to be a part of that array.

• The key value is used as a sort key. This is what <dpArray sort="ascending"> operates on. A common example would be an author's name: "last name, first middle".

• keys are case sensitive.

• The value can contain whatever output you want to store with that element, like a link to an author's archive page. All leading and trailing white space is trimmed off of the value.

• If you set two elements to the exact same key, it will overwrite the existing key. Put differently, keys must be unique. This can be used to your advantage in creating a unique list of elements from a larger list on non-unique elements.

<dpComment>

D E F I N I T I O N:

<dpComment> provides a method for you to put comments within your template. Unlike HTML comments, these comments will be removed when the template is built.

<dpComment>Comment goes here.</dpComment>

<dpComment>
Comment goes here.
</dpComment>

A T T R I B U T E S:

Not applicable.

E X A M P L E S:

<dpComment>
--------------------------------------------------------------------------
Create a list of all the authors in my database.
--------------------------------------------------------------------------
</dpComment>

<dpQuery issue="all" realm="author" sort="author">
   <dpAuthor><br>
</dpQuery>

<dpCurrentIssue>

D E F I N I T I O N:

This tag will return the issue/issueID of the latest issue in your database. It's purpose is primarily to use in a conditional test to see if the issue being built is the current issue or not.

<dpCurrentIssue
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

Please refer to the common attributes page for the common attribute descriptions.

E X A M P L E S:

<dpIf <dpIssue> = <dpCurrentIssue>>
    {create author archive pages}
</dpIf>

This Week in Film:
<dpQuery issue="<dpCurrentIssue>" section="film">
    <dpHeadline link="on"><br>
    <dpSummary><p>
</dpQuery>

<dpInclude>

D E F I N I T I O N:

<dpInclude> allows you to pull in (include) a template within a template. This is most commonly used for pulling in a template full of common macros, or design headers and footers.

<dpInclude
  template="template name"
>

A T T R I B U T E S:

template="(template name)"

Name of external template.

<dpLength>

D E F I N I T I O N:

<dpLength> returns the length of a string in paragraphs (p), sentences (s), words (w), or characters (c).

<dpLength unit="p|s|w|c">string or tag(s) to evaluate</dpLength>

A T T R I B U T E S:

Not applicable.

E X A M P L E S:

<dpLength unit="w">How many words?</dpLength> would return 3

<dpLength unit="w">How many characters?</dpLength> would return 18

A more common usage would be:

<dpVar totalParagraphs="<dpLength unit="p"><dpStory></dpLength>">

You now have a variable that holds the number of total paragraphs this story has. This can be used for layout purposes, statistical information like word count, a variable to determine if you should split this story into multiple pages, etc.

<dpMath>

D E F I N I T I O N:

<dpMath> lets you perform mathematical calculations within the tag and will return the result.

<dpMath calculation goes here>

O P E R A T O R S:

+, -, *, /, ( )

E X A M P L E S:

<dpMath 4+4> would return 8

<dpMath <dpLength unit="p"><dpStory></dpLength> - 4>
would return the length of the story in paragraphs subtracting 4.

<dpSpawn>

D E F I N I T I O N:

Spawn provides a method for a template to build additional files. This is most commonly used to generate server side includes, or to create and/or update mini sites.

This syntax it used to define a template inline. Mostly common for creating include files.

<dpSpawn path="relative path" file="file name">
   template defined here
</dpSpawn>

This syntax references an external template you've defined in the Template Manager. This is a common method for mini sites.

<dpSpawn path="relative path" file="file name" template="template name">

A T T R I B U T E S:

path="(relative path)"

The location or where the file should go, using relative addressing: path="/archives/"

file="(file name)"

The name of the file.

template="(template name)"

Name of external template.

E X A M P L E S:

The following code will build author archives for all of the authors in your database. It uses a template defined in the Template Manager called "author archives".

<dpQuery issue="all" realm="author">
   <dpSpawn path="/archives/authors/" file="<dpAuthorID>.html" template="author archives">
</dpQuery>

Navigational Tags

The navigational tags relate specifically to directional navigation within your web site. They allow you to add features such as page forward and page back between stories, threading across issues within a specific column, page numbering systems, or hybrids of all of the above. See <dpQuery> for examples of site navigation related to suggested links, such as "more by this author", "recently in this column", or "other Jazz reviews".

<dpColumnURL>

D E F I N I T I O N:

The URL of a specific column being built or queried. This is most often used to point to the first story within a column, which may be a dynamic element, depending on your publication.

<dpColumnURL
  column = "this|column|columnID"
>

A T T R I B U T E S:

column="this|column|columnID"

The <dpColumnURL> tag always defaults to the column the story being built or queried is in, which is notated by column="this". If you want to query the beginning of a different column, you can set the column value to a specific column/columnID. Examples:

<dpColumnURL column="this"> - smith.html
<dpColumnURL column="Jeff Smith"> -
<dpColumnURL column="curr"> - curr.html

E X A M P L E S:

<dpColumnURL>	smith.html
<a href="<dpColumnURL column="curr">">Go to the Currents Features</a>	Go to the Currents Features

<dpPageBackURL>

D E F I N I T I O N:

The URL of the previous page from the story currently being built or queried.

<dpPageBackURL>

A T T R I B U T E S:

Not applicable.

E X A M P L E S:

<dpPageBackURL>	mailbag.html
<a href="<dpPageBackURL>"><img src="../images/pageback.gif"></a>
<dpIf <dpPageBackUrl>>   <a href="<dpPageBackURL>"><img src="../images/pageback.gif"></a> </dpIf>

<dpPageForwardURL>

D E F I N I T I O N:

The URL of the next page from the story currently being built or queried. Page sequence is determined by the order of the stories within pagination.

<dpPageForwardURL>

A T T R I B U T E S:

Not applicable.

E X A M P L E S:

<dpPageForwardURL>	skinny.html
<a href="<dpPageForwardURL>">Page Forward</a>	Page Forward
<dpIf <dpPageForwardURL>>   <a href="<dpPageForwardURL>">Page Forward</a> </dpIf>	Page Forward

<dpPageNumber>

D E F I N I T I O N:

The page number of the story currently being built or queried.

<dpPageNumber
  type = "issue|section"
  position = "this|last|first"
  default="default text"
  style="lower|upper|title|spaced|roman|decimal|identifier|
         noHtml|noHtmlStyle|scriptEncode|uriEncode"
  link="on|off"
  start="#p|#s|#w|#c|begin|end|resume"
  stop="#p|#s|#w|#c|begin|end|resume"
  length="#p|#s|#w|#c|begin|end"
>

A T T R I B U T E S:

type="issue|section"

The <dpPageNumber> tag always defaults to issue page numbering, which numbers pages front to back in the issue. An alternate page numbering type, section numbering, is also available. In section numbering each section begins with page 1.

<dpPageNumber type="issue"> - 2
<dpPageNumber type="section"> - 2

position="this|last|first"

The default page position is always the page you are viewing, known as "this". You may also easily access the first and last page of the issue or section, by using the position attribute. This is frequently used in comparison tests to see if you are currently viewing the last page of an issue or section.

<dpPageNumber type="issue" position="this"> - 2
<dpPageNumber type="issue" position="last"> - 39
<dpPageNumber type="section" position="this"> - 2
<dpPageNumber type="section" position="last"> - 8

Please refer to the common attributes page for the common attribute descriptions.

E X A M P L E S:

<dpPageNumber>	2
Page <dpPageNumber type="section">	Page 2
<dpPageNumber style="roman">	II
The last page in this issue is page <dpPageNumber position="last">	The last page in this issue is page 32

<dpSectionURL>

D E F I N I T I O N:

The URL of a specific section being built or queried. This is most often used to point to the first story within a section, which may be a dynamic element, depending on your publication.

<dpSectionURL
  section = "this|section|sectionID"
>

A T T R I B U T E S:

section="this|section|sectionID"

The <dpSectionURL> tag always defaults to the section the story being built or queried is in, which is notated by section="this". If you want to query a the beginning of a different section, you can set the section value to a specific section/sectionID. Examples:

<dpSectionURL section="this"> - mailbag.html
<dpSectionURL section="City Week"> - cw.html
<dpSectionURL section="cityweek"> - cw.html

E X A M P L E S:

<dpSectionURL>	mailbag.html
The first story in this section is <a href="<dpSectionURL>"><dpSectionURL></a>	The first story in this section is mailbag.html
<a href="<dpSectionURL section="music">">Go to the Music Section</a>	Go to the Music Section
<a href="<dpSectionURL section="Currents">">Currents</a> . <a href="<dpSectionURL section="Music">">Music</a> . <a href="<dpSectionURL section="Cinema">">Cinema</a> . <a href="<dpSectionURL section="Books">">Books</a> . <a href="<dpSectionURL section="Review">">Review</a> . <a href="<dpSectionURL section="City Week">">City Week</a>	Currents . Music . Cinema . Books . Review . City Week

<dpThreadBackURL>

D E F I N I T I O N:

The URL of the previous story in this column's sequence.

<dpThreadBackURL>

A T T R I B U T E S:

Not applicable.

E X A M P L E S:

<dpThreadBackURL>	../1999-05-07/smith.html
<a href="<dpThreadBackURL>">Previously in this column</a>	Previously in this column
<dpIf <dpThreadBackURL>>   <a href="<dpThreadBackURL>">Previously in this column (error checked)</a> </dpIf>	Previously in this column (error checked)

Queries

Queries allow you to query your database to find matches based on the criteria you set within the query tag. Common uses of queries include table of contents pages, suggested links, more stories by a specific author, previously in this column, page numbering systems, query if a story is running or not this issue, and much, much more.

<dpQuery>

D E F I N I T I O N:

<dpQuery
  issue="this|all|archives|issue|issueID|
        -this|-all|-archives|-issue|-issueID"
  section="this|all|section|sectionID|
          -this|-all|-section|-sectionID"
  column="this|all|column|columnID|
         -this|-all|-column|-columnID"
  author="this|all|author|authorID|
         -this|-all|-author|-authorID"
  columnType="all|column|interstitial|
             -all|-column|-interstitial"
  userField="name|match|value"
  volumeNumber="#|-#"
  issueNumber="#|-#"
  includethis="yes|no"
  paginated="yes|no|all"
  max="#"
  min="#"
  sort="issue|section|column|author|story|
       -issue|-section|-column|-author|-story"
  exclude="<dpQuery>"
  realm="author|column|section|issue"
  return="value|count"
>

Simple Query Format:

<dpQuery>
  {Looping Query Section}
</dpQuery>

The query tag is a container tag, meaning it requires an opening and closing tag: <dpQuery></dpQuery>. To define and execute a query, the above syntax is all that is needed. However, you will usually use at least one attribute to refine your query for your specific needs.

Everything that appears within the {Looping Query Section} will be repeated for each match.

For example, the following syntax queries all of the publication's archives looking for matches of the cinema column. If it finds a match, it will output a linked headline of the matching story.

<dpQuery column="cin">   <dpHeadline link="on"> </dpQuery>

Native Talent Last Night Stand Seeing Through The Roos X Marks The Plot etc.

Complete Query Format:

The query tag also includes additional tags that can be optionally used within the query container to extend the functionality of the query tag.

<dpQuery>
  {Header Section}
  <dpLoop>
    {Looping Query Section}
  </dpLoop>
  {Footer Section}
  <dpFail>
    {Failed Query Section}
</dpQuery>

<dpLoop></dpLoop>

The <dpLoop></dpLoop> container tag allows you to designate the {Looping Query Section}. In the simple format, <dpLoop></dpLoop> is assumed.

The advantage to using the <dpLoop></dpLoop> container tag is so that you can define a {Header Section} and/or a {Footer Section}

The header and footer sections will only be displayed once for the entire query, where the information within the <dpLoop></dpLoop> container tag will be displayed for each match. Please see the examples below.

<dpFail>

The <dpFail> tag allows you to define what should be displayed if there are no matches. By default, if there are no matches, the entire query will fail and nothing within the query container will be displayed. Note: <dpFail> is similar to an else clause.

A T T R I B U T E S:

issue = "this|all|archives|issue|issueID"

The issue attribute allows you to choose whether you want to query only the issue being built, all issues, just the archives, a specific issue, or a combination of issues. Note: like all Dispatch attributes, you may use multiples, such as <dpQuery issue="this" issue="1998-05-07">

issue="this" - This is the default value and only queries the issue being built.

issue="all" - Queries all issues, including the issue being built.

issue="archives" - Queries all issues before the issue being built. The issue being built is not included, only the issues that precede it in date. Most commonly used for suggested links.

issue="issue|issueID" - You can specify a specific issue using <dpIssue>/<dpIssueID> format: yyyy-mm-dd. Example: issue="1999-10-22"

section = "this|all|section|sectionID"

The section attribute allows you to query only within the section being built, all sections, a specific section, or a combination of sections.

section="this" - limits the query to the current section being built. For example, if the page being built is in the film section, it would only query film.

section="all" - queries all sections. This is the default value.

section="section|sectionID" - queries a specific section you designate. Both <dpSection> & <dpSectionID> syntax can be used. Example: section="music"

column = "this|all|column|columnID"

The column attribute allows you to query only the specific column being built, all columns, a specific column, or a combination of columns.

column="this" - limits the query to the current column being built. For example, if the story being built is a cinema feature column, it would only query other stories that are cinema feature columns.

column="all" - queries all columns. This is the default value.

column="column|columnID" - queries a specific column you designate. Both <dpColumn> & <dpColumnID> syntax can be used. Example: column="cover"

author = "this|all|author|authorID"

The author attribute allows you to query only the specific author being built, all authors, a specific author, or a combination of authors.

author="this" - limits the query to the current author of the story being built. For example, if the story being built is written by Jeff Smith, it would only query other stories that were written by Jeff Smith.

author="all" - queries all authors. This is the default value.

author="author|authorID" - queries a specific author you designate. Both <dpAuthor> & <dpAuthorID> syntax can be used.

paginated = "yes|no|all"

The paginated attribute limits the query to only paginated pages, only non-paginated pages, or both paginated and non-paginated pages.

paginated="yes" - limits the query to paginated pages only. This is the default.

paginated="no" - limits the query to non-paginated pages only.

paginated="all" - queries both paginated and non-paginated pages.

includethis = "yes|no"

The includethis attribute tells the query whether it should use the story currently being built within the query or not.

includethis="yes" - tells the query to include itself, the story currently being built, within the query.

includethis="no" - tells the query not to include itself, the story currently being built, within the query. This is the default.

max = "#"

The max attribute limits the amount of stories to be available for output. Max takes any decimal value. For example, if you defined your query and wanted to make sure it only contained a maximum of three results, you would use max="3". The max attribute is handled at the very end of the query, which means that your query will still be calculated over a full set. Only after all filters and sorting has been applied is the set reduced to the maximum value. The default is max="", which applies no limitations.

min = "#"

The min attribute sets a minimum amount of the query set before it will process. For example, if you only wanted the query to execute if there where at least three results within the set, you would use min="3". You could also combine min and max to set a minimum and maximum, such as min="3" and max="4". This will never process less then three or more then four.

sort = "+-(issue|section|column|author|story)"

You can sort your query results ascending or descending by any of these values or a combination of them. The direction of the sort works as follows: sort="issue" sorts by issues ascending, sort="+issue" is the same and also sorts by issues ascending, sort="-issue" reverse sorts by issues or descending. You may also combine sorts to achieve multiple sorting. For example, <dpQuery sort="-issue" sort="story"> sorts the issues descending and then by story ascending.

+ = ascending
- = descending

exclude = "<dpQuery>"

The exclude attribute allows you to exclude a query set from the query you are performing. For example, say you wanted to list more stories by author and more stories by column on the same page. These queries are likely to have a few of the same links. If you want to make sure they don't, you can use the exclude attribute.

realm="author|column|section|issue"

If you set the realm attribute, the query will loop once for each unique author, section, column, or issue matched by the rest of the query. This is most often used to create a list of all of your authors, sections, columns or issues.

userField="name|match|value"

The userField attribute allows you to query over a specific userField. It takes multiple values which allow you to fine tune your query. The first value is the name of the user field, the second value defines how to match it, and the remaining value(s) specifies what to match.

columnType="all|column|interstitial"

By default Dispatch queries all columns, but there are times when you may want to limit the queries to just stories or just interstitials. A common use of this is when you want to avoid having an interstitial show up in an all inclusive index of the issue.

return="value|count"

By default a query will always return the values of the query (return="value"). The return attribute can also allow you to find out just how many values a query would have had, rather then returning them (return="count"). This would most commonly be used in a conditional test, and should be written without the close query </dpQuery>.

For example:

The following code first creates a list of up to 3 (max="3") stories by "this" author from the archives. It then performs a test to see if there were greater than 3 (gt 3) stories by this author in the archives. If there were, it puts in a link to their author archive page. If there weren't, nothing is displayed. The goal here was to prevent the "more..." link from being displayed unless there truly were more. <dpQuery return="count"> makes it easy to achieve this, and avoids incrementing variables.

  <dpQuery issue="archives" author="this" max="3">  
    More by <dpAuthor>:<br>
    <dpLoop>
      <dpHeadline link="on"><br>
    </dpLoop>
  </dpQuery>

  <dpIf <dpQuery issue="archives" author="this" return="count"> gt 3>
     <a href="../archives/authors/<dpAuthorID>.html">more...</a><br>
  </dpIf>  

Another example for comparison:

Note: return="value" is the default, and therefore not needed.

  <dpQuery issue="archives" column="music">  
    <dpHeadline><br>
  </dpQuery>

would return this:

The Sound and the Fury
Scavengers of the Vast Wasteland
Make Your Mama Proud
High Impact

---

<dpQuery issue="archives" column="music" return="count">

would return "4".

E X A M P L E S:

<dpQuery column="cin">   <b>Recently in this column:</b><br>   <dpHeadline link="on"><br> </dpQuery>	Recently in this column: Native Talent Recently in this column: Last Night Stand Recently in this column: Seeing Through The Roos Recently in this column: X Marks The Plot etc.
<dpQuery column="cin">   <b>Recently in this column:</b><br>   <dpLoop>     <dpHeadline link="on"><br>   </dpLoop> </dpQuery>	Recently in this column: Native Talent Last Night Stand Seeing Through The Roos X Marks The Plot etc.
<b>Recently in this column:</b><br> <dpQuery column="danehy">   <dpHeadline link="on"><br> </dpQuery>	Recently in this column:
<b>Recently in this column:</b><br> <dpQuery column="danehy">   <dpHeadline link="on"><br>   <dpFail>      No matches found<br> </dpQuery>	Recently in this column: No matches found

Variables & Macros

Variables and Macros allow you to create your own macro subroutines, or save a value in a variable for later use within your template. A common use of macros would be a capsule style layout for your table of contents pages, or a subroutine to create suggested author links. It is also common to place all of your site's macros in their own file that your templates can all reference. Organizing your templates like this, can aid in streamlining and modifying your templates.

<dpMacro>

D E F I N I T I O N:

Macros are similar to variables, but rather than setting a value they define a series of instructions you can use within your template. If you end up doing the same thing more then once within your template, macros are usually a helpful shorthand.

<dpMacro macroName="value">

or

<dpMacro macroName>value</dpMacro>

Macro Usage:

<dpMacro macroName>

A T T R I B U T E S:

Not applicable.

E X A M P L E S:

<dpMacro myCapsuleStyle>
   <b><dpHeadline link="on"></b><br>
   <dpSummary><br>
   <dpAuthor><p>
</dpMacro>

<dpQuery section="music">
   <dpMacro myCapsuleStyle>
</dpQuery>

<dpQuery section="film">
   <dpMacro myCapsuleStyle>
</dpQuery>

<dpMacroDefine>

D E F I N I T I O N:

<dpMacroDefine> is the preferred way of defining macros. By defining macros with <dpMacroDefine> you have the extra advantage of being able to call a macro from within macro definition.

<dpMacroDefine macroName>
  macro
</dpMacroDefine>

A T T R I B U T E S:

Not applicable.

E X A M P L E S:

<dpMacroDefine linkLayout>
  <dpHeadline><br>
  <dpSummary><p>
</dpMacroDefine>

<dpMacroDefine sectionLinks>
  <dpQuery issue="this" section="this">
    <dpMacro linkLayout>
  </dpQuery>
</dpMacroDefine>

<dpVar>

D E F I N I T I O N:

Variables allow you to create your own variables you can use within a template. Variables are usually used to save or set values you want to reference later in your template.

<dpVar variableName="value">

or

<dpVar variableName>value</dpVar>

Variable Usage:

<dpVar variableName>

A T T R I B U T E S:

style="lower|upper|title|spaced|roman|decimal|noHtml|noHtmlStyle|identifier|scriptEncode"

Please refer to the common attributes page for additional details on the style attribute.

E X A M P L E S:

<dpVar myName="Deuteronomy">

My name is <dpVar myName>
would display
My name is Deuteronomy

<dpIf <dpColumnID>="feature">
   <dpVar headerImage="cool_image.gif">
<dpElse>
   <dpVar headerImage="plain_image.gif">
</dpIf>

<img src="<dpVar headerImage>">
would display cool_image.gif if it was the feature and plain_image.gif if it wasn't.

<dpVarDefine>

D E F I N I T I O N:

<dpVarDefine> is the preferred method of defining variables. The advantage to using <dpVarDefine> is the ability to nest variables. Note: all leading and trailing padding is removed from the variable definition.

<dpVarDefine variableName>
  variable
</dpVarDefine>

A T T R I B U T E S:

style="lower|upper|title|spaced|roman|decimal|noHtml|noHtmlStyle|identifier|scriptEncode"

Please refer to the common attributes page for additional details on the style attribute.

E X A M P L E S:

<dpVarDefine myCounter>
  0
</dpVarDefine>

<dpVarDefine myCounter>
  <dpMath <dpVar myCounter> + 1>
</dpVarDefine>

Home: Support: Reference Guide

Questions? Comments? Please write support@desert.net.