Project

General

Profile

metacat / docs / user / harvestListEditor.html @ 3067

1
<!--
2
  * harvestListEditor.html
3
  *
4
  *      Authors: Duane Costa
5
  *    Copyright: 2004 Regents of the University of California and the
6
  *               National Center for Ecological Analysis and Synthesis,
7
  *               and the University of New Mexico.
8
  *  For Details: http://www.nceas.ucsb.edu/
9
  *      Created: 2004 June 11
10
  *      Version: 
11
  *    File Info: '$ '
12
  * 
13
  * 
14
-->
15
<HTML>
16
<HEAD>
17
<TITLE>Harvest List Editor</TITLE>
18
<link rel="stylesheet" type="text/css" href="@docrooturl@default.css">
19
</HEAD> 
20

    
21
<BODY>
22
  <table width="100%">
23
    <tr>
24
      <td class="tablehead" colspan="2">
25
        <p class="label">Harvest List Editor</p>
26
      </td>
27
      <td class="tablehead" colspan="2" align="right">
28
        <a href="./harvester.html">Back</a>
29
      </td>
30
    </tr>
31
  </table>
32

    
33
<h4>Introduction</h4>
34
<p>
35
The Harvest List Editor is a tool that assists in composing and editing a 
36
<a href="./harvester.html#HarvestList">Harvest List</a>. The Harvest List
37
editor displays a Harvest List as a table of rows and fields. Each row in
38
the table corresponds to a single &lt;document&gt; element in the 
39
corresponding Harvest List XML file, where a &lt;document&gt; represents
40
a single document to be harvested. Each row contains the following fields:
41
<ul>
42
<li>Row #<br>Displays the table row number. This field is used for visual reference only;
43
it is non-editable and its value is not included in the
44
XML file that is generated when the Harvest List is saved to disk.</li>
45
<li>Scope<br>the value of the &lt;scope&gt; element for this document</li>
46
<li>Identifier<br>the value of the &lt;identifier&gt; element for this document</li>
47
<li>Revision<br>the value of the &lt;revision&gt; element for this document</li>
48
<li>Document Type<br>the value of the &lt;documentType&gt; element for this document</li>
49
<li>Document URL<br>the value of the &lt;documentURL&gt; element for this document</li>
50
</ul>
51
</p>
52
<p>For each &lt;document&gt; element to be included in the Harvest List, edit a row in the
53
table, filling
54
in values for each of the five editable fields: Scope, Identifier, Revision,
55
Document Type, and Document URL. When you have finished adding &lt;document&gt;
56
elements to the Harvest List, save the Harvest List to disk. Each of these steps are 
57
explained in more detail <a href=#Using>below</a>.</p>
58

    
59
<h4><a name="Configuring">Configuring the Harvest List Editor</a></h4>
60
<p></p>
61
The Harvest List Editor has a number of settable properties that control its
62
behavior. All configuration information is managed in a single file,
63
<b>.</b>harvestListEditor (note the leading dot character), which should be 
64
created using a plain text editor and placed in the user's home directory. 
65
To determine the user's home directory, open a system command window or terminal 
66
window and typing the following:
67
<ul>
68
<li></li>
69
On Windows:
70
<code><pre>
71
  echo %USERPROFILE%
72
</pre></code>
73
</li>
74
<li>
75
On Linux/Unix:
76
<code><pre>
77
  echo $HOME
78
</pre></code>
79
</li>
80
</ul>
81
</p>
82
<p>
83
The following table summarizes the properties that can be configured in the
84
.harvestListEditor file. Note that all properties are optional;
85
setting them improves the convenience of using the Harvest List Editor
86
but it is not a requirement.
87
<p>
88
  <table border="1">
89
    <tr>
90
      <td><b>Property</b></td>
91
      <td><b>Description</b></td>
92
      <td><b>Possible or default value</b></td>
93
    </tr>
94
    <tr>
95
      <td>defaultHarvestList</td>
96
      <td>This property determines the location of a Harvest List
97
          file that the Harvest List Editor will automatically open for
