View System Documentation - HTML_CONTENT Content Management
HTML_CONTENT XML files contain simple elements like TITLE (which contain the page's window title and content title), META_DATA, KEYWORDS (both of which are used as HTML HEAD meta data text elements), OTHER_CSS, OTHER_SCRIPT, and the main CONTENT element which contains the core page's body content HTML elements and text. See the HTML_CONTENT XML Model page for specific XML element definitions. The CONTENT element which contains the HTML elements and text are typically copied within this section of the resultant output HTML page:
<body>
<table id="body">
<tr>
<td class="LeftColumn">
[left context nav menu]
</td>
<td class="RightColumn">
[content header provided by SiteSpecific.xslt -
this is typically the contents of the TITLE
]
XSLT copies the content of the <CONTENT> element here
(processed for ibis: name spaced elements)
[content footer provided by SiteSpecific.xslt -
this is typically the org unit information]
HTML pages are built by using an XSLT and some Java code that resides on
the server. This Java code performs an XML/XSLT transformation which produces
an HTML file. This page discusses the best practices, basic XML gotcha's
when XML files contain HTML elements, URL Addressing, ibis: namespaced
elements, and how to view/test an HTML_CONTENT page.
XML Gothca's
Because the HTML content is contained within an XML file and is thus XML content, the HTML code MUST adhere to the XML standards. Some of these basic rules are discussed on the XML Basics page. Listed below are some common problems that HTML web page developers may experience when putting HTML elements into the CONTENT XML element:- " " is undefined in XML. One way around this when using the ISO-8859-1 encoding, is to use   or   as both of these will produce a non-breaking space character.
- All singular, empty/non containing/bracketing element tags must use the XHTML singular element convention. Element tags like <br>, <hr>, and <input name='myInput' type='radio'> needs to be <br/>, <hr/>, and <input name='myInput' type='radio'/> etc. Note the "/" character at the end of the tag with older Netscape version needing a space before the / e.g. "_/".
- XML only accepts three characters below the space character " " (0x20): tab (0x9), line feed (0xA), and carriage return (0xD).
- The "<", ">", and "&" characters are NOT allowed within an element's text (as these are used to define elements). These need to be escaped as <, >, and &.
Note that the XML CDATA <![CDATA[ some content ]]>
statement can be used if the content contains malformed XML or allot of reserved
characters. This can be handy for large embedded scripts, large sections of
HTML code that is simply copies and pasted within a file without the time to
go through and cleanup, or to show example HTML code snippets etc.
Best Practices
Listed below are some simple best practices that will help create and maintain HTML content pages. See the HTML Page Design page for more information.- Format HTML_CONTENT XML documents consistently. This includes indenturing and nesting, white space to break up element contents, wrapping of long text onto multiple lines, keeping text lines to around 80 characters per line so that most editors can display properly and so that the text may be easily printed.
- When indenturing, use the "Tab" character instead of spaces. Make sure the editor being used does not substitute the "tab" character with "n" spaces. This keeps indented documents smaller. It also allows for far easier global search and replace changes to be made.
- HTML content should be kept as simple as possible.
- Use the standard or other centrally stored CSS definitions. This allows for the localization of global look and feel properties thus helping to keep system maintenance lower while boosting system look and feel consistency.
- Avoid HTML attributes formatting and localized "style" attribute usage - use CSS whenever possible.
- Use the "ibis:" namespace for all local IBIS-PH View System resource referencing. See the next topic.
- Take advantage of the ibis: name spaced elements. If enhanced functionality is desired add it to either the SiteSpecific.xslt or to the HTMLContentPage.xslt.
HTML Relative VS. Absolute URL Addressing
Relative URL addressing provides a way to address a resource relative to the current web server's resource path without having to specify the protocol, server address, port, application context, and directory path information. This helps page maintenance as the links are not dependent on the application's deployed directory or how the web server is configured or how the application is mapped. Most web developers (especially dynamically created content JSP and ASP developers) use relative addressing as much as possible to not only simplify page link URLs but also to simplify image links, stylesheet links, and script links. The majority of all local application links contained within the HTML_CONTENT XML pages should use absolute resource addressing. This is because unless the page is using the same URL mapping that goes to the same Java servlet controller or which points to the same directory, the resource will not be located or delivered correctly. Because absolute addressing is very site and deployment specific and thus difficult to maintain a special mechanism has been built into the "HTMLContentPage.xslt" CONTENT processing template. This mechanism uses the "ibis:" namespace for link type URL attributes (src='', action='', href=''). When the template processes these type attributes with the "ibis:" namespace prefix the attribute's resource link value will be prefixed with the "WebAppURLContextPrefix" parameter value (which is added by the Java controller code via an XSLT parameter). This allows the link to be an absolute application link without having to know the application's context address. See the Resource Addressing page for more specific information. Listed below are some examples.
Given:
WebAppURLContextPrefix Parameter =
"http://the.server:8080/the_app_context/"
External link to Utah's "Disease Fact Sheets":
<a href="http://health.utah.gov/epi/fact_sheets/Default.htm">
Utah's Disease Fact Sheets Page
</a>
==> http://health.utah.gov/epi/fact_sheets/Default.htm
Internal application link to the "IBIS-PH Acknowledgments" page:
<a ibis:href="home/Acknowledgments.html">
IBIS-PH Acknowledgments Page
</a>
==> http://the.server:8080/the_app_context/home/Acknowledgments.html
Internal application using a relative addressing link to the
"IBIS-PH Acknowledgments" page when on the IBIS-PH Welcome Page.
This shows relative addressing which is possible since both page
exist in the same directory and are thus based on the same path
(home):
<a href="Acknowledgments.html">IBIS-PH Acknowledgments Page</a>
==> [http://server/app_context/home/]Acknowledgments.html
where the browser supplies the implied relative address
of: http://server/app_context/home/
Internal application link to an image file:
<img src="contentfile/image/thoth.gif"/>
==> http://the.server:8080/the_app_context/image/thoth.gif
IMPORTANT: If the page contains any "ibis:" namespace type attributes then
the 'xmlns:ibis="http://www.ibisph.org"' must be applied the the main
HTML_CONTENT, CONTENT, or any parent containing element.
Example:
<CONTENT xmlns:ibis="http://www.ibisph.org">Processing "ibis:" namespace elements within HTML_CONTENT/CONTENT
Listed below are types of "ibis:" elements that are processed within the HTML_CONTENT/CONTENT elements via the HTMLContentPage.xslt. They are:ibis:include
This element has an "href" attribute that is typically a file name pointer relative to the current XML file. This value may also be a complete URL but this has not been tested. The href attribute is named this way to be consistent with the more standard "xi:include" element. The "ibis:include" element also has an option to only include and process the child files text and elements. This flag is implemented as an attribute and if present with any value is enabled. The attribute is called: "include-children-only".
Example of a Birth Query Module including the "Year.xml" section file (where the file is stored in a subdirectory named "section":<ibis:include href="section/Year.xml"/>
Example of an HTML_CONTENT including a file from a peer directory named "home" which includes all the content after that included file's main root element:<ibis:include href="../home/SomeFile.xml" include-children-only="x"/>
ibis:ExpandableSelectionsList
Provides ability to more easily embed an expandable content list. The initial SELECTIONS/SELECTIONs are the container control with sub SELECTIONS/SELECTIONs being turned into a unordered list. Note that the approp CSS and JS will need to be included and initialized. Code creates a control element with an ID based on the optional NAME sub element+ position() looping value. This will create unique ID's in most cases.ibis:SelectionsTree
Provides ability to more easily create an expandable tree structure based on the standard SELECTIONS/SELECTION structure. Note that the approp CSS and JS will need to be included and initialized. For this to work, the SELECTIONS element must be a child element. The parent ID is based on position() thus only enabling one tree per document.ibis:ExpandableSection
Provides ability to more easily embed an expandable content block into the CONTENT. Note that the approp CSS and JS will need to be included and initialized. Code creates a control element with an ID based on the optional NAME sub element. If NAME doesn't exist then the position() is used. This will create unique ID's in most cases. The CONTENT text() and sub elements will be ibis:copied into the assoc content container DIV.
Viewing an HTML_CONTENT Page
To display an XML PAGE page it must first be transformed from XML to HTML. This is done via an XSLT (XML transformation stylesheet). The XSLT is an XML file that contains a defined language/rules on how XML element contents are to be manipulated. The XSLT that is typically used to transform an XML HTML_CONTENT page to HTML is contained with the "xslt/html/HTMLContent.xslt" file. This transformation is controlled and performed on the server using Java servlet controller code. There are two basic ways to do a transformation using the View System. 1) use the generic XML/XSLT "view" Java servlet controller, 2) use a special mapped XML/XSLT transformation Java servlet controller. The generic transformation Java servlet controller simply specifies the XML and XSLT files to be used for the transformation as of the request's URL. The latter option involves some URL mapping magic (see the How URL Resource Mapping Works page for more info). If the mapping is already configured to handle HTML_CONTENT XML file pages for a given directory then all that is needed is to create the HTML_CONTENT XML file in the directory and specify the XML filename with an HTML extension in the browser's URL address. Both of these options are discussed below.XSLT NOTES:
The "xslt/html/HTMLContentPage.xslt" XSLT template file is used to create an HTML page based on an HTML_CONTENT XML document. This XSLT simply implements a few "Page." template overrides and imports the optional "SiteSpecific.xslt" XSLT template to allow custom site specific template override definitions. These templates are specific to the HTML_CONTENT XML elements. The main body content is copied from the CONTENT element by the "ibis:copy" match template. These templates basically copy any and all text and non "ibis:" elements contained within the CONTENT element tags and pastes that content into the main HTML page's content area. See the XSLT Design page for more details on how the pages are laid out and which templates are used.For "ibis:" type elements, the "HTMLContentPage.xslt" will process those elements and not copy them. This includes the "ibis:include" as well as any special "ibis:" type namespace processing.
The generic "View" servlet controller method is typically only used now
for testing purposes and a few other transformations like the XSLT page
documentation/reports. However, it can be used for a production deployment
and for quite a while Utah's entire site used only this simple mechanism.
Using this basic transformation keeps the system very simple and straight
forward. Configuration and system maintenance are very minimal and there
is not a reliance on the more specialized Java servlet controller code.
However, this makes the system more difficult for internal navigation
and is difficult for web crawlers to index the site.
Utah Home Welcome XML PAGE Page Viewing Examples
The following examples show how to display the existing Utah "Home Welcome" page via the two different page display mechanisms. The first uses the generic View servlet controller. Note the URL request parameters (query string) which has the "xml=home/html_content/Welcome.xml". This controller has the base XML directory set to "[tomcat]/webapps/ibisph-view/xml". The "xml" URL request parameter specified is then concatenated with the XML path property to get the file's actual, real path of "[tomcat]/webapps/ibisph-view/xml/home/html_content/Welcome.xml". The XSLT file is located in the exact same way except it uses the "xslt" URL parameter and has the Java controller set with an XSLT path property. For the mapped example the "WEB-INF/config/spring/home.xml" bean configuration file contains several bean definitions which are used to control the "home" type transformations (see the "Home.HTMLContent.XML.Path", "Home.HTMLContent.Controller", "Home.Page.XSLT.SystemID" and the "Home.HTMLContent.View" bean definitions). Basically how this controller works is that it pulls the filename part of the requested resource's URL and uses that value along with the XML path bean/property to specify the actual HTML_CONTENT XML file to be used (the XSLT is specified as a bean property with the view property containing the XML/XSLT transformation engine).
Generic "home/Welcome" View Servlet Controller Example:
http://ibis.health.utah.gov/view
?xml=home/html_content/Welcome.xml
&xslt=html/home/HTMLContent.xslt
Existing "home/Welcome" Mapped Servlet Controller Example:
http://ibis.health.utah.gov/home/Welcome.html
Java Controller and URL Mapping Configuration Overview
If the page is to be referenced as a ".html" file (made to look like a static HTML page) then the following items are needed (using Utah's Home type page requests as an example):- Verify/create an entry in the web.xml's "servlet-mapping" for the page's
directory which looks like:
<servlet-mapping> <servlet-name>Dispatcher.Servlet</servlet-name> <url-pattern>/home/*</url-pattern> </servlet-mapping> - Verify/create an entry in the "request_dispatcher.xml" Spring bean
configuration file's URL mapping section (URL to controller) which looks
like:
<property name="mappings"> <props> <prop key="/home/**">Home.HTMLContent.Controller</prop> - Verify/create the appropriate bean views and controller property settings
for the files XML directory and which XSLT to use which includes:
<bean id="Home.HTMLContent.XML.Path" class= "org.springframework.beans.factory. config.MethodInvokingFactoryBean"> <property name="targetObject"><ref bean="Context.Servlet"/></property> <property name="targetMethod"><value>getRealPath</value></property> <property name="arguments"> <list><value>xml/home/html_content</value></list> </property> </bean> . . . <bean id="Home.HTMLContent.Controller" class= "org.ibisph.mvc.controller.XMLSystemIDFromEndOfPathInfo"> <constructor-arg index="0"> <ref bean="Home.HTMLContent.XML.Path"/> </constructor-arg> <constructor-arg index="1"> <ref bean="Home.HTMLContent.View"/> </constructor-arg> <property name="defaultXMLFilename"> <value>welcome.xml</value> </property> </bean> . . . <bean id="Home.HTMLContent.XSLT.SystemID" class= "org.ibisph.resource.FileSystemID"> <constructor-arg index="0" type="java.lang.String"> <ref bean="Context.Servlet.RootPath"/> </constructor-arg> <constructor-arg index="1" type="java.lang.String"> <value>xslt/home/page.xslt</value> </constructor-arg> </bean> . . . <bean id="Home.HTMLContent.View" class= "org.ibisph.mvc.view.XSLTXMLTransformation"> <constructor-arg index="0"> <ref bean="Home.HTMLContent.XSLT.SystemID"/> </constructor-arg> <constructor-arg index="1"> <ref bean="XSLT.Transformation"/> </constructor-arg> </bean>