diff --git a/docs/_images/cp-channel-new-field.png b/docs/_images/cp-channel-new-field.png new file mode 100644 index 000000000..e7ef96d49 Binary files /dev/null and b/docs/_images/cp-channel-new-field.png differ diff --git a/docs/channels/entries.md b/docs/channels/entries.md index 13cade934..7ec525e66 100755 --- a/docs/channels/entries.md +++ b/docs/channels/entries.md @@ -761,119 +761,27 @@ To show only the month of December in 2003 you'll do this NOTE: **Note:** Don't combine these parameters with the `display_by` parameter discussed previously, as these take precedence over that parameter. In addition, the three parameters must be applied "in order", meaning that you must specify the year if you specify the month and you must specify both month and year to use day. -## Single Variables +## Variables -[TOC=3 hide] - -### `{absolute_count}` - -The absolute "count" out of the current entries being displayed by the tag, including those entries on previous pages (if using pagination). - -If five entries are being displayed per page, then for the fourth entry on the second page the {absolute_count} variable would have a value of "9" - -**BONUS:** Since the Search module utilizes channel variables, {absolute_count} is also available to the Search Results tag. - -### `{absolute_results}` - -This variable will always display the absolute total number of results that are returned by the tag, regardless of pagination. - -### `{absolute_reverse_count}` - -The _opposite_ of `{absolute_count}`, in that it displays the entry count position counting backwards from the absolute total. Works across pagination, so the fifth entry in a list of fifteen entries would display "10". - -### `{author}` - -The author's screen name, if it exists; otherwise, this variable will display the username. - -### `{author_id}` - -The member ID of the author. - -### `{avatar_image_height}` - -The height of the avatar image associated with the entry's author. Typically used as such: - - {if avatar} - {author}'s avatar - {/if} - -### `{avatar_image_width}` - -The width of the avatar image associated with the entry's author. Typically used as such: - - {if avatar} - {author}'s avatar - {/if} - -### `{avatar_url}` - -The URL to the avatar image associated with the entry's author. Typically used as such: - - {if avatar} - {author}'s avatar - {/if} - -### `{channel}` - -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_.) - -### `{channel_short_name}` - -The short name of the channel of the currently displayed entry. - -### `{channel_url}` - - {channel_url} - -The [URL of the channel](control-panel/channels.md#settings-tab) the current entry belongs to, set on Control Panel. - -### `{comment_auto_path}` - -This variable is replaced by the URL set in the **Comment Page URL** preference under `Developer --> Channels` in the channel's **Settings** tab. No entry id, URL Title, or other information is included; this is the exact URL from the preference. - -### `{comment_expiration_date}` - - {comment_expiration_date format="%Y %m %d"} - -The date on which commenting expires for this entry, if they do. See [Date Variable Formatting](templates/date-variable-formatting.md) for more information. - -### `{comment_entry_id_auto_path}` - -This variable is replaced by the URL set in the **Comment Page URL** preference under `Developer --> Channels` in the channel's **Settings** tab. The ID number of the entry will be automatically added. For example, this: - - my entry - -Would be rendered like this: - - my entry +Most Channel Entries variables are rendered with a single tag. -### `{comment_subscriber_total}` +However there are some variables (most notably `{categories}` as well as some complex custom fields, such as Grid or Fluid) that need to be rendered as tag pair. -Total number of subscribers to comments for a particular entry. - -### `{comment_total}` - -The total number of comments for a particular entry. - -### `{comment_url_title_auto_path}` +Variable pairs contain an opening and closing tag as well as content in-between. Example: -This variable is replaced by the URL set in the **Comment Page URL** preference under `Developer --> Channels` in the channel's **Settings** tab. The URL Title of the entry will be automatically added. For example, this: + {date_heading}

{entry_date format="%Y %m %d"}