98
          editing on startup. Set this
99
          property to the path to the Harvest List file that
100
          you expect to edit most frequently.</td>
101
      <td>Examples:
102
        <br><code>/home/jdoe/public_html/harvestList.xml</code><br>
103
            <code>C:/temp/harvestList.xml</code>
104
      </td>
105
    </tr>
106
    <tr>
107
      <td>defaultScope</td>
108
      <td>Determines the value that is pasted into the <em>Scope</em> field
109
          of the currently selected row when the 
110
          <code>Paste Defaults</code> button is clicked. The <em>Scope</em> 
111
          field should contain a symbolic identifer that indicates which 
112
          family of documents this EML document belongs to.</td>
113
      <td>
114
          Example:&nbsp;&nbsp;&nbsp;xyz_dataset<br>
115
          Default:&nbsp;&nbsp;&nbsp;&nbsp;dataset
116
      </td>
117
    </tr>
118
    <tr>
119
      <td>defaulIdentifer</td>
120
      <td>Determines the value that is pasted into the <em>Identifier</em> field
121
          of the currently selected row when the <code>Paste Defaults</code> button 
122
          is clicked. The <em>Identifier</em> field should contain
123
          a numeric value indicating the identifier for this particular
124
          EML document within the Scope.</td>
125
      <td>
126
          Example:&nbsp;&nbsp;&nbsp;2<br>
127
          Default:&nbsp;&nbsp;&nbsp;&nbsp;1
128
      </td>
129
    </tr>
130
    <tr>
131
      <td>defaultRevision</td>
132
      <td>Determines the value that is pasted into the <em>Revision</em> field
133
          of the currently selected row when the <code>Paste Defaults</code> button 
134
          is clicked. The <em>Revision</em> field should contain a numeric
135
          value indicating the revision number of this EML document within
136
          the Scope and Identifier.</td>
137
      <td>
138
          Example:&nbsp;&nbsp;&nbsp;2<br>
139
          Default:&nbsp;&nbsp;&nbsp;&nbsp;1
140
      </td>
141
    </tr>
142
    <tr>
143
      <td>defaultDocumentType</td>
144
      <td>Determines the value that is pasted into the <em>Document Type</em> field
145
          of the currently selected row when the <code>Paste Defaults</code> button 
146
          is clicked.</td>
147
      <td>A document type specification
148
          <br><br>
149
          Default:<br> <code>eml://ecoinformatics.org/eml-2.0.0<code>
150
      </td>
151
    </tr>
152
    <tr>
153
      <td>defaultDocumentURL</td>
154
      <td>Determines the value that is pasted into the <em>Document URL</em> field
155
          of the currently selected row when the <code>Paste Defaults</code> button 
156
          is clicked. Typically, this value would be set to the portion
157
          of the URL that all harvested EML documents at your site share in common.</td>
158
      <td>A URL, or partial URL
159
          <br><br>
160
          Example:<br> <code>http://somehost.institution.edu/somepath/<code>
161
          <br><br>
162
          Default:<br> <code>http://<code>
163
      </td>
164
    </tr>
165
  </table>
166
</p>
167
The contents of a sample .harvestListEditor configuration file appear below:
168
<pre><code>
169
defaultHarvestList=C:/temp/harvestList.xml
170
defaultScope=demo_document
171
defaultIdentifier=1
172
defaultRevision=1
173
defaultDocumentURL=http://www.lternet.edu/~dcosta/
174
defaultDocumentType=eml://ecoinformatics.org/eml-2.0.0
175
</code></pre>
176

    
177
<h4><a name=#Running>Running the Harvest List Editor</a></h4>
178
  After the Harvest List Editor has been appropriately 
179
  <a href=#Configuring>configured</a>, it can be run as follows:
180
  <ol>
181
  <li>Open a system command window or terminal window.</li>
182
  <li>Set the METACAT_HOME environment variable to the value of the Metacat
183
      installation directory. Some examples follow:
184
      <ul>
185
        <li>On Windows:
