The citations helper in Sakai's Resources tool lets users search external indexes of resources and import citations into a special type of resource called a Citation List. When using the citations helper, people will see a screen that offers various ways to add citations. Here's an example:
Most users will see these three buttons (""Search Google Scholar", "Create New Citation" and "Import Citations") and possibly others, especially for searching databases provided by a university's library. In the past, the additional sources had to be supported by special code included in the Sakai release used by the university, and then details of its configuration had to be added after the Sakai code was deployed and the Sakai instance was started up. This becomes a little more flexible in Sakai 2.9, but it also means that the strings needed for i18n of the citations helper might change while sakai is running.
Search sources that can be plugged into the citations helper are configured in an XML file that is uploaded into the citations-admin site of a running instance of Sakai. We'll refer to that file as "config.xml" below. The way the citations helper works can be changed on the fly by uploading a new version of that file.
As of Sakai 2.9, the config.xml file may include an XML element similar to the following:
<map id="saveciteClients">
<entry>
<string>en</string>
<list>
<map>
<entry><string>id</string><string>google-search</string></entry>
<entry><string>searchurl_base</string><string>http://scholar.google.com/schhp</string></entry>
<entry><string>linkurl_id</string><string>default</string></entry>
<entry><string>searchurl_label</string><string>Search Google Scholar</string></entry>
<entry><string>searchurl_description</string><string>Search worldwide database of scholarly resources and save search results to
this citation list.</string></entry>
<entry><string>return_label</string><string>Back to Google Scholar</string></entry>
<entry><string>close_label</string><string>Close Window</string></entry>
<entry><string>window_width</string><string>1080</string></entry>
<entry><string>window_height</string><string>720</string></entry>
</map>
</list>
</entry>
<entry>
<string>es</string>
<list>
<map>
<entry><string>id</string><string>google-search</string></entry>
<entry><string>searchurl_base</string><string>http://scholar.google.com/schhp</string></entry>
<entry><string>linkurl_id</string><string>default</string></entry>
<entry><string>searchurl_label</string><string>Buscar en Google Académico</string></entry>
<entry><string>searchurl_description</string><string>Buscar base de datos mundial de recursos académicos y guardar los resultados
de búsqueda a esta lista de citas.</string></entry>
<entry><string>return_label</string><string>Volver a Google Académico</string></entry>
<entry><string>close_label</string><string>Cerrar la ventana</string></entry>
<entry><string>window_width</string><string>1080</string></entry>
<entry><string>window_height</string><string>720</string></entry>
</map>
</list>
</entry>
</map>
This example has two main entries. The first defines the list of search sources that will be shown in English, and the second defines the search sources that will be shown in Spanish. In this case, each list (Spanish and English) includes just one element, which configures the way Google Scholar will be shown for users in English and Spanish locales. Real Sakai installations might add one or more other entries in each list to define other search sources that users can access through the citations helper. Those additional entries should include all of the entries shown above, but with values appropriate to that search source. For example, if you are adding an entry to search databases through the university's library, you would add another "map" tag to each of the list elements. Within the new map tag in the English list, the "searchurl_label" entry might look like this:
<entry><string>searchurl_label</string><string>Search Library Resources</string></entry>
And "searchurl_label" entry in the Spanish list might look like this:
<entry><string>searchurl_label</string><string>Buscar recursos de la biblioteca</string></entry>
Most of the values of the entries will be translations of strings that are to appear in the user interface, but there may also be some configuration values in these entries that differ with the locale. For example, the value of the "searchurl_base" entry indicates the URL of the database to be searched. In an ideal early-21st Century world, that URL might include a reference to the locale of the page being requested, so those values may vary. Also the value of the "linkurl_id" entry specifies a string replacement for the branding of the sakai instance that is to be done in the vendor's search results (i.e. replacing "Sakai" with a different name in the label "Import into Sakai"). If you want the vendor to use a different string replacement based on locale, you would register different values with the Sakaibrary volunteers (sakaibrary@umich.edu) and then specify the appropriate value for linkurl_id here.
Here is a list of the entries and their purpose:
- id, where the value is an identifer that is unique within this list of clients (i.e. within the list of clients defined for the current locale.
- searchurl_base - The base URL used to access the search source. This should NOT include a separator ('?') or any request parameters. One or two query parameters will be added to the base URL - linkurl_base and linkurl_id. The value of the linkurl_base will be the URL for the savecite servlet in this sakai instance (See org.sakaiproject.citation.api.SearchManager.getSaveciteUrl(String, String)). The linkurl_id, if provided, is an identifer used by the search source to identify this sakai instance.</li>
- linkurl_id - A short string that, if present, is included as the value for the "linkurl_id" query parameter as described above.
- searchurl_label - A short string that will be used as the label on the button that launches a search in the search source.
- searchurl_description - A description of the search to help users choose which search to use.
- <li>return_label - The label that will appear on a button in the confirmation dialog that users will see after saving a citation from search results. This button takes the user back to the search results in the same window.
- close_label - The label that will appear on a button in the confirmation dialog seen by users after saving a citation from the search results. This button closes the window in which the search results were shown, effectively returning the user to the "add citation" dialog in the main window.
- window_width - the width in pixels of the dialog in which the search source will be shown.
- window_height - the height in pixels of the dialog in which the search source will be shown.
More documentation of the configuration of the citations helper is in the Citations Helper pages of confluence.