Help and How-tos JCar Getting Started

Getting Started

J-CAR provides Joomla! users with the ability to search, browse and display items contained within a digital asset management system within a content management framework. Joomla! administrators, managers and authors can now build content rich sites which include meta data and assets from digital repositories, as well as FAQs, news feeds, blogs, tutorial and more. J-CAR uses open standards such as OAI-PMH, SRW/SRU and OpenSearch to filter and retrieve digital assets.

Prerequisites

As well as having a working Joomla! install, you will also need to have the following PHP extensions installed and configured;

  • PHP5 XSL

J-CAR is built for PHP5 or higher only.

Before you start

First of all, the process outlined uses the following examples (use your own to configure correctly);

  1. An OAI GetRecord verb uses the URL, http://dspace.wijiti.com/i/testing/oai/request?verb=GetRecord&metadataPrefix=mets&identifier=oai:dspace.wijiti.com:123456789/8
  2. 2. You are using SRW/SRU for searching and it is located at http://dspace.wijiti.com/srwu/testing/search/testing

Installation

The JCar extension suite contains a number of components, plugins and modules which each carry out different functions.

A full list of installation steps is provided below:

  • Install both the J-CAR component and J-CAR plugin,
  • Configure the J-CAR plugin by setting the following parameters;
    • OAI URL: http://dspace.wijiti.com/i/testing/oai
    • URN: dspace.wijiti.com
    • Prefix: 123456789
  • Install the J-CAR Search plug-in,
  • Configure the Search plug-in to use SRW/SRU (OpenSearch is much the same);
    • Search Engine: SRW/U
    • Search Engine URL: http://dspace.wijiti.com/srwu/testing/search/testing
    • URL Type: Internal via com_jcar
  • Install the J-CAR Related Subjects module

To install any of the JCar extensions, you will need to;

  • Download the package files from http://joomlacode.org/gf/project/j-car/frs/
  • Log into your Joomla! Site's administrator control panel (http://your.joomla.site/administrator),
  • Select Install/Uninstall from the Extensions top menu,
  • Use any one of the three installation options.

Below are step-by-step instructions for configuring each of the available J-CAR extensions;

J-CAR Component

Once you have installed the J-CAR component that's it. There is also the ability to customize the look-and-feel of the displayed items through the use of transformers. For more information, see “J-CAR Transformers”.

J-CAR Plugin

Once installed, you will need to configure the J-CAR plug-in to access your OAI-compatible repository.

Select Extensions->Plugin Manager from the administrator top menu, locate the plug-in name “Content - JCAR” and click on it.

Configure the following plug-in parameters (remembering to enable the plug-in once you have completed the parameter configuration);

OAI-PMH URL:

The URL you use to access OAI-PMH requests from your digital assets repository. If you are using DSpace, an example URL might be http://dspace.archive.tld/oai. Note that you do not need the ending forward-slash “/”.

OAI Identifier URN:

The URN portion of the OAI identifier. E.g. dspace.archive.tld

OAI Identifier Prefix:

The handle prefix portion of the OAI identifier. If you haven't configured a handle server, the default value, 123456789, should be sufficient

Transformer:

The transformer to use when rendering an OAI-compatible item. A transformer is specified in two parts; a transformer group and the transformation document, with each part separated by an underscore “_”. If the transformation document portion is not specified, default will be used.

Transformers available out-of-the-box are;

  • default (if you leave the Transformer parameter blank, J-CAR will default to this transformer)
  • default_simple
  • default_thumbnail

To find out more about customized transformers, see “J-CAR Transformers”.

J-CAR Editor Plugin

Joomla!'s content editor has a number of buttons located at the bottom of the editor area for embedding various plug-ins into an article.

The J-CAR Editor Plugin simply needs to be enabled to start working. Once enabled, create an article that you would like to embed an OAI-compatible item into, and click the “JCAR Item” button. You should see something like;

{jcar url=|urn=|prefix=|id=|transformer=}

To find out more about embedding the J-CAR plugin into an article, see “Article Content and J-CAR”

J-CAR Search Plugin

