====== OpenURLs ======

VuFind® uses [[https://en.wikipedia.org/wiki/OpenURL|OpenURLs]] in two ways:

  * To embed [[https://en.wikipedia.org/wiki/COinS|COinS]] citations.
  * To connect to link resolvers.

===== Constructing OpenURLs =====

VuFind®'s OpenURL construction logic is controlled by [[development:plugins:record_drivers|record drivers]], so it is possible to build different OpenURLs in different contexts.

===== Configuring Link Resolvers =====

See the [OpenURL] section of [[.files:config.ini]] for the available settings for interacting with link resolvers. VuFind® can operate in a simple mode where OpenURLs are linked to an external link resolver, and it also supports an "embedded" mode for certain resolvers in which resolver results can be embedded directly into the VuFind® results. To support embedded mode for a new resolver, you can implement a custom [[development:plugins:link_resolver_drivers|link resolver driver]].

===== Configuring OpenURL Visibility =====

Sometimes it is only appropriate to display OpenURL links under specific circumstances.

There is a [[.files:config.ini]] setting to control which areas of VuFind® display OpenURL links.

Custom [[development:plugins:record_drivers|record driver]] code can be used to control whether or not specific types of records provide OpenURLs.

==== Defining OpenURL Rules ====

//Starting with VuFind® 2.5, there is also a JSON-based configuration file to set criteria for OpenURL visibility based on record attributes, allowing more configurability with less need for code customization.//

If you want to define that OpenURLs are only enabled for certain records you can do so by adding rules to ''$VUFIND_LOCAL_DIR/config/vufind/OpenUrlRules.json'' in [[http://www.w3schools.com/json/json_syntax.asp|json format]].

The JSON file consists of an array of one or more rulesets which are evaluated in order. If ANY ruleset indicates that an OpenURL should be displayed, it will be displayed -- in other words, the rulesets are combined with a Boolean OR, not a Boolean AND. In most common scenarios, only one ruleset is required.

A ruleset consists of an ''exclude'' and an ''include'' block defining which records should be enabled for OpenURL ("include") and which ones should be disabled ("exclude"). If no "include" block exists, OpenURLs are not enabled for any record; if no "exclude" block exists, OpenURLs are not disabled for any record. If an "include" block exists but does not contain any more specific rules, OpenURLs are enabled for every record; on the other hand if an "exclude" block exists without any further rules, OpenURLs are still NOT disabled.

Each "include" and "exclude" block consists of subrulesets defining record properties: at the time of writing only the properties ''recorddriver'' and ''methods'' are implemented, meaning that you can enable/disable OpenURLs for a record based on the record driver in use and/or on defined method return values. The "recorddriver" is defined as a ''key:value'' pair: the record driver named as given in value (full class name; inheritance accounted for). The "methods" are defined as "key:value" pairs as well, but the keys are interpreted as [[development:architecture:record_driver_method_master_list|record driver method names]] and the values are interpreted as return values for the given method.

To match any value but false (i.e. also empty strings) set value to ''*'' - this allows any record with the defined method returning anything but false. Defining any other value than "*" will have to match exactly -- if, for example, you specify an array, all values in the array must be matched by the record driver (no more, no less). However, if you want to add some fuzzyness to the matching rules you can use an array containing defined values plus "*" which will mean that every defined value must be matched but if more values are returned from the record driver this still counts as a match.

**The rules are being checked top-down, first match applies. exclude-rules are checked FIRST, include-rules are checked SECOND.**

Example:
<code>
[
  {
    "exclude":
    [
      {
        "recorddriver":"VuFind\RecordDriver\SolrDefault",
        "methods": {
            "getFormat:":"Journal"
        }
      }
    ],
    "include":
    [
      {
        "methods": {
            "getFormat":["Article", "*"]
        }
      }
    ]
  }
]
</code>

This will enable OpenURLs for every record that has at least the format "Article" except VuFind\RecordDriver\SolrDefault-Records with the format ''Journal''.

The default OpenUrlRules.json enables OpenURLs for any record returning anything but false for ''getCleanISSN'' (except for special case ''Pazpar2'' which must always return an OpenURL in order to allow linking):

<code>
[
  {
    "exclude" : [],
    "include" :
    [
      {
        "methods": {
            "getCleanISSN":"*"
        }
      },
      {
        "recorddriver":"VuFind\\RecordDriver\\Pazpar2"
      }
    ]
  }
]
</code>