Project

General

Profile

metacat / docs / user / metacat / source / themes.rst @ 8290

1
Modifying and Creating Themes
2
=============================
3
.. versionadded:: 2.2.0
4

    
5
.. contents::
6
  
7
Metacat's theming system, MetacatUI, is deployed separately from Metacat, allowing more 
8
independent user interface customization. MetacatUI is structured in a model-view-controller
9
architecture using `Backbone.js <http://www.backbonejs.org>`_. Some background knowledge on Backbone.js may be helpful for 
10
advanced modification of MetacatUI, but is not necessary for editing the CSS styling and HTML of 
11
the included MetacatUI views. 
12

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

    
15
   MetacatUI's default home page. Users can customize the appearance using themes. 
16

    
17
Quick Start Using the Default Theme
18
-----------------------------------
19
To use the default theme, shown in the figure above, follow these steps for a quick start with MetacatUI:
20

    
21
1. Copy the ``js/themes/default`` directory and rename it to your organization's name or choose a unique theme name.
22

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

    
25
3. In the ``js/themes/<yourtheme>/img`` directory, add the following image files:
26

    
27
	* Your organization's logo
28
	* Any supporter or donor logos to use in the footer
29

    
30
4. Create a ``templates`` directory in ``js/themes/<yourtheme>`` and copy the following files from ``js/templates`` into
31
that new directory:
32

    
33
	* footer.html
34
	* navbar.html
35

    
36
5. Open the ``js/themes/<yourtheme>/templates/footer.html`` file and change the footer logo image paths and the link paths to direct to 
37
your new footer images and their corresponding web addresses. For example, 
38

    
39
	::
40
	
41
	  <a href="http://nceas.ucsb.edu" target="_blank"><img alt="NCEAS" src="./js/themes/themename/img/nceas-logo-white.png"></a>
42
	  
43
	You can also add or modify the "Help" email addresses displayed in the footer.
44

    
45
6. Open the ``js/themes/<yourtheme>/templates/navbar.html`` file and replace the Metacat logo file with your organization's logo file.
46

    
47

    
48
7. Open ``index.html``. Edit the following line to reflect your theme name (``data-theme``) and your Metacat
49
   context (``data-metacat-context``):
50

    
51
	::
52
	 
53
	  <script data-theme="default" data-metacat-context="metacat" id="loader" type="text/javascript" src="loader.js"></script>
54

    
55

    
56
Creating a Custom Theme
57
-----------------------
58
All themes share the same CSS, HTML, JavaScript and image files. Any of these files can be customized by creating
59
a new theme. By creating a new theme, these shared default files
60
are overridden by your custom theme files.
61

    
62
1. Copy an existing theme directory structure, found in ``js/themes``, and rename that directory after your new theme.
63
Notice that each theme directory looks something like this:
64

    
65
	::
66
	
67
	  css/
68
	  img/
69
	  routers/
70
	  templates/
71
	  config.js
72
		
73

    
74
2. Only the ``config.js`` file is required for your theme - overrides are added to this configuration file as needed.
75

    
76
3. Add a CSS file to your theme by creating a CSS file in the ``js/themes/<yourtheme>/css/`` directory
77
   named ``metacatui.css``
78

    
79
4. Add your custom images to the ``js/themes/<yourtheme>/img`` directory.
80

    
81
5. Add HTML templates to the ``js/themes/<yourtheme>/templates`` directory.
82

    
83
6. Open the ``js/themes/<yourtheme>/config.js`` file. In here you will define your theme and themeMap.
84
	
85
  ::
86
	
87
	var theme = theme || "default";
88
	var themeMap = 
89
	{
90
		'*': {
91
			// example overrides are provided here
92
			//'views/AboutView' : 'themes/' + theme + '/views/AboutView.js',
93
			//'templates/navbar.html' : 'themes/' + theme + '/templates/navbar.html'
94
			}
95
	};
96
		
97
Give your theme a name on the first line. Then follow the commented out examples in ``themeMap`` to
98
explicitly tell MetacatUI which default shared files should be overridden with your custom theme 
99
files. The pattern is:
100
	
101
	``path/originalFile.html : 'themes/' + theme + '/path/newFile.html'``
102
	
103
**Note: You do not have to override the CSS or image files.**
104

    
105
7. Open ``index.html``. Edit the following line to reflect your theme name (``data-theme``) and your Metacat
106
context (``data-metacat-context``):
107

    
108
	::
109
	 
110
	  <script data-theme="default" data-metacat-context="metacat" id="loader" type="text/javascript" src="loader.js"></script>
111

    
112

    
113
Changing the background images on the default theme
114
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
115
The ``js/templates/app.html`` file contains the ``<img>`` element for the background image:
116

    
117
	::
118
	
119
	  <img src="" class="bg" id="bg_image" data-image-count="9" />
