Skip directly to searchSkip directly to the site navigationSkip directly to the page's main content

View System Documentation - HTML_CONTENT Content Management

This page describes how to create and view the "HTML_CONTENT" type XML documents. HTML_CONTENT XML documents are simple HTML content containers that allow for static HTML type pages to be built and displayed in/by the IBIS-PH View System without having to manually code the entire page. This allows the content developer to focus on the page's main content rather than having to concern themselves with the page layout, headers/banners, navigation, footers, etc. Put another way, it provides the site with a consistent look and feel while allowing the author free to be able to create any type of HTML page with lessened HTML coding and page maintenance. This mechanism also has other special features due to the use of XSLT templates which include processing SELECTION type lists, collapsible sections, expandable tree selections, and modularizing file content into multiple files via the "ibis:include" mechanisms.

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:
  • "&nbsp;" is undefined in XML. One way around this when using the ISO-8859-1 encoding, is to use &#xA0; or &#160; 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 &lt;, &gt;, and &amp;.
  • Extended ASCII characters like char 128 can be problematic. These typically are from MS-Word via copy/paste. If you have an error showing up in you tomcat console log that mentions invalid character then it is likely an extended character. To find use Notepade++ or some other text editor and do an enhanced find or regex find. An example to find possible invalid chars (anthing not [tab]-127) is to use an expression like:
    [^\x08-\x7F]+

    NOTE: This above test can be used for any other XML content file.

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 ibis:src="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>
    				
The information provided was retrieved on: Fri, 13 December 2019 8:55:10.

Content updated: Fri, 28 Apr 2017 14:06:16 MDT