{/date_heading} - my entry +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. -Would be rendered like this: +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. - my entry +[TOC=3] -### `{count}` +### Entry Variables -The "count" out of the current entries being displayed. If five entries are being displayed, then for the fourth entry the {count} variable would have a value of "4". +[TOC=4] -### `{cp_edit_entry_url}` +#### `{cp_edit_entry_url}` {if logged_in} Edit Entry @@ -885,27 +793,13 @@ The URL of the entry form in the control panel where this entry can be edited. I Edit Entry {/if} -### `{edit_date}` - -The date on which the entry was last edited. See [Date Variable Formatting](templates/date-variable-formatting.md) for more information. - -### `{email}` - -The author's raw email address. - -### `{entry_date}` - - {entry_date format="%Y %m %d"} - -The date the entry was submitted. See [Date Variable Formatting](templates/date-variable-formatting.md) for more information. - -### `{entry_id}` +#### `{entry_id}` {entry_id} The ID number of the channel entry. -### `{entry_id_path}` +#### `{entry_id_path}` {entry_id_path='channel/archives'} @@ -917,139 +811,143 @@ Would be rendered like this: my entry -### `{entry_site_id}` +#### `{forum_topic_id}` -The Site ID of the channel entry. +If you have the Discussion Forum Module installed and if you have associated a forum thread with a channel entry (via the "Forum" section of the Publish tab), this is the ID number of the forum thread. It will typically be used like so: -### `{expiration_date}` + {if forum_topic} + Discuss this in our forums + {/if} - {expiration_date format="%Y %m %d"} +#### `{page_uri}` -The expiration date of the entry. See [Date Variable Formatting](templates/date-variable-formatting.md) for more information. +If you have the Pages (or Structure) 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: -### `{forum_topic_id}` + {if page_uri != ''} View this page {/if} -If you have the Discussion Forum Module installed and if you have associated a forum thread with a channel entry (via the "Forum" section of the Publish tab), this is the ID number of the forum thread. It will typically be used like so: +#### `{page_url}` - {if forum_topic} - Discuss this in our forums - {/if} +If you have the Pages (or Structure) 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: -### `{gmt_entry_date}` + {if page_url != ''} View this page {/if} - {gmt_entry_date format="%Y %m %d"} +#### `{permalink}` -The date the entry was submitted in GMT. This variable is **not** localized for each user's date settings. See [Date Variable Formatting](templates/date-variable-formatting.md) for more information. +This variable defaults to site index with entry ID number: -### `{gmt_edit_date}` + https://example.com/235/ - {gmt_edit_date format="%Y %m %d"} +In addition, you can specify a template group/template and the entry ID will automatically be added: -The date on which the entry was last edited in GMT. This variable is **not** localized for each user's date settings. See [Date Variable Formatting](templates/date-variable-formatting.md) for more information. + {permalink="channel/archives"} -### `{ip_address}` +Will render as: -The IP address of the author when they posted the entry. + https://example.com/channel/archives/235/ -### `{member_search_path}` +#### `{status}` - {member_search_path='search/results'} +The status of the entry (open, closed, etc.) -This variable is replaced by a URL that passes the author's member name to your search results Template. In this way, you can display all entries made by the author. You should specify the Template_Group/Template that you use to display search results. For example: +#### `{title}` - View entries by this member +The title of the entry -### `{page_uri}` +#### `{title_permalink}` -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: +This variable uses the "url title" as the link. It defaults to the site index with the "url title": - {if page_uri != ''} View this page {/if} + https://example.com/my_ugly_boyfriend/ -### `{page_url}` +In addition, you can specify a specific template group/template and the "url title" will automatically be added: -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: + {title_permalink="channel/archives"} - {if page_url != ''} View this page {/if} +Will render as: -### `{permalink}` + https://example.com/channel/archives/my_ugly_boyfriend/ -This variable defaults to site index with entry ID number: +NOTE: **Note:** When creating a new entry, if you don't supply the "url title" then it will be automatically created from the actual entry title. Spaces are turned into underscores and quotes are removed. For example, "Joe's night out" becomes "joes_night_out". - https://example.com/235/ +#### `{url_title}` -In addition, you can specify a template group/template and the entry ID will automatically be added: +The human readable title used in the URL as a permalink. - {permalink="channel/archives"} +#### `{url_title_path}` -Will render as: + {url_title_path='channel/archives'} - https://example.com/channel/archives/235/ +The URL to the specified template. The "url title" of the entry will be automatically added. For example, this: -### `{profile_path}` + permalink - {profile_path='member'} +Would be rendered like this: -The URL to the author of the current entry. The ID number of the author will be automatically added. Used in a link: + permalink - {author} +#### `{my_entry_custom_field}` -### `{recent_comment_date}` +Any of entry custom fields can be accessed using the field's [short name](/control-panel/field-manager/field-manager-settings.md#createedit-field) (as single tag or tag pair, whichever is supported by the [field type](/fieldtypes/overview.md)) - {recent_comment_date format="%Y %m %d"} +### Channel and Site Variables -The date of the most recent comment associated with the entry. See [Date Variable Formatting](templates/date-variable-formatting.md) for more information. +[TOC=4] -### `{relative_url}` +#### `{channel}` -The URL stored in your Channel URL setting under Channel Management, with the domain information removed. For example, if your setting is the variable will output /index.php/site/index/. Typically only used in the Atom feed Template. +The name of the channel that the currently displayed entry is assigned to. -### `{relative_date}` +#### `{channel_id}` -The amount of time that has passed between when the entry was submitted and the current time. The output is displayed in the format 1 day, 3 hours, 45 minutes. This variable is useful for displaying something such as "This entry was posted 1 day, 3 hours, 45 minutes ago." +The ID number of the actual channel (not the _entry_.) -### `{reverse_count}` +#### `{channel_short_name}` -The _opposite_ of `{count}`, in that it displays the entry count position counting backwards from the total. Like `{count}`, this is relative to the number of entries the tag is currently displaying. If you want the counts to include paginated results, you may want `{absolute_reverse_count}`. +The short name of the channel of the currently displayed entry. -### `{screen_name}` +#### `{channel_url}` -The author's screen name, if it exists. This variable will not return anything if the author does not have a screen name defined. + {channel_url} -### `{signature}` +The [URL of the channel](control-panel/channels.md#settings-tab) the current entry belongs to, set on Control Panel. -The signature associated with the entry's author. Typically used as such: +#### `{entry_site_id}` - {if signature}