186
        <pre>set METACAT_HOME=C:\somePath\metacat</pre></li>
187
        <li>On Linux/Unix (bash shell):
188
        <pre>export METACAT_HOME=/home/somePath/metacat</pre></li>
189
      </ul>
190
  <li>cd to the following directory:
191
      <ul>
192
        <li>On Windows:
193
        <pre>cd %METACAT_HOME%\lib\harvester</pre></li>
194
        <li>On Linux/Unix:
195
        <pre>cd $METACAT_HOME/lib/harvester</pre></li>
196
      </ul>
197
  <li>Run the appropriate Harvester shell script, as determined by the
198
      operating system:
199
      <ul>
200
        <li>On Windows:
201
        <pre>runHarvestListEditor.bat</pre></li>
202
        <li>On Linux/Unix:
203
        <pre>sh runHarvestListEditor.sh</pre></li>
204
      </ul>
205
  </li>
206
  </ol>
207
  <p>The Harvest List Editor application will start executing, automatically
208
     opening the default Harvest List for editing if the 
209
     <code>defaultHarvestList</code>
210
     property has been appropriately configured in the 
211
     <code>.harvestListEditor</code>
212
     file in the user's home directory.
213
  </p>
214

    
215
<h4><a name=#Using>Using the Harvest List Editor</a></h4>
216

    
217
<h5>The File Menu</h5>
218
The File Menu contains the following menu items:
219
<ul>
220
<li><code>New</code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
221
Opens a new (empty) Harvest List file for editing.
222
</li>
223
<li><code>Open...</code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
224
Opens an existing Harvest List file for editing.
225
</li>
226
<li><code>Save</code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
227
Saves the Harvest List file to disk using its current file name.
228
</li>
229
<li><code>Save As...</code>
230
Saves the Harvest List file to disk, prompting for a different file name.
231
</li>
232
<li><code>Validate</code>&nbsp;&nbsp;&nbsp;&nbsp;
233
Validates the currently open Harvest List and issues messages about any errors that are detected.
234
</li>
235
<li><code>Exit</code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
236
Exits the Harvest List Editor.
237
</li>
238
</ul>
239

    
240
<h5>The Button Pallette</h6>
241
The Harvest List Editor contains the following buttons in the button pallette
242
at the bottom of the editor window:
243
<ul>
244
<li><code>Cut</code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
245
Cut the currently selected row from the table and save the values to the clipboard.
246
</li>
247
<li><code>Copy</code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
248
Copy the values from the currently selected row into the clipboard.
249
</li>
250
<li><code>Paste</code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
251
Paste the values from the clipboard into the currently selected row.
252
</li>
253
<li><code>Paste Defaults</code>
254
Paste the default values into the currently selected row. The default values
255
are specified in the <a href=#Configuring>.harvestListEditor</a> configuration file.
256
</li>
257
</ul>
258

    
259
<h5>Editing the Harvest List</h5>
260
<p>
261
To edit the Harvest List, enter values for each of the five editable fields
262
(all fields except the "Row #" field) for a given row in the table. Each
263
row in the table corresponds to a single document that you wish to add to
264
the Harvest List.
265
</p>
266
<p>
267
Empty rows in the table are ignored when generating the Harvest List;
268
therefore, "holes" in the table are allowed.
269
For example, rows #1 and #3 may contain values while row #2 may be empty.
270
However, if any one of the editable fields in a row contains a value, then
271
all five of the editable fields should contain values. Partially filled-in
272
rows will cause errors that will result in an invalid Harvest List.
273
</p>
274
<p>
275
You can <code>Cut</code>, <code>Copy</code>, and <code>Paste</code> rows 
276
from one location to another by selecting a row
277
and clicking the corresponding button. You can paste the default
278
values into the currently selected row by clicking the 
279
<code>Paste Defaults</code> button.
280
Only one row may be selected at any given time: all cut, copy, and paste
281
operations work on only a single row rather than on a range of rows.
282
</p>
283

    
284
<a href="./harvester.html">Back</a>
285

    
286
</BODY>
287
</HTML>