The J-CAR Search Plug-in provides search and filter capabilities using the Joomla! search functionality.

To configure the plug-in, select Extensions->Plugin Manager from the administrator top menu, locate the plug-in name “Search - JCAR” and click on it.

Configure the following plug-in parameters (remembering to enable the plug-in once you have completed the parameter configuration);

Search Engine:

The search engine you are using for querying your digital assets repository. Current options are SRW/SRU and Open Search.

Search Engine URL:

The URL of the remote search engine you selected above minus any query string parameters. See your search engine's documentation for more information about this URL.

URL Type:

The type of link to display in the results list. Available values are;

  • Internal via com_jcar: Links to com_jcar, displaying all your digital assets in the Joomla! site,
  • External, directly to archive: Links directly to the item in your digital asset repository,
  • External via the handle server: Links to the item by handle.

External Repository URL:

The URL of the repository to link to. Only specify this URL if you have selected the URL Type "External, directly to archive".

Search Area Label:

The label that appears in the search areas checkbox list on the search page.

J-CAR Related Subjects

Once installed and enabled, the J-CAR Related Subjects module does not require any further configuration. However, you may wish to position it on pages that are either; a) displaying an item embedded in an article using the J-CAR plug-in, or b) displaying an item via the J-CAR component. If not, the J-CAR Related Subjects module will have no associated item to retrieve a list of subjects from and will appear blank.

Article Content and J-CAR

You can use the J-CAR plug-in to embed OAI-compatible items from your digital repository straight into a Joomla! article.

To embed J-CAR;

  • Log into your Joomla! Administrator control panel,
  • Select Content->Article Manager from the top menu,
  • Create an article or edit an existing one,
  • Click on the JCAR Item button located at the bottom of the WYSIWYG editor, or type the following; {jcar url=|urn=|prefix=|id=|transformer=}

Once embedded, specify one or more the following plug-in parameters (see J-CAR Search Plugin for more information about each of the parameters):

url: (optional)

The URL you use to access OAI-PMH requests from your digital assets repository. E.g. http://dspace.archive.tld/oai

urn: (optional)

The URN portion of the OAI identifier. E.g. dspace.archive.tld

prefix: (optional)

The handle prefix portion of the OAI identifier. E.g. 123456789

id: (mandatory)

The id of the item you want to embed

transformer: (optional)

The transformer to use when rendering the item. Out-of-the-box values could be; default, default_simple, default_thumbnail.

NOTE: you do not need to specify all parameters when embedding the J-CAR plug-in as most of the parameters are retrieved from the J-CAR plug-in's global settings. Instead, use only those parameters you wish to override.

The minimum plug-in code required is {jcar id=} where is the embedded item identifier.

Enhancements

The way J-CAR renders digital assets and meta data on the screen can be enhanced and customized to better match your environment or site design.

If you have knowledge of XSL, XML and PHP, you can get a customized transformer up and running fairly quickly.

J-CAR Transformers

J-CAR uses XSL transformers to translate the OAI-PMH XML code into HTML that better matches the Joomla! look and feel.

Developing a Transformer

Transformers have a basic hierarchy that must be adhered to in order for the specified transformer to be loaded correctly. The minimum file system hierarchy looks like;

  • <transformer-group>
    • default.xsl.php
    • <transformation-document-1>.xsl.php
    • <trasformation-document-2>.xsl.php
    • <transformation-document-n>.xsl.php

You can have zero or more transformation documents provided there is at least the default.xsl.php.

Once you have developed your hierarchy, you can use the Joomla! API or straight PHP in your transformation documents to carry out any server-side processing before the XSL transformation takes place. Processing may include Mootools imports, additional JView processing and JText language translations.

Transformer Installation

Once you have your tranformer ready, simply copy it to the J-CAR component's transformers directory which is located at path/to/your/joomla/site/components/com_jcar/transformers.

Configuration

Lastly, to enable your new transformer, update the “Transformer” parameter in the J-CAR plug-in's parameter settings.

To load the default transformation document, simply specify <transformer-group>.

To load a transformation document other than the default, specify <transformer-group>_<transformation-document-n>.