tonyair/silverstripe-framework
1
0
Fork 0
mirror of https://github.com/silverstripe/silverstripe-framework synced 2024-07-01 08:59:42 +02:00
Code Issues Projects Releases Wiki Activity

Clarified <% include %> use in SS4 (see #5952)

Browse Source
This commit is contained in:
Ingo Schommer 2016-09-06 12:14:11 +12:00
parent a96edf4477
commit 54aad839c4
2 changed files with 16 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
docs/en/02_Developer_Guides/01_Templates/01_Syntax.md
View File

@ -49,12 +49,17 @@ text-based format.
SilverStripe templates are plain text files that have `.ss` extension and located within the `templates` directory of
a module, theme, or your `mysite` folder.
By default, templates will have the same name as the class they are used to render. So, your Page class will
By default, templates will have the same name as the class they are used to render. So, your `Page` class will
be rendered with the `templates/Page.ss` template.
When the class has a namespace, the namespace will be interpreted as subfolder within the `templates` path. For, example, the class `SilverStripe\Control\Controller` will be rendered with the
When the class has a namespace, the namespace will be interpreted as a subfolder within the `templates` path.
For example, the class `SilverStripe\Control\Controller` will be rendered with the
`templates/SilverStripe/Control/Controller.ss` template.
If you are using template "types" like `Layout` or `Includes`, these are just folders which you need
to append to your template file location. One exception is the `<% include %>` template tag,
where you need to leave out the `Includes/` folder.
## Variables
Variables are placeholders that will be replaced with data from the [DataModel](../model/) or the current
@ -204,13 +209,15 @@ Within SilverStripe templates we have the ability to include other templates usi
will be searched for using the same filename look-up rules as a regular template. However in the case of the include tag
an additional `Includes` directory will be inserted into the resolved path just prior to the filename.
E.g.
* `<% include SideBar %>` will include `templates/Includes/Sidebar.ss`
* `<% include MyNamespace/SideBar %>` will include `templates/MyNamespace/Includes/Sidebar.ss`
:::ss
<% include SideBar %> <!-- chooses templates/Includes/Sidebar.ss -->
<% include MyNamespace/SideBar %> <!-- chooses templates/MyNamespace/Includes/Sidebar.ss -->
Note that in SilverStripe 3, you didn't have to specify a namespace in your `include` tag, as the template engine didn't
use namespaces. As of SilverStripe 4, the template namespaces need to match the folder structure of your template files.
When using subfolders in your template structure
(e.g. to fit with namespaces in your PHP class structure), the `Includes/` folder needs to be innermost.
:::ss
<% include MyNamespace/SideBar %> <!-- chooses templates/MyNamespace/Includes/Sidebar.ss -->
The `include` tag can be particularly helpful for nested functionality and breaking large templates up. In this example,
the include only happens if the user is logged in.

2
docs/en/04_Changelogs/4.0.0.md
View File

@ -84,7 +84,7 @@ Templates are now much more strict about their locations. You can no longer put
folder and have it be found. Case is now also checked on case-sensitive filesystems.
Either include the folder in the template name (`renderWith('MyEmail.ss')` => `renderWith('emails/MyEmail.ss')`),
move the template into the correct directory, or both.
move the template into the correct directory, or both. This also affects `<% include %>` statements in templates.
When using `<% include %>` template tag you should continue to leave out the `Includes` folder.
`<% include Sidebar %>` will match only match `Includes/Sidebar.ss`, not `Sidebar.ss`.