source: main/trunk/model-sites-dev/waikato-edu/collect/README-science-activities.txt@ 33696

--------------------
  README
--------------------
A. RECREATING THE science-activities GREENSTONE COLLECTION's import FOLDER'S CONTENTS FROM SCRATCH
B. REBUILDING THE science-activities COLLECTION
C. VIEWING THE COLLECTION WHEN IT'S ALREADY BEEN BUILT
D. INFORMATION AND WARNINGS



A. RECREATING THE science-activities GREENSTONE COLLECTION's import FOLDER'S CONTENTS FROM SCRATCH
---------------------------------------------------------------------------------------------------
ONLY if you ever want to REGENERATE the folders for ingesting into GS3 your crate folders, PDF/Word files and metadata, then:

0. Obtain the TT4.02 Science Resources Crates content from the Uni of Waikato Education Department. We do not have the permission to distribute it or make it public.
But assuming the Education Dept. has given this content you in a zip format, follow the instructions below.

1. Extract the TT4.02_Science Resources_Crates.zip, which will create a folder called TT4.02_Science Resources_Crates.
For example, extract it on the Desktop and your Windows desktop will now have a new folder called "TT4.02_Science Resources_Crates".
If not already present, obtain the 14 .csv files labelled between A-1 to F-2 from the Education department and put them into the new TT4.02_Science Resources_Crates folder.

2. Next, move the file web/sites/waikato-edu/collect/science-activities/DATA-PREPARATION/procCrates.bat into the new TT4.02_Science Resources_Crates folder as well.

In our example, your extracted TT4.02_Science Resources_Crates was on the Desktop, e.g. at C:\Users\You\Desktop\TT4.02_Science Resources_Crates
Whatever the actual location, remember it and use it in the following. I will stick with the example of C:\Users\You\Desktop\TT4.02_Science Resources_Crates

Double-click on the procCrates.bat script.

Wait until the procCrates.bat script has finished processing the TT4.02_Science Resources_Crates folder contents. It should have created a folder called "import" in C:\Users\You\Desktop\TT4.02_Science Resources_Crates.

[ONLY IF things didn't work out correctly in step a, then you can delete any folder called "import" that it produced and run the procCrates.bat script manually, to look for any issues.

Open a DOS prompt:
    first hold down the Windows key on the keyboard (located between Alt and Ctrl keys) and press the R key (R for run);
    then a little dialog will pop up. Type "cmd" into its edit field and press enter and a DOS prompt will appear.

In the DOS prompt, type:
    cd C:\Users\You\Desktop\TT4.02_Science Resources_Crates
(i.e. "cd" followed by the full path to the actual location of your extracted folder)

Next type:
    procCrates.bat

Wait for the script to finish.
]

3. ONLY if you now want to reingest and rebuild your collection with the contents of the new import folder, use a file browser to do the following:
- Delete all except the top-level metadata.xml file in your Greenstone 3 installation's "web/sites/waikato-edu/collect/science-activities/import" folder.
- Go into the "C:\Users\You\Desktop\TT4.02_Science Resources_Crates\import" folder. You should see subfolders A-1 to F-2.
- MOVE all these into your Greenstone 3 installation's "web/sites/waikato-edu/collect/science-activities/import" folder, where you should already have the old solitary metadata.xml file at this level.

To rebuild the science-activities collection, follow the instructions under "REBUILDING THE SCIENCE ACTIVITIES COLLECTION" below.



B. REBUILDING THE science-activities COLLECTION
------------------------------------------------
1. Run the GLI/Greenstone Librarian Interface application of your installed Greenstone.
2. In GLI, select File > Open. Choose your "science-activities" collection.
3. When this finishes opening, click on the Create tab in GLI.
4. Find the Build Collection button at the bottom and press it. This can take a long time, maybe 15 mins or more. Eventually it will finish building and you can press the Preview button also at the bottom of the Create pane to have it open a browser for you and show you the finished collection.



C. VIEWING THE COLLECTION WHEN IT'S ALREADY BEEN BUILT BEFORE
--------------------------------------------------------------
You only have to rebuild a collection when you make changes to it or if it's never been built before.
Otherwise, if a collection has already been built at some point and hasn't been modified since, you can preview it directly as follows.

Start your Greenstone's installation's "Greenstone Server" application. Pressing this application's "Enter Library" button should open your default browser on your Greenstone DL home page. Visit your new science-activities collection, as it's prebuilt.



D. INFORMATION AND WARNINGS
----------------------------
- I exported each crate's .csv file individually from Excel (by default it exports in ASCII encoding format, so I left it as such and let the procCrates.bat script deal with this).
I did this by opening the "Crates (TT4.02).xlsx" file that was in the TT4.02_Science Resources_Crates.zip downloaded from your Google drive. Then I clicked on each sheet and did Save As > *.csv (the most basic CSV option).

- the procCrates.bat now processes each crate's csv file and outputs additional metadata from before.
In processing each csv file, it simplifies the Activity Name (handles &, ", ', etc) to make it more compatible as metadata for Greenstone.
NOTE: I have had to change / (forward slash) to ; (semi-colon) as the / is used as a hierarchy separator by the browsing classifier code.

- The collections in the "waikato-edu" Greenstone site make use of the custom Greenstone metadata set file "educationresources.mds".
It can be found at waikato-edu/collect/science-activities/metadata/educationresources.mds (if you've already moved the waikato-edu site into your Greenstone 3 installation, it can be found within your Greenstone 3 installation directory at web/sites/waikato-edu/collect/science-activities/metadata/educationresources.mds).
    * You can copy the educationresources.mds file into gli/metadata to re-use it for other collections you create from scratch.
    * Alternatively, any collection created based on the science-activities collection will automatically inherit a copy of hte educationresources.mds Greenstone metadata set file.
    
- I've modified web/sites/waikato-edu/siteConfig.xml with a single additional line to have a word icon for docx files too (not just for the old .doc files). The additional line is:
    <replace macro="_icondocx_" scope="metadata" text="&lt;img src='interfaces/default/images/imsword.gif' border='0'/&gt;" resolve="false"/>

- In GLI's Design tab, I configured the plugins used to build your collection, and set up the search indexes and browsing classifiers that should be available:
    only one search Index on ActivityName, as you requested
    and one browsing classifier that works with the newly introduced er.CrateHierarchy metadata
- I used GLI's Format tab to set up the display of the search results and browsing classifier content.
Basically, when you BROWSE to an activity, under the activity name you will see its document(s). For each document: you get an icon linked to the HTML version of each document (produced by Greenstone), an appropriate icon linking to the original document format (PDF or docx) and the FILENAME of the document, since the activity name of the browser is what the filename is found under.
When you SEARCH for an activity name or part of an activity name, you once more get the HTML doc icon and source doc icon but this is then further followed by the ACTIVITY NAME and then the filename in brackets.

Based on the changes made to GLI's Design and Format panels, a customised collectionConfig.xml is generated for this collection. When you create future collections through GLI, you can use "Base collection on" option in GLI's New Collection dialog to base those future collections on the design and formatting of this collection (make sure you assign the same metadata). Making this choice in GLI will automatically reuse the same collectionConfig.xml, inheriting all its configurations. The new collection thus created will also get to use the same metadata sets, including the custom one we prepared, "educationresources.mds".

So all the hard work here went into procCrates.bat and into setting up the collection's configuration, which produced collectionConfig.xml.


WARNINGS
Beware not to change the encoding of procCrates.bat from ASCII to UTF-8 or other encodings. If you wish to edit this file, open it in Notepad++ and leave it's encoding in ASCII.

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