OHMS Viewer installation and customization instructions
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License (Version 3) as published by the Free Software Foundation.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.
The OHMS Viewer includes:
jQuery jQuery UI Fancybox Colorbox FlowPlayer
Use and modifications of these libraries must comply with their respective licenses.
- PHP 5.3+
- Tested with Apache httpd on Linux, but other setups (e.g., Windows/IIS) should also work.
In the instructions below, file references (such as css/viewer.css) refer to the relative path to files from the extracted OHMS Viewer zip file.
I. Install the Viewer Files
Download the OHMS Viewer zip file.
Create a subdirectory on the web server to store the OHMS Viewer. If your web server stores pages in /var/www/html and you want to access the viewer as http://example.com/ohms-viewer/, then you would create the subdirectory "ohms-viewer" in /var/www/html/.
Extract the OHMS Viewer zip file into the subdirectory you created.
II. Set the values for the configuration file
The next steps will require using a text editing program to create your configuration file for the Viewer. This configuration file allows you to set the background colors, the Usage and Rights statements and images used on the Viewer page. You can refer to the config.example.ini in the Viewer subdirectory "config"as a guide for settings values.
Create the configuration file "config.ini". Rename the file "config.template.ini" to "config.ini" in the Viewer subdirectory "config". The reason for this is that if you implement a newer version of the Viewer, your current config.ini file will not be overwritten or replaced (though a future version may require changes to your config.ini).
Next, you must configure the OHMS Viewer to access the location for your repository cache files exported from OHMS. The cache files can be located on the same server, inside the Viewer directory, or on another server. To set the server path to access the cache files:
The config.ini has the property "tmpDir". Change this line to the server directory path for the cache files.
Inside the Viewer directory:
tmpDir = /var/www/html/ohms-viewer/cachefiles
On the server:
tmpDir = /usr/local/share/cachefiles/
On another server:
tmpDir = http://example.com/cachefiles/
In any case, you must ensure that the location you specify exists and is readable by the OHMS Viewer.
Set the repository name. Replace the existing entry that states "Your Repository Name" with your repository name as entered in the "repository" data field of your cache files. The names must match exactly (the same uppercase or lowercase letters and any punctation). For example, if your repository's name is "John J. Doe Center, University of Us" then that is what must be entered (without the double quotes).
The CSS file name (the "css" config property). The default setting is to the "custom_default.css" file located in the "css" subdirectory of the Viewer. We suggest you keep this file name. Edit the custom_default.css values to the background colors you wish to use. This is further discussed in the next installation section.
Set the location for the footer image (such as a logo) that appears in the footer area of the viewer (the "footerimg" config property). The image must reside in the root directory of your web site. An example is that if the image file is "footerimage.jpg" in the "images" subdirectory of your site, you would enter: images/footerimage.jpg .
Set the alternate text for the footer image that will appear when a computer pointing device (such as a mouse) hovers over the image or that is read by a screen reader. This is entered for the "footerimgalt" config property.
Set the contact email address for the "contactemail" config property.
Set the link to the web site for the repository owner for the "contactlink" config property. This may be the same as the URL for your site hosting the Viewer.
Set the text for the copyright holder information for the "copyrightholder" config property. If this text will list an entry such as a department or division of an organization (for example "History Department, University of State"), then each entity should be inside the HTML
<span></span>tags such as:
History DepartmentUniversity of State
Set the Open Graph "description" value for the "open_graph_description" config property. The Open Graph protocol provides a way for links placed in social media sites to display thumbnail images, descriptions and titles. The "description" is what will always appear as the description (such as "Our Repository") for every link to interviews hosted by your OHMS Viewer.
Set the Open Graph image to use for links placed in social media sites ("open_graph_image" config property). This will be the image seen with links placed in social media site postings (it does not appear on the Viewer page). The image must reside in the root directory of your web site. An example is that if the image is "ourimage.jpg" in the "images" subdirectory of your site, you would enter: images/ourimage.jpg .
Please note that the "title" that appears for links in social media sites using Open Graph is set by the "title" data field in the linked interview cache file.
III. Configuring the style values in the CSS file
The file css/custom_default.css contains a base set of style elements for the Viewer you can configure (The file css/viewer.css contains the overall CSS values if you wish to further change settings). You can edit the "background" attribute for body, #header, #footer, #audio-panel, or #subjectPlayer to set the background color. For example, if you want the footer to have a light red background, you can edit #footer to include the line
IV. Using the Viewer with your interview XML files exported from OHMS
After installing and configuring the Viewer, you can begin testing and using it immediately. You must have your interview files exported from OHMS in the directory you set for the "tmpDir" configuration property. The URL for using the Viewer would be your web site address and the subdirectory for the Viewer along with the page (viewer.php) that processes the interview file. An example is:
If this URL does not load properly or you receive an error message about not finding the interview file, check the following:
- The subdirectory name where the Viewer is located is correct.
- The "tmpDir" in the configuration file is correct for the location where you placed your interview files exported from OHMS.
- The name of the XML file after "cachefile=" in the URL is correct.
- Check the permissions on the subdirectories for the Viewer and XML interview files to make sure that your web server can read/access files.
Extending OHMS Viewer
I. Implementing a different media player for interview files with "Other" as the media file host
This will entail changing the following files:
/tmpl/viewer.tmpl.php /tmpl/player_other.tmpl.php /js/viewer_other.js
We recommend making backups of those files before doing this (or at least keep track of where you stored the Zip file for future use).
The two most likely scenarios for implementing a different player and what we suggest in doing so are: