Skip to content

Available global level parameters

Configuring blocks is about providing global level parameters. The parameters entrystore, namespaces, labelProperties, bundles, entitytypes and type2template will be detected when expressed on any top-level block (not when used within handlebar templates). The rest of the global level parameters have to be expressed in a config block or in the __entryscape_config expression like this:

<script>
  window.__entryscape_config = {
      some_parameter: "some value"
  }
</script>

For more options on how global level parameters can be expressed see the pages on parameters and syntax.

entrystore

The entrystore parameter tells which instance to connect to, exemplified above.

entrystore: "http://example.com/store"

page_language

Forces all blocks to render in a specific language, values should be a two letter ISO 639-1 language code like en.

routes

Provides a way to extract the parameters from the current URL by providing a set of routes. For example:

routes: [
  {
    regex: /^https:\/\/data.riksarkivet.se\/resource\/(\d+)_(\d+)$/,
    entry: 2,
    context: 1
  },
  {
    regex: /^https:\/\/data.riksarkivet.se\/tora\/(\w+)$/,
    entry: 1,
    context: "61"
  },
  {
    regex: /^https:\/\/data.riksarkivet.se\/id\/(\w+)$/,
    lookup: 1,
    lookupLiteral: 'dcterms:identifier'
  },
  {
    regex: /\/sv\/.*?.*uri=(.+)/,
    uri: 1,
    page_language: 'sv'
  },
  {
    regex: /\/sv\/.*?.*uri=(.+)/,
    uri: 1,
    page_language: 'en'
  }
],

In this example the first routes matches URLs containing both the entry id and context id separated via an underscore, note how the entry and context values are integers referring to the order of the regular expression capturing groups. The second route matches another set of URLs with a single entry id in it and providing a fixed context, this is done by providing a string for the context parameter in the route. In the third route the entry is detected via a lookup procedure using dcterms:identifier. The two last route matches a query string for the uri parameter as well as provides an override for the page language. The uri parameter is used to look up entries by their resource URI.

You can read a bit more about the various parameters in the routes in the how to specify an entry section.

context

Restricts all blocks (unless overridden) to make all requests in the entrystore instance within the specified context. An individual context may be given or an array of multiple contexts. A context is indicated via its context id, in most cases this is a number provided as a string.

context: "3"

Note: if you do not want to restrict all blocks to this/these contexts you have to provide it per context instead, most blocks that work with entries accept this parameter.

entry

A specific entry can be indicated on the global level, however, in most situations this only makes sense as a fallback for testing. If so, the entry is indicated by providing the entry parameter in conjunction with the context parameter (the latter has a wider use as described above). Alternatively it is possible to provide the uri or the lookup parameter potentially in conjuction with parameters context, lookupURI or lookupLiteral, read more about how to use these parameters in the sections entry from parameters.

namespaces

This is an object that provides a mapping from the abbreviation to the full namespace. The mapping will be registered centrally and make it possible to express other parameters less verbose (both global and block level). For example:

"namespaces": {
    "ex": "http://example.com/"
}

Observe that a bunch of common namespaces are already registered like: rdf, rdfs, dc, dcterms, foaf, skos, dcat, xsd, ical, vcard, owl, wot, org, vs, gn, schema. You can look them up using prefix.cc.

labelProperties

To render an entry (or any resource in a RDF graph) there must be a way to construct a suitable label. For instance, for the text block this can be achieved by specifying the parameter property. Another possibility is to rely on the labelProperties fallback which provides a list of properties that are checked in order to construct a suitable label. The default labelProperties looks like:

    [
      "foaf:name",
      ["foaf:firstName", "foaf:lastName"],
      ["foaf:givenName", "foaf:familyName"],
      "vcard:fn",
      "skos:prefLabel",
      "dcterms:title",
      "dc:title",
      "rdfs:label",
      "skos:altLabel",
      "vcard:hasEmail"
    ] 

bundles

In addition to the RDForms template bundles provided by default in blocks (includes support for dcat, dcterms, foaf) you can indicate additional template bundles to be loaded like this:

