<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

Home: Support: Reference Guide: Queries: <dpQuery>

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