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

View System Documentation - Site Customization

This page provides an overview of the activities and types of files that are used to customize the application for a new site. The types of tasks include look and feel and content management. This page mainly focuses on the look and feel tasks with more detailed "content management" infantine being provided in another section of this documentation. Likewise more detailed component view information is provided in the "View System's View" documentation. Listed below are the typical types of customization tasks:

The following sections provide more detailed information about the activity and gives some samples of what might be changed. Also note that this page only deals with user interface customization. Please see the Configuration page for detailed information on how to configure the application. Configuration items include how to map resources, how to turn on/off certain portions of the application, how to specify the URLs to use, how to specify where files are located, and other system properties like the system administrator's email address and the IBIS-Q Query System URL etc.

Cascading Style Sheets (CSS)

CSS files contain properties that control the formatting of the IBIS-PH pages. These properties include foreground and background colors, widths, positions of items on the page, font style and sizes, mouse over pointers, margins, padding/spacing, borders, and various other HTML presentation related properties. The "stylesheet.css" file contains the majority of the properties for all pages displayed by the system. This css file simply imports most of the .css files contained within the css directory. Special sectional/page specific properties can be added as needed or may override previously defined styles. See the CSS discussion in the HTML Page Design page for more information about the overall page design and CSS files. The application also provides a CSS to XSLT Xref Report page which lists the CSS class styles used in the XSLT files.

Typical CSS items changed:
  • Widths, margins, and paddings of the BODY, TABLEs, DIVs and SPANs
  • Foreground and background colors of the BODY, DIVs and SPANs, TABLEs/cells, links etc.
  • Any alignment properties like center align BODY and container's DIV to have an auto left and right margin width etc.

IMPORTANT NOTE: The system's page HTML elements are coded for the specific class names defined within these CSS files. So if an adopter wanted to incorporate their own CSS properties into their IBIS deployment they would have to change the class names defined within the XSLT code. This would make upgrades much more difficult so it is recommended that adopters keep the IBIS CSS property classes and simply modify those class property definitions to match their site.

Site Specific XSLTs

The CSS properties control the visual characteristics of the HTML elements while the XSLTs control the creation of the actual HTML element structure. The ability to customize the layout of the pages is handled by overriding "called" XSLT API templates with site specific versions. The site specific XSLT code is contained within files named "SiteSpecific.xslt". XSLTs that produce a page contain "Page" in their name. XSLTs that do not contain "Page" in their name are library type XSLTs that typically contain "called" or "matched" XSLT template definitions. Most page type XSLTs are contained within a subdirectory where a specific SiteSpecific.xslt can be defined that applies to that page only. The more general templates reside in the parent (upper level) directories.

The general page API definition is contained with the "xslt/html/Page.xslt" file with the site specific look and feel overrides and other general templates defined within the "xslt/html/SiteSpecific.xslt" file. This main site specific XSLT typically includes "Page.xxxx" templates that implement the page's banner, header, footer, and left hand content (typically navigation related) used by all/most pages. In some cases it is also desirable to change the layout of the page. This can be done but the HTML API must be retained as all sub "Page" type XSLT files are build on that API. See the site specific discussion in the XSLT Design page for more information.

Typical templates defined/overridden in the root "xslt/html/SiteSpecific.xslt" file:
  • Set the webmasater's email address by updating the value of the variable named "html.ibisphWebmasterEmailAddress"
  • Set any extra CSS file references in the "Page.standardCSS" template
  • Set the HTML code needed for the optional top most banner ("Page.banner")
  • Set the HTML code needed for the optional header section ("Page.header")
  • Set the HTML code needed for the optional bottom footer section ("Page.footer")
  • Implement site navigation Javascript or static HTML menu. For the Utah site, a new API call was created and then implemented in the site specific XSLT code for that particular page/section ("SiteSpecific.contextNavigation").

Examples templates defined/overridden in page/section specific "xslt/html/*/SiteSpecific.xslt" files:
  • Turn off the banner HTML code for indicator profile pages and query result pages by implementing a blank "Page.banner" template
  • Create a site specific query "Usage Agreement" by implementing code in a template named "SiteSpecific.initContent".
  • Implement site navigation Javascript or static HTML menu code for each XSLT page/section.


Graphics - Banners, Headers, Buttons

Each site will probably want to use their own banner and header graphics. This can include other graphics like standard buttons, department logos etc. These files can be put on another web server and referenced or copied into the applications directory tree. In either case the image referencing is done within the "SiteSpecific.xslt" files (typically in the main root "xslt/SiteSpecific.xslt" file) or via the CSS "background" property.