"bundles": [
   "https://example.com/my/template/bundle.js"
],

collections

For more advanced search there is a need for facets and filters to work, this is achieved by defining collections. The collection parameter is quite advanced with many options and demands its own section.

clicks

This is a global level parameter that is used for the link and multiSearch blocks to make it possible to make blocks extensions reusable for different organizations. See more documentation on the link block. Lets look at how two example clicks configurations affect the links from the following simple link block:

<div data-entryscape="link" data-entryscape-namedclick="art"></div>

Example with fragment identifiers to static html file

clicks: {
  artist: '/artist.html',
  art: '/art.html
}

the links will be expressed as:

http://some_domain.com/art.html?#esc_context=3&esc_entry=5

Example with parameters to routed sited

clicks: {
  artist: '/artist/${context}/${entry}',
  art: '/art/${context}/${entry}
},

the links will be expressed as:

http://some_domain.com/art/3/5

Note: the parametrized clicks should in most cases be used in conjunction with a route expression to allow detecting the correct entry on the target webpage (assuming it is also driven by blocks):

routes: [
  {
    regex: /art\/(\w+)\/(\w+)$/,
    context: 1,
    entry: 2,
  },
],

linkBehaviour

If linkBehaviour is explicitly set to "link" all metadata renderings will use links when encountering a related entity. If not set, a dialog will be utilized and an appropriate RDForms template will attempt to be detected via the type2template mapping below. The default is to use a dialog.

type2template

When using rdforms templates to show metadata it is sometimes neccessary to detect which template to use for an entity (RDF resource in an RDF graph). For this purpose it is possible to provide a mapping between type of the entity and which RDForms template to use:

"type2template": {
    "foaf:Agent": "idOfTemplateForAgent"
}

entitytypes

In some situations you need more complicated ways of matching entities to templates, e.g. when a simple type is not unique enough. In the following example both countries and continents are represented as gn:FeatureCode, but we can make the distinction based on the gn:featureCode property instead. For the country we need to capture a range of different featureCodes since they all correspond to countries in different legal states, this is done by providing an array for the property, it is interpreted as a disjunction (or:ed together) when searching. Since the simple map form cannot be used we use the entitytypes attribute instead like this:

"entitytypes" : {
  "country": {
    constraints: {
      "rdf:type": "gn:Feature",
      "gn:featureCode": [
         "gn:A.PCLD", "gn:A.PCLI","gn:A.PCLIX", "gn:A.PCLH", 
         "gn:A.TERR", "gn:A.PCLS", "gn:A.PCLF", "gn:A.PCL"]
    },
    template: "countryTemplateId",
  },
  "continent": {
    constraints: {
      "rdf:type": "gn:Feature",
      "gn:featureCode": ["gn:L.CONT"]
    },
    template: "continentTemplateId",
  },
}

Indicate that a value is a uri by surrounding it with < and >. Placing a ~ before the key will negate "~key": "value" => NOT key:value.

blocks

The blocks global level parameter is a way of introducing new blocks, in most cases by extending another, for instance the following defines a new block called name.

blocks: [
  {
     block: 'name',
     extends: 'text',
     content: '${foaf:givenName} ${foaf:familyName}'
  }
]

See more in the custom blocks section for how to define new blocks.

minimumSearchLength

By default the minimum search length in the Solr index of EntryStore is three, however, there are ways to bypass this limitation by using more verbose and more expensive queries (e.g. by using wildcards). Hence, switching to a shorter minimum search length should not be done without careful considerations of the performance impact.

query

By default the searchList uses the title field in the EntryStore solr index. This can be changed by the global level query paramer, here is an example of how it can look like:

query: {
  'metadata.predicate.literal_t.893797ba': 'term', // foaf:name
  'metadata.predicate.literal_t.3f2ae919': 'term',  // dcterms:title
},

This means we will only search for foaf:name and dcterms:title. So, if we are searching for "train" the query will be expanded to:

 metadata.predicate.literal_t.893797ba:train+OR+
 related.metadata.predicate.literal_t.893797ba:train

See the EntryStore solr index documentation on how the hashed solr fields are constructed. As a side note, here is how you can get the 8 character string for a specific property using bash:

> echo -n http://purl.org/dc/terms/title | md5sum | cut -c1-8
3f2ae919

Since we are using the literal_t in the search term we will match whole words but we will not get a match against a title (or foaf:name) "trainwreck". To achieve this we have to either remove the _t or instruct the query builder to append a wildcard. This is achieved by changing the term to a term+ in the query above. Now, by searching for "trai" will work and match both "train" and "trainwreck", however searching for "train" will only match "trainwreck". To solve this we give the query builder the value term*, which means that it will search for both "train" and "train*".

Now, it could be argued that it would be better to remove rely on the text_ngram option, i.e. to remove the _t from the literal_t expressions in the query above. In most cases this works just fine, however for longer or shorter queries this may not work as the default ngram length in EntryStore is 3 characters. So the approach above is useful when setting the global level parameter minimumSearchLength to 1 or 2.

Finally the expressions above also allow for boosting certain search fields by appending an integer like this:

query: {
  'metadata.predicate.literal_t.893797ba': 'term,10', // foaf:name
  'metadata.predicate.literal_t.3f2ae919': 'term,5',  // dcterms:title
},

Boosting is relevant when relying on the score based sorting (relevancy).

limitOptions

The user may want to control the number of returned results, this is achieved via the limit block. However, the options are defined on the global level like this:

limitOptions: [10, 20, 30],

Max limit is 100. The first number will be default for all list-blocks. To override set property limit on list.

sortOptions

The user may want to control the sort order, this is achieved via the sort block. However, the options are defined on the global level like this:

sortOptions: [
  {
    label: 'Relevancy',
    value: 'score+desc,modified+desc',
  },
  {
    label: 'Latest',
    value: 'modified+desc',
  },
  {
    label: 'Alfabetical',
    value: 'title.sv+desc',
  },
],

named

In some situations you have values that are URIs without there being a suitable label expressed in the metadata graph at hand. In these cases it is possible to provide a lookup table that provides names for URIs. For instance:

named: {
  'https://creativecommons.org/publicdomain/mark/1.0/': {
     en: 'Public Domain Mark 1.0'
  }
}

This lookup table is respected in multiple blocks like text, prop and facets. Se documentation on each block for more information.

jsonp

In many scenarios blocks will be included on webpages which have another domain than the EntryStore API. Henceforth, the browser will make cross domain requests which in modern browsers requires CORS to be enabled. This is something that may or not be enabled on your EntryStore API endpoint. Therefore, by default blocks uses jsonp call to make sure requests will go through. If you know for sure your EntryStore API endpoint has CORS enabled you can set the global level parameter jsonp to false.

filter

This global level parameter is used to complement the search in the list and searchList blocks. The parameter may either be a function being passed the solrQuery object from EntryStore.js to make custom tweaks or an object being passed to the or method of the same instance.

baseFilter

The base filter global level parameter allows for one or several values from collections to be preselected without being visible in the URL as parameters. The preselected values will be shown as selected facets, as selected values in searchFilter blocks, as values in a multiSearch block and will affect checked/unchecked state of the checkboxFilter. If a value is deselected it will appear in a negative manner in the URL.

baseFilter: {
    nameOfCollection: 'value'
}

forcePublicRequests

By default all solr queries sent to the EntrysStore API endpoint include the public:true setting. This means that any ACL checks are avoided even if the user happens to be authenticated to the EntryStore API. This behaviour is enforced by default to not fool developers thinking that the public read-only user interface somehow now shows protected information just because they happen to be signed in in another tab. The only case when it makes sense to set`forcePublicRequest to false is if you want to build a user interface for signed in users of EntryScape.

errorBlock

Blocks comes with two distinct solutions for presenting errors. The modal dialog and the error block. By default the modal dialog is activated. To supress the modal dialog and let an error block handle the errors instead you have to set the errorBlock global level parameter to true. (Unfortunately, automatically detecting the presence of an error block cannot be done in time to handle potential errors from other blocks, hence it has to be signalled explicitly on the global level.)