View System Documentation - ibis:include Implementation
There are two mechanisms employed by the IBIS-PH View System to enable the include operations. They are:
Two Step XSLT Transformation
An include processing XSLT is used by a Java controller object to create a temporary, fully ibis:include processed XML document in memory. The page presentation XSLT is then instructed to use this in memory XML document to produce the end user page.Internal XSLT XML Container Variable
The "Page" producing XSLT contains an all inclusive XSLT variable which has processed the "ibis:include" elements - variable that contains all XML document's elements. This approach is used for HTML_CONTENT pages and for the Query Module Selection pages.
The rest of this page is broken down into the following sections: background, features/limitations, a more detailed description of how each approach works, directories and naming standards, and lastly a couple of examples.
Background
As of May, 2005, the IBIS system uses the Xerces Java XML parser (version 2.6.x). This parser is a standard open source parser which has xinclude support. However, to get it to work, a Java system property must be set. The problem here is that the IBIS-PH View system has to be deployable to many different app servers and needs to exist with other web applications being served on that same app server. So it needs to exist stand alone within the deployed environment. Also, some system administrators might not be able to/want to implement this feature while other app servers might use another xml package. This normally wouldn't be a problem since all that would need to be done is to include the XML related packages as part of the IBIS-PH View app's deployment. But this is where the problem is - XML parsers have their own way of loading themselves and there is not a way to override this behavior (see the XML Parser Notes page for a more detailed discussion).ibis: Namespace Prefix
The namespace prefix referenced in the "include" element namespace is "ibis:" and NOT the typical "xi:" or "xinc". This was done because of make sure that the developer knew that the standard "xi:include" was not being used - to lessen confusion on figuring out where the "include" was coming from/how to enable. Put another way, if NOT a standard xinclude type element it needs to be clear that the include is implemented as part of the system and the "ibis:" prefix helps the user know to look in the main, core "ibis.xslt" file which also contains the "ibis.copy" match template. Put yet another way: this makes it more obvious that the include solution is an IBIS specific, special thing which has special needs (namely that the transformation package needs to pre process the source XML file with another XSLT).IMPORTANT: The namespace signature/identifier MUST
match exactly. An "ibis:include" element with its namespace
declared in the XSLT as: xmlns:ibis="http://www.ibisph.org" will not
process an XML file's include statement if its "ibis:" namespace is
declared as: xmlns:ibis="http://some.other.address" - even though
both are legal values.
To enable this type of functionality for the IBISQ modules, a simple two step process involving code in the Java controller which uses an XSLT to provide this functionality. Not only does this solution provide the ability to do simple xinclude type operations but it also enables a special "include-sub-only" operation where only the elements and contents below the xinclude file's root element are included. The down side is that this is not seamless and requires a special processing/pre usage transformation to work. When a module request is made, the Java servlet/controller object does two transformations. The first transformation uses the "xslt/xml/query/module/ConfigurationIncludeCriteriaExclude.xslt" transformation stylesheet which simply copies the contents of the base XML document . The stylesheet simply processes all the <ibis:include ...> elements. When an "include" element is found, the XSLT opens the document specified via the associated href="" attribute and then copies the elements from the included file into the current source document. The second transformation performs the real requested transformation but uses the first transformation's XML result to create the HTML page.
When a module request is made, the Java servlet/controller object does two transformations. The first transformation uses the "xinclude.xslt" transformation stylesheet which simply copies the contents of the base XML document. The stylesheet simply processes all the <ibis:include ...> elements. When an "include" element is found, the XSLT opens the document specified via the associated href="" attribute and then copies the elements from the included file into the current source document. The second transformation performs the real requested transformation but uses the first transformation's XML result to create the HTML page.
Another more seamless Xinclude XSLT solution exists and is implemented for the Module Selection type pages and . This solution utilizes a main variable that contains all the "xincluded" documents. The page then needs to reference this main variable to get the correct data elements. This approach consumes memory for those large Module Selection pages (of which there are only a couple). It is also slower. Since Query Module Selection pages are good candidates to be artifacted or since most are small this solution is used. See the Query Module Selection XSLT documentation for a further discussion.
How It Works
Limitations and Features
Listed below are the features and limitations of the "xinclude.xslt":- Xincludes can reference any file that can be accessed by a URL or a file path.
- The standard "include" is designed to work like the standard xinclude. However, only the "href" attribute is used. The xinclude spec specifies that "xbase" and a "type" attribute are available but at this time the xinclude.xslt has only implemented support for the href attribute. These other attributes can be inserted/specified for the future when a parser that supports this functionality natively becomes available. Just be aware that these extra attributes are currently not used/recognized.
- A special "include-sub-only" element exists that allows for the included file's root element to not be inserted into the destination (main file which contains the xinclude statement) XML file structure.
- Xincldues are recursive and can be nested (you can have an xinclude inside a file that itself will be xincluded). However, to lessen maintenance complexity, it is recommended that this practice be lightly used (the exception and not the rule).
- Xinclude files MUST match ALL the standards of an XML file (namely a prologue, root element, well formed etc.).
- Due to the fact that this solution involves the need for a pre transformation, xincludes must be specifically programmed for and are currently only implemented for Query Modules.
- XML validation can not be done until after the intermediate transformation has taken place. This is also sometimes the case even when using an XML parser that supports xinclude - due to where that parser implements it's xinclude functionality in it's processing sequence v.s. where it implements the validation (some processors do validation first before anything others do it last after an xinclude is performed).
- This extra transformation step can potentially slow down the responsiveness of the system.
- The xinclude XSLT is coded to look for the "ibis:" namespace when doing either type of xinclude. So if a different namespace say "xin" or "xi" is used the xinclude XSLT will not be able to find the <xi:xinclude> element and thus the document will not be included/inserted. Also, the namespace MUST match ibis namespace so even though "xmlns:xi=http://www.w3.org/2001/XInclude" and "xmlns:xi=http://www.w3.org/2003/XInclude" are typical namespaces used in most Xinclude examples found on the web, it does not match the value specified in the xinclude.xslt file which as of 8/15/2004 is: "xmlns:ibis=http://ibis.health.utah.gov/ibisq_xml".
Basic Usage
Any XML element can be included within a parent XML document simply by adding an element like:<ibis:include href="filename_of_content_to_be_included.xml" xmlns:ibis="http://ibis.health.utah.gov/ibisq_xml"/>Where the href attribute specifies a URL, or an explicitly pathed filename, or a relatively pathed filename (relative to the source xml document). Listed below are the requirements:
- If the path does not start with a "/" character then the path is relative to the source xml document's directory.
- Included element segments MUST have a main container element. So for example you can not have a simple list of ANSWER elements within the included file. These elements MUST be contained within an element. So for this example put all the ANSWER elements within an <ANSWERS> element. When this is done, note that you MUST have all the other container's element attributes defined within the xincluded file as well, otherwise those elements will be incorrectly nested.
- The namespace must be specified either within the xinclude element or within one of the containing elements. This namespace is: xmlns:ibis="http://ibis.health.utah.gov/ibisq_xml".
Advanced Usage
This section discusses two topics. 1) The singular declaration of the ibis namespace, and 2) the usage of the "include-sub-only" include element that does NOT copy the root element.Singular Declaration of the IBIS Namespace: If there are multiple xincludes within a file, then it is probably easier to specify/create the "ibis" namespace within the file's root element rather then include the declaration within each xinclude statement. An example of this root element namespace declaration as well as how the include statement would look is shown below:
<QUERY xmlns:ibis="http://ibis.health.utah.gov/ibisq_xml"> . . . <ibis:include href="first_filename_of_content_to_be_included.xml"/> . . . <ibis:include href="next_filename_of_content_to_be_included.xml"/>Any XML element can be included within a parent XML document simply by adding an element like:
<ibis:include href="filename_of_content_to_be_included.xml" xmlns:ibis="http://ibis.health.utah.gov/ibisq_xml"/>Usage of the "include-sub-only" include element: This element is used in exactly the same way as the normal "include" element is used and has the same requirements. The main difference between the "include" element and this element is that when the "include-sub-only" element is used, the root element of the XML file being included is ignored with all sub text and elements added to the element of the source document being processed. The reason this is discussed in the Advanced Usage section is because using this feature can enable layered include files to be used. For example if an answers xinclude which includes the county type answers is used for 90% of all the time for the module file with the last 10% needing a few special county options like "other" or "unknown" then a standard county xinclude can be built with a special xinclude which xincludes the standard answers and then defines the extra answer elements needed. This is not possible with the standard "include" element because it copies the entire root element starting with the root element's tag.
IMPORTANT: This functionality can be very powerful. However, this is a non standard
solution which is currently only setup for IBISQ modules and measure selection type XMLs.
As such its usage is not transparently ported to other parts of the system.
Xinclude Directory Structure for Utah's IBIS System (as of August 2004):
The following directory structure shows the current xinclude directories which are located under the "webapps/ibisph-view/xml/query" directory.
| Directory | Content Description |
|---|---|
| /xinclude | |
| /answers | main container for all xinclude files |
| /data_issue | answers element definitions to be xincluded |
| /data_note | data issue element definitions |
| /data_source | data note element definitions |
| /dimension | data source element definitions |
| /help | dimension definitions which match 1:1 the answer definitions |
| /overview | help definitions to be xincluded |
| /text | Generic text element definitions which are can be xincluded in other xinclude files like overview, help, data issues, data notes, data sources |
NOTES:
- Any file structure can be used for the system - there are not any hard coded directories needed for this system to work. For the Tomcat application server the main query XML directory is typically: {$tomcat_home}/webapps/ibisph-view/xml/query. The main starting directory location for the query xml files is typically "xml/query". If a different base location is used then a value can be specified in a Java "properties" file which is named "global.properties" and is stored in the root of the application's directory.
- The directory names are named via a standard where all directory names are lower case. This is useful for web and application server standards because file names are case sensitive.
- The directory is named according to the type of root container XMl element. So the answers directory contains XML files that all have "ANSWERS" as their main root element.
File Naming Conventions
Within each directory, the files should be named as consistently and descriptively as possible. The file should be mixed case going from most specific to least specific. If the file applies to a specific dataset, it should contain an underscore character "_" then the dataset name.Basic XML Example
This example deals only with snippets of XML elements as complete XML listings are too large. Below is shown a specific portion of a query module XML definition which deals with the local health district question and answers elements. The first listing shows what the non xincluded XML would normally look like. The second listing shows what the new, revised xinclude XML snippet. The third listing shows the full local health district XML answer set which was xincluded in listing 2. The example assumes the above directory structure where the module XML file resides in the xml/query/Module directory.Listing 1 (original XML module local health district question/answers element definition):
<ANSWER>
<TITLE>Local Health District</TITLE>
<VALUE>4</VALUE>
<QUESTION>
<TITLE>Select the Health District(s):</TITLE>
<DESCRIPTION>Filter by health district</DESCRIPTION>
<ANSWERS>
<TYPE>MULTIPLE</TYPE>
<NAME>geoLHD</NAME>
<ANSWER><TITLE>Bear River</TITLE> <VALUE>1</VALUE></ANSWER>
<ANSWER><TITLE>Central Utah</TITLE> <VALUE>2</VALUE></ANSWER>
<ANSWER><TITLE>Davis County</TITLE> <VALUE>3</VALUE></ANSWER>
<ANSWER><TITLE>Salt Lake Cnt</TITLE><VALUE>4</VALUE></ANSWER>
<ANSWER><TITLE>Southeastern</TITLE> <VALUE>5</VALUE></ANSWER>
<ANSWER><TITLE>Southwest UT</TITLE> <VALUE>6</VALUE></ANSWER>
<ANSWER><TITLE>Summit County</TITLE><VALUE>7</VALUE></ANSWER>
<ANSWER><TITLE>Tooele County</TITLE><VALUE>8</VALUE></ANSWER>
<ANSWER><TITLE>Tri-County</TITLE> <VALUE>9</VALUE></ANSWER>
<ANSWER><TITLE>Utah County</TITLE> <VALUE>10</VALUE></ANSWER>
<ANSWER><TITLE>Wasatch Cnty</TITLE> <VALUE>11</VALUE></ANSWER>
<ANSWER><TITLE>Weber/Morgan</TITLE> <VALUE>12</VALUE></ANSWER>
</ANSWERS>
</QUESTION>
</ANSWER>
Listing 2 (xincluded XML module local health district question/answers element definition):
<ANSWER>
<TITLE>Local Health District</TITLE>
<VALUE>4</VALUE>
<QUESTION>
<TITLE>Select the Health District(s):</TITLE>
<DESCRIPTION>Filter by health district</DESCRIPTION>
<ibis:include href="Answers/Geography/LHD.xml"
xmlns:ibis="http://ibis.health.utah.gov/ibisq_xml"
/>
</QUESTION>
</ANSWER>
Listing 3 (complete xincluded XML local health district question/answers module
element definition located in the Answers/Geography directory under the Module
directory):
<ANSWERS> <TYPE>MULTIPLE</TYPE> <NAME>geoLHD</NAME> <ANSWER><TITLE>Bear River</TITLE> <VALUE>1</VALUE></ANSWER> <ANSWER><TITLE>Central Utah</TITLE> <VALUE>2</VALUE></ANSWER> <ANSWER><TITLE>Davis County</TITLE> <VALUE>3</VALUE></ANSWER> <ANSWER><TITLE>Salt Lake County</TITLE><VALUE>4</VALUE></ANSWER> <ANSWER><TITLE>Southeastern</TITLE> <VALUE>5</VALUE></ANSWER> <ANSWER><TITLE>Southwest UT</TITLE> <VALUE>6</VALUE></ANSWER> <ANSWER><TITLE>Summit County</TITLE> <VALUE>7</VALUE></ANSWER> <ANSWER><TITLE>Tooele County</TITLE> <VALUE>8</VALUE></ANSWER> <ANSWER><TITLE>Tri-County</TITLE> <VALUE>9</VALUE></ANSWER> <ANSWER><TITLE>Utah County</TITLE> <VALUE>10</VALUE></ANSWER> <ANSWER><TITLE>Wasatch County</TITLE> <VALUE>11</VALUE></ANSWER> <ANSWER><TITLE>Weber/Morgan</TITLE> <VALUE>12</VALUE></ANSWER> </ANSWERS>
Advanced XML Example
This example builds on the above example but shows how the layered technique could be applied to an "Unknown" value xinclude file using the ibis include-sub-only element.Listing 4 (base standard ANSWER elements which are meant to be a part of another xinclude file. Note that the ANSWERS's TYPE and ROWS_TO_SHOW type elements are not present - just the core ANSWER elements. File is named list4.xml for this example):
<ANSWERS> <ANSWER><TITLE>Bear River</TITLE> <VALUE>1</VALUE></ANSWER> <ANSWER><TITLE>Central Utah</TITLE> <VALUE>2</VALUE></ANSWER> <ANSWER><TITLE>Davis County</TITLE> <VALUE>3</VALUE></ANSWER> <ANSWER><TITLE>Salt Lake County</TITLE><VALUE>4</VALUE></ANSWER> <ANSWER><TITLE>Southeastern</TITLE> <VALUE>5</VALUE></ANSWER> <ANSWER><TITLE>Southwest UT</TITLE> <VALUE>6</VALUE></ANSWER> <ANSWER><TITLE>Summit County</TITLE> <VALUE>7</VALUE></ANSWER> <ANSWER><TITLE>Tooele County</TITLE> <VALUE>8</VALUE></ANSWER> <ANSWER><TITLE>Tri-County</TITLE> <VALUE>9</VALUE></ANSWER> <ANSWER><TITLE>Utah County</TITLE> <VALUE>10</VALUE></ANSWER> <ANSWER><TITLE>Wasatch County</TITLE> <VALUE>11</VALUE></ANSWER> <ANSWER><TITLE>Weber/Morgan</TITLE> <VALUE>12</VALUE></ANSWER> </ANSWERS>Listing 5 (standard ANSWERS element which would be used via the standard xinclude for 90% of all modules):
<ANSWERS> <TYPE>MULTIPLE</TYPE> <NAME>geoLHD</NAME> <ibis:include-sub-only href="list4.xml"/> </ANSWERS>Listing 6 (layered exception ANSWERS element which would be used for the 10% of the modules that need the "Unknown" ANSWER element):
<ANSWERS> <TYPE>MULTIPLE</TYPE> <NAME>geoLHD</NAME> <ibis:include-sub-only href="list4.xml"/> <ANSWER><TITLE>Unknown</TITLE><VALUE>13</VALUE></ANSWER> </ANSWERS>Modules would then do an xinclude using the standard "include" element for the appropriate 90% answers file (listing 5) or the 10% answers file (listing 6). This page discusses the usage of the IBIS xinclude functionality for certain IBIS-PH View System XML files. Xinclude is a mechanism that enables an XML file's elements to be split out of the main XML file into sub XML files. This allows sections of elements to be modularized and potentially referenced/reused by many different XML files. The primary benefits of doing this are lessened module development time, lessened system maintenance, and higher data integrity. The downside of using xincludes is complexity of finding content and knowing where that content is used. The rest of this document is broken down into the following sections: background, limitations, usage, directories and naming standards, and lastly a couple of examples.
Background
As of 2008, the IBIS system uses the Xerces Java XML parser (version 2.x). This parser is a standard open source parser which has xinclude support. However, it isdisabeledd by default. To enable it, a Java system wide JVM property must be set. The problem here is that the IBIS-PH View system has to be deployable to many different app servers and needs to exist with other web applications being served on that same app server without requiring any "special needs" from system administrators (who might not be able to/want to implement this feature). If the XML parsers were not part of the standard distribution JVM then this wouldn't be a problem since all that would need to be done is to include the XML related packages as part of the IBIS-PH View app's deployment. But this is where the problem is; The Sun Java JVM includes an XML parser and with the JAXP technology, they have their own way of loading themselves and there is not a way to override this behavior (see the XML Parser Notes page for a more detailed discussion).To provide this type of functionality for the IBIS-PH View System query module XML files, a simple two step process is used. When a query module is requested, the Java controller uses an intermediary XSLT to process the "ibis:include" elements. It then performs the real requested XSLT transformation to return the requested page to the user. Not only does this solution provide the ability to do simple xinclude type operations but it also enables the exclusion of non used CONFIGURATION elements and excluded criteria elements. The down side to this "ibis:include" mechanism is that this is not seamless and requires a special intervening pre processing/usage transformation (which is what the XML parser does internally).
Another more seamless xinclude XSLT solution exists and is implemented
for the Module Selection type pages. This solution utilizes an XSLT
variable that contains all the processed "ibis:included" files. The
page building XSLT then uses this XSLT variable to access the XML
content to build the appropriate page. This approach consumes more
memory and for those large Module Selection pages (of which there are
only a couple) it is also slower. Since Query Module Selection pages
are good candidates to be artifacted or since most are small this
solution is used. See the Query Module Selection XSLT documentation
for a further discussion.
ibis: Namespace Prefix
The namespace prefix referenced in the xincludes element namespace is "ibis:" and NOT the typical "xi:" or "xinc". This was done because of the "include-sub-only" element which is NOT a standard xinclude type element and it needs to be clear that the xinclude is implemented as part of the system and not confused with the standard xinclude. Put another way: this makes it more obvious that the xinclude solution is an IBIS specific, special thing which has special needs (namely that the transformation package needs to pre process the source XML file with another XSLT).IMPORTANT: The namespace signature/identifier MUST match exactly. Put
another way, an "ibis:include" element with its namespace declared in the XSLT as:
xmlns:ibis="http://www.ibisph.org" will not process an XML file's include statement
if its "ibis:" namespace is declared as: xmlns:ibis="http://some.other.address".
Limitations and Features
Listed below are the features and limitations of the "xinclude.xslt":- Xincludes can reference any file that can be accessed by a URL or a file path.
- The standard "include" is designed to work like the standard xinclude. However, only the "href" attribute is used. The xinclude spec specifies that "xbase" and a "type" attribute are available but at this time the xinclude.xslt has only implemented support for the href attribute. These other attributes can be inserted/specified for the future when a parser that supports this functionality natively becomes available. Just be aware that these extra attributes are currently not used/recognized.
- A special "include-sub-only" element exists that allows for the included file's root element to not be inserted into the destination (main file which contains the xinclude statement) XML file structure.
- Xincldues are recursive and can be nested (you can have an xinclude inside a file that itself will be xincluded). However, to lessen maintenance complexity, it is recommended that this practice be lightly used (the exception and not the rule).
- Xinclude files MUST match ALL the standards of an XML file (namely a prologue, root element, well formed etc.).
- Due to the fact that this solution involves the need for a pre transformation, xincludes must be specifically programmed for and are currently only implemented for Query Modules.
- XML validation can not be done until after the intermediate transformation has taken place. This is also sometimes the case even when using an XML parser that supports xinclude - due to where that parser implements it's xinclude functionality in it's processing sequence v.s. where it implements the validation (some processors do validation first before anything others do it last after an xinclude is performed).
- This extra transformation step can potentially slow down the responsiveness of the system.
- The xinclude XSLT is coded to look for the "ibis:" namespace when doing either type of xinclude. So if a different namespace say "xin" or "xi" is used the xinclude XSLT will not be able to find the <xi:xinclude> element and thus the document will not be included/inserted. Also, the namespace MUST match ibis namespace so even though "xmlns:xi=http://www.w3.org/2001/XInclude" and "xmlns:xi=http://www.w3.org/2003/XInclude" are typical namespaces used in most Xinclude examples found on the web, it does not match the value specified in the xinclude.xslt file which as of 8/15/2004 is: "xmlns:ibis=http://ibis.health.utah.gov/ibisq_xml".
The IBIS-PH View System provides several xinclude type reports that can help with this but it is still an issue.
Basic Usage
Any XML element can be included within a parent XML document simply by adding an element like:<ibis:include href="filename_of_content_to_be_included.xml" xmlns:ibis="http://ibis.health.utah.gov/ibisq_xml"/>Where the href attribute specifies a URL, or an explicitly pathed filename, or a relatively pathed filename (relative to the source xml document). Listed below are the requirements:
- If the path does not start with a "/" character then the path is relative to the source xml document's directory.
- Included element segments MUST have a main container element. So for example you can not have a simple list of ANSWER elements within the included file. These elements MUST be contained within an element. So for this example put all the ANSWER elements within an <ANSWERS> element. When this is done, note that you MUST have all the other container's element attributes defined within the xincluded file as well, otherwise those elements will be incorrectly nested.
- The namespace must be specified either within the xinclude element or within one of the containing elements. This namespace is: xmlns:ibis="http://ibis.health.utah.gov/ibisq_xml".
Advanced Usage
This section discusses two topics. 1) The singular declaration of the ibis namespace, and 2) the usage of the "include-sub-only" include element that does NOT copy the root element.Singular Declaration of the IBIS Namespace: If there are multiple xincludes within a file, then it is probably easier to specify/create the "ibis" namespace within the file's root element rather then include the declaration within each xinclude statement. An example of this root element namespace declaration as well as how the include statement would look is shown below:
<QUERY xmlns:ibis="http://ibis.health.utah.gov/ibisq_xml"> . . . <ibis:include href="first_filename_of_content_to_be_included.xml"/> . . . <ibis:include href="next_filename_of_content_to_be_included.xml"/>Any XML element can be included within a parent XML document simply by adding an element like:
<ibis:include href="filename_of_content_to_be_included.xml" xmlns:ibis="http://ibis.health.utah.gov/ibisq_xml"/>Usage of the "include-sub-only" include element: This element is used in exactly the same way as the normal "include" element is used and has the same requirements. The main difference between the "include" element and this element is that when the "include-sub-only" element is used, the root element of the XML file being included is ignored with all sub text and elements added to the element of the source document being processed. The reason this is discussed in the Advanced Usage section is because using this feature can enable layered include files to be used. For example if an answers xinclude which includes the county type answers is used for 90% of all the time for the module file with the last 10% needing a few special county options like "other" or "unknown" then a standard county xinclude can be built with a special xinclude which xincludes the standard answers and then defines the extra answer elements needed. This is not possible with the standard "include" element because it copies the entire root element starting with the root element's tag.
IMPORTANT: This functionality can be very powerful. However, this is a non standard
solution which is currently only setup for IBISQ modules and measure selection type XMLs.
As such its usage is not transparently ported to other parts of the system.
Xinclude Directory Structure for Utah's IBIS System (as of August 2004):
The following directory structure shows the current xinclude directories which are located under the "webapps/ibisph-view/xml/query" directory.
| Directory | Content Description |
|---|---|
| /xinclude | |
| /answers | main container for all xinclude files |
| /data_issue | answers element definitions to be xincluded |
| /data_note | data issue element definitions |
| /data_source | data note element definitions |
| /dimension | data source element definitions |
| /help | dimension definitions which match 1:1 the answer definitions |
| /overview | elp definitions to be xincluded |
| /text | Generic text element definitions which are can be xincluded in other xinclude files like overview, help, data issues, data notes, data sources |
NOTES:
- Any file structure can be used for the system - there are not any hard coded directories needed for this system to work. For the Tomcat application server the main query XML directory is typically: {$tomcat_home}/webapps/ibisph-view/xml/query. The main starting directory location for the query xml files is typically "xml/query". If a different base location is used then a value can be specified in a Java "properties" file which is named "global.properties" and is stored in the root of the application's directory.
- The directory names are named via a standard where all directory names are lower case. This is useful for web and application server standards because file names are case sensitive.
- The directory is named according to the type of root container XMl element. So the answers directory contains XML files that all have "ANSWERS" as their main root element.
File Naming Conventions
Within each directory, the files should be named as consistently and descriptively as possible. The file should be mixed case going from most specific to least specific. If the file applies to a specific dataset, it should contain an underscore character "_" then the dataset name.Basic XML Example
This example deals only with snippets of XML elements as complete XML listings are too large. Below is shown a specific portion of a query module XML definition which deals with the local health district question and answers elements. The first listing shows what the non xincluded XML would normally look like. The second listing shows what the new, revised xinclude XML snippet. The third listing shows the full local health district XML answer set which was xincluded in listing 2. The example assumes the above directory structure where the module XML file resides in the xml/query/Module directory.Listing 1 (original XML module local health district question/answers element definition):
<ANSWER>
<TITLE>Local Health District</TITLE>
<VALUE>4</VALUE>
<QUESTION>
<TITLE>Select the Health District(s):</TITLE>
<DESCRIPTION>Filter by health district</DESCRIPTION>
<ANSWERS>
<TYPE>MULTIPLE</TYPE>
<NAME>geoLHD</NAME>
<ANSWER><TITLE>Bear River</TITLE> <VALUE>1</VALUE></ANSWER>
<ANSWER><TITLE>Central Utah</TITLE> <VALUE>2</VALUE></ANSWER>
<ANSWER><TITLE>Davis County</TITLE> <VALUE>3</VALUE></ANSWER>
<ANSWER><TITLE>Salt Lake Cnt</TITLE><VALUE>4</VALUE></ANSWER>
<ANSWER><TITLE>Southeastern</TITLE> <VALUE>5</VALUE></ANSWER>
<ANSWER><TITLE>Southwest UT</TITLE> <VALUE>6</VALUE></ANSWER>
<ANSWER><TITLE>Summit County</TITLE><VALUE>7</VALUE></ANSWER>
<ANSWER><TITLE>Tooele County</TITLE><VALUE>8</VALUE></ANSWER>
<ANSWER><TITLE>Tri-County</TITLE> <VALUE>9</VALUE></ANSWER>
<ANSWER><TITLE>Utah County</TITLE> <VALUE>10</VALUE></ANSWER>
<ANSWER><TITLE>Wasatch Cnty</TITLE> <VALUE>11</VALUE></ANSWER>
<ANSWER><TITLE>Weber/Morgan</TITLE> <VALUE>12</VALUE></ANSWER>
</ANSWERS>
</QUESTION>
</ANSWER>
Listing 2 (xincluded XML module local health district question/answers element definition):
<ANSWER>
<TITLE>Local Health District</TITLE>
<VALUE>4</VALUE>
<QUESTION>
<TITLE>Select the Health District(s):</TITLE>
<DESCRIPTION>Filter by health district</DESCRIPTION>
<ibis:include href="Answers/Geography/LHD.xml"
xmlns:ibis="http://ibis.health.utah.gov/ibisq_xml"
/>
</QUESTION>
</ANSWER>
Listing 3 (complete xincluded XML local health district question/answers module
element definition located in the Answers/Geography directory under the Module
directory):
<ANSWERS> <TYPE>MULTIPLE</TYPE> <NAME>geoLHD</NAME> <ANSWER><TITLE>Bear River</TITLE> <VALUE>1</VALUE></ANSWER> <ANSWER><TITLE>Central Utah</TITLE> <VALUE>2</VALUE></ANSWER> <ANSWER><TITLE>Davis County</TITLE> <VALUE>3</VALUE></ANSWER> <ANSWER><TITLE>Salt Lake County</TITLE><VALUE>4</VALUE></ANSWER> <ANSWER><TITLE>Southeastern</TITLE> <VALUE>5</VALUE></ANSWER> <ANSWER><TITLE>Southwest UT</TITLE> <VALUE>6</VALUE></ANSWER> <ANSWER><TITLE>Summit County</TITLE> <VALUE>7</VALUE></ANSWER> <ANSWER><TITLE>Tooele County</TITLE> <VALUE>8</VALUE></ANSWER> <ANSWER><TITLE>Tri-County</TITLE> <VALUE>9</VALUE></ANSWER> <ANSWER><TITLE>Utah County</TITLE> <VALUE>10</VALUE></ANSWER> <ANSWER><TITLE>Wasatch County</TITLE> <VALUE>11</VALUE></ANSWER> <ANSWER><TITLE>Weber/Morgan</TITLE> <VALUE>12</VALUE></ANSWER> </ANSWERS>
Advanced XML Example
This example builds on the above example but shows how the layered technique could be applied to an "Unknown" value xinclude file using the ibis include-sub-only element.Listing 4 (base standard ANSWER elements which are meant to be a part of another xinclude file. Note that the ANSWERS's TYPE and ROWS_TO_SHOW type elements are not present - just the core ANSWER elements. File is named list4.xml for this example):
<ANSWERS> <ANSWER><TITLE>Bear River</TITLE> <VALUE>1</VALUE></ANSWER> <ANSWER><TITLE>Central Utah</TITLE> <VALUE>2</VALUE></ANSWER> <ANSWER><TITLE>Davis County</TITLE> <VALUE>3</VALUE></ANSWER> <ANSWER><TITLE>Salt Lake County</TITLE><VALUE>4</VALUE></ANSWER> <ANSWER><TITLE>Southeastern</TITLE> <VALUE>5</VALUE></ANSWER> <ANSWER><TITLE>Southwest UT</TITLE> <VALUE>6</VALUE></ANSWER> <ANSWER><TITLE>Summit County</TITLE> <VALUE>7</VALUE></ANSWER> <ANSWER><TITLE>Tooele County</TITLE> <VALUE>8</VALUE></ANSWER> <ANSWER><TITLE>Tri-County</TITLE> <VALUE>9</VALUE></ANSWER> <ANSWER><TITLE>Utah County</TITLE> <VALUE>10</VALUE></ANSWER> <ANSWER><TITLE>Wasatch County</TITLE> <VALUE>11</VALUE></ANSWER> <ANSWER><TITLE>Weber/Morgan</TITLE> <VALUE>12</VALUE></ANSWER> </ANSWERS>Listing 5 (standard ANSWERS element which would be used via the standard xinclude for 90% of all modules):
<ANSWERS> <TYPE>MULTIPLE</TYPE> <NAME>geoLHD</NAME> <ibis:include-sub-only href="list4.xml"/> </ANSWERS>Listing 6 (layered exception ANSWERS element which would be used for the 10% of the modules that need the "Unknown" ANSWER element):
<ANSWERS> <TYPE>MULTIPLE</TYPE> <NAME>geoLHD</NAME> <ibis:include-sub-only href="list4.xml"/> <ANSWER><TITLE>Unknown</TITLE><VALUE>13</VALUE></ANSWER> </ANSWERS>Modules would then do an xinclude using the standard "include" element for the appropriate 90% answers file (listing 5) or the 10% answers file (listing 6).