Configuring refbase

This document presents some tips how to configure your refbase installation:

The refbase admin has a variety of options to configure or customize refbase. Some of them are listed in this article. If you don't find the desired option, please refer to file initialize/ini.inc.php within your refbase installation. This configuration file contains many global settings which are not accessible via the refbase web interface:

• initial database settings (database name, admin email, database URL, character set, etc)
• default user settings when a new user is created
• visibility of files (e.g., .pdf files)
• important settings for file upload (file renaming, directory creation, etc)
• appearance of links within refbase
• server settings for link resolvers (OpenURL, ISBN)
• rich text formatting (e.g., greek letters, italic or superscript/subscript text)

The configuration file initialize/ini.inc.php is well commented, therefore you will find much more information in this file.

Below you can find answers to some frequently asked questions about configuring refbase.

How can I change the logo?

You can change the main logo image that's displayed in the refbase page header by setting variable $logoImageURL in initialize/ini.inc.php to the path of your logo file. In addition, please be sure to set the variables $logoImageWidth and $logoImageHeight to the dimensions of your logo. You may also be interested to specify your own paths for the smaller logos ($logoSmallImageURL and $faviconImageURL).

How can I setup refbase so that users can register themselves?

By default, only the admin is allowed to setup new user accounts. Here's how to setup your refbase installation such that users can automatically register themselves:

In initialize/ini.inc.php set the $addNewUsers variable to "everyone". Then, provide a link on the main page to user_details.php where users can use the provided form to register themselves.

Just set the $addNewUsers variable back to "admin" if you want to prevent other users from messing with your users table.

How can I change the default number of records shown?

You can change the default number of records that is returned by any (web, RSS or SRU) query by changing the value of the $defaultNumberOfRecords variable in initialize/ini.inc.php.

How can I change the default language?

You can change the language that's displayed by default in file intialize/ini.inc.php within your refbase root directory. Search for this paragraph:

// The default language selection, can be overwritten by userdefined language
$defaultLanguage = "de"; // e.g. "en", "de" or "fr"

and set the value of the $defaultLanguage variable to either "en" (English), "de" (German) or "fr" (French). In case of problems, please check that your desired default language is enabled within MySQL table languages.

Note that logged-in database users can switch to another language. This can be done by clicking the Options link when logged in.

How can I make some PDFs available to all users?

Ususally, access to PDFs should only be made available to logged-in users. This is controlled by variable $fileVisibility in initialize/ini.inc.php. However, often one wants to make a few PDFs available to all users. Variable $fileVisibilityException (also in initialize/ini.inc.php) can be used to specify a condition where attached files will be displayed to all users, no matter whether they're logged in or not.

By default, refbase will publicly display files for all records where the thesis field in table refs is not empty, i.e. if a thesis type has been specified for the record:

$fileVisibilityException = array("thesis", "/.+/");

If, instead, you'd like to allow public access to PDFs for arbitrary records, a common approach would be to put some unique string into one of the fields from table refs, and use this field & identifier string in variable $fileVisibilityException.†As an example, for all records where the attached PDF should be displayed publicly, you could add the string "author copyright" to the notes field. Then use the following pattern:

$fileVisibilityException = array("notes", "/author copyright/");

As another example, if you'd like to offer public access to all PDFs that where authored by a member of your institution, you could make use of the contribution_id field (more info), and specify this field and your institutional abbreviation in variable $fileVisibilityException. If your institutional abbreviation is, say, "NUCAPT", you'd use this pattern:

$fileVisibilityException = array("contribution_id", "/NUCAPT/");

How can I change options & permissions for everyone who's not logged in?

Setting options via the web interface

When logged in as admin, you can set options and access permissions for everyone who's not logged in by calling the script user_options.php with the userID=0 parameter:

user_options.php?userID=0

For all permissions that are set to off, the relevant interface elements will be hidden from the refbase GUI.

Note that some of the available user permissions require a user being logged in. I.e., enabling these options for anyone who isn't logged in won't have any effect. Following user permissions require a login:

• Add records
• Edit records
• Delete records
• File upload
• User groups
• User queries
• Import
• Batch import
• Modify options

If you want to allow users who are not logged in to query the refbase database via the SRU search/retrieve webservice, then either the Export or the Batch export user permission needs to be enabled. This will allow export of XML records via sru.php but won't allow a user who isn't logged in to export records via the web interface.

Setting options within ini.inc.php

If you like to change the permission to see/download files (e.g., .pdf files), you (the admin) can find the appropriate option in file initialize/ini.inc.php. The relevant variable is called $fileVisibility. You are able to allow file download for everyone, logged-in users only, or on a user-specific basis.

Additionally, you can set exceptions to this rule in variable $fileVisibilityException, which enables you to always allow download access to files that meet a particular criterion. A typical usage example would be to always grant download access to theses or papers that were written by members of your own institution.

For more details, please refer to the comments in ini.inc.php.

How can I change the default citation style?

You can use variable $defaultCiteStyle in file initialize/ini.in.php to change the citation style that's displayed by default in the web interface (Citation view) as well as for export of formatted citation lists to RTF, PDF, LaTeX, etc. The given style name must have a matching entry in the styles table of your refbase MySQL database.

Note that the admin can enable or disable particular citation styles individually for each user. And if desired, logged-in users can deselect some of the enabled styles in their user-specific options.

How can I change the names & order of citation styles?

Changing the names of citation styles

Here's how to change the names of citation styles displayed in the "Cite using style" drop-down (in the form below the query results list): Currently, you have to directly edit the styles MySQL table. E.g., to change the display name of the "Polar Biol" citation style to "Default" execute the following MySQL command from within your SQL command line interpreter:

UPDATE styles SET style_name = "Default" WHERE style_name = "Polar Biol";

Note that you must also change the corresponding names for the variables $defaultCiteStyle and $defaultUserStyles in initialize/ini.inc.php.

Changing the order of citation styles

Similar to the above, you can edit the styles MySQL table to change the order of citation styles displayed in the "Cite using style" drop-down menu. If, for example, you want to switch the order of the first two citation styles, execute the two commands below:

UPDATE styles SET order_by = "2" WHERE style_id = 1;
UPDATE styles SET order_by = "1" WHERE style_id = 2;

Note: this example assumes that you have table entries with style_id's of 1 and 2, otherwise adopt or use something like:

UPDATE styles SET order_by = "...(whatever)..." WHERE style_name = "...(whatever)..."

The order_by field is of type varchar(25), i.e., you can also use more fine grained values (such as "1a", "1b", etc).

How can I add or disable a particular citation style?

Adding a citation style

Currently, citation styles are written as a PHP function, so you'll need to know a bit of PHP to add your own style. The PHP function that outputs records in citation format is called citeRecord(). For each citation style, there's a separate file with a dedictated version of this function. These citation style files are located within the cite sub-directory of your refbase root directory.

To build your own style, you may want to have a look at the existing citation style files and modify one of them to suit your needs.

After you've created your own citation style, copy it into the cite sub-directory of your refbase root directory. Then, in order to add your citation style file to the "Cite using style" drop-down, execute the following MySQL command from within your SQL command line interpreter:

INSERT INTO styles VALUES (NULL, 'STYLENAME', 'true', 'STYLEFILE', '1', '1');

In the above MySQL command, replace STYLENAME with the actual name of your citation style. This name will appear in the "Cite using style" drop-down. Similarly, STYLEFILE must be replaced with the file name of your citation style file, prefixed with "styles/" (example: "styles/MyStyleFile.php"). In addition, you can change the first number ('1') in the above command to change the position at which your style name will be displayed in the drop-down. To see all available styles and confirm that your style has been successfully added to the styles MySQL table, execute this command:

SELECT * FROM styles;

Now, login as admin via the refbase web interface, click on "Manage Users" and activate your new style (using the "edit options" link) for all those users who shall see this style. If you've enabled/disabled any citation styles for the admin user, you'll have to logout and login again in order to see your changes.

Disabling a citation style

You can globally disable existing styles by setting the style_enabled field to "false". E.g., if you want to disable the "Polar Biol" citation style, execute:

UPDATE styles SET style_enabled = "false" WHERE style_name = "Polar Biol";

How to create a new citation style

Before we start this section, a comment in advance:

To improve refbase: If you have created a new citation style, we would be interested to offer this style for all refbase users. If possible, please

• post this new .php file to the community.
• include the journal title for you built the style with their website.

This section should contain information/hints for non-php professionals

Adapting existing work

Before investing energy in creating a new style, it is wise to check the refbase subversion repository for new styles that are under development but not yet included in the project release. Be aware that styles obtained from the bleeding edge branch are not necessarily in working condition, and even if they appear to work, may be unfit for a production environment.

How can I add a new interface language?

In order to add a new language (locale) to refbase, you need to perform these steps:

• Within the refbase locales/ directory, copy one of the existing subdirectories and rename it to the two-letter code of the language you'd like to add (e.g. "es" in case of Spanish).
• Within your new subdirectory, translate all lines in file common.inc into your language, and save a copy of this file with encoding "Unicode (UTF-8, no BOM)" to common_utf8.inc.
• Issue following MySQL command via sql_search.php when logged into refbase as admin:

INSERT INTO languages VALUES (NULL, 'LANGCODE', 'true', '4');

In the above MySQL command, replace LANGCODE with the two-letter code of your language, e.g. "es" for Spanish. In addition, you can change the last number ("4" in the above example) to alter the position at which your language name will be displayed in the language drop-down.

The new language option should now appear within the language drop-down in the refbase user options.

To see all currently available languages and to confirm that your language has been successfully added to the languages MySQL table, execute this command from within your MySQL command line interpreter (after you've selected the refbase MySQL database):

SELECT * FROM languages;

Please note that in refbase-0.9.0, not the entire interface is available for localization. We plan to finish internationalization until version 1.0.

If you've translated the refbase interface strings in common.inc into your own language, please send us this file so that we can include it with a future release of refbase.