Integrating refbase into your web site

From refbase

This page describes how to integrate refbase into an existing web site, and how to dynamically include refbase results into other sites.

Contents

Integrating refbase into an existing web site

Skins

refbase does not feature a formal skin/template mechanism (yet). However, one can go a long way by editing the refbase CSS and header/footer files. refbase-0.9.5 and above feature many CSS hooks that should allow you to easily change the appearance of the program.

Alternative skins that have already been developed are available in the contrib/skins directory. You can replace your includes/header.inc.php and includes/footer.inc.php files with these. You may also need to copy files to the css directory. Please see the 'README' files within the contrib/skins directory for more information.

MediaWiki

refbase ships with a MonoBook skin for integration with MediaWiki. See the contrib/skins/mediawiki-monobook directory for more information. An installation of refbase that uses this skin is the Northwestern University Center for Atom-Probe Tomography: http://arc.nucapt.northwestern.edu/refbase/

In the contribs/mediawiki directory, there is also a refbase extension for MediaWiki to more easily include reference information from refbase in a wiki page. The refbase MediaWiki extension allows you to place a serial number within markup tags such as:

<refbase>12</refbase>

Metadata for the reference is retrieved from refbase and marked-up according to a MediaWiki citation template.

WordPress

If you'd like to embed refbase results within a WordPress blog post or the WordPress sidebar, the easiest method may be to use one of the WordPress iframe plugins. See also the description for IFRAME below.

Including refbase results into other sites

refbase-0.9.5 or greater allows you to dynamically include results from an online refbase database into other web pages. The sections below describe different implementation methods. All methods make use of the refbase show.php API. More info about the show.php API is available here and here.

IFRAME

Using an HTML <iframe> is probably the easiest method to dynamically include results from a refbase database into another web site. This allows for browsing of results and other refbase features such as changing views & display options, searching within results, or exporting of records. A life example can be seen here. Note that this dummy page is just a static HTML page and it could be located everywhere on the internet, i.e. it does not need to be located in the refbase script directory.

If you check out the HTML source of that example page, you'll see the refbase IFRAME at the very bottom of the HTML code:

<div style="position: absolute; top: 300px; width: 95%;">
    <script language="JavaScript" type="text/javascript">
        function iFrameHeight(id) {
            var e = document.getElementById(id);
            var h = 0;
            if (!document.all) {
                h = e.contentDocument.height;
                e.style.height = h + 60 + 'px';
            } else if (document.all) {
                h = document.frames(id).document.body.scrollHeight;
                document.all.frames(id).style.height = h + 20 + 'px';
            }
        }
    </script>
    <h2 align="left">Recent Publications:</h2>
    <iframe id="refbase-citations" name="refbase-citations" onload="iFrameHeight('refbase-citations')" align="top" width="100%" height="100%" scrolling="auto" frameborder="0" src="http://beta.refbase.net/show.php?author=thomas,%20d%2En%2E&amp;without=dups&amp;submit=Cite&amp;citeOrder=year&amp;client=inc-refbase-1%2E0&amp;showLinks=1&amp;showRows=5" width="100%" height="500">
        <p><a href="http://beta.refbase.net/show.php?author=thomas,%20d%2En%2E&amp;without=dups&amp;submit=Cite&amp;citeOrder=year&amp;client=inc-refbase-1%2E0&amp;showLinks=1&amp;showRows=5">view references</a></p>
    </iframe>
</div>

In the above HTML code, the JavaScript (given in <script>...</script>) could be left out but it helps to adjust the height of the iframe to its actual content. The enclosing <div>...</div> tags are used to position the IFRAME on the page. You'll likely want to adopt this to your needs.

The IFRAME takes a regular show.php URL as (URL-encoded) source URL but includes the client parameter with "inc-refbase-1.0" as its value. This is the trigger that causes refbase to return a stripped-down HTML page which only includes the search results forms, browse links and the actual results. It also ensures that external links and links to individual records are displayed in a new browser window/tab. Here's the full URL (decoded for clarity reasons), try it out:

