Configuring the Client

Overview

This page describes how to customize client applications for Variations. There are two types of clients, one for digitizers and the other for end users. The client software is the same in both cases, but it is configured differently, and the digitizer client installer includes some additional programs.

Digitizer Client
- is intended for staff to use in putting content into the Variations system
- includes encoder tools in the installer, for creating compressed derivatives
- is supported on Windows PCs only

End-User Client
- is intended for use by end-users wanting to listen to audio or view scores
- can still display digitizer and/or cataloger tabs in the Variations Search window for authorized users
- does NOT include encoder tools in the installer
- can be built for both Windows PCs and Mac OS X

Download Application & Configuration Files

Windows

Download and unzip the Variations Client Construction Kit zip file:

first go to Client Construction Kit Download Page on SourceForge
then select the latest version Client Contruction Kit zip file download link.
The download sequence for the browser should commence.
Unzip the zip file to a new directory.

Mac OSX

Download and unpack the Variations Client Construction Kit gzipped tar file:

first go to Client Construction Kit Download Page on SourceForge
then select the latest version Client Contruction Kit gzipped tar file download link.
The download sequence for the browser should commence.
Unpack the gzipped tar file to a new directory.

Configure Client

Windows & Mac

The client configuration allows for the integration between the end user (production and customers) software, the server software, and your institutions systems. The configuration of the client is done through the modification of the dml.conf files discussed below.

Properties in dml.conf

Windows
dml.conf can be be found at variations/client/conf/client/ in the directory where the files have been downloaded

Mac
dml.conf can be be found at Variations.app/Contents/Resources/Java/conf/client in the directory where the files have been downloaded

Digitizer-Cataloger and End User Properties

The file dml.conf will be installed and accessed by the client for the configuration of the End user distribution. The same dml.conf will be installed and accessed by the client for the configuration of the digitizer and catalogers distribution.

Login/Authentication Properties

Location

Windows
- End User: /Variations/Client/conf/client/dml.conf

Mac
- End User: /Variations.app/Contents/Resources/Java/conf/client/dml.conf

Modification Instructions

Manually set the properties that have a next to them

Property Name	Example Value(s)	Description
dml.login.serviceName	<library_name>	Connecting through RMI to a LibraryApplication server, available in the Client through Client.getLibraryName()
dml.login.autoFillUsername	true\|false	Fill in username field with the value in user.name, usually the current system username
dml.login.useCookie	true\|false	First attempt to login using stored cookie and save a cookie on login
dml.login.realm.x	iu.edu,Indiana University	Realm used for Kerberos login, x should be replaced with the number of the realm starting with 1
dml.login.rmiRegistryHost	server1.dlib.indiana.edu	Hostname of the RMI registry hosting the LibraryApplication servers. This value should be the fully qualified hostname of your Variations Server
dml.login.loginHandler	edu.indiana.dml.client.login.CommandLineLoginHandler	Full class name of the Login Handler to use for client logins
dml.login.adminMode	true\|false	Enable Admin Mode by default if permissions allow it. If not present or commented out, user will be prompted to choose admin or end-user mode.
dml.login.digitizerMode	true\|false	Enable Digitizer Mode by default if permissions allow it. If not present or commented out, user will be prompted to choose admin or end-user mode.

Client Properties

Location

Windows
- End User: /Variations/Client/conf/client/dml.conf

Mac
- End User: /Variations.app/Contents/Resources/Java/conf/client/dml.conf

Modification Instructions

Manually set the properties that have a next to them

Property Name	Example Value(s)	Description
dml.client.preloadClasses	true\|false	To preload classes before they are used to increase responsiveness if being run over a network
dml.client.lessonsOn	true\|false	Determines if the experimental Lesson Editor should be enabled
dml.qtj.verboseMode	true\|false	If true, QTJava will output extra debugging info
dml.client.url.userguidebase	http://Webserver.dlib.indiana.edu/variations/use/	Path to the user guide which appears when the application fails to load

Digitizer Properties

For Mac installations there is no digitizer & cataloger client so these values will not be applicable.

Location

Windows
- Digitizer & Cataloger: /Variations/Client/conf/client/dml.conf
Mac
- Mac does not currently support digitizer properties

Modification Instructions

Manually set the properties that have a next to them

Property Name	Example Value(s)	Description
dml.digitizer.defaultWAVdirectory	Z:\ \	The default directory to look for wav files in the audio digitizer panel
dml.digitizer.defaultCDdirectory	D:\ \	The default directory to look for a CD for track importation
dml.digitizer.defaultTIFFdirectory	Z:\ \	The default directory to look for tiff files in the score digitizer panel
dml.digitizer.warnOnEncode	true\|false	A dialog warning digitizers that encoding may take a long time

Cataloger Properties

Note that these properties are used by catalogers and digitizers since both need to access the Z39.50 server. These properties do not need to exist for end-users. These properties also need to be in place on the server (in conf/client/dml.conf) in order for bin/generateAccessPage.sh to work properly.

Location

Windows
- Digitizer & Cataloger: /Variations/Client/conf/client/dml.conf
Mac
- Mac does not currently support digitizer properties

Modification Instruction

Manually set the properties that have a next to them