Site Navigation / Menu

Site navigation can be handled in a variety of ways. This includes a list of HTML anchor links (simple) to commercial DHTML menuing systems (complex). The navigation is typically handled within the site specific XSLTs. Utah developed a simple HTML and CSS based 508 compliant system that will use Javascript if present to make the menus more interactive. In previous versions, Utah had used the Milonic Menu DHTML package. Other sites like Arizona implemented a simple HTML navigation system. For Utah, they put the context type navigation menu items in the "Page.leftContent" XSLT template. The main section navigation was placed as a sub template in the "Page.header" template. Both of these templates are defined in the main SiteSpecific.xslt with page specific implementations defined in their respective sub directory SiteSpecific.xslt files.

If using the Utah menu system there are two basic things to update:

Static HTML Content HTML_CONTENT XML files

Most of the pages on the IBIS-PH site are used to display indicator profile data and query result data. These data are presented via dynamically generated pages (XML data files transformed into HTML presentation files using XSLT files and Java controller code). The site also has static type pages where the content does not change frequently, nor is it data centric. These pages include the Welcome page, overview/introduction type pages, contents and usage pages, help pages, and other site meta data type pages. Since these pages are used mainly to convey information about the system and are all formatted differently a simple HTML embedded HTML_CONTENT XML file is used. Almost all of these files will need to be modified/deleted/added to since these files are very specific to each site implementing this system. So most of the files used on Utah's site are only usable as basic templates and/or examples. It is possible to host straight HTML files on the application server or host static content on a separate, ordinary web server. However, doing this will take away the advantages of more easily maintaining a consistent look and feel for all the web pages plus having to deal with navigation issues. See the HTML_CONTENT XML Content page for a more detailed discussion on how to maintain HTML_CONTENT pages.

Modify all the "[tomcat/webapps/ibisph-view/xml/*/html_content/*.xml" files. This includes deleting files not used/needed and creating new directories and files as needed. Typically the "xml/home/html_content/Welcome.xml", "xml/query/html_content/Introduction.xml", "xml/indicator/html_content/Introduction.xml", and the usage type pages are used and will need to be updated.

Query Acknowledgement and Module Page Javascript Initialization

Utah shows a "Query Acknowledgement" or "Query Usage Agreement" message when a user first enters a query module page. The Javascript and message are both contained within the "xml/query/module/SiteSpecific.xslt" file's "siteSpecific.initContent" template. This is a improvised API which is called by the parent site specific XSLT file. This same template is used to call the Javascript that initializes the query module builder page. This initialization code is required for the page to work. This code allows a site to specify the default user interface controls for the query module page.

Update the Default Index Page

The site provides a default index redirection page. This simple HTML page contains three redirection mechanisms. The appropriate default URL needs to be updated in this file for each site if the site does not use a "home/Welcome.html" page as the default entry page. This file is located in the application's root directory and is named "index.html".

Update the Site Specific Error JSP Pages

There are two site specific JSP pages that need to be updated. The first is "jsp/_site_specific_header.jsp" which needs to have its header and banner HTML code changed appropriately. The second is the "_site_specific_options.jsp" file which contains the HTML code which gives site specific options on who to contact and what options are available when a user requests a page that results in an unexpected error.

Update the AgileBlox ACXML Property file

An XML property file is used to control the system's chart colors, border widths, fonts, tick marks, legend symbols etc. The property file is located/named: "WEB-INF/config/common_agileblox_chart_properties.acxml". Some chart properties like legend, label angles, distances and auto sizing is controlled in the Java controller code due to the fact that these values need to be adjusted based on the data being presented. Chart width is specified in two places: the ACXML file and for SVG images, within the "Graphic.xslt" that controls the HTML code needed to display the SVG image.

Update the "xml/org_units.xml" file

If the IBIS-PH Data Administration application is not being used and IF the site wants agency and department information to be displayed in the content footer then this file needs to be edited accordingly. Specifically the element named "DEFAULT" needs to be updated as well as any other org names that will be used within the query module XML files.

If the admin app is being used, then it contains a mechanism to maintain and publish the organization unit information so the above does not apply.

SVG Map Layers

