Skip to content

added docs for orderby filename... as well as a bunch of standardizat… #1005

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 5, 2025
Merged

added docs for orderby filename... as well as a bunch of standardizat… #1005

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 31 additions & 27 deletions docs/channels/entries.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -277,7 +277,7 @@ You can hard code the channel tag to show a specific channel entry. You may also

entry_id="13|42|147"

Or use "not" to exclude entries::
Or use "not" to exclude entries:

entry_id="not 45|534|807"

Expand Down Expand Up @@ -311,15 +311,15 @@ NOTE: **Note:** Using this parameter will automatically constrain the entries ta

### `group_id=`

NOTE: We recommend using [primary_role_id=](#primary_role_id) parameter instead, which works the same but more clearly conveys that the filtering is happening on primary role ID.
NOTE: We recommend using the [primary_role_id=](#primary_role_id) parameter instead, which works the same but more clearly conveys that the filtering is happening on primary role ID.

group_id="4"

You can decide from which Member Role (by specifying the role ID) you wish entries to be shown. If you choose "4", then only entries created by members of the Primary Role with the ID of 4 will be shown. You can choose multiple Roles using a pipe:

group_id="2|3|4"

Or exclude role using "not"
Or exclude roles using "not"

group_id="not 2|3|4"

Expand Down Expand Up @@ -368,10 +368,14 @@ The `orderby` parameter sets the display order of the entries. Setting options f
- `orderby="view_count_three"`
- `orderby="view_count_four"`

In addition you can order by a [channel field](control-panel/field-manager/field-manager-settings.md). Use the "short_name" of the field:
In addition, you can order by a [channel field](control-panel/field-manager/field-manager-settings.md). Use the "short_name" of the field:

orderby="name_of_field"

You can also order results by file names:

orderby="file_field:filename"

NOTE: **Note:** Ordering by a Relationship field will cause entries to appear in the order the relationships were made, not based on any content from the related entries.

NOTE: **Note:** **Random** ordered entries have special rules applied. "Sticky" entries will not appear first; they will appear randomly with all other entries. If the tag is not paginated, each page load, a new selection of random entries will be returned. If the tag **is** paginated, then the order of the entries is randomly set on the first page load and stored for the user's session so that entries show up only once in the paginated results.
Expand All @@ -398,17 +402,17 @@ Will result in:

Default Site - Entry One - Albert
Default Site - Entry Two - Bobby
Second Site  - Entry One - Alligator
Second Site  - Entry Two - Buffalo
Second Site - Entry One - Alligator
Second Site - Entry Two - Buffalo

If you have multiple Sites where each site has a field with the same exact short name, then you can specify that short name (without the site specified) and ExpressionEngine will treat those two fields as the same value and be able to order them as if they were the same field:

orderby="body"

Default Site - Entry One - Albert
Second Site  - Entry One - Alligator
Second Site - Entry One - Alligator
Default Site - Entry Two - Bobby
Second Site  - Entry Two - Buffalo
Second Site - Entry Two - Buffalo

Thus, the output will then be ordered by the body, regardless of the originating site.

Expand Down Expand Up @@ -570,7 +574,7 @@ This example would return all results where the body field is empty.

search:body="not IS_EMPTY"

This example would return all results where the body field is **not** empty, i.e. only entries where the body field had content.
This example would return all results where the body field is **not** empty, i.e., only entries where the body field had content.

The IS_EMPTY search constant can also be used in conjunction with other search terms, for both "Exact" and "Contains" type matching.

Expand All @@ -590,13 +594,13 @@ NOTE: **Note:** You may use multiple search: parameters in a channel entries tag

{exp:channel:entries search:style="=ale" search:region="germany|belgium" search:rating="=3|4|5"}

When using multiple search parameters, all search parameters must be matched in order for an entry to be included. The above example would pull back only those entries where the style is 'ale', the region is 'germany' or 'belgium' and the rating is 1, 2 or 3.
When using multiple search parameters, all search parameters must be matched in order for an entry to be included. The above example would pull back only those entries where the style is 'ale', the region is 'germany' or 'belgium', and the rating is 3, 4, or 5.

### `show_current_week=`

show_current_week="yes"

Requires use of the [display_by=](#display_by) "week" parameter. When set to "yes", it displays the current week by default (i.e. no pagination in the URL) and automatically adjusts the pagination links to indicate the correct page for that week.
Requires use of the [display_by=](#display_by) "week" parameter. When set to "yes", it displays the current week by default (i.e., no pagination in the URL) and automatically adjusts the pagination links to indicate the correct page for that week.

### `show_expired=`

Expand Down Expand Up @@ -739,15 +743,15 @@ This parameter limits the query by username. You can use the pipe character to q

username="tom|dick|harry"

Or you can add "not" to exclude usernames
Or you can add "not" to exclude usernames:

username="not tom|dick|harry|fred"

You can also use the token `"CURRENT_USER"` to show entries from only the currently logged in user.

username="CURRENT_USER"

This allow each logged-in user to get only their entries. Users who are not logged in won't see anything. Alternatively, you can use the token `"NOT_CURRENT_USER"` to show entries **except** from the currently logged in user.
This allows each logged-in user to get only their entries. Users who are not logged in won't see anything. Alternatively, you can use the token `"NOT_CURRENT_USER"` to show entries **except** from the currently logged-in user.

username="NOT_CURRENT_USER"

Expand Down Expand Up @@ -791,7 +795,7 @@ If five entries are being displayed per page, then for the fourth entry on the s

### `{absolute_index}`

Similar to `absolute_count` but starts at 0 instead of 1. So the first entry will have value of "0" and the second entry will have a value of "1" etc.
Similar to `absolute_count` but starts at 0 instead of 1. So the first entry will have a value of "0" and the second entry will have a value of "1", etc.

### `{absolute_results}`

Expand Down Expand Up @@ -839,7 +843,7 @@ The name of the channel that the currently displayed entry is assigned to.

### `{channel_id}`

The ID number of the actual channel (not the _entry_.)
The ID number of the actual channel (not the _entry_).

### `{channel_short_name}`

Expand Down Expand Up @@ -969,7 +973,7 @@ The date on which the entry was last edited in GMT. This variable is **not** loc

### `{index}`

Similar to `count` but starts at 0 instead of 1. So the first entry will have value of "0" and the second entry will have a value of "1" etc.
Similar to `count` but starts at 0 instead of 1. So the first entry will have a value of "0" and the second entry will have a value of "1", etc.

### `{ip_address}`

Expand All @@ -985,13 +989,13 @@ This variable is replaced by a URL that passes the author's member name to your

### `{page_uri}`

If you have the Pages Module installed and if you have associated a static page with a channel entry (via the "Pages" section of the Publish tab), this is the page uri for the page. It will typically be used like so:
If you have the Pages Module installed and if you have associated a static page with a channel entry (via the "Pages" section of the Publish tab), this is the page URI for the page. It will typically be used like so:

{if page_uri != ''} <a href="{page_uri}">View this page</a> {/if}

### `{page_url}`

If you have the Pages Module installed and if you have associated a static page with a channel entry (via the "Pages" section of the Publish tab), this is the page url for the page (the site URL + the page URI). It will typically be used like so:
If you have the Pages Module installed and if you have associated a static page with a channel entry (via the "Pages" section of the Publish tab), this is the page URL for the page (the site URL + the page URI). It will typically be used like so:

{if page_url != ''} <a href="{page_url}">View this page</a> {/if}

Expand Down Expand Up @@ -1071,7 +1075,7 @@ The width of the signature image associated with the entry's author. Typically u

### `{status}`

The status of the entry (open, closed, etc.)
The status of the entry (open, closed, etc.).

### `{switch}`

Expand Down Expand Up @@ -1156,19 +1160,19 @@ Conditionals allow you to more precisely control your content.

NOTE: **Note:** A more complete explanation of conditional control structures and operators can be found on the [Conditional Tags](templates/conditionals.md) page.

Here is an example that tests for the "summary" field being not empty
Here is an example that tests for the "summary" field being not empty:

{if summary != ""}
The summary is not empty!
{/if}

An alternate, shorthand syntax can accomplish the same thing
An alternate, shorthand syntax can accomplish the same thing:

{if summary}
The summary is not empty!
{/if}

If only the variable name is in the conditional statement it tests for "not empty".
If only the variable name is in the conditional statement, it tests for "not empty".

Many of the single variables can be used in a conditional. You may always use the short name of one of your custom entry fields in a conditional. In addition, there are several unique conditionals.

Expand Down Expand Up @@ -1250,7 +1254,7 @@ Lastly, if you want to simply display your 404 page (with 404 headers) when no e

NOTE: **Note:** If you have several nested tags, each one would need to include a `{if no_results}` pair to be parsed correctly.

For instance, if you have Grid field with `{if no_results}` block, the parent `{exp:channel:entries}` tag pair would need to include `{if no_results}` block as well.
For instance, if you have a Grid field with an `{if no_results}` block, the parent `{exp:channel:entries}` tag pair would need to include an `{if no_results}` block as well:
```
{exp:channel:entries channel="blog"}
{if no_results} No entries {/if}
Expand Down Expand Up @@ -1297,13 +1301,13 @@ You may test whether an entry is set to be "sticky". You may also test whether i

[TOC=3]

Variable pairs contain an opening and closing tag as well as content in-between. Example:
Variable pairs contain an opening and closing tag as well as content in between. Example:

{date_heading} <h1>{entry_date format="%Y %m %d"}</h1> {/date_heading}

The reason variable pairs have an opening and closing pair is because the information between the pairs can be shown or not shown if the criteria for each tag is met.

In the case of the "date_heading" pair, for example, it only appears at a certain interval that you set (hourly, daily, weekly, monthly, etc.). By using a pair of variables you can put HTML formatting between them that only gets shown when the interval is met. Otherwise, the chunk is not displayed.
In the case of the "date_heading" pair, for example, it only appears at a certain interval that you set (hourly, daily, weekly, monthly, etc.). By using a pair of variables, you can put HTML formatting between them that only gets shown when the interval is met. Otherwise, the chunk is not displayed.

### `{date_footer}`

Expand Down Expand Up @@ -1462,9 +1466,9 @@ The category ID associated with the category's parent (or 0 in the case of a top

{path='channel/index'}

This variable will be replaced by a URL to the specifies Template Group/Template. The category designation information will automatically be added to the end of the URL so that the target page will know which category to display.
This variable will be replaced by a URL to the specified Template Group/Template. The category designation information will automatically be added to the end of the URL so that the target page will know which category to display.

If you want the category links to point to your site index instead of a particular template group/template you can use SITE_INDEX instead:
If you want the category links to point to your site index instead of a particular template group/template, you can use SITE_INDEX instead:

{categories} <a href="{path='SITE_INDEX'}">{category_name}</a> {/categories}

Expand Down