 |
<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.
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
|
A D D I T I O N A L < D P Q U E R Y > E X A M P L E S:
S E E A L S O:
Other tag examples that incorporate <dpQuery>
|
|
Print Friendly Version