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.

Defining and Using an <dpArray>

The following will define an array named "myList". It will then load two values into the array. Notice that the values require a key which is used for sorting, and a value which is used when you display the array.

T A G   C O D E:

<dpArrayElement name="myList" key="gerken, wil">
      Wil Gerken<br>
</dpArrayElement>

<dpArrayElement name="myList" key="forbes, collin">
      Collin Forbes<br>
</dpArrayElement>

The following will sort the values in the "myList" array and display them all.

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

which will return:

      Collin Forbes<br>
      Wil Gerken<br>

Give it a try in the tag tester.

E F F E C T:

Creating an Author List

The following produces a two column layout of unique authors sorted alphabetically. To add links to the author archive page, modify the array element to include the desired link. For instance:

<a href="../authors/<dpAuthorID number="<dpVar i>">"><dpAuthor number="<dpVar i>"></a><br>

T A G   C O D E:

<dpQuery issue="all" realm="author">
    <dpLoop var="i" from="1" to="<dpAuthor return="count">">
      <dpArrayElement name="myList" key="<dpAuthor number="<dpVar i>"
format="lastfirst">">
        <dpAuthor number="<dpVar i>"><br>
      </dpArrayElement>
    </dpLoop>
</dpQuery>

<dpComment>
Set middle marker and offset by one if uneven so left side gets extra length.
</dpComment>

<dpVar top="<dpArray name="myList" return="count">">
<dpVar middle="<dpMath <dpVar top>/2>">
<dpIf <dpMath <dpVar top>%<dpVar middle>> != 0>
    <dpVar middle="<dpMath <dpVar middle>+1>">
</dpIf>

<dpComment>
Render dual column table
</dpComment>

<table border="1" cellpadding="5" cellspacing="1">
<tr>
<td valign="top">
<ul>
<dpLoop var="i" from="1" to="<dpVar top>">
    <li><dpArray name="myList" sort="ascending" number="<dpVar i>">
    <dpIf <dpVar i> = <dpVar middle>>
      </ul>
      </td>
      <td valign="top">
      <ul>
    </dpIf>
</dpLoop>
</ul>
</td>
</tr>
</table>

E F F E C T:

<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>

Home: Support: Reference Guide: Miscellaneous Tags

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