Metacat

Modifying and Creating Themes

.. contents::

independent user interface customization. Check the `MetacatUI GitHub <https://github.com/NCEAS/metacatui>`_ for the most up to date version.

MetacatUI is structured in a model-view-controller

advanced modification of MetacatUI, but is not necessary for editing the CSS styling and HTML of

.. figure:: images/screenshots/image007.png

Quick Start Using the Default Theme

	* Your organization's logo

	* Any supporter or donor logos to use in the footer

	* footer.html

	* navbar.html

	::

	  	<img alt="NCEAS" src="./js/themes/yourtheme/img/nceas-logo-white.png">

	  </a>

In the ``js/themes/<yourtheme>/config.js`` file, change the theme name on line 1, ``default``, to your chosen new theme name.

In the ``themeMap``, add a new line for every template you have edited and added to your new theme. An example for the footer.html and navbar.html files is below.

  ::

	var themeMap =

	{

		'*': {

			// example overrides are provided here

			'templates/navbar.html' : 'themes/' + theme + '/templates/navbar.html',

			'templates/footer.html' : 'themes/' + theme + '/templates/footer.html'

			}

	};

   context (``data-metacat-context``). (The Metacat context is the name of the directory in which Metacat is installed in the Tomcat web-application directory (most likely "metacat"). Whomever installed Metacat will know what this directory is called. If your MetacatUI is already successfully retrieving datasets during searches, this is already set and can be left as is.)

Creating a Custom Theme

	::

	  css/

	  img/

	  routers/

	  templates/

	  config.js

  ::

	var theme = theme || "default";

	var themeMap =

	{

		'*': {

			// example overrides are provided here

			//'views/AboutView' : 'themes/' + theme + '/views/AboutView.js',

			//'templates/navbar.html' : 'themes/' + theme + '/templates/navbar.html'

			}

	};

explicitly tell Metacat which default shared files should be overridden with your custom theme

	``path/originalFile.html : 'themes/' + theme + '/path/newFile.html'``

context (attribute ``data-metacat-context``):

	::

Changing the background images on the default theme

	::

	  <img src="" class="bg" id="bg_image" data-image-count="9" />

Change the ``data-image-count`` attribute to the number of images you would like to cycle through in your custom

that all numbers from 1 to your specified total (``data-image-count``) are included. (i.e. do not skip any numbers, such as ``bg1.jpg``, ``bg3.jpg`` ...)

Advanced options for custom themes

The ``router.js`` file can be modified to render different views based on the URL. For example,

a theme which has no home page and routes users to the ``DataCatalogView`` view instead, would modify ``router.js``

like so:

	::

	  	// MetacatUI Router

		// ----------------

		var UIRouter = Backbone.Router.extend({

			routes: {

				'about'                     : 'renderAbout',

				'about(/:anchorId)'         : 'renderAbout',

				'plans'                     : 'renderPlans',

				'tools(/:anchorId)'         : 'renderTools',

				'data(/search/:searchTerm)(/page/:page)' : 'renderData',

				'view/*pid'                 : 'renderMetadata',

				'external(/*url)'           : 'renderExternal',

				'logout'                    : 'logout',

				'signup'          			: 'renderLdap',

				'account(/:stage)'          : 'renderLdap',

				'share'                     : 'renderRegistry'

In this example, the index path, ``''``, was changed from

the value ``renderIndex`` which renders the ``IndexView.js`` view, to ``routeToData`` which reroutes to ``data``,

in turn rendering the ``DataCatalogView`` view.

	::

	  	routeToData: function () {

			console.log('Called UIRouter.routeToData()');

			this.navigate("data", {trigger: true});

		},

For more information about ``Backbone.js``, see the Backbone.js documentation at `www.backbonejs.org <http://www.backbonejs.org>`_

-----------------------

MetacatUI can also be configured to use custom DataONE endpoints for both Member Node and Coordinating Node APIs.

The ``dataone`` theme shows an example of this endpoint customization in the ``AppModel.js`` file.

In custom themes, the AppModel.js values can be edited to suit your particular deployment needs.

	::

	  	context: '',

		d1Service: "/cn/v2",

		d1CNBaseUrl:  "https://cn.dataone.org",

		d1CNService: "/cn/v2",

But querying a Metacat Member Node would be configured as:

	::

	  	context: '/metacat',

		d1Service: '/d1/mn/v2',

		d1CNBaseUrl: "https://cn.dataone.org/",

		d1CNService: "cn/v2",

----------------------

.. deprecated:: 2.2.0

   mechanism is still included and used for aspects of rendering metadata, but is

   not the preferred method for building web clients for Metacat.

   To MetacatUI themes, select ``metacatui`` as the default skin during skin configuration

   in the administration interface.

Skins are used in Metacat to customize the appearance of the search and display

web interface that is presented by Metacat.  Skins can be used to make a Metacat

instance exactly integrate into an existing web site, and are fully customizable.

To create and customize your own Metacat skin, you must first create a skin

directory. This is most easily accomplished by copying one of the existing skin

directories. Step-by-step directions for creating and installing a custom skin

are included below:

  ::

    sudo cp -r <CONTEXT_DIR>/style/skins/default/ <CONTEXT_DIR>/style/skins/[yourSkin]/

  Where ``<CONTEXT_DIR>`` is the directory in which the Metacat application

  code lives  and ``[yourSkin]`` is the name you wish to apply to your skin.

2. In ``[yourSkin]`` directory, change all files named ``default.xxx`` to

   ``yourSkin.xxx``. The following files should be changed:

  ::

    default.css

    default.js

    default.properties

    default.properties.metadata.xml

    default.xml

3. In the metacat.properties file(``<CONTEXT_DIR>/WEB_INF/metacat.properties``),

   add ``[yourSkin]`` to the value of the skin.names property.

4. Restart Tomcat. Log in as the user that runs your Tomcat server (often "tomcat") and type:

  ::

Navigate to Metacat's Configuration utility  and select the Configure Skins

option. Your custom skin should appear as a choice in the skins list. Change

the layout and style by modifying the header, footer, css, and other files in

your new skin directory.

It is important to note that all customized skins will be overwritten when

Metacat is reinstalled or upgraded. Please remember to back up your skins before

reinstalling or upgrading Metacat.