Hyrax - Customizing Hyrax: Difference between revisions
(16 intermediate revisions by 3 users not shown) | |||
Line 8: | Line 8: | ||
= Web page customization = | = Web page customization = | ||
Hyrax's public "face" is the web pages that are produced by servlets running in the Tomcat servlet engine. Almost all of these pages can be completely customized by the site administrator by editing a combination HTML, XSLT, and CSS files. | Hyrax's public "face" is the web pages that are produced by servlets running in the Tomcat servlet engine. Almost all of these pages can be completely customized by the site administrator by editing a combination of HTML, XSLT, and CSS files. | ||
== Where to make the changes == | == Where to make the changes == | ||
All of the default versions of the HTML, XSLT, and CSS files come bundled with | All of the default versions of the HTML, XSLT, and CSS files come bundled with Hyrax in the ''$CATALINA_HOME/webapps/opendap/docs'' directory. You can make changes there, but installing new versions of the OLFS software will overwrite your modifications. | ||
However, if the ''docs'' directory is copied (preserving its structure) to ''$CATALINA_HOME/content/opendap/'' (creating the directory ''$CATALINA_HOME/content/opendap/docs''), then Hyrax will serve the files from the new location. | |||
;Warning: ''Do NOT remove files from this new directory (Or the old one for that matter). Each file, in its location, is required by Hyrax. You can make changes to the files but you should not rename or remove them.'' | |||
Nothing inside the ''$CATALINA_HOME/content'' directory is (automatically) changed when installing new versions of Hyrax. | Nothing inside the ''$CATALINA_HOME/content'' directory is (automatically) changed when installing new versions of Hyrax. | ||
'''The rest of these | '''The rest of these instructions are written with the assumption that a copy of the ''docs'' directory has been made as described above.''' | ||
== What to change == | == What to change == | ||
Line 41: | Line 35: | ||
| '''index.html''' | | '''index.html''' | ||
| | | | ||
| ''$CATALINA_HOME/content/docs'' | | ''$CATALINA_HOME/content/opendap/docs'' | ||
| | | | ||
| The documentation web page for the top level of Hyrax. As shipped it contains a description of Hyrax and links to documentation and funders. The contents.html pages (aka the OPeNDAP directories) links to this document. <br/><br/> | | The documentation web page for the top level of Hyrax. As shipped it contains a description of Hyrax and links to documentation and funders. The contents.html pages (aka the OPeNDAP directories) links to this document. <br/><br/> | ||
Line 47: | Line 41: | ||
| '''error400.html''' | | '''error400.html''' | ||
| | | | ||
| ''$CATALINA_HOME/content/docs'' | | ''$CATALINA_HOME/content/opendap/docs'' | ||
| | | | ||
| Contains the default error page that Hyrax will return when the | | Contains the default error page that Hyrax will return when the client request generates a '''Bad Request''' error (Associated with an HTML status of 400) <br/><br/> | ||
|- | |- | ||
| '''error403.html''' | | '''error403.html''' | ||
| | | | ||
| ''$CATALINA_HOME/content/docs'' | | ''$CATALINA_HOME/content/opendap/docs'' | ||
| | | | ||
| Contains the default error page that Hyrax will return | | Contains the default error page that Hyrax will return when the client request generates a '''Forbidden''' error. (Associated with an HTML status of 403) <br/><br/> | ||
|- | |- | ||
| '''error404.html''' | | '''error404.html''' | ||
| | | | ||
| ''$CATALINA_HOME/content/docs'' | | ''$CATALINA_HOME/content/opendap/docs'' | ||
| | | | ||
| Contains the default error page that Hyrax will return | | Contains the default error page that Hyrax will return when the client request generates a '''Not Found''' error. (Associated with an HTML status of 404) <br/><br/> | ||
|- | |- | ||
| '''error500.html''' | | '''error500.html''' | ||
| | | | ||
| ''$CATALINA_HOME/content/docs'' | | ''$CATALINA_HOME/content/opendap/docs'' | ||
| | | | ||
| Contains the default error page that Hyrax will return | | Contains the default error page that Hyrax will return when the client request generates an '''Internal Server Error'''. (Associated with an HTML status of 500) <br/><br/> | ||
|- | |- | ||
| '''error501.html''' | | '''error501.html''' | ||
| | | | ||
| ''$CATALINA_HOME/content/docs'' | | ''$CATALINA_HOME/content/opendap/docs'' | ||
| | | | ||
| Contains the default error page that Hyrax will return | | Contains the default error page that Hyrax will return when the client request generates an '''Not Implemented'''. (Associated with an HTML status of 501) <br/><br/> | ||
|- | |- | ||
| '''error502.html''' | | '''error502.html''' | ||
| | | | ||
| ''$CATALINA_HOME/content/docs'' | | ''$CATALINA_HOME/content/opendap/docs'' | ||
| | | | ||
| Contains the default error page that Hyrax will return | | Contains the default error page that Hyrax will return when the client request generates an '''Bad Gateway'''. (Associated with an HTML status of 502) <br/><br/> | ||
|- | |- | ||
|} | |} | ||
Line 85: | Line 79: | ||
<br/> | <br/> | ||
=== | === CSS Files === | ||
{| | {| | ||
Line 94: | Line 88: | ||
|<u>Description</u> | |<u>Description</u> | ||
|- | |- | ||
| ''' | | '''contents.css''' | ||
| | |||
| ''$CATALINA_HOME/content/opendap/docs/css'' | |||
| | |||
| The contents.css style sheet provides the default colors and fonts used in the Hyrax site. It is referenced by all of the HTML and XSL files to coordinate the visual aspects of the site.<br/><br/> | |||
|- | |||
| '''thredds.css''' | |||
| | | | ||
| ''$CATALINA_HOME/content/docs/ | | ''$CATALINA_HOME/content/opendap/docs/css'' | ||
| | | | ||
| The | | The thredds.css style sheet provides the default colors and fonts used by the THREDDS component of Hyrax. <br/><br/> | ||
|- | |||
|} | |||
<br/> | |||
<br/> | |||
=== Image Files === | |||
There are a number of image files shipped with Hyrax. Simply replacing key image files will allow you to customize the icons and logos associated with the Hyrax server. | |||
{| | |||
|<u>File</u> | |||
| | |||
|<u>Location</u> | |||
| | |||
|<u>Description</u> | |||
|- | |- | ||
| ''' | | '''logo.gif''' | ||
| | | | ||
| ''$CATALINA_HOME/content/docs/ | | ''$CATALINA_HOME/content/opendap/docs/images'' | ||
| | | | ||
| | | Main Logo for the directory view (produced by contents.css and contents.xsl) | ||
|- | |- | ||
| ''' | | '''favicon.ico''' | ||
| | | | ||
| ''$CATALINA_HOME/content/docs/ | | ''$CATALINA_HOME/content/opendap/docs/images'' | ||
| | | | ||
| The | | The cute little icon preceding the URL in the address bar of your browser. To be used this file needs to be installed into Tomcat [http://docs.opendap.org/index.php/Hyrax_-_Installation_Instructions#Miscellaneous as described here] | ||
|- | |- | ||
| ''' | | '''BadDapRequest.gif, BadGateway.png,<br/> favicon.ico, folder.png,<br/> forbidden.png, largeEarth.jpg,<br/> logo.gif, nasa-logo.jpg,<br/> noaa-logo.jpg, nsf-logo.png,<br/> smallEarth.jpg, sml-folder.png,<br/> superman.jpg''' | ||
| | | | ||
| ''$CATALINA_HOME/content/docs/ | | ''$CATALINA_HOME/content/opendap/docs/images'' | ||
| | | | ||
| | | These files are referenced by the default collection of web content files (described above) that ship with Hyrax. | ||
|} | |||
<br /> | |||
<br /> | |||
=== XSL Transform Files === | |||
These files are used to transform XML documents used by Hyrax. Some transforms operate on source XML from internal documents such as BES responses. Other transforms change things like THREDDS catalogs into HTML for browsers. | |||
''All of these XSLT files are software, and should be treated as such. They are intimately tied to the functions of Hyrax. The likelihood that you can change these files and not break Hyrax is fairly low.'' | |||
<font size="+1" style="bold">Current Operational XSLT</font> | |||
{| | |||
|<u>File</u> | |||
| | |||
|<u>Location</u> | |||
| | |||
|<u>Description</u> | |||
|- | |- | ||
| ''' | | '''catalog.xsl''' | ||
| | | | ||
| ''$CATALINA_HOME/content/docs/xsl'' | | ''$CATALINA_HOME/content/opendap/docs/xsl'' | ||
| | | | ||
| The | | The catalog.xsl file contains the XSLT transformation that is used to transform BES showCatalog responses into THREDDS catalogs. | ||
|- | |- | ||
| ''' | | '''contents.xsl''' | ||
| | | | ||
| ''$CATALINA_HOME/content/docs/xsl'' | | ''$CATALINA_HOME/content/opendap/docs/xsl'' | ||
| | | | ||
| The contents.xsl file contains the XSLT transformation that is used to build the [http://docs.opendap.org/index.php/ServerDispatchOperations#OPeNDAP_Directory_Response OPeNDAP Directory Response] (''see [http://docs.opendap.org/images/6/6e/DirectoryView.png img]'') <br/><br/> | | The contents.xsl file contains the XSLT transformation that is used to build the [http://docs.opendap.org/index.php/ServerDispatchOperations#OPeNDAP_Directory_Response OPeNDAP Directory Response] (''see [http://docs.opendap.org/images/6/6e/DirectoryView.png img]'') <br/><br/> | ||
|- | |- | ||
| '''dap_3. | | '''dap_3.2_ddxToRdfTriples.xsl''' | ||
| | | | ||
| ''$CATALINA_HOME/content/docs/xsl'' | | ''$CATALINA_HOME/content/opendap/docs/xsl'' | ||
| | | | ||
| | | ''Experimental'' - This XSLT is used to produce an RDF representation of a DAP 3.2 DDX. | ||
|- | |- | ||
| '''dataset.xsl''' | | '''dataset.xsl''' | ||
| | | | ||
| ''$CATALINA_HOME/content/docs/xsl'' | | ''$CATALINA_HOME/content/opendap/docs/xsl'' | ||
| | | | ||
| | | This transform is used to in conjunction with the opendap.threddsHandler code to produce HTML pages of THREDDS catalog dataset element details. | ||
|- | |- | ||
| '''error400.xsl''' | | '''error400.xsl''' | ||
| | | | ||
| ''$CATALINA_HOME/content/docs/xsl'' | | ''$CATALINA_HOME/content/opendap/docs/xsl'' | ||
| | | | ||
| The error400.xsl contains the XSLT transformation that is used to build the web page that is returned when the server generates a Bad Request (400) HTTP status code. If for some reason this page cannot be generated then the HTML version (''$CATALINA_HOME/content/docs/error400.html'') will be sent.<br/><br/> | | The error400.xsl contains the XSLT transformation that is used to build the web page that is returned when the server generates a Bad Request (400) HTTP status code. If for some reason this page cannot be generated then the HTML version (''$CATALINA_HOME/content/opendap/docs/error400.html'') will be sent.<br/><br/> | ||
|- | |- | ||
|- | |- | ||
| '''error500.xsl''' | | '''error500.xsl''' | ||
| | | | ||
| ''$CATALINA_HOME/content/ | | ''$CATALINA_HOME/content/opendap/docs/xsl'' | ||
| | | | ||
| The | | The error400.xsl contains the XSLT transformation that is used to build the web page that is returned when the server generates a Internal Server Error (500) HTTP status code. If for some reason this page cannot be generated then the HTML version (''$CATALINA_HOME/content/opendap/docs/error500.html'') will be sent.<br/><br/> | ||
|- | |- | ||
| '''thredds.xsl''' | | '''thredds.xsl''' | ||
| | | | ||
| ''$CATALINA_HOME/content/docs/xsl'' | | ''$CATALINA_HOME/content/opendap/docs/xsl'' | ||
| | | | ||
| | | This transform is used to in conjunction with the opendap.threddsHandler code to produce HTML pages of THREDDS catalog details. | ||
|- | |- | ||
| '''version.xsl''' | | '''version.xsl''' | ||
| | | | ||
| ''$CATALINA_HOME/content/ | | ''$CATALINA_HOME/content/opendap/docs/xsl'' | ||
| | | | ||
| | | This transform is used to provide a single location for the Hyrax version number shown in the public interface. | ||
|- | |- | ||
|} | |} | ||
<br/> | <br/> | ||
== | <font size="+1" style="bold">Experimental XSLT</font> | ||
<br/> | |||
{| | {| | ||
|<u>File</u> | |<u>File</u> | ||
Line 204: | Line 214: | ||
|<u>Description</u> | |<u>Description</u> | ||
|- | |- | ||
| ''' | | '''dapAttributePromoter.xsl''' | ||
| | |||
| ''$CATALINA_HOME/content/opendap/docs/xsl'' | |||
| | |||
| ''Experimental'' - This XSLT file can be used to promote DAP Attributes whose names contain a namespace prefix to XML elements of the same name os the Attribute. ''Not currently in use.'' | |||
|- | |||
| '''dapAttributesToXml.xsl''' | |||
| | |||
| ''$CATALINA_HOME/content/opendap/docs/xsl'' | |||
| | |||
| ''Experimental'' - This XSLT file might be used to promote DAP Attributes encoded with special XML attributes to represent any XML to the XML the Attribute was encoded to represent. ''Not currently in use.'' | |||
|- | |||
| '''dap_2.0_ddxToRdfTriples.xsl''' | |||
| | | | ||
| ''$CATALINA_HOME/content/docs/ | | ''$CATALINA_HOME/content/opendap/docs/xsl'' | ||
| | | | ||
| | | ''Experimental'' - This XSLT can be used to produce an RDF representation of a DAP2 DDX. ''Not currently in use.'' | ||
|- | |- | ||
| ''' | | '''dap_3.3_ddxToRdfTriples.xsl''' | ||
| | | | ||
| ''$CATALINA_HOME/content/docs/ | | ''$CATALINA_HOME/content/opendap/docs/xsl'' | ||
| | | | ||
| | | ''Experimental'' - This XSLT can be used to produce an RDF representation of a DAP 3.3 DDX. ''Not currently in use.'' | ||
|- | |- | ||
| | | '''namespaceFilter.xsl''' | ||
| | |||
| ''$CATALINA_HOME/content/opendap/docs/xsl'' | |||
| | |||
| ''Experimental'' - This XSLT can be used to filter documents so that only elements in a particular namespace are returned. ''Not currently in use.'' | |||
| | |||
| | |||
| | |||
|- | |- | ||
| ''' | | '''wcs_coveragePage.xsl''' | ||
| | | | ||
| ''$CATALINA_HOME/content/docs/ | | ''$CATALINA_HOME/content/opendap/docs/xsl'' | ||
| | | | ||
| | | ''Experimental'' - This XSLT is used by the prototype CEOP WCS gateway client to produce an HTML page with coverage details. ''Not currently in use.'' | ||
|- | |- | ||
| ''' | | '''wcs_coveragesList.xsl''' | ||
| | | | ||
| ''$CATALINA_HOME/content/docs/ | | ''$CATALINA_HOME/content/opendap/docs/xsl'' | ||
| | | | ||
| | | ''Experimental'' - This XSLT is used by the prototype CEOP WCS gateway client to produce an HTML page with a list of available coverages. ''Not currently in use.'' | ||
|- | |- | ||
| ''' | | '''xmlToDapAttributes.xsl''' | ||
| | | | ||
| ''$CATALINA_HOME/content/docs/ | | ''$CATALINA_HOME/content/opendap/docs/xsl'' | ||
| | | | ||
| | | ''Experimental'' - This XSLT can be used to covert any XML content into a set of specially encoded DAP Attributes. The resulting Attribute elements have XML ''type'' attributes that are not currently recognized by any OPeNDAP software. ''Not currently in use.'' | ||
|- | |||
|} | |} | ||
<br/> | |||
<br /> | <br/> | ||
<br /> | |||
= Software Customization = | = Software Customization = |
Latest revision as of 18:51, 27 September 2014
There are several ways in which Hyrax can be customized:
- Web interface look and feel can be changed, as can the pages served.
- Custom DispatchHandlers for the OLFS
- Custom RequestHandlers for the BES.
Web page customization
Hyrax's public "face" is the web pages that are produced by servlets running in the Tomcat servlet engine. Almost all of these pages can be completely customized by the site administrator by editing a combination of HTML, XSLT, and CSS files.
Where to make the changes
All of the default versions of the HTML, XSLT, and CSS files come bundled with Hyrax in the $CATALINA_HOME/webapps/opendap/docs directory. You can make changes there, but installing new versions of the OLFS software will overwrite your modifications.
However, if the docs directory is copied (preserving its structure) to $CATALINA_HOME/content/opendap/ (creating the directory $CATALINA_HOME/content/opendap/docs), then Hyrax will serve the files from the new location.
- Warning
- Do NOT remove files from this new directory (Or the old one for that matter). Each file, in its location, is required by Hyrax. You can make changes to the files but you should not rename or remove them.
Nothing inside the $CATALINA_HOME/content directory is (automatically) changed when installing new versions of Hyrax.
The rest of these instructions are written with the assumption that a copy of the docs directory has been made as described above.
What to change
HTML Files
The HTML files provide the static content of a Hyrax server.
File | Location | Description | ||
index.html | $CATALINA_HOME/content/opendap/docs | The documentation web page for the top level of Hyrax. As shipped it contains a description of Hyrax and links to documentation and funders. The contents.html pages (aka the OPeNDAP directories) links to this document. | ||
error400.html | $CATALINA_HOME/content/opendap/docs | Contains the default error page that Hyrax will return when the client request generates a Bad Request error (Associated with an HTML status of 400) | ||
error403.html | $CATALINA_HOME/content/opendap/docs | Contains the default error page that Hyrax will return when the client request generates a Forbidden error. (Associated with an HTML status of 403) | ||
error404.html | $CATALINA_HOME/content/opendap/docs | Contains the default error page that Hyrax will return when the client request generates a Not Found error. (Associated with an HTML status of 404) | ||
error500.html | $CATALINA_HOME/content/opendap/docs | Contains the default error page that Hyrax will return when the client request generates an Internal Server Error. (Associated with an HTML status of 500) | ||
error501.html | $CATALINA_HOME/content/opendap/docs | Contains the default error page that Hyrax will return when the client request generates an Not Implemented. (Associated with an HTML status of 501) | ||
error502.html | $CATALINA_HOME/content/opendap/docs | Contains the default error page that Hyrax will return when the client request generates an Bad Gateway. (Associated with an HTML status of 502) |
CSS Files
File | Location | Description | ||
contents.css | $CATALINA_HOME/content/opendap/docs/css | The contents.css style sheet provides the default colors and fonts used in the Hyrax site. It is referenced by all of the HTML and XSL files to coordinate the visual aspects of the site. | ||
thredds.css | $CATALINA_HOME/content/opendap/docs/css | The thredds.css style sheet provides the default colors and fonts used by the THREDDS component of Hyrax. |
Image Files
There are a number of image files shipped with Hyrax. Simply replacing key image files will allow you to customize the icons and logos associated with the Hyrax server.
File | Location | Description | ||
logo.gif | $CATALINA_HOME/content/opendap/docs/images | Main Logo for the directory view (produced by contents.css and contents.xsl) | ||
favicon.ico | $CATALINA_HOME/content/opendap/docs/images | The cute little icon preceding the URL in the address bar of your browser. To be used this file needs to be installed into Tomcat as described here | ||
BadDapRequest.gif, BadGateway.png, favicon.ico, folder.png, forbidden.png, largeEarth.jpg, logo.gif, nasa-logo.jpg, noaa-logo.jpg, nsf-logo.png, smallEarth.jpg, sml-folder.png, superman.jpg |
$CATALINA_HOME/content/opendap/docs/images | These files are referenced by the default collection of web content files (described above) that ship with Hyrax. |
XSL Transform Files
These files are used to transform XML documents used by Hyrax. Some transforms operate on source XML from internal documents such as BES responses. Other transforms change things like THREDDS catalogs into HTML for browsers.
All of these XSLT files are software, and should be treated as such. They are intimately tied to the functions of Hyrax. The likelihood that you can change these files and not break Hyrax is fairly low.
Current Operational XSLT
File | Location | Description | ||
catalog.xsl | $CATALINA_HOME/content/opendap/docs/xsl | The catalog.xsl file contains the XSLT transformation that is used to transform BES showCatalog responses into THREDDS catalogs. | ||
contents.xsl | $CATALINA_HOME/content/opendap/docs/xsl | The contents.xsl file contains the XSLT transformation that is used to build the OPeNDAP Directory Response (see img) | ||
dap_3.2_ddxToRdfTriples.xsl | $CATALINA_HOME/content/opendap/docs/xsl | Experimental - This XSLT is used to produce an RDF representation of a DAP 3.2 DDX. | ||
dataset.xsl | $CATALINA_HOME/content/opendap/docs/xsl | This transform is used to in conjunction with the opendap.threddsHandler code to produce HTML pages of THREDDS catalog dataset element details. | ||
error400.xsl | $CATALINA_HOME/content/opendap/docs/xsl | The error400.xsl contains the XSLT transformation that is used to build the web page that is returned when the server generates a Bad Request (400) HTTP status code. If for some reason this page cannot be generated then the HTML version ($CATALINA_HOME/content/opendap/docs/error400.html) will be sent. | ||
error500.xsl | $CATALINA_HOME/content/opendap/docs/xsl | The error400.xsl contains the XSLT transformation that is used to build the web page that is returned when the server generates a Internal Server Error (500) HTTP status code. If for some reason this page cannot be generated then the HTML version ($CATALINA_HOME/content/opendap/docs/error500.html) will be sent. | ||
thredds.xsl | $CATALINA_HOME/content/opendap/docs/xsl | This transform is used to in conjunction with the opendap.threddsHandler code to produce HTML pages of THREDDS catalog details. | ||
version.xsl | $CATALINA_HOME/content/opendap/docs/xsl | This transform is used to provide a single location for the Hyrax version number shown in the public interface. |
Experimental XSLT
File | Location | Description | ||
dapAttributePromoter.xsl | $CATALINA_HOME/content/opendap/docs/xsl | Experimental - This XSLT file can be used to promote DAP Attributes whose names contain a namespace prefix to XML elements of the same name os the Attribute. Not currently in use. | ||
dapAttributesToXml.xsl | $CATALINA_HOME/content/opendap/docs/xsl | Experimental - This XSLT file might be used to promote DAP Attributes encoded with special XML attributes to represent any XML to the XML the Attribute was encoded to represent. Not currently in use. | ||
dap_2.0_ddxToRdfTriples.xsl | $CATALINA_HOME/content/opendap/docs/xsl | Experimental - This XSLT can be used to produce an RDF representation of a DAP2 DDX. Not currently in use. | ||
dap_3.3_ddxToRdfTriples.xsl | $CATALINA_HOME/content/opendap/docs/xsl | Experimental - This XSLT can be used to produce an RDF representation of a DAP 3.3 DDX. Not currently in use. | ||
namespaceFilter.xsl | $CATALINA_HOME/content/opendap/docs/xsl | Experimental - This XSLT can be used to filter documents so that only elements in a particular namespace are returned. Not currently in use. | ||
wcs_coveragePage.xsl | $CATALINA_HOME/content/opendap/docs/xsl | Experimental - This XSLT is used by the prototype CEOP WCS gateway client to produce an HTML page with coverage details. Not currently in use. | ||
wcs_coveragesList.xsl | $CATALINA_HOME/content/opendap/docs/xsl | Experimental - This XSLT is used by the prototype CEOP WCS gateway client to produce an HTML page with a list of available coverages. Not currently in use. | ||
xmlToDapAttributes.xsl | $CATALINA_HOME/content/opendap/docs/xsl | Experimental - This XSLT can be used to covert any XML content into a set of specially encoded DAP Attributes. The resulting Attribute elements have XML type attributes that are not currently recognized by any OPeNDAP software. Not currently in use. |