120
	  
121
Change the ``data-image-count`` attribute to the number of images you would like to cycle through in your custom
122
theme. To have the same background image on all views, change this value to 1.
123

    
124
Store the background image files in ``img/backgrounds``. Keep the naming convention of ``bg1.jpg``, ``bg2.jpg``, etc.
125
with all numbers from 1 to your chosen total present (i.e. do not skip any numbers, such as ``bg1.jpg``, ``bg3.jpg`` ...)
126

    
127

    
128
Advanced options for custom themes
129
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
130
Advanced users can choose to override the JavaScript files for even more customization of MetcatUI.
131

    
132

    
133
The ``router.js`` file can be modified to render different views based on the URL. For example,
134
a theme which has no home page and routes users to the ``DataCatalogView`` view instead, would modify ``router.js``
135
like so:
136

    
137
	::
138
	 
139
	  	// MetacatUI Router
140
		// ----------------
141
		var UIRouter = Backbone.Router.extend({
142
			routes: {
143
				'' 					: 'routeToData',    // default is data search page
144
				'about'                     : 'renderAbout',  // about page
145
				'about(/:anchorId)'         : 'renderAbout',  // about page anchors
146
				'plans'                     : 'renderPlans',  // plans page
147
				'tools(/:anchorId)'         : 'renderTools',  // tools page
148
				'data(/search/:searchTerm)(/page/:page)' : 'renderData',    // data search page
149
				'view/*pid'                 : 'renderMetadata',    // metadata page
150
				'external(/*url)'           : 'renderExternal',    // renders the content of the given url in our UI
151
				'logout'                    : 'logout',    // logout the user
152
				'signup'          			: 'renderLdap',    // use ldapweb for registration
153
				'account(/:stage)'          : 'renderLdap',    // use ldapweb for different stages
154
				'share'                     : 'renderRegistry'    // registry page
155
			},
156
			
157
In this example, the index path, ``''``, was changed from
158
the value ``renderIndex`` which renders the ``IndexView.js`` view, to ``routeToData`` which reroutes to ``data``,
159
in turn rendering the ``DataCatalogView`` view.
160

    
161
	::
162
	  		
163
	  	routeToData: function () {
164
			console.log('Called UIRouter.routeToData()');
165
			this.navigate("data", {trigger: true});
166
		},
167
		
168
	**Note: Remember to include any views or router.js in your list of overrides in js/themes/<yourtheme>/config.js
169
	for each file you modify**
170

    
171

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

    
174

    
175

    
176
Creating a Custom Skin
177
----------------------
178
.. deprecated:: 2.2.0
179
   Use MetacatUI themes for any new UI development. Metacat's original skinning 
180
   mechanism is still included and used for aspects of rendering metadata, but is 
181
   not the preferred method for building web clients for Metacat.
182
   
183
   To MetacatUI themes, select ``metacatui`` as the default skin during skin configuration
184
   in the administration interface.
185
	
186
Skins are used in Metacat to customize the appearance of the search and display
187
web interface that is presented by Metacat.  Skins can be used to make a Metacat
188
instance exactly integrate into an existing web site, and are fully customizable.
189

    
190
To create and customize your own Metacat skin, you must first create a skin 
191
directory. This is most easily accomplished by copying one of the existing skin 
192
directories. Step-by-step directions for creating and installing a custom skin 
193
are included below:
194

    
195
1. Copy an existing skin directory. We recommend using the "default" directory.
196

    
197
  ::
198
  
199
    sudo cp -r <CONTEXT_DIR>/style/skins/default/ <CONTEXT_DIR>/style/skins/[yourSkin]/
200

    
201
  Where ``<CONTEXT_DIR>`` is the directory in which the Metacat application 
202
  code lives  and ``[yourSkin]`` is the name you wish to apply to your skin.
203

    
204
2. In ``[yourSkin]`` directory, change all files named ``default.xxx`` to 
205
   ``yourSkin.xxx``. The following files should be changed:
206

    
207
  ::
208
  
209
    default.css
210
    default.js
211
    default.properties
212
    default.properties.metadata.xml
213
    default.xml
214

    
215
3. In the metacat.properties file(``<CONTEXT_DIR>/WEB_INF/metacat.properties``), 
216
   add ``[yourSkin]`` to the value of the skin.names property.
217

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

    
220
  ::
221
  
222
    /etc/init.d/tomcat6 restart
223

    
224
Navigate to Metacat's Configuration utility  and select the Configure Skins 
225
option. Your custom skin should appear as a choice in the skins list. Change 
226
the layout and style by modifying the header, footer, css, and other files in 
227
your new skin directory.
228

    
229
It is important to note that all customized skins will be overwritten when 
230
Metacat is reinstalled or upgraded. Please remember to back up your skins before
231
reinstalling or upgrading Metacat.
232