Cascading Fallback
From DLXS Documentation
(→How to troubleshoot) |
|||
| Line 53: | Line 53: | ||
The following screenshot shows what you should see: | The following screenshot shows what you should see: | ||
| - | [Image:Tpl-with-cascading.png] | + | [[Image:Tpl-with-cascading.png]] |
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: | 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] | + | [[Image:Tpl-without-cascading.png]] |
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. | 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. | ||
| Line 63: | Line 63: | ||
The following screenshot shows <code>CssLink/CssLink</code>, meaning that cascading fallback is being used: | The following screenshot shows <code>CssLink/CssLink</code>, meaning that cascading fallback is being used: | ||
| - | [Image:Csslink-with-cascading.png] | + | [[Image:Csslink-with-cascading.png]] |
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. | 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. | ||
| Line 69: | Line 69: | ||
Contrast this with screenshot, which never nests <code>CssLink</code> inside a <code>CssLink</code>: | Contrast this with screenshot, which never nests <code>CssLink</code> inside a <code>CssLink</code>: | ||
| - | [Image:Csslink-without-cascading.png] | + | [[Image:Csslink-without-cascading.png]] |
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. | 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. | ||
Revision as of 14:16, 23 March 2011
Contents |
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.
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"?>.)
How it works
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.
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.
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.
