mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-10-22 14:05:37 +02:00
Merge pull request #4785 from muskie9/docs/LinkingModes
DOCS update LinkingModes description
This commit is contained in:
Jono Menz
commit
fa68b4d4c5
@ -166,7 +166,7 @@ The Menu for our site is created using a **loop**. Loops allow us to iterate ove
|
||||
<% loop $Menu(1) %>
|
||||
|
||||
returns a set of first level menu items. We can then use the template variable
|
||||
*$MenuTitle* to show the title of the page we are linking to, *$Link* for the URL of the page and *$LinkingMode* to help style our menu with CSS (explained in more detail shortly).
|
||||
*$MenuTitle* to show the title of the page we are linking to, *$Link* for the URL of the page, and `$isSection` and `$isCurrent` to help style our menu with CSS (explained in more detail shortly).
|
||||
|
||||
> *$Title* refers to **Page Name** in the CMS, whereas *$MenuTitle* refers to (the often shorter) **Navigation label**
|
||||
|
||||
@ -174,7 +174,7 @@ returns a set of first level menu items. We can then use the template variable
|
||||
:::ss
|
||||
<ul>
|
||||
<% loop $Menu(1) %>
|
||||
<li class="$LinkingMode">
|
||||
<li class="<% if $isCurrent %>current<% else_if $isSection %>section<% end_if %>">
|
||||
<a href="$Link" title="$Title.XML">$MenuTitle.XML</a>
|
||||
</li>
|
||||
<% end_loop %>
|
||||
@ -191,16 +191,12 @@ This creates the navigation at the top of the page:
|
||||
|
||||
### Highlighting the current page
|
||||
|
||||
A useful feature is highlighting the current page the user is looking at. We can do this with the template variable: `$LinkingMode`. It returns one of three values:
|
||||
A useful feature is highlighting the current page the user is looking at. We can do this by using the `is` methods `$isSection` and `$isCurrent`.
|
||||
|
||||
* *current* - This page is being visited
|
||||
* *link* - This page is not currently being visited
|
||||
* *section* - A page under this page is being visited
|
||||
|
||||
For example, if you were here: "Home > Company > Staff > Bob Smith", you may want to highlight 'Company' to say you are in that section. If you add $LinkingMode to your navigation elements as a class, ie:
|
||||
For example, if you were here: "Home > Company > Staff > Bob Smith", you may want to highlight 'Company' to say you are in that section.
|
||||
|
||||
:::ss
|
||||
<li class="$LinkingMode">
|
||||
<li class="<% if $isCurrent %>current<% else_if $isSection %>section<% end_if %>">
|
||||
<a href="$Link" title="$Title.XML">$MenuTitle.XML</a>
|
||||
</li>
|
||||
|
||||
@ -231,7 +227,7 @@ Adding a second level menu is very similar to adding the first level menu. Open
|
||||
:::ss
|
||||
<ul>
|
||||
<% loop $Menu(2) %>
|
||||
<li class="$LinkingMode">
|
||||
<li class="<% if $isCurrent %>current<% else_if $isSection %>section<% end_if %>">
|
||||
<a href="$Link" title="Go to the $Title.XML page">
|
||||
<span class="arrow">→</span>
|
||||
<span class="text">$MenuTitle.XML</span>
|
||||
@ -243,7 +239,7 @@ Adding a second level menu is very similar to adding the first level menu. Open
|
||||
This should look very familiar. It is the same idea as our first menu, except the loop block now uses *Menu(2)* instead of *Menu(1)*.
|
||||
As we can see here, the *Menu* control takes a single
|
||||
argument - the level of the menu we want to get. Our css file will style this linked list into the second level menu,
|
||||
using our usual *$LinkingMode* technique to highlight the current page.
|
||||
using our usual `is` technique to highlight the current page.
|
||||
|
||||
To make sure the menu is not displayed on every page, for example, those that *don't* have any nested pages. We use an **if block**.
|
||||
Look again in the *Sidebar.ss* file and you will see that the menu is surrounded with an **if block**
|
||||
@ -254,7 +250,7 @@ like this:
|
||||
...
|
||||
<ul>
|
||||
<% loop $Menu(2) %>
|
||||
<li class="$LinkingMode">
|
||||
<li class="<% if $isCurrent %>current<% else_if $isSection %>section<% end_if %>">
|
||||
<a href="$Link" title="Go to the $Title.XML page">
|
||||
<span class="arrow">→</span>
|
||||
<span class="text">$MenuTitle.XML</span>
|
||||
@ -301,12 +297,12 @@ The following example runs an if statement and a loop on *Children*, checking to
|
||||
:::ss
|
||||
<ul>
|
||||
<% loop $Menu(1) %>
|
||||
<li class="$LinkingMode">
|
||||
<li class="<% if $isCurrent %>current<% else_if $isSection %>section<% end_if %>">
|
||||
<a href="$Link" title="$Title.XML">$MenuTitle.XML</a>
|
||||
<% if $Children %>
|
||||
<ul>
|
||||
<% loop $Children %>
|
||||
<li class="$LinkingMode">
|
||||
<li class="<% if $isCurrent %>current<% else_if $isSection %>section<% end_if %>">
|
||||
<a href="$Link" title="Go to the $Title.XML page">
|
||||
<span class="arrow">→</span>
|
||||
<span class="text">$MenuTitle.XML</span>
|
||||
|
||||
@ -153,30 +153,30 @@ link.
|
||||
### Linking Modes
|
||||
|
||||
:::ss
|
||||
$LinkingMode
|
||||
$isSection
|
||||
$isCurrent
|
||||
|
||||
When looping over a list of `SiteTree` instances through a `<% loop $Menu %>` or `<% loop $Children %>`, `$LinkingMode`
|
||||
will return context about the page relative to the currently viewed page. It can have the following values:
|
||||
|
||||
* `link`: You are neither on this page nor in this section.
|
||||
* `current`: You are currently on this page.
|
||||
* `section`: The current page is a child of this menu item, so the current "section"
|
||||
When looping over a list of `SiteTree` instances through a `<% loop $Menu %>` or `<% loop $Children %>`, `$isSection` and `$isCurrent`
|
||||
will return true or false based on page being looped over relative to the currently viewed page.
|
||||
|
||||
For instance, to only show the menu item linked if it's the current one:
|
||||
|
||||
:::ss
|
||||
<% if $LinkingMode = current %>
|
||||
<% if $isCurrent %>
|
||||
$Title
|
||||
<% else %>
|
||||
<a href="$Link">$Title</a>
|
||||
<% end_if %>
|
||||
|
||||
An example for checking for `current` or `section` is as follows:
|
||||
|
||||
`$LinkingMode` is reused for several other variables and utility functions.
|
||||
:::ss
|
||||
<a class="<% if $isCurrent %>current<% else_if $isSection %>section<% end_if %>" href="$Link">$MenuTitle</a>
|
||||
|
||||
|
||||
|
||||
**Additional Utility Method**
|
||||
|
||||
* `$LinkOrCurrent`: Determines if the item is the current page. Returns "link" or "current" strings.
|
||||
* `$LinkOrSection`: Determines if the item is in the current section, so in the path towards the current page. Useful
|
||||
for menus which you only want to show a second level menu when you are on that page or a child of it. Returns "link"
|
||||
or "section" strings.
|
||||
* `$InSection(page-url)`: This if block will pass if we're currently on the page-url page or one of its children.
|
||||
|
||||
:::ss
|
||||
|
||||
@ -11,15 +11,15 @@ top level menu with a nested second level using the `Menu` loop and a `Children`
|
||||
<ul>
|
||||
<% loop $Menu(1) %>
|
||||
<li>
|
||||
<a href="$Link" title="Go to the $Title page" class="$LinkingMode">
|
||||
<a href="$Link" title="Go to the $Title page" class="<% if $isCurrent %>current<% else_if $isSection %>section<% end_if %>">
|
||||
$MenuTitle
|
||||
</a>
|
||||
|
||||
<% if $LinkOrSection == section %>
|
||||
<% if $isSection %>
|
||||
<% if $Children %>
|
||||
<ul class="secondary">
|
||||
<% loop $Children %>
|
||||
<li class="$LinkingMode"><a href="$Link">$MenuTitle</a></li>
|
||||
<li class="<% if $isCurrent %>current<% else_if $isSection %>section<% end_if %>"><a href="$Link">$MenuTitle</a></li>
|
||||
<% end_loop %>
|
||||
</ul>
|
||||
<% end_if %>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user