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

Creating E-commerce Links and Passing Arguments for External Queries

Using User Defined Fields, you can create e-commerce links for books, movies, or music reviews.

For example, if you have a User Defined Field named "book title," you can create a link to that book at Amazon.com. Find the format that Amazon.com uses for its queries. For books, the URL (at the time of writing this) is: http://www.amazon.com/exec/obidos/external-search?keyword=book+title&mode=books Add the following code to your template. It may look a bit cryptic, but it should make sense if you read through it.

T A G   C O D E:

<a href="http://www.amazon.com/exec/obidos/external-search?keyword=<dpUserField name="book title" style="lower" style="nohtml" style="urlEncode">&mode=books">Search for related books at Amazon.com</a>

or

<a href="http://www.amazon.com/exec/obidos/external-search?keyword=<dpUserField name="book title" style="lower" style="nohtml" style="urlEncode">&mode=books">Purchase <dpUserField name="book title"> at Amazon.com</a>

Basically, we've replaced the keyword section, which previously had "book+title", with the following: <dpUserField name="book title" style="lower" style="nohtml" style="urlEncode">, which says take the Book Title, change it to lower case, remove any HTML it may have, and encode it so it can be passed in a URL.


Try it out and you'll see how it connects directly to the Amazon search allowing the reader to get right to the book they want. You can use this dynamic tag code to create smart links to external sites.


Here's another example using Google.com and a variable:

<dpVar encodedTitle="<dpUserField name="book title" style="lower"
style="noHtml" style="urlEncode">">

 <a href="http://www.google.com/search?q=<dpVar encodedTitle>&mode=books"
target="_blank">Search Google for more on <dpUserField name="book
title"></a>

This would create a link like the following:

http://www.google.com/search?q=good+omens

E F F E C T:

Sorting By UDF

To sort by a UDF, simply add a sort value like the following to your query.

T A G   C O D E:

The following will sort by film title from a to z:

<dpQuery sort="userField:film title">
   
The following will reverse sort by film title from z to a:

<dpQuery sort="-userField:film title">

And the following will first sort by film title, then by issue:

<dpQuery sort="userField:film title" sort="issue">

 

Here are a few real life examples:

<dpQuery issue="all" userField="film genre" sort="userfield:film title"
sort="fuzzy" max="4">
  <dpUserField name="film title"><br>
</dpQuery>

The above query looks through "all" issues, matching any stories based on
film genres. It then sorts the output alphabetically by "film title", then
does a "fuzzy" sort for the best matches. To shorten this list for our demo, we set the max output to 4:

 Apocalypse Now
 Grand Illusion
 Since You Went Away
 Welcome to Sarajevo


Here's the same basic query with a reverse sort:

<dpQuery issue="all" userField="film genre" sort="-userfield:film title"
sort="fuzzy" max="4">
  <dpUserField name="film title"><br>
</dpQuery>

Output:

 Welcome to Sarajevo
 Since You Went Away
 Grand Illusion
 Apocalypse Now

Sorting by UDFs allows you to organize your output alphabetically. It is also the ideal way to create lists of UDF values.

E F F E C T:

Debugging Queries with <dpUserField number="all">

Use the number attribute of a User Defined Field in queries to examine the output and fine tune your queries for best results.

T A G   C O D E:

<dpUserField name="film genre" number="all"> will return something like the following:

    romance, comedy, cult

This can be useful information when exploring suggested link matches. For example, if you want a list of up to five suggested links of other films with similar film genres as the story you are reading, use the following:

Suggested Links for <dpHeadline>:<br>

<dpQuery issue="archives" userField="film genre" sort="fuzzy" max="5">
  <dpHeadline link="on"><br>
</dpQuery>


which would output something like this:

Suggested Links for Planet of the Vampires:
  The Body Snatcher
  The Changeling
  The Exorcist
  Halloween
  House of Wax


That works perfectly, but provides little output to confirm how the match happened while debugging your templates. Here's a modification using
<dpUserField number="all"> to provide better output while testing:

Suggested Links for <dpHeadline> (<dpUserField name="film genre" number="all">)<br>

<dpQuery issue="archives" userField="film genre" sort="fuzzy" max="5">
  <dpHeadline link="on"> (<dpUserField name="film genre" number="all">)<br>
</dpQuery>

which would output something like this:

Suggested Links for Planet of the Vampires (Classic, Horror)
  The Body Snatcher (Classic, Horror)
  The Changeling (Horror)
  The Exorcist (Horror)
  Halloween (Horror)
  House of Wax (Horror)

E F F E C T:

Retrieving UDF Values

The following syntax demonstrates options for retrieving and manipulate the values associated with a User Defined Field:

T A G   C O D E:

<dpUserField name="film genre"> - comedy
<dpUserField name="film genre" number="all"> - comedy, drama, romance
<dpUserField name="film genre" number="1"> - comedy
<dpUserField name="film genre" number="2"> - drama
<dpUserField name="film genre" number="3"> - romance
<dpUserField name="film genre" return="count"> - 3
<dpUserField name="film genre" number="all" style="upper"> - COMEDY, DRAMA, ROMANCE

E F F E C T:

Customizing UDF Display

The following macro shows how to control the display of User Defined Field values which contain multiple entries:

T A G   C O D E:

Here are a few examples of the values from a User Defined Field of "film genre":

   comedy, horror, sci-fi
   comedy, horror and sci-fi
   comedy and horror and sci-fi
   comedy - horror - sci-fi

Change the separators within the macro below to get the different results shown above.

<dpMacro myUserFieldStyle>
  <dpVar totalValues="<dpUserField name="<dpVar fieldName>" return="count">">
  <dpLoop var="i" from="1" to="<dpVar totalValues>">
    <dpIf <dpVar i> = <dpVar totalValues>>
      <dpUserField name="<dpVar fieldName>" number="<dpVar i>">
    <dpElseIf <dpVar i> = <dpMath <dpVar totalValues>-1>>
      <dpUserField name="<dpVar fieldName>" number="<dpVar i>"> and
    <dpElse>
      <dpUserField name="<dpVar fieldName>" number="<dpVar i>">,
    </dpIf>
  </dpLoop>
</dpMacro>

To call this macro, use the following tag code:

<dpVar fieldName="film stars">
<dpMacro myUserFieldStyle>

This sets the variable fieldName to "film stars" so the macro knows what UDF to manipulate.

This logic can also be used for other User Defined Fields with values containing multiple entries, such as author and artist names.

E F F E C T:

Home: Support: Reference Guide: Display Tags: <dpUserField>

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