The Utah map is a custom SVG file (set of files). These files were created/converted into an SVG from state ArcView shape files. These raw SVG files were then incorporated into an XSLT. The "map.xslt" file contains SVG code for all the layers and for the layer that shows the controls. Script was developed which provides the SVG map to be interactive. To implement a map, the SVG layers need to be built (with the coordinate system being adjusted so that the layer is positioned correctly) and the Map.xslt file would need to be modified to accommodate the width and height differences. The page's HTML SVG containing elements would also need to be modified for the new SVG size. A separate page or set of documentation pages will need to be developed that explain how the map.xslt file works and how to create/convert the needed SVG layers as this is not a trivial topic. Note that one of the major issues was to generalize the vectors to reduce the map's file size to a reasonable amount. If the SVG code is not generalized enough the map file can be quite large.

Brief List of Items Changed for the DC DeploymentDeploymentExample
  • Pulled the latest deployment package from the Utah repository in installed.
  • Created a "css/site_specific" directory with a "stylesheet.css" file which imports the parent stylesheet.css. Added below imports updated colors, backgrounds, fonts, sizes and a few misc properties of which most were top and context navigation related.
  • Updated the "xslt/html/SiteSpecific.xslt" to implement the HTML footer code needed for DC, email address, stubbed out the Page.contentFooter template so that org units would not display, and set the "Page.standardCSS" template to point to the "css/site_specific/stylesheet.css" file.
  • Updated the "xslt/html/query/SiteSpecific.xslt" to implement the appropriate bread crumb links.
  • Imported DC specific banner/header and button graphic images and named the same to the generic Utah image files.
  • Updated the "\index.html" page to point to the query/Introduction page
  • Updated the "xml/menu/sections.xml" file to comment out all the non query sub SECTION elements.
  • Updated the "xml/menu/query_section.xml" file and commented out all of the non implemented DC query module selections. Added a couple of DC specific menu items that they have on their DOH pages.
  • Checked out all of the module and module selection files from the repository that were created/updated by Shandra and Tong and put into the appropriate "xml/query/module" sub directory.
  • Updated the "WEB-INF/config/specific.properties" file and changed the email address and the ibis-q url.
  • Edited the "xml/query/html_content/Introduction.xml" file to put in DC references and remove "Utah".
  • Edited the "xslt/query/module/builder/SiteSpecific.xslt" file to update the Builder.initContent template which has the module usage agreement; Utah to DC.
  • updated "jsp/_site_specific*.jsp" files for CSS and Utah to DC content.
  • Checked all changed files into the Utah adopters DC repository.
Customization Level of Effort TableCustomizationTable Listed below is a table of the types of files associated with the IBIS-PH View system. The first column lists the file set or the type of file. The next column "Likelyhood of Change" shows the likelyhood that this type of file will need to be modified (on a scale from 1 to 5 with 1 being almost never changed to 5 being will most likely always be changed). The next column tries to describe the percentage of the content that will most likely be changed. The last column briefly describes the types of changes that might be performed on the file(s).

File TypeLikelyhood of ChangePercent of Content ChangedActivity
css/*.css510-30%background colors, font characteristics, text alignment, table cell properties
image/*.gif (jpeg etc.)520-100%Agency header, banner, navigation related images
js/*.js00%These files may be augmented with agency specific menuing systems etc. but these files are core objects and should not be modified.
jsp/*.jsp510%Need to change the header and footer jsp files to reflect agency header and footer. Also need to modify the error jsp page with the appropriate contact information etc.
WEB-INF/web.xml10-50%Controls the servlet URL mapping, filter mapping, error pages, mime types
WEB-INF/config/ site_specific.properties510-100%IBIS-Q URL, system administrator email address
WEB-INF/config/ spring/*.xml10-30% Spring configuration files and URL mapping. This configuration depends on site paths, XML/XSLT data file paths, and Java controllers used.
xml/org_units.xml570-100% Organization Unit contact information. IBIS-PH Data Admin application, if used, publishes this info. Also this can be maintained by hand or can be removed from the page if not desired.
xml/menu/*.xml330-100% Menu items. If using the IBIS-PH View System menu, then most of these XML elements will need to be updated. Otherwise it can be deleted or not touched.
xml/map/layers/*.xml590-100% 90% is only for agency's geographical layers. 100% is if all controls etc. are desired to be changed.
xml/*/ html_content/*.xml550-100% Static content type pages. This includes a welcome page, overviews, etc.
xml/query/ module/*.xml510-90%Query module builder interface and selection XML control files. If datasets match Utah's and adopting agency is good with the steps, questions and answers then only the selection type pages will need to be modified. Otherwise these files will need to be changed accordingly.
xslt/html/*/ SiteSpecific.xslt510-90%Page layout, system navigation/menuing
xslt/*/*.xslt00%All changes should be put into the appropriate SiteSpecific.xslt but these files can be updated and modified as desired. However, updating to the latest code will be more difficult.