Intro to Query Wrangler

If you're familiar with Drupal Views then you'll be right at home with Query Wrangler. If you've never used Drupal's views you'll be pleasantly surprised with how easy it is to build a powerful query and display it as a widget or a page.

Adding a Query

Query name

Give the query a name. This name is only displayed to the admin, not the user.

Query Type

• Widget Query: Create a query that will be available as a widget to place in the sidebar.
• Page Query: Create a query that becomes it's own page. This query required you to give it a page path where the query can be seen. For example you want to list all of the users that are Editors on your site. Create a Page Query and set the page path to team/members. Then when users go to [yoursite.com]/team/members they will see the query.
• Override Query: Create a Query that takes the place of an existing WordPress page such as the Catagory or Tag pages display.

Basic Settings

Title

This is the title that will be displayed to the user with your query

Style

• Full Posts means that all of the fields associated with a post or a page will be displayed in the query. Fields means that you can decide to only show certain fields from the post in the query. This would be useful if you only wanted to show the titles of posts, or maybe titles and dates but not the teaser.
• Full Settings: If you've selected Full as the style you can set the Full Settings to either Complete or Excerpt. This means that the body of the post will either show completely or only an excerpt will be displayed in the query.
• Field Settings: If you've selected Field as the style you can set the Field Settings to unformatted, unordered list or ordered list. This governs how each query entry will be displayed. For instance if you select unformatted each row of the query will be displayed in a <div> element. If you select unordered each row will be displayed as a bulleted item in an unordered HTML list. Selecting ordered list will display the rows as a numbered item in an ordered HTML list.

Items per page

Items per page allows you to set how many items should be displayed on each page or widget.

Offset

Offset allows you to skip a certain number of items at the beginning of the query. For example if you have a list of posts: post 1, post 2 and post 3 with no offset they would be displayed normally. But if you change the offset to 1 the display will be post 2 and post 3. Changing the offset to 2 would only display post 3.

This is useful if you have two widgets close together, one is for featured items and the other is for the rest of the items. You can use the same query parameters but set the Items per page on the Featured widget to 1. Then on the second widget set the items per page to however many other items you want to show and set the offset to 1. This way the featured item in the first widget will be skipped.

Sort Options

Order by
The order by option allows you to select how you'd like to order your query items. The options are:

• None: No sorting is used
• Post ID: Items are sorted by their post ID
• Author: Items are sorted alphabetically by their Author
• Title: Items are sorted alphabetically by their Title
• Date: Items are sorted chronologically by their post date
• Modified: Items are sorted chronologically by their last modified date
• Parent: Items are sorted alphabetically by their Parent
• Random: Items are sorted randomly
• Comment Count: Items are sorted by their comment count. This is a good way to sort for popularity
• Menu Order: Items are sorted by their menu order. This only applies to Page types

Order

You can select whether to display the items in ascending or descending order. Ascending order is forwards like an alphabetical sort, descending order is backwards like dates from the future to the present.

Header

This is a place to put content or markup to appear above the query. This only appears once over the whole query, not above each row within the query.

Footer

This is a place to put content or markup to appear below the query. This only appears once below the whole query, not above each row within the query.

Empty Text

This is the text displayed if the query returns no results. This is useful for dates "No upcoming events found" or for other purposes "There are no users who are Editors"

CSS Classes

Here you can add a custom CSS class that will be placed on the query so you can style it any way you'd like.

Filters

Filters allow you to only include the content you want in your query and filter out everything you don't want.

Post Types

You can select which post type you want to include in your query

Post Status

• Published: only allow published content in the query. This would be good for a list of posts with the highest number of comments.
• Pending: only allow pending content in the query. You could use this for an admin widget showing an Editor how many posts are pending review.
• Draft: only allow draft content in the query. Filtering by Draft could be used to show a user how many posts they have saved as draft.
• Future (Scheduled): only allow content that is scheduled for the future. Tease users with the titles of upcoming articles to keep interest high.
• Trashed: only allow content that has been trashed. Make a widget for admins to keep an eye on content being thrown out around the site.

Catagories

Filter content by the catagory it's in. Multiple catagories can be selected at once.

Catagory Options:

• Any catagory plus children catagories: Include catagories that are children of the selected catagories.
• Any catagory without children catagories: Use content from any catagory that does not have any child catagories.
• All Catagories selected: include content from all selected catagories.
• Not in the catagories selected: This is a negative selection. If you have the catagories Baseball, Basketball, Football and Hockey and check Hockey and Football normally that would include content only from Hockey and Football. But if you select Not in the catagories selected with Hockey and Football checked the query will pull content from all catagories but those two.

Tags

Filter content by tags. Multiple tags can be selected at once.

Tag Options

• Any of the selected tags: If multiple tags are selected and content has any one of those tags it will be included
• All of the selected tags: If multiple tags are selected content will not be included unless it has all the tags selected.
• None of the selected tags: If multiple tags are selected content will be included as log as it doesn't have any of the selected tags.

Page Parent

Page content will only be included if it's parent is the same at the one listed in this field

Fields

If you selected Fields in the Style option under Basic Settings you'll get a new set of options allowing you to add specific fields.

Add Fields

You will be shown all of the available fields associated with the Post Types you've selected in the Filters section. You can select as many as you'd like. Once you've selected the fields click Add Selected Fields.

You can then click on each field to fine-tune its display:

• Exclude this field from display: This will include the data in the query but not display it. This is useful if other fields use this one for calculations
• Link this field to the post: Clicking this will make the field link to it's post page. This is very useful for Title fields and fields used for custom "read more..." links.
• Create Lable for this field: Create a label to display with the field. This is useful if you have a field that's a plain number with no explaination.
• Rewrite the output of this field: If you'd like to customize how the field is output click this. It gives you access to tokens representing all of the fields that are selected before it. Using this and the Exclude this field from display you can make a field display complex inline values.

Rearrange Fields

Rearrange the order that the fields are displayed. This is also helpful when you are hiding the output of some fields and rewriting their contents with others. Make sure the field that is rewriting the others is arranged after the hidden fields so it has access to their values as tokens.