Property Name	Example Value(s)	Description
dml.z3950.Contributor.enabled	true\|false	Enable Z39.50 Searches on Contibutor records
dml.z3950.Contributor.host	es07.uits.indiana.edu	Hostname for Contributor Z39.50 searches
dml.z3950.Contributor.port	12202	Port for Contributor Z39.50 searches
dml.z3950.Contributor.database	AWRD	Database for Contributor Z39.50 searches
dml.z3950.Contributor.field.x.name	any	Field to search on in Z39.50 (x can be within 0 to 4)
dml.z3950.Contributor.field.x.label	Contributor Name	Label to be displayed in search window for this field
dml.z3950.Contributor.field.x.example	(For example, Beethoven, Bach Sebastian)	Example to be displayed in search window for this field
dml.z3950.Container.enabled	true\|false	Enable Z39.50 Searches on Container records
dml.z3950.Container.host	opac.example.edu	Hostname for Container Z39.50 searches
dml.z3950.Container.port	210	Port for Container Z39.50 searches
dml.z3950.Container.database	INNOPAC	Database for Container Z39.50 searches
dml.z3950.Container.field.id.name	12	Field to search on in Z39.50 for a unique id (when non-empty search only on this field)
dml.z3950.Container.field.id.label	Variations ID*	Label to be displayed in search window for this field
dml.z3950.Container.field.id.example	(e.g., B1234567)	Example to be displayed in search window for this field
dml.z3950.Container.field.x.name	author	Field to search on in Z39.50 (x can be within 1 to 4)
dml.z3950.Container.field.x.label	Author	Label to be displayed in search window for this field
dml.z3950.Container.field.x.example	(e.g., Beethoven, Bach)	Example to be displayed in search window for this field
dml.z3950.Work.enabled	true\|false	Enable Z39.50 Searches on Work records
dml.z3950.Work.host	es07.uits.indiana.edu	Hostname for Work Z39.50 searches
dml.z3950.Work.port	12202	Port for Work Z39.50 searches
dml.z3950.Work.database	AWRD	Database for Work Z39.50 searches
dml.z3950.Work.field.x.name	author	Field to search on in Z39.50 (x can be within 0 to 4)
dml.z3950.Work.field.x.label	Author	Label to be displayed in search window for this field
dml.z3950.Work.field.x.example	(e.g., Beethoven, Bach)	Example to be displayed in search window for this field

Logging

Location

Windows
- /Variations/Client/conf/client/client_file.lcf
- /Variations/Client/conf/client/client_console.lcf
Mac
- End User: /Variations.app/Contents/Resources/Java/conf/client/client_file.lcf
- End User: /Variations.app/Contents/Resources/Java/conf/client/client_console.lcf

Modification Instructions
In both client_console.lcf and client_file.lcf, the RemoteHost property should be set to your Variations server:

log4j.appender.loggingServer.RemoteHost=example.example.edu

Readme and Other Files

Below is a list of text and xml files that can be quickly customized for an institution. Manually set the properties that have a next to them.

Legal Notices

Location
- Windows
  - /Variations/Client/data/legal_notices.html
- Mac
  - /Variations.app/Contents/Resources/Java/data/legal_notices.html
  - /Terms-of-Use.html

Customization
- Customize the Terms of Use section to match your institution's policies

Version Information
Clients have their version numbers stored in VERSION. When attempting to connect to a Variations server, a client will check to make sure that their version number appears in those supported. Servers store the client versions that they support and updates to the version number of a client should be coordinated with the server. A restart of the Variations server is required to pick up on changes to the supported versions file.

Location
- On the Server at: conf/server/versions/LibraryName.versions
- Version Number File found at: Variations/Client/VERSION
Customization
- Update the list of acceptable version numbers on the server to include the the version of the client you are installing
- Restart the Server

About Variations Information
All lines in this file are read and displayed on the splash screen as well as in About Variations

Location
- Windows
  - Variations/Client/COPYING
- Mac
  - Variations.app/Contents/Resources/Java/COPYING
Customization
- You do not need to modify this file

Read Me file
The Read Me file contains general information about Variations and will be displayed after installation.

Location
- Windows
  - Variations/readme.rtf
- Mac
  - Important-Installation-Instructions.html
Customization
- Read Through the file and edit where necessary
- Be sure to update the user guide and support links

Example files can be found in data/, data/annotation, data/playlists, and data/timeline.

Client Branding

Currently the Variations team does not support the branding of the Variations client. If you wish to try branding the client for your institution please review the files below. Please contact the Variations team with any questions or difficulties concerning the branding elements.

Branding Elements:

Splash Screen
Icon
Graphics
Search XSLT

SplashScreen, Icons, and Graphics
- Location
  - Resources

Search XSLT Files
- Customization Instructions
  - Customization can be done by replacing any of these files with one of the same type and dimensions or editing the original ones.
- Location
  - data/admin
  - data/bookmark
  - data/search
  - data/timeline
- Modification Instructions
  - These files do not need to be modified. If you are interested in changing these files please contact the Variations team for more information.

Digitizer Tools

The digitizer tools are used by digitizers to encode and ingest scores and audio into the server. These tools will be linked automatically with the digitizer installation (which you will build in the next step). Please visit the pages linked below and configure the tools for you institutions needs.

Next Steps

After you have completed the client configuration process, you can being building the installer at Building the Client Installer - 6.0.

Configuring the Client

Overview

Contents

Download Application & Configuration Files

Windows

Mac OSX

Configure Client

Windows & Mac

Properties in dml.conf

Digitizer-Cataloger and End User Properties

Login/Authentication Properties

Client Properties

Digitizer Properties

Cataloger Properties

Logging

Readme and Other Files

Client Branding

Digitizer Tools

Next Steps