show.php?author=thomas, d.n.&without=dups&submit=Cite&citeOrder=year&client=inc-refbase-1.0&showLinks=1&showRows=5

AJAX

This method allows to include refbase results via an AJAX-style JavaScript. Simple examples can be seen here and here, and a real-world example is available here (for the latter, click the "Recent Publications" link in the navigation bar). As you can see from these examples, this JavaScript method allows to highlight selected parts of the citation (e.g. particular authors) in bold face.

The examples make use of the refbase javascript/show.js script to asynchronously query a refbase database and embed the returned results within the HTML page upon page load.

Check out the HTML source of the two simple examples (linked above). Both examples contain HTML forms that call the refbase showRefs() JavaScript function to generate & send a show.php query based on the form elements chosen by the user. Upon success, found results are written back to the web page. Both examples show slightly different ways of accomplishing the same thing. Btw, the second example will degrade gracefully if JavaScript isn't available and also shows what happens if nothing was found (e.g. try author "D. Piepenburg").

In addition to the client=inc-refbase-1.0 parameter, this JavaScript method requires the wrapResults=0 parameter to be present in the show.php URL. This causes refbase to output only a partial document structure containing solely the search results.

Here's the full URL that the JavaScript function generates (for author "D.N. Thomas" and contribution_id "refbase"). Note that the HTML source now only contains the results table holding the citations and links:

show.php?client=inc-refbase-1.0&wrapResults=0&submit=Cite&citeOrder=year&citeStyle=APA&showLinks=1&showRows=100&startRecord=1&without=dups&contribution_id=refbase&author=thomas, d.n.

Of course, you can tweak the usual show.php URL parameters to change the appearance of the results list. You can also leave out particular parameters, in which case refbase will use its global defaults (defined in initialize/ini.inc.php).

Here's a simple example that omits the links column (showLinks=0) and uses <div> tags in combination with CSS classes to allow for easy styling (viewType=Mobile):

show.php?client=inc-refbase-1.0&wrapResults=0&submit=Cite&showLinks=0&viewType=Mobile&without=dups&author=thomas, d.n.

Custom script

If you don't want to use any of the above methods, and you're using a high-level scripting language (such as PHP, Perl, Python or Ruby) to generate your web pages, you could always fetch results directly from within your script code, and include the returned HTML bits when serving your web page.

A nice real-world example of this method can be seen here. As another example, the refbase main page (index.php) uses function fetchDataFromURL() to fetch the five most recently added publications (as formatted citations), and includes them into the web page. Here's the appropriate show.php request:

show.php?client=inc-refbase-1.0&wrapResults=0&submit=Cite&citeOrder=creation-date&showRows=5&records=all

As before, you need to include the client=inc-refbase-1.0 and wrapResults=0 parameters in the show.php URL so that refbase will only return partial HTML in response to your script's request.

APIs and tools

This section lists other APIs and clients/tools that may be used to integrate refbase data within your web site or work flow. Direct access to refbase data via standardized APIs may be useful if you need full control over the presentation of the data, or if you want to post-process the data before including them elsewhere.

  • If you know the permanent identifier for a record in the refbase database, the unAPI service gives you quick access to the record(s) in various export and citation formats.
  • The OpenSearch service let's you search refbase via a standardized search syntax (CQL) & retrieve results as Atom XML, HTML, RSS, SRW_DC XML or SRW_MODS XML. The refbase OpenSearch service can also return search suggestions for a given query.
  • The SRU/W web service is another standard search/retrieve service that supports CQL searches and outputs SRW_DC XML or SRW_MODS XML.
  • The 'refbase' command line client offers a shell interface to the refbase show.php API and implements some useful functionality on top of it.
  • The Biblio::Refbase Perl module implements an object-oriented interface to the refbase show.php API that can be used from within your own Perl scripts.


Let us know if you have further questions.