From 3a182d196da1fb10bc59429429c0790c24c0bb1d Mon Sep 17 00:00:00 2001 From: Yuri Salimovskiy Date: Fri, 19 Jan 2024 14:52:34 +0200 Subject: [PATCH] migrated Structure docs --- docs/add-ons/structure/examples.md | 336 ++++++ docs/add-ons/structure/overview.md | 35 +- docs/add-ons/structure/page-types.md | 92 ++ docs/add-ons/structure/tags.md | 1218 +++++++++++++++++++++ docs/toc_sections/_advanced_usage_toc.yml | 12 +- 5 files changed, 1688 insertions(+), 5 deletions(-) create mode 100644 docs/add-ons/structure/examples.md create mode 100644 docs/add-ons/structure/page-types.md create mode 100644 docs/add-ons/structure/tags.md diff --git a/docs/add-ons/structure/examples.md b/docs/add-ons/structure/examples.md new file mode 100644 index 000000000..59b389a0d --- /dev/null +++ b/docs/add-ons/structure/examples.md @@ -0,0 +1,336 @@ + + +# Structure Examples + +[TOC] + +## Navigation Examples + +### Main Navigation + + Restrict navigation to only the top level pages: + + {exp:structure:nav start_from="/" max_depth="1"} + +### Sitemap and All Navigation + + Show all pages within your site: + + {exp:structure:nav start_from="/" show_depth="999"} + +### Sub Navigation + + This version of the tag reveals children of the current page as you drill down within your hierarchy. + + {exp:structure:nav start_from="/{segment_1}"} + +### Adding An Overview (Parent) Link To Sub Navigation + + - `show_overview=“yes”`: Add a link to the top of your navigation that links to the top parent + - `rename_overview=“Overview”`: Change the title of the link to your top level parent page. + + {exp:structure:nav + start_from="/{segment_1}" + show_overview="yes" + rename_overview="Overview"} + + This will add the following to the beginning of your navigation list: + +
  • Top Level
    • + + You can also manipulate sub navigation instances using show_depth and max_depth to reveal more levels at one (show_) or restrict how deep users can drill down the hierarchy (max_). + +### Structure Nav Basic Example + + {exp:structure:nav_basic show_depth="4"} + {if root:count == 1} + + {/if} + + {root:title} + {if root:has_children} +
      + {root:children} + + {child:title} + {if child:has_children} + + {/if} + + {/root:children} +
    + {/if} + + {if root:count == root:total_results} + + {/if} + {/exp:structure:nav_basic} + + +### Structure Nav Advanced Example + + {exp:structure:nav_advanced show_depth="4"} + {if root:count == 1} + + {/if} + {/exp:structure:nav_advanced} + + +## Sibling Tag Examples + +The sibling tag allows you to traverse back and forth through the current page's entries using tag pairs and variables within the tag. It is intended for normal pages within the hierarchy and not listing entries. An example for listings follows the sibling tag below. + +### Linking to Page's Siblings + + {exp:structure:siblings} + {prev} + Prev: {title} + {/prev} + {next} + Next: {title} + {/next} + {/exp:structure:siblings} + +### Linking to Listing Entry's Siblings + + {exp:channel:next_entry channel="news"} + Previous Page + {/exp:channel:next_entry} + {exp:channel:prev_entry channel="news"} + Next Page + {/exp:channel:prev_entry} + + +## Conditionally Display Sub Navigation or HTML + +You can conditionally display the sub navigation and/or any surrounding HTML using the following parameters with nav_sub: + + {if structure:child_ids != ''} +
    + {exp:structure:nav start_from="/{segment_1}"} +
    + {/if} + +Additionally, you can show alternate markup or content using if:else as follows: + + {if structure:child_ids != ''} +
    + {exp:structure:nav start_from="/{segment_1}"} +
    + {if:else} + No children! + {/if} + +## Displaying Child Page Content (Structure Entries Examples) + +You can use the Structure Entries tag to output the children of a specific parent: + + {exp:structure:entries parent_id="9"} +

    {title}

    +

    {page_uri}

    + {/exp:structure:entries} + +## Conditionally Display Content If A Page Has Children + + {if '{structure:child_ids}' != ''} +

    This page has children!

    + {if:else} +

    This page does NOT have children!

    + {/if} + +## Comments + +### Comment Entries + + {exp:comment:entries entry_id="{structure:page:entry_id}" parse="inward"} + + +### Comment Form + + {exp:comment:form channel="blog" entry_id="{structure:page:entry_id}" parse="inward"} + + +### Channel Form + +The following are examples to integrate your Structure site with Channel Form to have full creating and editing capabilities. + +### Creating A New Listing Entry + + You can choose to make certain values editable or not, notes are listed inline below: + + {exp:channel:form channel="your-listing-channel" return="/your-return-url"} + + + + +

    Title:

    + +

    Structure URI:

    +

    + {/exp:channel:form} + +### Creating a New Page + + You can choose to make certain values editable or not, notes are listed inline below: + + {exp:channel:form channel="your-page-channel" return="/your-return-url"} +

    Title:

    + +

    Template: {exp:structure:saef_select type="template"}

    + +

    Parent: {exp:structure:saef_select type="parent"}

    + +

    Structure URI:

    +

    + {/exp:channel:form} + + +### Editing a Listing Entry + + When editing entries, you can use existing segments or an addon like Freebie to create additional ones to feed into your channel:form tag below: + + {exp:channel:form channel="your-listing-channel" entry_id="{some_segment}" return="/your-return-url"} + +

    Title:

    + +

    Template: {exp:structure:saef_select type="template" entry_id="{entry_id}"}

    + +

    Parent: {exp:structure:saef_select type="parent" entry_id="{entry_id}"}

    +

    Structure_uri:

    +

    + {/exp:channel:form} + +### Editing a Page + When editing entries, you can use existing segments or an addon like Freebie to create additional ones to feed into your channel:form tag below: + + {exp:channel:form channel="your-page-channel" entry_id="{some_segment}" return="/your-return-url"} + +

    Title:

    + +

    Template: {exp:structure:saef_select type="template" entry_id="{entry_id}"}

    + +

    Parent: {exp:structure:saef_select type="parent" entry_id="{entry_id}"}

    +

    Structure_uri:

    +

    + {/exp:channel:form} + +## Pro Variables + +By default, the variable created (e.g. `{some_variable}`) will only return a page's entry_id, but if you use the full tag (e.g. `{exp:pro_variables:parse var="some_var"}`) it will return the full url. + +## Duplicate Pages in Navigation + +You can have pages live in more than one place in your navigation by creating a redirect to one “official” place the page lives. + +- Create a new template called “internal_link” with a PHP redirect and the custom field name for the URL value (PHP code below) +- Allow this template to use PHP under the template preferences +- Make a new channel named “Internal Link” with a custom field using only our StructureFrame fieldtype +- Make this channel managed by Structure under the module channel settings and set the default template to your new “internal_link” template +- Assign a new page to this new channel (named the exact same title if desired) and upon visiting you will be redirected to the original page location + + + +**Note:** Make sure your channel has "Automatically turn URLs and email addresses into links?" turned off under the channel settings + +## Linking to an External Page or File in Navigation + +You can have pages link offsite or even to files using the following method: + +- Create a new template called “external_link” with a PHP redirect and the custom field name for the URL value (PHP code below) +- Allow this template to use PHP under the template preferences +- Make a new channel named “External Link” with a custom field that is either a text field (to input a URL offsite) or a file upload field (to link to a PDF, Word doc, etc) +- Make this channel managed by Structure under the module channel settings and set the default template to your new “external_link” template +- Assign a new page to this new channel (named the exact same title if desired) and upon visiting you will be redirected to the external page or file + + + + **Note:** Make sure your channel has "Automatically turn URLs and email addresses into links?" turned off under the channel settings + +## Multi Language Sites + +The recommended method is to have your default language at the top level and make separate branches for your alternate languages like this: + +- /about +- /services +- /contact +- /es/about +- /es/services +- /es/contact +- /fr/about +- /fr/services +- /fr/contact + +You can then use the nav_sub tag and either the start_from or exclude_status parameters. When using exclude_status you can assign statuses by language to control the output. + +### Example nav_sub code: + + {if segment_1 'es' OR segment_1 'fr'} + {!-- START FROM SEGMENT 2 IF NOT DEFAULT LANGUAGE --} + {exp:structure:nav start_from='/{segment_1}/{segment_2}'} + {if:else} + {!-- START FROM SEGMENT 1 IF DEFAULT LANGUAGE --} + {exp:structure:nav start_from='/{segment_1}'} + {/if} + + This method does not require different custom fields per language as they’re all separate pages powered by the same code and quite often the same templates. + \ No newline at end of file diff --git a/docs/add-ons/structure/overview.md b/docs/add-ons/structure/overview.md index 333aebeb7..3718ad821 100644 --- a/docs/add-ons/structure/overview.md +++ b/docs/add-ons/structure/overview.md @@ -3,7 +3,7 @@ ExpressionEngine User Guide (https://github.com/ExpressionEngine/ExpressionEngine-User-Guide) @link https://expressionengine.com/ - @copyright Copyright (c) 2003-2020, Packet Tide, LLC (https://packettide.com) + @copyright Copyright (c) 2003-2024, Packet Tide, LLC (https://packettide.com) @license https://expressionengine.com/license Licensed under Apache License, Version 2.0 --> @@ -13,4 +13,35 @@ Structure is a powerful add-on that lets you create pages, generate navigation, It forgoes the default template_group/template setup and creates “static” and “listing” pages that are all editable through a tree sitemap view. With Structure enabled, traditional page style content and multiple entry pages can live within the same area. -NOTE:**Note:** Documentation for Structure is still being migrated. Until this is complete, please reference the [Structure documentation on EEHarbor's website](https://eeharbor.com/structure/documentation). \ No newline at end of file +[*Tags*](add-ons/structure/tags.md) + +## Module Settings + +Use Module Settings page in Structure control panel to provide the settings for Structure behavior and appearance. + +You can also set up individual permissions for the members roles that are allowed to access Structure add-on (as set on [Role Setting](control-panel/member-manager.md#role-settings) page) + +## Channel Settings + +Before Structure can be used, it is important to set the channels you want to use with it. Channel Settings page in Structure add-on control panel is listing all channels in your site. You can select which channels you want to use with Structure and set the page type for each channel. + +### Channel Name +All existing channels will display within your channel settings. + +### Page Type +Structure has three [page types](add-ons/structure/page-types.md) to use within your site. + +### Show in page selector +This determines if this channel is available from the global or in-row "Add Page" controls. Only available for channels of the type "Page". + +### Default template +Channels of the type "Page" or "Listing" have defaults templates assigned to them that are used when new entries are created. This does not affect existing entries. + +### Make each entry a single asset +Channels of the type "Asset" have the option to Add/Edit all entries. With this enabled, each entry you add is a single editable item and authors can not add more entries. This is useful for specific bits of copy or finite items someone does not need access to add more of. + +## Page Types + +All content is displayed using normal channel tags, but depending on the content type you can use different Structure page types to accomplish your hierarchy. Structure believes everything on your site should be editable through a single interface, so we provide several page type to manipulate your content within. + +[Read about page types here](add-ons/structure/page-types.md) diff --git a/docs/add-ons/structure/page-types.md b/docs/add-ons/structure/page-types.md new file mode 100644 index 000000000..8acbae225 --- /dev/null +++ b/docs/add-ons/structure/page-types.md @@ -0,0 +1,92 @@ + + +# Page Types in Structure + +[TOC] + +## Pages + +Pages are generally what are referred to as “static pages”, but can be posted anywhere in your hierarchy to any channel you choose. This means they can use any custom fields as well to tailor your content as needed. Pages show up in Structure navigation tags and the main CP site tree. Pages are also containers for listings. + +### Create Pages + - Assign a channel to the type “Page” under Structure » Channel Settings and assign it the default template you want your pages to use + - Start building your site tree through the Structure CP using the “add page” control or through the Publish tab + - When adding or editing an entry there is a Structure tab in which you can customize the page URL or assign it to a template other than the default one you assigned under settings + - No matter what template your channel is assigned to use under the settings, templates can be changed any time per page by editing the “Template” dropdown under the Structure tab when editing an entry + - You can use Structure `nav_main` and `nav_sub` tags to link to all of your pages in various ways + - Further pages can be added by the same method and assigning parents under the Structure tab or through the “add page” link next to each page + +### Displaying Content +Pages are shown using basic channel tags and methods you already use building EE sites. The same rules apply, except that you can not include dynamic="off" because Structure needs this to find the current page through the URL you are accessing. Structure will match that with the appropriate entry and display it based off the URL. + + {exp:channel:entries channel="your-page-channel"} +

    {title}

    + {custom-field-name} + {/exp:channel:entries} + +## Listings + +Listings must be attached to a page and connect to a channel to enable easy adding and editing. Listing entries do not show up in the structure hierarchy, but still have URLs and Structure data posted to them. Listings are generally used for content that appears on a single page and clicks through to a detail - like a listing of news, blog posts, etc. However, they can be used to display multiple entries on a single page, since all content is still shown through channel tags. When something consists of multiple entries and does not need to appear within the site navigation, listings are a great solution. + +### Create Listings + **NOTE:** Listings must be attached to a page and the channel used for a listing can not have any Structure data posted to it to avoid duplicate URLs and hierarchy. + - Assign a channel to the type “Listing” under Structure » Channel Settings and assign it the default template you want your pages to use + - Edit the page you want to attach your listing to + - Click the Listing checkbox and select the channel you assigned in the first step + - Save and return to the Structure CP + - You can now add/edit entries in this channel attached to the original page + +### Using Listings +Listings are always attached to another page, each entry in the listing contains page data (like URLs) of their own. They are effectively subpages of the containing page, but do not show up in the navigation hierarchy. Listings are useful for any content that is generally a large set, are not structural, but appear in a list on the containing page - like events, news, blog posts, etc. They generally click through to some kind of detail page, but they can also be used for smaller sets if you do not want the entries to appear within navigation, but output on a single page, like staff bios. + +When visiting the containing page, listings are just like displaying entries as you normally do in EE when unrelated to the current template or URL. Because we want to display data unrelated to the current page, adding dynamic="off" tells EE to display a listing of entries other than the current page. This way, you can still have page data and content associated with a page containing a listing and show the actual listing entries. You link to pages with page_url and page_uri instead of the traditional template_group/template permlink method. + +
      + {exp:channel:entries channel="your-listing-channel" dynamic="no"} +
    • {title}
      • + {/exp:channel:entries} +
    + +## Assets + +Assets do not contain Structure data or page URLS and are meant as buckets of information that will be called into other templates and sections. For example: banner ads, snippets of text used in callouts and entries that will be related to pages. Assets are normal entries, so they can still be called through the regular templating system as needed. + +### Example: Callout Text + +Assets are useful for calling entries into pages as support content or relating pages to them. If you enable the "Split Assets Per Entry" option each entry you create will become its own asset, instead of acting as a bridge to Add/Edit multiple entries. + + + {exp:channel:entries channel="your-asset-callout-channel" entry_id="XX"} +

    Featured Event

    +

    {title}

    +

    {custom-field-name}

    + {/exp:channel:entries} + +### Example: Random entries + +Calling an exact entry can give your clients a way to edit specific bits of content displayed wherever you choose: + +

    Sponsors

    + {exp:channel:entries channel="your-asset-callout-channel" orderby="random" limit="2"} + title + {/exp:channel:entries} + +### Example: Related Entries + +Assets can also be used as support information that can be shared among any channels on your site by using Relationship field. If you had an “Instruments” channel containing entries for vocals, guitar, bass and drums you could relate each entry to a band member and display it using the following, where “member-instruments” is your related custom field: + + {exp:channel:entries channel="your-band-member-channel"} +

    {title}

    +
      + {member-instruments} +
    • {title}
      • + {/member-instruments} +
    + {/exp:channel:entries} \ No newline at end of file diff --git a/docs/add-ons/structure/tags.md b/docs/add-ons/structure/tags.md new file mode 100644 index 000000000..aec66395b --- /dev/null +++ b/docs/add-ons/structure/tags.md @@ -0,0 +1,1218 @@ + + +# Structure Tags + +[TOC=3] + +### `{exp:structure:breadcrumb}` + +The breadcrumb tag displays in a standardized format and has a few parameters to control its output. + +#### Parameters + +##### `channel:title` + +defaults to entry title (when unset) + +Uses a specific custom field per channel instead of the default title variable. + + {exp:structure:breadcrumb channel:title="channel:custom_field|channel_2:custom_field_2"} + +##### `home_link` + +Used to change the Home link to an alternate URL. Useful for multi language sites. + + {exp:structure:breadcrumb home_link="/fr"} + +##### `inc_here` + +accepts: "y","n" + +Default: y + + {exp:structure:breadcrumb inc_here="yes|no"} + +###### `inc_home` + +accepts: "y","n" + +Default: y + + {exp:structure:breadcrumb inc_home="yes|no"} + +###### `inc_separator` + +accepts: "y","n" + +Default: yes + + {exp:structure:breadcrumb inc_separator="no"} + +###### `add_last_class` + +Adds a class of last to your trail + +Default: yes + + {exp:structure:breadcrumb add_last_class="no"} + +###### `here_as_title` + +accepts: "y","n" + +Default: defaults to no + + {exp:structure:breadcrumb here_as_title="yes"} + +###### `rename_home` + +yes/no + +Used to change the Home link text to an alternate word. Useful for multi language sites. + + {exp:structure:breadcrumb rename_home="Casa"} + +###### `separator` + +Spaces are automatically added around the element for you. + + {exp:structure:breadcrumb separator=":"} + +###### `uri` + +Useful for search results pages to show where item was found (Example: "Found in About » News") + + {exp:structure:breadcrumb uri="/tags/breadcrumbs/"} + +###### `wrap_each` + +Do not include < or > around tag, Structure writes it for you. + + {exp:structure:breadcrumb wrap_each="li"} + +###### `wrap_here` + +Do not include < or > around tag, Structure writes it for you. + + {exp:structure:breadcrumb wrap_here="em"} + +###### `wrap_separator` + +Do not include < or > around tag, Structure writes it for you. + + {exp:structure:breadcrumb wrap_separator="span"} + +### `{exp:structure:entries}` + +A replacement for the channel tag to call a parent's children. You can use all of the same variables as a channel tag within it + +#### Parameters + +###### `parent_id` + +Assign which children to show within the entires tag. 0 shows top level. + + {exp:structure:entries parent_id="8"} + +###### `include_hidden` + +defaults to no + +Shows pages marked as hidden. + + {exp:structure:entries include_hidden} + +### `{structure:}` + +A library of global variables related to the current page. Variables will not work inside snippets. + +#### Variables + +###### `child_listing:channel_id` + +The channel ID of a channel attached as a listing + + {structure:child_listing:channel_id} + +###### `child_listing:short_name` + +The channel short name of a channel attached as a listing + + {structure:child_listing:short_name} + +###### `is:page` + +Returns 1 or blank for the current page + +Detects if the current page is a page type of "Page" in Structure » Channel Settings + + {structure:is:page} + +###### `is:listing` + +Returns 1 or blank for the current page + +Detects if the current page is a listing detail page + + {structure:is:listing} + +###### `is:listing:parent` + +Returns 1 or blank for the current page + +Detects if the current page is a page type of "Listing" in Structure » Channel Settings (has a listing attached to it) + + {structure:is:listing:parent} + +###### `page:entry_id` + +The current page's "entry_id" variable + + {structure:page:entry_id} + +###### `page:title` + +The same as EE's native "title" variable + + {structure:page:title} + +###### `page_title_for:XXX` + +The title of a specific entry using the entry ID (in place of XXX) + + {structure:page_title_for:XXX} + +###### `page:slug` + +The segment for the current page + + {structure:page:slug} + +###### `page_slug_for:XXX` + +The slug of a specific entry using the entry ID (in place of XXX) + + {structure:page_slug_for:XXX} + +###### `page:uri` + +The same as EE's native "page_uri" variable + + {structure:page:uri} + +###### `page_uri_for:XXX` + +The URI of a specific entry using the entry ID (in place of XXX) + + {structure:page_uri_for:XXX} + +###### `page:url` + +The same as EE's native "page_url" variable + + {structure:page:url} + +###### `page_url_for:XXX` + +The URL of a specific entry using the entry ID (in place of XXX) + + {structure:page_url_for:XXX} + +###### `child_ids` + +Returns IDs of children for the current page. Example: "24" or "4|8|5|16|23|42" + + {structure:child_ids} + +###### `sibling_ids` + +Returns IDs of sibling for the current page. Example: "24" or "4|8|5|16|23|42" + + {structure:sibling_ids} + +###### `child_ids_for:XXX` + +Returns IDs of children for a specific page (use the entry ID in place of XXX) + + {structure:child_ids_for:XXX} + +###### `parent:entry_id` + +The entry ID of the current page's parent + + {structure:parent:entry_id} + +###### `parent:slug` + +The single segment of the URL/URI of the current page's parent + + {structure:parent:slug} + +###### `parent:uri` + +The full URI of the current page's parent + + {structure:parent:uri} + +###### `parent:url` + +The full URL of the current page's parent + + {structure:parent:url} + +###### `top:entry_id` + +The entry ID of the current page's top level parent + + {structure:top:entry_id} + +###### `top:title` + +The "title" variable of the current page's top level parent + + {structure:top:title} + +###### `top:slug` + +The single segment of the URL/URI of the current page's top level parent + + {structure:top:slug} + +###### `top:uri` + +The full URI of the current page's top level parent + + {structure:top:uri} + +###### `top:url` + +The full URL of the current page's top level parent + + {structure:top:url} + +### `{exp:structure:nav}` + +The nav tag is intended for all navigation within your Structure site and will automatically add class="here" to the current page’s +and class="last" to the last. Examples of each parameters usage can be found in our navigation documentation examples. + +#### Parameters + +###### `add_level_classes` + +defaults to no + +Displays class="level_1", class="level_2", etc on each li + + {exp:structure:nav add_level_classes="yes|no"} + +###### `add_span` + +defaults to no + +Adds a span tag around each individual navigation element within the a tag. + +accepts: "y","n" + + {exp:structure:nav add_span="yes|no"} + +###### `add_unique_ids` + +defaults to no + +Adds a unique ID to the a tag using the top parent slug, default seperator and pageslug or entry ID. + + {exp:structure:nav add_unique_ids="yes|entry_id|no"} + +###### `css_class` + +Assigns a class to the ul. + + {exp:structure:nav css_class="sub_navigation"} + +###### `css_id` + +Assigns an ID to the ul. You can add "none" to optionally display no ID. + + {exp:structure:nav css_id="sub_navigation"} + +###### `current_class` + +defaults to here + +Change the class name added to the current page's li tag. + + {exp:structure:nav current_class="active"} + +###### `channel:title` + +defaults to entry title (when unset) + +Uses a specific custom field per channel instead of the default title variable. + + {exp:structure:nav channel:title="channel_name:field_name|another_channel:another_field"} + +###### `exclude` + +The parameter "exclude=" can be used to hide any single or multiple user defined entry numbers using the pipe character. All children under a specified ID will be hidden as well. + + {exp:structure:nav exclude="24"} + +###### `has_children_class` + +defaults to no + +Adds a class to pages that have children as an additional tiling hook. + +accepts: "y","n" + + {exp:structure:nav has_children_class="yes|no"} + +###### `include` + +integer + +The parameter "include=" can be used to selectively show specific pages from the same level. + + {exp:structure:nav include="24" } + +###### `include_ul` + +yes/no + +defaults to yes + +Conditionally output the surrounding ul tag. + + {exp:structure:nav include_ul="yes|no" } + +###### `max_depth` + +Only show up to XX levels deep from the current start_from parameter. Useful to hide pages under a desired level (like thank you or confirmation pages) or for main navigation. + + {exp:structure:nav max_depth="2"} + +###### `mode` + +defaults to sub + +Options are "sub", "main", and "full". + +Replacement for EE1's nav_main, nav_sub, and nav_full tags. + +_sub_: only displays 2 levels and any children on the same level of the same branch + +_full_: show the full tree + +_main_: show top nav but never any children + + {exp:structure:nav mode="sub"} + +###### `override_hidden_state` + +defaults to no Show all pages regardless of whether they're set to be hidden from the nav. + +accepts: "y","n" + +Default: no + + {exp:structure:nav override_hidden_state="yes"} + +###### `show_overview` + +defaults to no + +Shows a link at the top of your navigation that links to the current top level page. Use with rename_overview to change the title. + + {exp:structure:nav show_overview="yes"} + +###### `recursive_overview` + +defaults to no + +Show the overview link on every level, instead of only the first one. Works with show_overview. + + {exp:structure:nav recursive_overview="no|yes"} + +###### `rename_overview` + +defaults to "Overview" + +Rename the link at the top of your navigation that links to the current top level page. Use with show_overview to reveal. "title" uses the page's title field. + + {exp:structure:nav rename_overview="Overview|Whatever|title"} + +###### `start_from` + +Used to indicate where to begin revealing children. The "start_from" parameter must be a full URI or URL. + + {exp:structure:nav start_from="/about" or start_from ="/{segment_1}/{segment_2}"} + +###### `strict_start_from` + +Will NOT return a nav if there is no match to your "start_from" param. Normally, if there is no match, Structure returns the full nav starting from the base of your website. + + {exp:structure:nav strict_start_from="yes"} + +###### `show_depth` + +Reveals XX levels deep for ALL children pages of the current start_from parameter. + + {exp:structure:nav show_depth="2"} + +###### `show_expired` + +defaults to no + +Allows you to show or not show expired entries within the navigation tree. + +accepts: "y","n" + + {exp:structure:nav show_expired="yes|no"} + +###### `show_future_entries` + +Allows you to show or not show future entries within the navigation tree. + +accepts: "y","n" + +Default: no + + {exp:structure:nav show_future_entries="yes|no"} + +###### `site_url` + +defaults to no + +Include the absolute site URL in your nav links instead of relative links. + + {exp:structure:nav site_url="yes|no"} + +###### `status` + +defaults to Open + +Restrict pages by status, using normal EE syntax. When prefixed with "not" all entries except those are available. + + {exp:structure:nav status="Radical|Sweet"} + +### `{exp:structure:nav_advanced}` + +Allows more flexibility in building the navigation because is build to be used as a tag pair providing a number of variables. Acceot all the same parameters as the `{exp:structure:nav}` tag. + +#### Parameters + +###### `add_level_classes` + +defaults to no + +Displays class="level_1", class="level_2", etc on each li + + {exp:structure:nav_advanced add_level_classes="yes|no"} + +###### `add_span` + + +defaults to no + +Adds a span tag around each individual navigation element within the a tag. + +accepts: "y","n" + + {exp:structure:nav_advanced add_span="yes|no"} + +###### `add_unique_ids` + +defaults to no + +Adds a unique ID to the a tag using the top parent slug, default seperator and pageslug or entry ID. + + {exp:structure:nav_advanced add_unique_ids="yes|entry_id|no"} + +###### `css_class` + +Assigns a class to the ul. + + {exp:structure:nav_advanced css_class="sub_navigation"} + +###### `css_id` + +Assigns an ID to the ul. You can add "none" to optionally display no ID. + + {exp:structure:nav_advanced css_id="sub_navigation"} + +###### `current_class` + +defaults to here + +Change the class name added to the current page's li tag. + + {exp:structure:nav_advanced current_class="active"} + +###### `channel:title` + +defaults to entry title (when unset) + +Uses a specific custom field per channel instead of the default title variable. + + {exp:structure:nav_advanced channel:title="channel_name:field_name|another_channel:another_field"} + +###### `exclude` + +The parameter "exclude=" can be used to hide any single or multiple user defined entry numbers using the pipe character. All children under a specified ID will be hidden as well. + + {exp:structure:nav_advanced exclude="24"} + +###### `has_children_class` + +defaults to no + +Adds a class to pages that have children as an additional tiling hook. + +accepts: "y","n" + + {exp:structure:nav_advanced has_children_class="yes|no"} + +###### `include` + +integer + +The parameter "include=" can be used to selectively show specific pages from the same level. + + {exp:structure:nav_advanced include="24" } + +###### `include_ul` + +yes/no + +defaults to yes + +Conditionally output the surrounding ul tag. + + {exp:structure:nav_advanced include_ul="yes|no" } + +###### `max_depth` + +Only show up to XX levels deep from the current start_from parameter. Useful to hide pages under a desired level (like thank you or confirmation pages) or for main navigation. + + {exp:structure:nav_advanced max_depth="2"} + +###### `mode` + +defaults to sub + +Options are "sub", "main", and "full". Replacement for EE1's nav_main, nav_sub, and nav_full tags. + +_sub_: only displays 2 levels and any children on the same level of the same branch + +_full_: show the full tree + +_main_: show top nav but never any children + + {exp:structure:nav_advanced mode="sub"} + +###### `override_hidden_state` + +Show all pages regardless of whether they're set to be hidden from the nav. + +accepts: "y","n" + +Default: no + + {exp:structure:nav_advanced override_hidden_state="yes"} + +###### `show_overview` + +defaults to no + +Shows a link at the top of your navigation that links to the current top level page. Use with rename_overview to change the title. + + {exp:structure:nav_advanced show_overview="yes"} + +###### `recursive_overview` + +defaults to no + +Show the overview link on every level, instead of only the first one. Works with show_overview. + + {exp:structure:nav_advanced recursive_overview="no|yes"} + +###### `rename_overview` + +defaults to "Overview" + +Rename the link at the top of your navigation that links to the current top level page. Use with show_overview to reveal. "title" uses the page's title field. + + {exp:structure:nav_advanced rename_overview="Overview|Whatever|title"} + +###### `start_from` + +Used to indicate where to begin revealing children. The "start_from" parameter must be a full URI or URL. + + {exp:structure:nav_advanced start_from="/about" or start_from ="/{segment_1}/{segment_2}"} + +###### `strict_start_from` + +Will NOT return a nav if there is no match to your "start_from" param. Normally, if there is no match, Structure returns the full nav starting from the base of your website. + + {exp:structure:nav_advanced strict_start_from="yes"} + +###### `show_depth` + +Reveals XX levels deep for ALL children pages of the current start_from parameter. + + {exp:structure:nav_advanced show_depth="2"} + +###### `show_expired` + +defaults to no + +Allows you to show or not show expired entries within the navigation tree. + +accepts: "y","n" + + {exp:structure:nav_advanced show_expired="yes|no"} + +###### `show_future_entries` + +Allows you to show or not show future entries within the navigation tree. + +accepts: "y","n" + +Default: no + + {exp:structure:nav_advanced show_future_entries="yes|no"} + +###### `site_url` + +defaults to no + +Include the absolute site URL in your nav links instead of relative links. + + {exp:structure:nav_advanced site_url="yes|no"} + +###### `status` + +defaults to Open + +Restrict pages by status, using normal EE syntax. When prefixed with "not" all entries except those are available. + + {exp:structure:nav_advanced status="Radical|Sweet"} + +#### Variables + +All tags are prefixed based on their depth. The tag prefixes go in this order: + + - `root` + - `child` + - `grandchild` + - `great_granchild` + - etc. + +The basic tag has these variables (where is one of the depth levels listed above) + + - `{:entry_id}` + - `{:title}` + - `{:page_url}` + - `{:page_uri}` + - `{:count}` + - `{:total_results}` + - `{if :active}{/if}` + - `{if :has_active_child}{/if}` + - `{if :has_children}` + +There is also the children tag pair: + + {:children} + {:entry_id} + {:title} + {:children} + {:entry_id} + {/:children} + {/:children} + +Which would look like this with real prefixes: + + {root:children} + {child:entry_id} + {child:title} + {child:children} + {grandchild:entry_id} + {/child:children} + {/root:children} + +The advanced tag adds the following tags and also any custom fields: + + {:site_id} + {:channel_id} + {:author_id} + {:forum_topic_id} + {:ip_address} + {:url_title} + {:status} + {:versioning_enabled} + {:view_count_one} + {:view_count_two} + {:view_count_three} + {:view_count_four} + {:allow_comments} + {:sticky} + {:entry_date} + {:year} + {:month} + {:day} + {:expiration_date} + {:comment_expiration_date} + {:edit_date} + {:recent_comment_date} + {:comment_total} + {:channel} + {:channel_short_name} + {:your_custom_field} + + +###### `site_id` + +The Site id for the prefix + + {root:site_id} + +###### `channel_id` + +The channel id where this exists in + + {root:channel_id} + +###### `author_id` + +Who wrote this + + {root:author_id} + +###### `forum_topic_id` + + {root:forum_topic_id} + +###### `ip_address` + + {root:ip_address} + +###### `url_title` + +Useful for nav menus where wanting to link the topics + + {root:url_title} + +###### `status` + +The current status, example if it is open or closed + + {root:status} + +###### `versioning_enabled` + + {root:versioning_enabled} + +###### `allow_comments` + +does this allow for comments returns 1 for yes + + {root:allow_comments} + +###### `sticky` + +Is this entry sticky? Returns 1 if true + + {root:sticky} + +###### `entry_date` + + {root:entry_date} + +###### `year` + + {root:year} + +###### `month` + + {root:month} + +###### `day` + + {root:day} + +###### `expiration_date` + + {root:expiration_date} + +###### `comment_expiration_date` + + {root:comment_expiration_date} + +###### `edit_date` + + {root:edit_date} + +###### `recent_comment_date` + + {root:recent_comment_date} + +###### `comment_total` + + {root:comment_total} + +###### `channel` + + {root:channel} + +###### `channel_short_name` + + {root:channel_short_name} + +###### `your_custom_field` + + {root:your_custom_field} + +### `{exp:structure:nav_basic}` + +#### Parameters + +###### `add_level_classes` + +defaults to no + +Displays class="level_1", class="level_2", etc on each li + + {exp:structure:nav_basic add_level_classes="yes|no"} + +###### `add_span` + +defaults to no + +Adds a span tag around each individual navigation element within the a tag + +accepts: "y","n" + + {exp:structure:nav_basic add_span="yes|no"} + +###### `add_unique_ids` + +defaults to no + +Adds a unique ID to the a tag using the top parent slug, default seperator and pageslug or entry ID. + + {exp:structure:nav_basic add_unique_ids="yes|entry_id|no"} + +###### `css_class` + +Assigns a class to the ul. + + {exp:structure:nav_basic css_class="sub_navigation"} + +###### `css_id` + +Assigns an ID to the ul. You can add "none" to optionally display no ID. + + {exp:structure:nav_basic css_id="sub_navigation"} + +###### `current_class` + +defaults to here + +Change the class name added to the current page's li tag. + + {exp:structure:nav_basic current_class="active"} + +###### `channel:title` + +defaults to entry title (when unset) + +Uses a specific custom field per channel instead of the default title variable. + + {exp:structure:nav_basic channel:title="channel_name:field_name|another_channel:another_field"} + +###### `exclude` + +The parameter "exclude=" can be used to hide any single or multiple user defined entry numbers using the pipe character. All children under a specified ID will be hidden as well. + + {exp:structure:nav_basic exclude="24"} + +###### `has_children_class` + +yes/no + +defaults to no + +Adds a class to pages that have children as an additional tiling hook. + +accepts: "y","n" + + {exp:structure:nav_basic has_children_class="yes|no"} + +###### `include` + +integer + +The parameter "include=" can be used to selectively show specific pages from the same level. + + {exp:structure:nav_basic include="24" } + +###### `include_ul` + +yes/no + +defaults to yes Conditionally output the surrounding ul tag. + + {exp:structure:nav_basic include_ul="yes|no" } + +###### `max_depth` + +Only show up to XX levels deep from the current start_from parameter. Useful to hide pages under a desired level (like thank you or confirmation pages) or for main navigation. + + {exp:structure:nav_basic max_depth="2"} + +###### `mode` + +defaults to sub + +Options are "sub", "main", and "full". + +Replacement for EE1's nav_main, nav_sub, and nav_full tags. + +_sub_: only displays 2 levels and any children on the same level of the same branch + +_full_: show the full tree + +_main_: show top nav but never any children + + {exp:structure:nav_basic mode="sub"} + +###### `override_hidden_state` + +Show all pages regardless of whether they're set to be hidden from the nav. + +accepts: "y","n" + +Default: no + + {exp:structure:nav_basic override_hidden_state="yes"} + +###### `show_overview` + +defaults to no + +Shows a link at the top of your navigation that links to the current top level page. Use with rename_overview to change the title. + + {exp:structure:nav_basic show_overview="yes"} + +###### `recursive_overview` + +defaults to no Show the overview link on every level, instead of only the first one. Works with show_overview. + + {exp:structure:nav_basic recursive_overview="no|yes"} + +###### `rename_overview` + +defaults to "Overview" + +Rename the link at the top of your navigation that links to the current top level page. Use with show_overview to reveal. "title" uses the page's title field. + + {exp:structure:nav_basic rename_overview="Overview|Whatever|title"} + +###### `start_from` + +Used to indicate where to begin revealing children. The "start_from" parameter must be a full URI or URL. + + {exp:structure:nav_basic start_from="/about" or start_from ="/{segment_1}/{segment_2}"} + +###### `strict_start_from` + +Will NOT return a nav if there is no match to your "start_from" param. Normally, if there is no match, Structure returns the full nav starting from the base of your website. + + {exp:structure:nav_basic strict_start_from="yes"} + +###### `show_depth` + +Reveals XX levels deep for ALL children pages of the current start_from parameter. + + {exp:structure:nav_basic show_depth="2"} + +###### `show_expired` + +yes/no + +defaults to no + +Allows you to show or not show expired entries within the navigation tree. + +accepts: "y","n" + + {exp:structure:nav_basic show_expired="yes|no"} + +###### `show_future_entries` + +Allows you to show or not show future entries within the navigation tree. + +accepts: "y","n" + +Default: no + + {exp:structure:nav_basic show_future_entries="yes|no"} + +###### `site_url` + +defaults to no Include the absolute site URL in your nav links instead of relative links. + + {exp:structure:nav_basic site_url="yes|no"} + +###### `status` + +defaults to Open + +Restrict pages by status, using normal EE syntax. When prefixed with "not" all entries except those are available. + + {exp:structure:nav_basic status="Radical|Sweet"} + +#### Variables + +All tags are prefixed based on their depth. The tag prefixes go in this order: + + - `root` + - `child` + - `grandchild` + - `great_granchild` + - etc. + +The basic tag has these variables (where is one of the depth levels listed above) + + - `{:entry_id}` + - `{:title}` + - `{:page_url}` + - `{:page_uri}` + - `{:count}` + - `{:total_results}` + - `{if :active}{/if}` + - `{if :has_active_child}{/if}` + - `{if :has_children}` + +There is also the children tag pair: + + {:children} + {:entry_id} + {:title} + {:children} + {:entry_id} + {/:children} + {/:children} + +Which would look like this with real prefixes: + + {root:children} + {child:entry_id} + {child:title} + {child:children} + {grandchild:entry_id} + {/child:children} + {/root:children} + +### `{exp:structure:saef_select}` + +Used inside a Channel Form to select the parent and template assign to a page + +#### Parameters + +##### `type` + +string + +defaults to none + +Outputs form fields to select the template or parent + + {exp:structure:saef_select type=”template|parent”} + +### `{exp:structure:siblings}` + +This tag will traverse back and forth between siblings pages in your main navigation tree and auto-detect where you are in the hierarchy. + +#### Parameters + +###### `entry_id` + +defaults to Current page's ID Allows you to force a different starting page. + + {exp:structure:siblings entry_id="XX"} + +#### Variable pairs + +##### `next` + +Available variables: `title`, `url`, `entry_id`, `parent_id`, `channel_id`, `status` + + {exp:structure:siblings} + {next} + {title} + {/next} + {/exp:structure:siblings} + +#### `prev` + +Available variables: `title`, `url`, `entry_id`, `parent_id`, `channel_id`, `status` + + {exp:structure:siblings} + {prev} + {title} + {/prev} + {/exp:structure:siblings} + +### `{exp:structure:titletrail}` + +The titletrail tag displays in a standardized format and has a few parameters to control its output. + +Format = Page You're On » Parent Page » Top Level Nav » Site Name + +#### Parameters + +##### `channel:title` + +string + +defaults to entry title (when unset) Uses a specific custom field per channel instead of the default title variable. + + {exp:structure:titletrail channel:title="channel:custom_field|channel_2:custom_field_2"} + +##### `entry_id` + +string + +defaults to current page's ID Specify a trail to show + + {exp:structure:titletrail entry_id="XX"} + +##### `reverse` + +yes/no + +Output = "Site Name » Parent Page » Page You're On" + + {exp:structure:titletrail reverse="yes"} + +##### `separator` + +Spaces are automatically added around the element for you. + + {exp:structure:titletrail separator=":"} + +##### `site_name` + +defaults to no + +Adds your site name to the beginning of the trail. + + {exp:structure:titletrail site_name="yes"} diff --git a/docs/toc_sections/_advanced_usage_toc.yml b/docs/toc_sections/_advanced_usage_toc.yml index a40751102..20cc83b94 100644 --- a/docs/toc_sections/_advanced_usage_toc.yml +++ b/docs/toc_sections/_advanced_usage_toc.yml @@ -120,9 +120,15 @@ - name: Statistics href: add-ons/statistics.md - name: Structure - href: add-ons/structure/overview.md - - name: Emoticon (Deprecated) - href: add-ons/emoticon.md + items: + - name: Overview + href: add-ons/structure/overview.md + - name: Page Types + href: add-ons/structure/page-types.md + - name: Tags + href: add-ons/structure/tags.md + - name: Examples and Techniques + href: add-ons/structure/examples.md - name: Add-On Development items: