@orbis-cascade/primo-explore-external-search

    1.2.0 • Public • Published

    primo-explore-external-search

    Build Status npm

    Features

    A facet is added to the top of the sidebar with options for transferring the user's search to an external target, such as WorldCat or Google Scholar. The options can be configured with custom text, images, and functions to translate Primo's search query into the target's query syntax.

    Screenshot

    screenshot

    Install

    1. Make sure you've installed and configured primo-explore-devenv.
    2. Navigate to your template/central package root directory. For example:
      cd primo-explore/custom/MY_VIEW_ID
      
    3. If you do not already have a package.json file in this directory, create one:
      npm init -y
      
    4. Install this package:
      npm install primo-explore-external-search --save-dev
      

    Usage

    Once this package is installed, add externalSearch as a dependency for your custom module definition.

    var app = angular.module('viewCustom', ['externalSearch'])

    Note: If you're using the --browserify build option, you will need to first import the module with:

    import 'primo-explore-external-search';

    You can configure the options available by passing an array of search target objects. Each object needs five properties:

    param type usage
    name string the name to display for the target
    url string (url) the base URL to which a Primo query transformed by mapping() will be appended
    img string (url) a URL to an icon representing the target
    alt string provide alternative text of images for screen readers
    mapping function a function to translate Primo queries and filters to the target's syntax. will receive an array of queries and an array of filters.

    Mappings

    A mapping function will always be passed an array of queries (e.g. 'any,contains,dogs') and filters (e.g. 'pfilter,exact,articles'). For an advanced search, these will also contain an operator such as AND or OR. The example below is the structure from an advanced search where any field contains 'dogs' and the author field starts with 'me' and the material type is set to 'articles'.

    queries = [
        'any,contains,dogs,AND',
        'creator,begins_with,me,AND'
    ]
    filters = [
        'pfilter,exact,articles,AND'
    ]

    It is up to the mapping function to parse these arrays and take action with them. Ultimately, the function should return a value, which will be appended to the end of the url property. One approach, as in the example below, is to match parts of the queries and filters to lookup tables using split(). If the mapping function is particularly complex, it may be prudent to use try/catch and return an empty string if the function fails, so that the user is at least redirected to the target page rather than taking no action at all.

    Example

    The example below adds options for WorldCat Discovery (for an example institution my.library) and Google Scholar.

    app.value('searchTargets', [{
        "name": "Worldcat",
        "url": "https://my.library.on.worldcat.org/search?",
        "img": "https://cdn.rawgit.com/alliance-pcsg/primo-explore-worldcat-button/7ee112df/img/worldcat-logo.png",
        "alt": "Worldcat Logo",
        mapping: function (queries, filters) {
          const query_mappings = {
            'any': 'kw',
            'title': 'ti',
            'creator': 'au',
            'subject': 'su',
            'isbn': 'bn',
            'issn': 'n2'
          }
          try {
            return 'queryString=' + queries.map(part => {
              let terms = part.split(',')
              let type = query_mappings[terms[0]] || 'kw'
              let string = terms[2] || ''
              let join = terms[3] || ''
              return type + ':' + string + ' ' + join + ' '
            }).join('')
          }
          catch (e) {
            return ''
          }
        }
      },
      {
        "name": "Google Scholar",
        "url": "https://scholar.google.com/scholar?q=",
        "img": "https://upload.wikimedia.org/wikipedia/commons/thumb/5/53/Google_%22G%22_Logo.svg/200px-Google_%22G%22_Logo.svg.png",
        "alt": "Google Scholar Logo",
        mapping: function (queries, filters) {
          try {
            return queries.map(part => part.split(",")[2] || "").join(' ')
          }
          catch (e) {
            return ''
          }
        }
      }
    ])

    Running tests

    1. Clone the repo
    2. Run npm install
    3. Run npm test

    Install

    npm i @orbis-cascade/primo-explore-external-search

    DownloadsWeekly Downloads

    25

    Version

    1.2.0

    License

    MIT

    Unpacked Size

    48.1 kB

    Total Files

    12

    Last publish

    Collaborators

    • kveldhui
    • eoulib
    • bryan_v
    • budak
    • jeremy2443