{signature}

{/if} +The Site ID of the channel entry. -### `{signature_image_height}` +### `{relative_url}` -The height of the signature image associated with the entry's author. Typically used as such: +The URL stored in your Channel URL setting under Channel Management, with the domain information removed. For example, if your setting is the variable will output /index.php/site/index/. Typically only used in the Atom feed Template. - {if signature_image} - {author}'s signature - {/if} +### `{trimmed_url}` -### `{signature_image_url}` +The domain name for your site, trimmed of any subdomains. For instance, beta.example.com becomes example.com. Typically only used in the Atom feed Template. -The URL to the signature image associated with the entry's author. Typically used as such: +### Counters - {if signature_image} - {author}'s signature - {/if} +[TOC=4] -### `{signature_image_width}` +#### `{absolute_count}` -The width of the signature image associated with the entry's author. Typically used as such: +The absolute "count" out of the current entries being displayed by the tag, including those entries on previous pages (if using pagination). - {if signature_image} - {author}'s signature - {/if} +If five entries are being displayed per page, then for the fourth entry on the second page the {absolute_count} variable would have a value of "9" -### `{status}` +**BONUS:** Since the Search module utilizes channel variables, {absolute_count} is also available to the Search Results tag. -The status of the entry (open, closed, etc.) +#### `{absolute_results}` -### `{switch}` +This variable will always display the absolute total number of results that are returned by the tag, regardless of pagination. + +#### `{absolute_reverse_count}` + +The _opposite_ of `{absolute_count}`, in that it displays the entry count position counting backwards from the absolute total. Works across pagination, so the fifth entry in a list of fifteen entries would display "10". + +#### `{count}` + +The "count" out of the current entries being displayed. If five entries are being displayed, then for the fourth entry the {count} variable would have a value of "4". + +#### `{switch}` {switch='option_one|option_two|option_three'} @@ -1068,220 +966,211 @@ The entries would then alternate between `
` and `