My favorites | Sign in
Project Home Downloads Wiki Issues Source
Search
for
Manual  
Updated Jan 13, 2009 by alexa...@gmail.com

ISIS User's Manual


Installation

Requirements

To run ISIS, you will need:

  • A web server running PHP 5.2
  • The SimpleXML package compiled into PHP
  • "Short tags" enabled in php.ini

If you wish to store your spatial metadata in a relational database, you will need to have MySQL or PostgreSQL installed and available. Otherwise, you can use the XML file data store, which does not require any extra software. There is no difference between the two in terms of how ISIS works; the choice comes down to whichever you feel more comfortable with.

At UNLV, we currently use the XML data store for logistic reasons. Your choice is not set in stone, as you can always use the control panel to export your data in ISIS SQL and ISIS XML format.

Acquire database privileges (RDBMS data store only)

For day-to-day operation, the database user will need SELECT privileges on the map and collection tables. For all features in the control panel to work, it will also need INSERT, UPDATE, and DELETE privileges on all tables. Talk to your database administrator about setting this up.

Create the database (RDBMS data store only)

Download the sample schema dump from the Downloads section to create your database tables. The SQL commands may need a little tweaking to work in your DBMS.

Create the XML data file (XML data store only)

Download data.xml from the Downloads section and put it in your ISIS xmldata folder.

Install the files

Download the latest version from the Downloads section. Unzip the distribution file and copy the files onto your web server.

Finally, make sure that all files are readable by your web server but that none are writable except configure.xml.php (and xmldata/data.xml if you are using the XML file data store).

Set ISIS_FOLDER_ROOT

ISIS_FOLDER_ROOT is a class constant in init.php. Set it to the path to your ISIS folder relative to the web server's document root. For example, if your ISIS URL were http://yourserver/isis, you would set it to /isis.

Generate a user for the control panel

The list of users who can log into the control panel is stored in config.xml.php. Before you can log in, you will need to add a user for yourself. Navigate to http://yourserver/your_isis_folder/admin/usergen.php in your web browser and enter a username and password. Copy the resulting XML block into the <users> block in the config.xml.php file.

Usernames and passwords can be any combination of uppercase and lowercase letters and numbers and can include periods, dashes, and underscores, but nothing else.

Initial configuration in the control panel

You should now be able to log into the control panel. You can reach it by navigating to http://yourserver/your_isis_folder/admin/ in your web browser. Click on the Configuration tab to change the default coverage of the main map, the number of zoom levels, and many other settings. This has to be done for ISIS to work properly.

Acquire some geodata

The main map is not going to be very pretty or useful with nothing in it. You will want to install at least a basemap, with perhaps other layers as you wish. These layers can be in either SVG or raster (JPEG/GIF/PNG) format. Unfortunately, there is no "one-stop geodata shop" that will allow you to plug in geodata and run. You will have to find the data, which may come in any of a variety of formats, transform it, and export it to SVG/JPEG/etc. Bitmap data can usually be edited in a raster editing program such as Photoshop; vector data can be edited in a vector editing program such as Illustrator, which can then be used to export to SVG. If you have any GIS experts on campus, these would be great people to consult. (If you can contribute useful advice to this section, please add it to the comments at the bottom of the page.)

The important thing is that whatever geodata you use must match the native projection of the view. This projection has several names including geographic, equirectangular, plate carré, and others. Most map images on the web are not in this projection. A map in a different projection will not line up properly with the coordinates in the viewport; however, at larger scales (smaller area coverages), this is less of an issue. It's not much of an issue at all at the scale of a city, for example. Orient the geodata

Once you have your geodata file(s), put them in the geodata folder, and reference them from templates/mainmap.svg.php. This procedure is described in comments in the mainmap.svg.php file.

For SVG data, save the SVG data layers inside their own files. Within these files, wrap each layer (e.g. roads, borders, cities, etc.) within a group, adjusting the translate and scale factors as above:

<g id="my_data_layer" transform="translate(-124.09,-43.25), scale(0.01538)">
  <path d="..." />
</g>

Add one or more collections to the data store

This is done in the Collections section of the control panel. All maps must be associated with a collection, so this step must be done before the next.

Add maps to the data store

This is done in the control panel. Select the map's collection (which you added above) and input its pointer ("CISOPTR") and its bounding coordinates. The pointer is a number that can be found in the URL of the map's item record. For example, the map at the following URL:

http://digital.library.unlv.edu/cdm4/item_viewer.php?CISOROOT=/LV_Maps&CISOPTR=479&CISOBOX=1&REC=1

...has a pointer of 479. ("CISOPTR=479")

Coordinates should be entered as decimal degrees which, for the northwestern hemisphere, should have a positive latitude and a negative longitude. That means you need to input all longitudes in this hemisphere as negative numbers. (See the diagram at the right of the "Add Maps" page.)

Correctness is very important, as one typo can place a map in the wrong hemisphere. The form will reject invalid coordinates, but not necessarily incorrect ones, and it will check the remote server to ensure that an item record with the pointer you specified exists. But the input checking is not foolproof, so you should be careful as it is easy to let errors slip through.

Some maps do not have coordinates printed at their edges; for these, you could try the Coordinate Calculator (Excel spreadsheet) in conjunction with a measuring stick. Some maps do not have coordinates printed at all, and some maps use very different coordinate systems, making additional research necessary. Map librarians would probably know more about this than the ISIS developer and author of this manual does.

Perform additional customizations

You will probably want to remove the UNLV branding from the templates and add your own. You can do this with with a basic knowledge of HTML. The templates are located in the templates folder within the ISIS root folder and are named with the .html.php extension. Future releases will overwrite your template customizations, but it should be simple to migrate them over. It's not likely that the templates will change much between releases.

All of the design is at your mercy; just be careful to stay outside the <?php ?> tags unless you know what you're doing... or vice-versa if you're a PHP developer who is no good at web design.


Upgrading

Back up your existing installation

Back up your current ISIS folder, just in case.

Copy over the new ISIS folder

Copy over the new ISIS folder in place of the old one. Then, copy your existing /geodata folder from the old location to the new, and add your references to them back into mainview.svg.php. You will also have to migrate any changes you've made to the page templates and styles within /templates. If you are using the XML data store, you will want to copy back /xmldata/data.xml as well.

Update the configuration

Since the available settings may have changed since the last release, it would be better to update the new configure.xml.php with your settings from the old one rather than overwriting it entirely with the old one. This can be done via the control panel, just like the first time.


Help

You are encouraged to add notes, comments, corrections, etc. to this wiki page by filling out the comments box at the bottom of the page. For inquiries to the developer, please use the UNLV Libraries Digital Collections contact form, and your message will be routed to the appropriate person. ISIS is a low-priority, spare-time project, and support will be provided as time allows.


Sign in to add a comment
Powered by Google Project Hosting