source: main/trunk/ibisph-view/src/main/webapp/xslt/_ibis-include.xslt @ 22707

Last change on this file since 22707 was 22707, checked in by GarthBraithwaite_STG, 7 months ago

view - updated docs and internal workings of ibis.include.

File size: 14.5 KB
Line 
1<?xml version="1.0" encoding="ISO-8859-1"?>
2
3<xsl:stylesheet version="3.0" 
4        xmlns:xsl ="http://www.w3.org/1999/XSL/Transform" 
5        xmlns:xs  ="http://www.w3.org/2001/XMLSchema"
6        xmlns:ibis="http://www.ibisph.org"
7
8        exclude-result-prefixes="ibis xs xsl"
9>
10
11        <ibis:doc>
12                <name>ibis.include</name>
13                <summary>
14                        Library of generic/common ibis include and copy related apply/match
15                        functions.  Named include instead of ibis-copy as include is the
16                        primary usage.  This code also handles the ibis:href and webapp
17                        prefix type content matches.  Handling within is safe vs other
18                        special match handling.
19                       
20                        The IBIS-PH code in 6-2004 was locked into the xerces 2.6.x parser
21                        has xinclude support but it must be configured when starting the
22                        Java JVM or with Java system properties.  Since this was not a safe
23                        option for some deployments (like a shared app server) the system
24                        wide property solution is not an option.  To handle being able to
25                        deploy into environments where we didn't know which XSL engine is
26                        being used etc. this template match was created which now has some
27                        ibis specific parameters. 
28
29                        See: http://www.sagehill.net/docbookxsl/Xinclude.html
30
31                        At one point had a general CONTENT match.  However, this can not
32                        work within an included file because there are some cases where CONTENT
33                        elements need to be handled at different time / more specialized XSLT. 
34                        For example if matching on CONTENT that is within a SELECTION
35                        ibis:include the include match procssing picks it up and removes the
36                        CONTENT element within the selection list so the xslt does not know
37                        about it and can not process the list and content.  For CONTENT to
38                        be processed, specific matches are required.
39                       
40                        Some interesting apply options:
41                        xsl:apply-templates select="@* except (@id, @name, @class)"/
42                        xsl:apply-templates select="@id, @name, @class, @* except (@id, @name, @class)"/
43                        xsl:apply-templates select="*, except ELEMENT_X, @* except (@id, @name, @class)"/
44
45                        GARTH TODO: at some point could have other special ibis: processing
46                        included here for CONTENT type element processing.  The main
47                        HTML_CONTENT has ibis:help, ibis:SelectionsList, ibis:ContentBody etc. 
48                        To be included in the general ibis.copy processing special namespace
49                        processing is needed (see help.xslt and HTMLContentPage.xslt). 
50                        This also makes for loose xsd validation and more complex testing. 
51                </summary>
52        </ibis:doc>
53
54
55        <!-- ===================================== M A T C H   C O P Y   M O D E -->
56        <xsl:template match="*" mode="ibis.copy"
57                ibis:doc="Provides the ability to do an apply-templates to a copy-of of
58                        an element (some call this an 'identity transformation').  This
59                        allows for a deep copy with processing (which also allows ibis.include
60                        to be processed)."
61        >
62                <!-- Used the new element and copied the attributes, text, and sub
63                        elements so that any namespace attributes would not be copied.
64                        <xsl:apply-templates select="@*" mode="ibis.copy"/>
65                -->
66                <xsl:element name="{local-name()}">
67                        <xsl:apply-templates select="current()/@* | current()/text() | current()/*"  mode="ibis.copy"/>
68                </xsl:element>
69        </xsl:template>
70
71
72        <xsl:template match="text()" mode="ibis.copy" 
73                ibis:doc="Trims the text - not really needed for wiki - biggest issue
74                        with weird text was page indent on and extra line spacing etc.
75                        Another way: [xsl:value-of select=doublequotereplace(., '^\s+|\s+$', '')doublequote/]
76                "
77        >
78                <xsl:value-of select="."/>
79        </xsl:template>
80
81
82        <xsl:template match="@*" mode="ibis.copy" 
83                ibis:doc="Inner '@*' template that copies the non ibis: namespace
84                        elements and attributes.
85                "
86        >
87                <xsl:copy-of select="."/>
88        </xsl:template>
89
90        <xsl:template match="@ibis:doc" mode="ibis.copy" ibis:doc="Eats ibis:doc attribute"/>
91        <xsl:template match="ibis:doc"  mode="ibis.copy" ibis:doc="Eats ibis:doc element"/>
92
93
94        <!-- The following templates are used to help page developers avoid having to
95                hard code the deployment specific context into the URL path of IBIS related
96                web pages.  Example: If the app is deployed into a context called "ibisph-view"
97                and your page is "http://localhost/ibisph-view/about/welcome.html" and it
98                references an image that is under the "webapps/ibisph-view/image" directory
99                it would need a url like "src='/ibisph-view/image/the_image.gif'" to properly
100                get the correct resource.  A relative path of "src='image/the_image.gif'"
101                would cause the browser to request "http://localhost/ibisph-view/about/image/the_image.gif",
102                while a path of "src='/image/the_image.gif'" would request this resource
103                "http://localhost/image/the_image.gif" both of which are wrong.  If the context
104                path is coded so that the resource's URL is explicitly defined then a dependency
105                exists between the web pages and the context which makes the deployment not
106                as portable.  Since the web app context path is needed by the XSLTs to build
107                the correct HTML code it is implemented here to help static page development.
108                Relative links work fine if the resource it within the same directory e.g.
109                if the "about/welcome.html" page contains a relative link to the "about/content_usage.html"
110                page then all is well.  The "about/welcome.html" page can NOT contains a relative
111                link to the "indicator/introduction.html" as it will not find the correct
112                directory.
113
114                These templates simply add the web application's context path as a prefix
115                to the link reference attribute.
116
117                NOTE: The remoteRequestPath_ technique could be applied but these are left
118                as is so adopters do not have to redo their content pages - for now...
119GARTH TODO: at some future point convert everything to the more explicit
120ibis:baseRequstPath_  ibis:baseRequstPath_src, ibis:baseRequstPath_href
121        -->
122        <xsl:template match="@ibis:href" mode="ibis.copy" ibis:doc="Inner 'ibis:href' template that adds the 'WebAppURLContextPrefix' to the 'href' attribute.">
123                <xsl:attribute name="href" select="concat($ibis.baseRequestPath, .)"/>
124        </xsl:template>
125        <xsl:template match="@ibis:src" mode="ibis.copy" ibis:doc="Inner 'ibis:src' template that adds the 'WebAppURLContextPrefix' to the 'src' attribute.">
126                <xsl:attribute name="src" select="concat($ibis.baseRequestPath, .)"/>
127        </xsl:template>
128        <xsl:template match="@ibis:action" mode="ibis.copy" ibis:doc="Inner 'ibis:action' template that adds the 'WebAppURLContextPrefix' to the 'action' attribute.">
129                <xsl:attribute name="action" select="concat($ibis.baseRequestPath, .)"/>
130        </xsl:template>
131        <xsl:template match="@ibis:poster" mode="ibis.copy" ibis:doc="Inner 'ibis:poster' template that adds the 'WebAppURLContextPrefix' to the 'poster' attribute.">
132                <xsl:attribute name="poster" select="concat($ibis.baseRequestPath, .)"/>
133        </xsl:template>
134
135        <xsl:template match="@ibis:*[starts-with(name(), 'ibis:baseRequstPath_')]" mode="ibis.copy" 
136                ibis:doc="Adds the 'WebAppBaseRequestPath' as a prefix to the attribute value with the attribute named the suffix following 'ibis:baseRequstPath_'."
137        >
138                <xsl:attribute name="{substring(name(), 18)}" select="concat($ibis.baseRequestPath, .)"/>
139        </xsl:template>
140
141        <xsl:template match="ibis:baseRequestPath" mode="ibis.copy" 
142                ibis:doc="Mechanism that allows any ibis.copy processed XML CONTENT to
143                        to get the ibis.baseRequesttPath value.  This is useful for pages
144                        that have javascript that need this value.
145                        Usage: within the CONTENT have an [ibis:baseRequestPath/] element.
146                "
147        >
148                <xsl:value-of select="$ibis.baseRequestPath"/>
149        </xsl:template>
150
151
152        <!-- =============================== I B I S   I N C L U D E   M A T C H -->
153        <xsl:template match="ibis:include" mode="#all"
154                ibis:doc="
155                        'ibis:' namespace specific match template which opens and includes
156                        the document via the 'href' attribute and does an 'apply-templates'
157                        operation on its contents to process potential sub 'ibis:' matches
158                        and to copy its text, attributes, and processing instructions.  This
159                        is a simple match template that calls the main ibis.include template
160                        so that logic is centralized between this general ibis: match and
161                        the ConfigurationIncludeCriteriaExclude's config name ibis: match.
162
163                        If a children-only-flag attribute exists in the element then only the
164                        sub elements and child text are included and processed. This is useful
165                        for including an element's text without having to include its root
166                        element or for custom dimension lists for query modules.
167
168                        child-name-list (with list of delimited values) provides the ability
169                        to limit included elements (like DIMENSION) and any other include
170                        that has the standard NAME element.  This provides a mechanism to
171                        limit child elements to a given name or a CSV or white space delimited
172                        list of names.  This template by definition is limited to including
173                        only child elements so the  children-only-flag is not needed/used.
174
175                        apply-baseRequestPath causes the doc href to be prefixed with the
176                        ibis.baseRequestPath value.  For normal XSLT views the ibis.baseRequestPath
177                        value IS injected as a parameter into the transformation engine. 
178                        This value is NOT available and thus not injected into the special
179                        query module XSLT include processing (see the notes in the
180                        ConfigurationIncludeCriteriaExclude) so this attribute as of 7/7/2020
181                        can NOT be applied for any QM ibis:includes.
182                "
183        >
184                <xsl:call-template name="ibis.include">
185                        <xsl:with-param name="url"                  select="@href"/>
186                        <xsl:with-param name="applyBaseRequestPath" select="exists(@apply-baseRequestPath)"/>
187                        <xsl:with-param name="childNameList"        select="@child-name-list"/>
188                        <xsl:with-param name="includeChildrenOnly"  select="exists(@children-only-flag)"/>
189                </xsl:call-template>
190        </xsl:template>
191
192
193        <xsl:template name="ibis.include"
194                ibis:doc="
195                        Core processing template called when matching an ibis:include or when
196                        standard call-template xslt processing needs to include a file. 
197
198                        IMPORTANT NOTE:
199                        Prior to 7/7/2020 had various include attribute matching templates
200                        that handled more specialized processing.  However, as things evolved
201                        into more complex functionality that code was moved into this template
202                        so that more explicit processing could be implemented that is easier
203                        to follow and so that it could be called from various include matches 
204                        (like ConfigurationIncludeCriteriaExclude) so that didn't have to
205                        duplicate handling rules.  See that code for some of the attempts to
206                        allow for module matches.
207                "
208        >
209                <xsl:param name="url"/>
210                <xsl:param name="applyBaseRequestPath" select="false()"
211                        ibis:doc="Optional boolean flag if true() the url parameter used to
212                                open the document is prefixed with the ibis.baseRequestPath.
213                        "
214                />
215                <xsl:param name="childNameList"
216                        ibis:doc="Optional blank or csv list of child NAME element values to limit
217                                included elements (like DIMENSION) and any other includes that
218                                have the standard NAME element.  This is mostly used for selectively
219                                including query module dimensions and selections etc.  If set
220                                this takes precidence over the includeChildrenOnly param.
221                        "
222                />
223                <xsl:param name="includeChildrenOnly"  select="false()"
224                        ibis:doc="Optional boolean when if true() results in only including
225                                (and processing) the child sub elements and child text. This is
226                                useful for including an element's text without having to include
227                                its root element or for custom dimension lists for query modules.
228                        "
229                />
230
231                <xsl:variable name="url" select="if($applyBaseRequestPath) then concat($ibis.baseRequestPath, $url) else $url"/>
232                <xsl:choose>
233                        <xsl:when test="$childNameList">
234                                <xsl:variable name="childNamesToInclude" select="tokenize(normalize-space(replace($childNameList, ',', ' ')), '\s+')"/>
235<xsl:message select="'~~~~~~~~~~~~~~~~cn'"/>
236<xsl:message select="$childNamesToInclude"/>
237<xsl:message select="count($childNamesToInclude)"/>
238<xsl:message select="count($childNamesToInclude/*)"/>
239                                <xsl:apply-templates select="document($url)/*/*[NAME=$childNamesToInclude]" mode="ibis.copy"/>
240                        </xsl:when>
241                        <xsl:when test="$includeChildrenOnly">
242<xsl:message select="'~~~~~~~~~~~~~~~~co'"/>
243                                <xsl:apply-templates select="document($url, /)/(*/text() | */*)" mode="ibis.copy"/>
244                        </xsl:when>
245                        <xsl:otherwise>
246<xsl:message select="'~~~~~~~~~~~~~~~~otherwise'"/>
247                                <xsl:apply-templates select="document($url, /)/*" mode="ibis.copy"/>
248                        </xsl:otherwise>
249                </xsl:choose>
250        </xsl:template>
251
252
253        <xsl:template match="*" mode="ibis.copyOnlyChildren" 
254                ibis:doc="
255                        General mechanism to include only child/contained text and elements. 
256                        This is mainly used for processing HTML_CONTENT type elements where
257                        the main root element needs to be skipped and only it's contents
258                        copied.  This is similar behavior as ibis:include's children-only-flag.
259                "
260        >
261                <xsl:apply-templates select="current()/(text() | *)" mode="ibis.copy"/>
262        </xsl:template>
263
264
265        <xsl:template name="ibis.contentApplyTemplates"
266                ibis:doc="Explicit call to process general CONTENT and returns the
267                        actual text and child elements sans the CONTENT container element
268                        if it exists.  This is potentially safer compared to direct apply
269                        ibis.copyOnlyChildren because of the checking performed.  The apply
270                        mode=ibis.copyOnlyChildren is an easier call when there is a CONTENT
271                        element. 
272
273                        Tried apply/match of CONTENT but had issues with include processing
274                        handling/removing the CONTENT container element premarturely.  For
275                        example an include that contains SELECTION/CONTENT (which the
276                        selection XLST processes for explicitly later when creating the html). 
277                        When the include processes the file it would match and auto processes
278                        the SELECTION/CONTENT thus removing the CONTENT element from the
279                        parent SELECTION element and thus no longer exists when the SELECTION
280                        element is being processed by the explicit selection XSLT code. 
281                        This would result in problems with mega menu selections that had
282                        CONTENT and was also a problem with help content when being included.
283
284                        KNOWN VALUE CONTENT ELEMENTS as of 1/2021:
285                        HTML_CONTENT
286                                CONTENT
287                                ibis:ExpandableContent
288                                        CONTENT
289                        SELECTION/SELECTION
290                                CONTENT
291                        HELP
292                                CONTENT
293                "
294        >
295                <xsl:param name="content"/>
296
297                <xsl:apply-templates 
298                        select="if(exists($content/CONTENT))
299                                then $content/CONTENT/(text() | *)
300                                else $content/(text() | *)"
301                        mode="ibis.copy"
302                />
303        </xsl:template>
304
305</xsl:stylesheet>
306<!-- ============================= End of File ============================= -->
Note: See TracBrowser for help on using the repository browser.