In this session you will:
The intention is to give you some confidence using the system and finding your way around. Feel free to ask the assistants for help, or about anything you find confusing or interesting.
Don't worry about finishing everything. If you get stuck: ask!
To make this session practical we have pre-installed some linux boxes with the required perl modules, mysql and apache 2. You can SSH to your linux box with the username "epdemo". The password will be given to you by the assistants.
Your machine is:
.ecs.soton.ac.uk
Log in to it now!
We've already provided an apache that is preconfigured to run with eprints (on port 8080, running as user "epdemo", group "epdemo" and the configuration already has the line "Include /opt/eprints2/cfg/apache.conf" in it) so you don't have to do that bit.
The apache files are in /opt/httpd8080
Enter the following UNIX commands:
Now just check it's really installed:
EPrints is now installed.
We're skipping some stages of installing EPrints:
This program asks a whole load of questions:
configure_archive should have created a mysql database, a default config xml file in: /opt/eprints2/archives/myid.xml and made a default configuration and directories for the archive under /opt/eprints2/archives/myid/
Create the SQL tables
Import the "subjects" table (Library of congress is the default). The file is imported from /opt/eprints2/archives/myid/cfg/subjects
The --force option just stops it asking "are you sure?"
Copy the static images and webpages from the cfg dir to the archive website. Applies the template to the webpages.
Create the apache config files for all the archives. Note that this generates all the apache config files for all eprints archives on this server, so myid is not needed.
Start the eprints indexer. It runs in background to index the words in fields and documents.
Start apache (on port 8080)
note, this is a local setup of apache just for the demo, you'd usually start and stop it as the root user, but we can't let you be root on our machines!
Now open a web browser and goto http://footle.ecs.soton.ac.uk:8080/ (where footle is your machine name). If it's not working feel free to ask for help.
If you want to stop the webserver use:
That's not really a good way to do it normally, but handy for our demo session.
To create an administrator user called "adminuser" with password "secret" do this:
Make sure you can log into the "user area" of the new site using the admin users account. You'll have to provide a valid name for "adminuser" before it will let you continue. By default users without names may not do anything!
We're skipping some stages of setting up an archive. They are:
To do this you are going to need to edit some of the configuration files for our new archive. To do this you will need to use a text editor. vi, emacs and pico are available, maybe others.
Every page on eprints is wrapped in the site template. This can be found at /opt/eprints2/archives/myid/cfg/template-en.xml
The archive website can be split into four sections static, dynamic, views and abstracts. Each type of page is generated in a different way. When you change the style and want to relfect that change in the site you need to know how to get eprints to update the part of the site in question.
These are pages which do not change. They are built by the "generate_static" command which copies files from the directories /opt/eprints2/archives/myid/cfg/static/general/ and /opt/eprints2/archives/myid/cfg/static/en/ into the live website directory /opt/eprints2/archives/html/en
The "en" indicates english language files. The /general/ contains non-language specific files like icons and the style sheet.
Files in the cfg/static/en with the suffix .xpage are XML files containing only the contents of the page. Rather than just copy these, generate_static applies the site template to these and renames them to .html in the website dir.
Everything on the website which starts with /perl/, such as the latest deposits page, all the submission pages and the search pages.
These pages are created by mod_perl. The mod_perl part of eprints (the web server) only loads the config files once when you start apache.
To force the webserver to reload the configuration, either stop and start it, or run "force_config_reload" (although this is inefficient, it's handy if you're making lots of little changes.
Everything on the website which starts with /view/
These are the browse-by-subject, browse-by-year etc, pages. They are built by the script "generate_views" either on the command line or as an automated cron job.
We are going to ignore view pages to keep the workshop simple.
The pages which describe a record. eg. http://eprints.soton.ac.uk/44/
These are generated by the webserver part of eprints (see dynamic pages, above) but can be generated on the command line using generate_abstracts.
We are also going to ignore abstract pages in todays workshop.
Edit /opt/eprints2/archives/myid/cfg/template-en.xml
Add a horizontal ruler under the title: find the "h1" element and on the next line add <hr />
Note that this file is XML so all tags must be closed correctly.
If you feel confident, make some more interesting changes too.
run force_config_reload and generate_static to apply your new template to the static and dynamic pages. note that we are skipping generate_views and generate_abstracts pages.
Edit /opt/eprints2/archives/myid/cfg/static/general/eprints.css
Edit the "background" value for .header and .footer to be #ccffcc (light green).
Make more changes if you like.
Copy the new stylesheet into the live site:
Have a shufty around the website using a web browser to see your changes!
There's an easy way and a hard way to add a metadata field. The hard way is to add it when you've already got data you care about in your archive, because you have to add it to the config files then alter the sql tables by hand to accomodate it. (There's a page on wiki.eprints.org if you ever need to know how to do that).
But for today, the easy way: we edit the config files then run "erase_archive" to destroy the database and website (but NOT the configuration). Then run create_tables, import_subject etc. again.
We are going to add a new field "colour of cover" to eprints of type book and book_section.
EPrint types are described in /opt/eprints2/archives/myid/cfg/metadata-types.xml
We need a database field name for this field. Use cover_col.
Edit the fields configuration file: /opt/eprints2/archives/myid/cfg/ArchiveMetadataFieldsConfig.pm
Under "full_text_status" add this config:
{ name => "cover_col", type=> "set",
options => [ "red", "green", "blue", "other" ] },
That tells eprints that there's a field of type "set" with those options. Now we need to add the human readable names and descriptions. These go in the archive-specific phrase file. There's also one for all of eprints which contains all the phrases used in the interface, except for those which are archive specific.
Edit: /opt/eprints2/archives/myid/cfg/phrases-en.xml
Add the following phrases:
<ep:phrase ref="eprint_fieldname_cover_col">Colour of Book Cover</ep:phrase>
<ep:phrase ref="eprint_fieldhelp_cover_col">Select the approximate colour of the cover of the book.</ep:phrase>
<ep:phrase ref="eprint_fieldopt_cover_col_red">Mostly Red</ep:phrase>
<ep:phrase ref="eprint_fieldopt_cover_col_green">Mostly Green</ep:phrase>
<ep:phrase ref="eprint_fieldopt_cover_col_blue">Mostly Blue</ep:phrase>
<ep:phrase ref="eprint_fieldopt_cover_col_other">Other</ep:phrase>
Keywords like "cover_col" and "blue" are used in the database and not seen by the users. The phrases are the cosmetics of your new metadata field.
Now you need to add the metadata field to one or more types of record.
Edit: /opt/eprints2/archives/myid/cfg/metadata-types.xml
Make the cover colour optional for records of type "book_section" but required for type "book"... First find the book_section eprint type. It starts with: <type name="book_section">
Add this anywhere in the "type". Where you add it controls what where and on what page in the submission form the field appears:
<field name="cover_col" />
Now find type "book" and add:
<field name="cover_col" required="yes" />
Note: re-creating the database tables and restarting the indexer is only needed because you made a significant change to ArchiveMetadataConfig. Normally restarting apache is enough to make a config. change take effect.
OK, that's the configuration done. Now erase your website and database, and rebuild it:
MySQL root password is blank (just hit return).
There is no need to rerun generate_apacheconf as you've not changed anything to do with the actual serving of the website.
Now start and stop the webserver and indexer so they get the new configuration.
And create an admin user (again). Erase archive also destroyed all user data too!
On the website:
And if that all works first time give yourself a pat on the back!