Greenstone tutorial exercise

Using WebSwing GLI (Web GLI)

When a librarian or other collection designer wants to create/edit a collection on a Greenstone installation that's running on a remote server machine (such as on a cloud), there are several options to connect to the remote machine.

There is the new WebSwing GLI, which allows you to use the remote Greenstone installation's GLI through your local web browser, the specifics of which are described in this tutorial.

There is also client-gli, which requires you to first set up the remotely running Greenstone server to support client-GLI applications connecting to it. It also requires you to have a Greenstone installed in order to run a client-GLI.

(In the past, there was also the GLI applet, but support for Java applets has been deprecated by browsers over the past years.)

WebSwing GLI is the easiest route, as it is already set up and ready to use once you have your Greenstone server up and running. For this reason, going forward, WebSwing GLI will be maintained as the most up-to-date version of GLI that allows creating and editing collections on a remotely running Greenstone 3.

The following assumes you have a Greenstone 3 server that's already running, whether on a cloud or locally such as at the default location of http://localhost:8383/greenstone3/library.

Creating a user account

To connect with GLI to you need a user account that has collection-editing permissions or you can use the default "admin" user account that is already set up with the permissions of all-collections-editor. Refer to the tutorial Customization: Themes as to the password for the admin user, unless you've already changed its default password.

1. Visit your running Greenstone server's home page in the browser. Scroll down to the link labelled Administration Page and click it. As it says, it "Allows you to manage users". Before proceeding, you'll be asked to log in as the admin user (or as any custom users you created with administration privileges) in order to add new users.

2. Press the button Add a New User.

3. Fill out the fields. As a bare minimum, you will need to enter a username for the new user, enter a password for the account twice and assign what Groups the new user belongs to. Groups controls both access permissions and content creation permissions: whether the new user is in the right group to view restricted Greenstone collections and documents, and whether the user is in the right group to edit certain (or any) collection.

4. If you wish to give your new user the all-mighty rights of an administrator, you can add "administrator" to their Groups field. Usually, you will not want to go around giving every new user administrator rights. There are 3 kinds of pre-existing Groups that determine a user's content creation permissions: if they belong to all-collections-editor (like the default admin user does), they can create any Greenstone collection and edit any collection. If their Groups field contains personal-collections-editor, they have the right to create any collection they want, but only to edit the collections they created and not those created by others. Setting a user's Groups field to COLLNAME-collection-editor, where you have to edit COLLNAME to a specific collection's shortname, will allow the user to edit that collection. For instance, if a user has lucene-jdbm-demo-collection-editor in its list of groups, they have the right to edit the default Greenstone 3 collection "lucene-jdbm-demo".

5. For now, you could add "personal-collections-editor" to your new user's group to give them the right to create any collection and edit those. This will be sufficient to cover most Greenstone 3 tutorials. But for your user to have the additionally ability to edit the default "lucene-jdbm-demo" demonstration collection, you can append lucene-jdbm-demo-collection-editor to the groups field (separated by comma). Alternatively, you can just set the user's Groups field to all-collections-editor, if you're going to go through all the tutorials with WebSwing GLI using this new user account.

Accessing WebSwing GLI: a Greenstone Librarian Interface (GLI) application accessible over your browser

6. First run the Greenstone server:
   
   You need the GS3 server to be running in order to access WebSwing GLI. To launch the GS3 server, on Windows you can select the Greenstone 3 shortcut or double-click your GS3 installation's top-level gs3-server.bat script to launch the Greenstone Server Application dialogue. A small dialog should appear where you can click the central Enter Library button. Then wait for this application to open a browser and display the Greenstone server home page for you. Note that if you're on linux or a Mac, you can use the equivalent ./gs3-server.sh script to launch the same server application. For Mac binaries, you also have the option of double-clicking the gs3-server shortcut to launch this application.
   
   Alternatively, if you choose to run the Greenstone server from the command line, then first run gs3-setup.bat to set up the Greenstone environment needed for WebSwing GLI to properly function, before running ant start. The linux and Mac equivalent is to run source ./gs3-setup.sh before similarly running ant start to start up the GS3 server.

7. Start the WebSwing Greenstone Librarian Interface:
   
   Visit your running Greenstone server's home page in the browser. By default, for a locally running Greenstone, this would be at http://localhost:8383/greenstone3/library.

8. Scroll down to the link Greenstone Librarian Interface (GLI) and click it.

9. After some time a popup dialog will request a username and password. Enter the details for either the default admin account, or any user created earlier.

10. WebSwing GLI will load in your browser. Once it's finished loading up, you can start using GLI almost as usual.

WebSwing GLI is mostly the same as regular GLI except for a few notable differences:

• In the Gather panel, the Workspace tree view will not give you access to the file system (of either your machine or the remote machine running Greenstone) for web security reasons. With WebSwing GLI, you won't be gathering your documents by dragging and dropping them but by using a file browser to upload them into your collection:
  When you have a new or existing collection open in WebSwing GLI, you will find an Upload icon at the bottom right of WebSwing GLI's Gather panel. You can click this Upload icon to upload either individual files or a zipped file from your local machine onto the remote Greenstone collection.
  Often, you will find you need to upload many documents or folders of them, not individual files. In that case, first zip up your files and/or folders locally, then use the Upload icon to select the zip to upload it.
  (If GLI offers to add the ZipPlugin to your collection, you can choose to cancel out of it, as you generally mean to unzip them yourself in the gathering documents phase when using WebSwing GLI.)
  Once the uploaded zip appears in the Collection tree view, right click on it and select Unzip.
• Regular GLI allows you to double-click on any document you've gathered to view it whenever you have a default application set up to view that type of file. WebSwing GLI can only allow you to view documents that your browser is able to display. Double-clicking on any other type of document will download it onto your local machine, where you can then view it if you have the appropriate application installed for its file type.
• Similar to the Upload icon in the Gather panel, in the General section of the Format panel you will find that the two browse buttons (the URL to 'about page' image: and URL to 'home page' image:), which allow you to select custom images to use for your collection on the home page and about page, now actually has the net effect of uploading image files you select from your local file system onto your collection on the remote Greenstone installation.

For the rest, WebSwing GLI will work like regular GLI in the tutorials. So you are now set to, for instance, go through the A simple image collection tutorial using WebSwing GLI this time, bearing in mind the above differences. Try it out to familiarise yourself with WebSwing GLI.