Cascading Fallback
From DLXS Documentation
(New page: ==Description== With fallback, if a file is required (e.g., XML, XSL, CSS, etc.), the system will look through all the fallback layers, starting with the most specific (e.g., the collectio...) |
(→How to troubleshoot) |
||
| (6 intermediate revisions not shown.) | |||
| Line 1: | Line 1: | ||
==Description== | ==Description== | ||
| - | With fallback, if a file is required (e.g., XML, | + | With fallback, if a file is required (e.g., XML, XSLT, CSS, etc.), the system will look through all the fallback layers, starting with the most specific (e.g., the collection) and ending with the least specific (generally, t/text and lib/). Once the file is found, it is used and the search terminates. |
| - | E.g., if looking for textclass.css, say a collection is the following fallback layers: | + | E.g., if looking for <code>textclass.css</code>, say a collection is the following fallback layers (from highest to lowest): |
<ul> | <ul> | ||
| - | <li>/c/collid/ (no textclass.css)</li> | + | <li><code>/c/collid/</code> (no <code>textclass.css</code>)</li> |
| - | <li>/g/groupid/textclass.css</li> | + | <li><code>/g/groupid/textclass.css</code></li> |
| - | <li>/a/anotherlayer1/textclass.css</li> | + | <li><code>/a/anotherlayer1/textclass.css</code></li> |
| - | <li>/a/anotherlayer2/ (no textclass.css)</li> | + | <li><code>/a/anotherlayer2/</code> (no <code>textclass.css</code>)</li> |
| - | <li>/t/text/textclass.css</li> | + | <li><code>/t/text/textclass.css</code></li> |
</ul> | </ul> | ||
| - | Fallback will first search /c/collid/, which does not | + | Fallback will first search <code>/c/collid/</code>, which does not contain <code>textclass.css</code>. However, the next layer (<code>/g/groupid/</code>) has the file. <code>/g/groupid/textclass.css</code> will then be used, and the search stops. |
| - | The purpose of cascading fallback is to include all matching files in each ''fallback'' layer. So for the above example, /g/groupid/textclass.css, /a/anotherlayer1/textclass.css, and /t/text/textclass.css are all used. But they will be included in such a way that files from higher layers have higher precedence. | + | The purpose of cascading fallback is to include all matching files in each ''fallback'' layer. So for the above example, <code>/g/groupid/textclass.css</code>, <code>/a/anotherlayer1/textclass.css</code>, and <code>/t/text/textclass.css</code> are all used. But they will be included in such a way that files from higher layers have higher precedence. |
| - | Note that this behavior can be accomplished in normal fallback by used import statements in CSS | + | Note that this behavior can be accomplished in normal fallback by used import statements in CSS, XSLT, XML. However, with many levels, these import statements need to be updated, and there is a duplication of filesystem logic (the file exists on the filesystem AND you have to import it) that does not occur with cascading fallback. This prevents a range of potentially subtle bugs that become more likely when you use more fallback layers. |
==How to use== | ==How to use== | ||
| + | |||
| + | To use cascading fallback for a collection, simply set <code>cascadingfallback</code> in <code>collmgr</code> to <code>yes</code>. | ||
| + | |||
| + | To use cascading fallback for a group, simply set <code>cascadingfallback</code> in <code>collmgr</code> to <code>yes</code> for all its member collections. | ||
| + | |||
| + | Note that only the following files are supported: | ||
| + | |||
| + | <ul> | ||
| + | <li>XSLT</li> | ||
| + | <li>CSS</li> | ||
| + | </ul> | ||
| + | |||
| + | For unsupported files (e.g., XML), treat them as you would with normal fallback. (E.g., if you want to include <code>/t/text/langmapextra.en.xml</code> with <code>/c/collid/langmapextra.en.xml</code>, use <code><?CHUNK filename="../../m/mpubs/dlxsclassglobals.xml"?></code>.) | ||
==How it works== | ==How it works== | ||
| + | |||
| + | ===CSS=== | ||
| + | |||
| + | With cascading fallback, you no longer need to use <code>@import</code> to include CSS files from lower fallback layers. | ||
| + | |||
| + | With CSS declarations, if selectors have the same specificity, then those appearing later will be used. With cascading fallback, all matching CSS files will be included, but they will be included so that matching files from lower fallback layers are included before those in higher layers. | ||
| + | |||
| + | ===XSLT=== | ||
| + | |||
| + | With cascading fallback, you no longer need to use <code>xsl:import</code> to include XSLT files from lower fallback layers. | ||
| + | |||
| + | With XSLT templates, if templates have the same specificity, then those appearing later will be used. With cascading fallback, all matching XSLT files will be included in the virtual stylesheet, but they will be included so that matching files from lower fallback layers are included before those in higher layers. | ||
==How to troubleshoot== | ==How to troubleshoot== | ||
| + | |||
| + | If you enabled cascading fallback but believe it is not working, the first step is to determine whether cascading fallback is being used. Append <code>;debug=tpl</code> to the URL of a sample page, and look for the tracer output for an XSLT file. | ||
| + | |||
| + | The following screenshot shows what you should see: | ||
| + | |||
| + | [[Image:Tpl-with-cascading.png|thumb|center|border]] | ||
| + | |||
| + | Note that the tracer explicitly states that cascading fallback is being used for certain files. Contrast this with the following screenshot for a collection that is not using cascading fallback: | ||
| + | |||
| + | [[Image:Tpl-without-cascading.png|thumb|center|border]] | ||
| + | |||
| + | Another option is to look at the XML output to see whether the stylesheets are being processed using cascading fallback by appending <code>;debug=xml</code> to a URL. | ||
| + | |||
| + | The following screenshot shows <code>CssLink/CssLink</code>, meaning that cascading fallback is being used: | ||
| + | |||
| + | [[Image:Csslink-with-cascading.png|thumb|center|border]] | ||
| + | |||
| + | Why is CssLink nested? Cascading fallback does this because multiple files might match a single requested file. Note this it will use <code>CssLink/CssLink</code> regardless of whether there is one or more than one file. | ||
| + | |||
| + | Contrast this with screenshot, which never nests <code>CssLink</code> inside a <code>CssLink</code>: | ||
| + | |||
| + | [[Image:Csslink-without-cascading.png|thumb|center|border]] | ||
| + | |||
| + | If your styles are not appearing but you see <code>CssLink/CssLink</code> (meaning that cascading fallback is in effect), check to see whether you have any custom XSLT that is rendering stylesheets. It might be the case that your customization is preventing the XSLT logic from handling this correctly. | ||
Current revision
Contents |
[edit] Description
With fallback, if a file is required (e.g., XML, XSLT, CSS, etc.), the system will look through all the fallback layers, starting with the most specific (e.g., the collection) and ending with the least specific (generally, t/text and lib/). Once the file is found, it is used and the search terminates.
E.g., if looking for textclass.css, say a collection is the following fallback layers (from highest to lowest):
/c/collid/(notextclass.css)/g/groupid/textclass.css/a/anotherlayer1/textclass.css/a/anotherlayer2/(notextclass.css)/t/text/textclass.css
Fallback will first search /c/collid/, which does not contain textclass.css. However, the next layer (/g/groupid/) has the file. /g/groupid/textclass.css will then be used, and the search stops.
The purpose of cascading fallback is to include all matching files in each fallback layer. So for the above example, /g/groupid/textclass.css, /a/anotherlayer1/textclass.css, and /t/text/textclass.css are all used. But they will be included in such a way that files from higher layers have higher precedence.
Note that this behavior can be accomplished in normal fallback by used import statements in CSS, XSLT, XML. However, with many levels, these import statements need to be updated, and there is a duplication of filesystem logic (the file exists on the filesystem AND you have to import it) that does not occur with cascading fallback. This prevents a range of potentially subtle bugs that become more likely when you use more fallback layers.
[edit] How to use
To use cascading fallback for a collection, simply set cascadingfallback in collmgr to yes.
To use cascading fallback for a group, simply set cascadingfallback in collmgr to yes for all its member collections.
Note that only the following files are supported:
- XSLT
- CSS
For unsupported files (e.g., XML), treat them as you would with normal fallback. (E.g., if you want to include /t/text/langmapextra.en.xml with /c/collid/langmapextra.en.xml, use <?CHUNK filename="../../m/mpubs/dlxsclassglobals.xml"?>.)
[edit] How it works
[edit] CSS
With cascading fallback, you no longer need to use @import to include CSS files from lower fallback layers.
With CSS declarations, if selectors have the same specificity, then those appearing later will be used. With cascading fallback, all matching CSS files will be included, but they will be included so that matching files from lower fallback layers are included before those in higher layers.
[edit] XSLT
With cascading fallback, you no longer need to use xsl:import to include XSLT files from lower fallback layers.
With XSLT templates, if templates have the same specificity, then those appearing later will be used. With cascading fallback, all matching XSLT files will be included in the virtual stylesheet, but they will be included so that matching files from lower fallback layers are included before those in higher layers.
[edit] How to troubleshoot
If you enabled cascading fallback but believe it is not working, the first step is to determine whether cascading fallback is being used. Append ;debug=tpl to the URL of a sample page, and look for the tracer output for an XSLT file.
The following screenshot shows what you should see:
Note that the tracer explicitly states that cascading fallback is being used for certain files. Contrast this with the following screenshot for a collection that is not using cascading fallback:
Another option is to look at the XML output to see whether the stylesheets are being processed using cascading fallback by appending ;debug=xml to a URL.
The following screenshot shows CssLink/CssLink, meaning that cascading fallback is being used:
Why is CssLink nested? Cascading fallback does this because multiple files might match a single requested file. Note this it will use CssLink/CssLink regardless of whether there is one or more than one file.
Contrast this with screenshot, which never nests CssLink inside a CssLink:
If your styles are not appearing but you see CssLink/CssLink (meaning that cascading fallback is in effect), check to see whether you have any custom XSLT that is rendering stylesheets. It might be the case that your customization is preventing the XSLT logic from handling this correctly.
