Cascading Fallback
From DLXS Documentation
(→Description) |
|||
| Line 2: | Line 2: | ||
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 collection) and ending with the least specific (generally, t/text and lib/). Once the file is found, it is used and the search terminates. | 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 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): | + | E.g., if looking for <code>textclass.css</code>, say a collection is the following fallback layers (from highest to lowest): |
<ul> | <ul> | ||
| - | <li><code>/c/collid/</code> (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, XSL, 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>xsl</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. | ||
| + | |||
| + | ===XSL=== | ||
| + | |||
| + | With cascading fallback, you no longer need to use <code>xsl:import</code> to include XSL files from lower fallback layers. | ||
| + | |||
| + | With XSL templates, if templates have the same specificity, then those appearing later will be used. With cascading fallback, all matching XSL 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 | ||
Revision as of 14:06, 23 March 2011
Contents |
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 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, XSL, 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:
- xsl
- 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.
XSL
With cascading fallback, you no longer need to use xsl:import to include XSL files from lower fallback layers.
With XSL templates, if templates have the same specificity, then those appearing later will be used. With cascading fallback, all matching XSL 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
