Views Arguments

Arguments are parts of the URL of a view that can be used to reduce the result-set. A classic example of an argument would be in the case of taxonomy/term/TID or tracker/UID. In the former case, the view is restricted to posts tagged with the associated taxonomy ID; in the latter case, the view becomes restricted to posts by the specified user.

There is also a special case where arguments can be embedded into a View's URL. For example, the URL /user/$arg/track would be valid on any /user/WHATEVER/track URL, and the WHATEVER would be passed into the view as the first argument.

A given view can have multiple arguments. For example, you might have blogs as a view, and provide UID, Year, Month, and Day as arguments in that order. Thus the URL might look like blogs/1/2006/3/15 which would display all blog posts written by user id #1 on March 15th, 2006. Arguments can also be specified as *, which will be interpreted as 'all values'; so in this case, blogs/*/2006/3/15 would show blog posts by ALL users on that date.

Changed as of Jun 24, 2006: Argument Titles

As of today's update, titles for pages that have arguments now work the way most people probably thought they should work.

Argument Title Overview

If a page has an argument, the title for the last argument given is used. If that argument has no title, it continues to the previous argument's title; if there are no previous arguments, it uses the page's title. All of these arguments may use % substitution.

Argument Title Example

Let's say we have a view that will select nodes with an option to specify the node author and/or the taxonomy term to which that node belongs. The first argument is a user ID, and the second argument is a taxonomy term ID. Both arguments have the Default option set to a summary view; this means that if we give no arguments, we'll get a summary view for the user ID argument, which will be a list of users.

The Page Title (which is the "Title" textbox under the "Page" panel on the Views administration page) is the title of the page when no arguments are given. Since in our example view, omitting all arguments results in a summary view of users, we'll set the Page Title to "Users".

To recap, our first argument is a user ID and the second argument is a taxonomy term ID. Applying the explanation in the Argument Title Overview above to our example we get the following order of operations:

How Views determines the title for our example view

1. If both the user ID (argument 1) and taxonomy term ID (argument 2) are specified, our Title for the second argument will be used. We set it to "User %1, Term %2" so the resulting title would be something like "User John Doe, Term Some Term".
2. If a user ID (argument 1) is given, but not a taxonomy term ID (argument 2), then the Argument Title for the first argument will be used. In this case, we set it to "Terms for %1" so the resulting title would be "Terms for John Doe".
3. If neither argument is specified, the Page Title (the "Title" textbox under the "Page" panel) will be used resulting in a title of "Users".

What if I want to specify only the SECOND argument, but not the first?

Coming back to our example, what happens if we want to find all nodes under a particular taxonomy term, but we don't care who the node author is? This is where the Wildcard and Wildcard Sub argument options come in to play. Wildcard is the URL text that can be used in place of an argument when you want to return all results for that argument. Wildcard Sub is the text that will be used in the argument title for any %1, %2, etc. substitution.

For our example view, we'll set the Wildcard for the user ID argument to "all" and set Wildcard Sub to "(All Users)". Now if we access our view at the path my_example_view/all/34, our view will return all nodes in the taxonomy term ID 34 belonging to any user and the title of our page will be taken from the argument 2 Title resulting in something like "User (All Users), Term Some Term".

Argument Type

This simply displays the name of the argument.

Default

This option tells Views what to do if an argument isn't specified. The choices are:

• Return a Page Not Found. In this case, the argument is not optional, and if not specified, the view simply isn't there, and 404s the user.
• Show all values. In this case, the argument is completely optional, and if not there is simply ignored.
• Display a Summary View. In this case, if the argument is missing Views will not display the actual view, but instead will get a list of all possible arguments and display a list of them, with links to the view with the argument, and a count of posts that argument contains. In the above example, if the User ID argument is set to a Summary View, and the user goes to 'blogs', views will provide a list of every user with at least 1 blog post.

Title

The title specified for an argument is only used if 1) that argument is the last argument present. It is used to provide different titles based upon which arguments are present. With the blogs example above, the actual Title for that view might be "Users with Blog Posts, because if the UID is not present we'll get a summary view. The title for the UID argument might simply be "Blog Posts for %1", only showing the user, since if that title is used, the rest of the date is not specified. Please note that as of Jun 24, 2006 this is a change from previous behavior.

Option

The option field is specific to a given argument; often it is not even present. If it is present, its usage should be described in the help text for that argument.

Wildcard

The URL string that can be used in place of an argument when you want to return all results for that argument, such as "all" or "*".

Wildcard Sub

The text that will be used in the argument title for any %1, %2, etc. substitution when that argument's Wildcard string was given for that particular argument.

The following is a list of arguments supported by Views by default. There can be much more than this! Modules can create argument handlers and provide them. As handlers are provided, they should all provide some form of documentation in the Views help section.

Node Type

The node type argument allows users to filter a view by specifying the type of node.

User ID Authored

The User ID argument allows users to filter to nodes authored by the specified user ID.

User ID Authored or Commented

The User ID argument allows users to filter a to nodes authored or commented on the specified user ID.

Taxonomy Term ID

The argument will filter by a taxonomy term ID. For this argument, set the option to the depth to search. See taxonomy for more information.

Taxonomy Term Name

The argument will filter by a taxonomy term name. For this argument, set the option to the number of characters, using 0 for full term; use 1 for an A/B/C style glossary.

Node Title

The argument will filter by the node title. For this argument, set the option to the number of characters, using 0 for full term; use 1 for an A/B/C style glossary.

Year

This argument allows users to filter by what year the node was posted, in the form of CCYY.

Month

Months are specified by the numbers 1-12. Since this argument does not specify a year, it is recommended that it usually follow a 'Year' argument.

Week

This allows the user to filter a view by the week number from 1-52. It is recommended this argument follow a 'Year' argument.

Month + Year

This argument combines Month and Year into a single argument, specified in the form CCYYMM.

Full Date

This argument is a complete date in the form of CCYYMMDD.

Node ID

This argument is a single Node ID.