The "Add New Query" and "Edit Query" screens consist of a large form with all the settings you need to create a query, or edit an existing query, respectively.
The Add New screen can be reached in one of two ways:
- In the top toolbar, go to Create > Query
- Go to Creator > Queries, then click “Add New”
The Edit screen can be reached by going to Creator > Queries, and then clicking on the name of the query you wish to edit.
Name
At the top of the screen is a large box where you can enter a name for your query. This should be a brief descriptive name, such as "Housing Database", "Featured Articles", or "Resource Search". This name will not appear publicly on your site.
The Settings Tab
The settings tab includes many options, but when adding a new query, you will only see one: "Query what?" After selecting a value for that option, other options will appear based on your selection.
Query What?
This is a dropdown list of all of your website's content types, including built-in types like Posts and Pages. In addition, it also includes an option for "Users", which allow you to query your site's registered users.
Once a selection is made, a "Narrow..." button will appear next to the dropdown, and an expanded list of settings will appear underneath.
The "Narrow..." option allows you to return more specific results than just a content type. Many options are available, so see the full documentation at Use "Narrow" to Limit Results.
Form
If you want this query to include a search form, check the box labeled "Include a search form". When you do, a "Form" tab will appear next to the "Settings" tab.
Additionally, a new checkbox will appear labeled "Keep form onscreen after submitting." Normally, when a query with a search form appears on your site, it will initially appear as the form only. Once you submit the form, a results page appears, without the form. By checking this box, the form will persist after it is submitted.
If that option is checked, a third option appears: "Show results before submitting form." This forces results to start appearing before any search is submitted. The form will appear at the top, with results listed underneath it. (When adding a widget or shortcode, you can also choose to display only the form, or only the results. See Queries Display Overview.)
Template
If you have SmartSimian Templates installed, this option allows you to select a template to use. This controls how each result in a query is displayed - which fields, information, and HTML markup.
If Templates is not installed, or if you haven't created any templates, a list of titles will be displayed by default.
The "Show title above template" checkbox is useful if you already have a template that doesn't include the content title. Checking the box will automatically add it to above the result.
Order
This option allows you to control the order of the results. It includes two dropdowns.
The first has two options, Ascending or Descending, which control whether the order should be low to high, or high to low, respectively.
The second dropdown controls how the order is determined. For content types, order can be determined by:
- Title
- Date published
- Date modified
- Menu order - if the content type has the "sub-pages and ordering" feature turned on, this refers to the "order" option.
- Author
- Random
- Slug - the post's lowercase-no-spaces title used in permalinks.
- ID - a unique number, assigned to the content when it is first added.
- Custom field - when this is chosen, an "Enter field name" option will appear where you can enter the custom field key.
- Existing fields - beneath the above options, any fields assigned to this content type will also be listed. (Taxonomy, connection, and instruction fields are not included.)
- Username
- Display name
- Email address
- Date registered
- Authored posts - the total number of posts on your site of which the user is set as the author.
- ID - a unique number, assigned to the user when the user is first registered.
Putting this all together, in order to display content alphabetically by title, you would select "Ascending" and "Title". To display most recent content first, you would select "Descending" and "Date Published".
Amount
The amount of content to display. If you to list paginate a large amount of results split up over multiple pages ("pagination"), this is the amount of content displayed on each page.
This is limited to 50 maximum results. Generally, anything larger than that should reasonably be split into multiple pages. Displaying too much content on a single page runs the risk of slowing down page load times.
Offset
Offset allows you to skip over a specified number of returned content.
For example, you may want to display recent posts, but skip over the most recent post. In that case, you would set offset to "1". Otherwise, you would leave offset blank.
Pagination
If your query is split up over multiple pages, Pagination allows you to add links to those pages.
These links can appear above the results, below the results, or both.
If you just need a simple list and don't want multiple pages, simply leave this at "None."
Note: by default, these links will be basic "Previous Page" and "Next Page" links. However, SmartSimian supports the popular WP-Pagenavi plugin; if activated, Pagination will instead display a more advanced set of page links.
Results Messages
Results messages contains two text boxes: "Results found" and "No results found".
Results found: the contents of Results Found will appear above a set of results. Examples:
- Displaying 1-10 of 55 pages.
- 15 results returned for "sample search phrase".
- View our available appointments below.
No results found: the contents of No Results Found will, logically, appear when no results are found to display.
Both text boxes accept HTML. In addition, a number of placeholders are available. These behave like shortcodes: you can add them into the text boxes and they will be replaced with a real value. The available placeholders are:
- [range] - The range of results you're currently looking at. For example, the second page of results with ten per page will be "10-20".
- [total] - The total number of results found across all pages.
- [content] - The label of your content type. The benefit to using this (instead of typing it in on your own) is that it will use the correct singular/plural form. For example, if only one Page is returned, it will say "Page" instead of "Pages".
- [params] - The user's search terms.
- [modify_search] - A link back to the search form, with the user's existing search terms already saved in the form.
- [new_search] - A link back to the search form, with all form data cleared out.
Container CSS classes
Before All Results
This is a text box in which arbitrary HTML can be entered. It will appear above all results.
Before Each Result
This is a text box in which arbitrary HTML can be entered. It will appear before each result in the list of results. One placeholder is available, [post_class]. This will be replaced by HTML classes with information about the result this box precedes. Sample usage: <div class="[post_class]">.
After Each Result
This is a text box in which arbitrary HTML can be entered. It will appear after each result in the list of results.
After All Results
This is a text box in which arbitrary HTML can be entered. It will appear after all results.
Sidebar
The following basic options appear in the right-hand sidebar:
Description
The description is only displayed within the WordPress admin area. It is an optional field, but can be helpful if you have multiple queries that use similar names, or even just for leaving a note for yourself, other developers, or even the client about the purpose of that query.
System Name
The system name, also referred to as the slug, is the lowercase “URL friendly” version of the name of the query. If left blank, it is generated automatically, and will contain only lowercase characters and underscores. You can choose an alternate system name if you like, but it cannot be modified again once the new query has been saved.
Shortcode
After saving a query, the shortcode will appear underneath the system name, and will be based on the system name. It is not editable. You can paste this shortcode into any page or template, and it will be replaced with the full query.
Delete/Save
Click the small red "Delete" link to delete the current query, or the large blue "Save" button to save or update the query. Note: unlike WordPress's content types, there is no "trash" for deleted queries. When you click delete, you will be asked if you are sure. Immediately after deleting, there will be a link to undo the deletion. After these two chances, however, the query will be deleted permanently.