Skip to content

Blocks reference

There are some parameters that applies to a lot of blocks and we avoid listing them per block to avoid clutter. There are basically three categories:

Entry dependant blocks - marked with entry dependant

Many blocks requires an entry to work as expected. To see which options that are available on how to provide the entry see the entries page.

Conditional visibility - marked with filter condition

Nearly all blocks can be hidden if a search filter is present or not. The available filters are defined in the global level parameter collections. The filtering is enabled by providing the if parameter. Like this:

<span data-entryscape="text"
      data-entryscape-if="collectionname==value"></span>.

Accessibility attributes - marked with aria support

Many of the blocks support parameters that provide accessability attributes, i.e. attributes like aria-label, aria-describedby, aria-live etc. The following table lists the parameters and how they translate to various aria attributes. Note that we also include the title attribute in this list for convenience.

parameter value translates to
title text title
label text aria-label
labelledby id aria-labelledby
describedby id aria-describedby
live text aria-live, the value should be one off, polite and assertive.

helloworld

This block does nothing more than print out the text "Hello world!" and is only used to make sure that the basics of blocks works in a specific setting.

text

entry dependant, filter condition

parameter value explanation
property RDF property Picks the value for the given property.
content string template Constructs a string from the string template that may contain variables, a variable should correspond to a property by being expressed via a namespace, e.g. foaf:name. The variables title and description are built in and corresponds to well known title and description properties. If multiple values exist for title and description the best are selected based on language preferences, all others are choosen arbitrary.
fallback handlebar template If there is no suitable value found (without content parameter) the fallback handlebar template is used. Can be a simple string like No value found to a more complicated handlebar template containing blocks, the current entry is passed. If the content parameter is provided the fallback must be a simple string and it will be used to replace variables that cannot be resolved.

text example 1 - no parameter The block can be used without any parameters, if so it tries to find a suitable label for the current entry by relying on the default label properties, see the global level labelProperties parameter for how to configure this.

<span data-entryscape="text"></span>

text example 2 - content parameter

The default behaviour can be overridden by providing the content parameter where anything looking like ${ns:prop} will be replaced with the corresponding value of the property (if it exists):

<span data-entryscape="text"
      data-entryscape-content="${vc:firstName} ${vc:lastName}"></span>

Note that unless the namespace is one of the well known it has to be declared in the global level namespaces parameter.

text example 3 - property parameter It possible to retrieve the value of a single property as well. The example also shows the use of a fallback value:

<span data-entryscape="text"
      data-entryscape-property="vc:firstName" data-entryscape-fallback="No name given"></span>

text example 4 - fallback can be a template Below we see how the fallback value is a template which can contain other blocks, in this case the text block again.

<span data-entryscape="text"
      data-entryscape-property="foaf:name" 
      data-entryscape-fallback='No name given for {{text property="foaf:mbox" }}'></span>

entry dependant, filter condition

parameter value explanation
click url The absolute or relative path to a webpage whereto the link should go. The current entry will be indicated by appending fragment parameters using the contextid and entryid unless the clickkey says otherwise. If the url contains the prefix esb: the rest of the url is a patterened url that will be constructed with help of the clickmask and expansion of variables, see example 6 nd 7 below.
namedclick string Similar to url, but reuses a click definition from the links global parameter.
property RDF property an alternative to click and namedclick. If given a link will be constructed from the value of the property in the metadata.
clickmask string Used together with the esb: prefix in click parameter (or in the global links parameter if namedclick is used) to extract part of the resourceURI. See example below.
clickkey string specifies another parameter to use when constructing the link, replacing the default usage of contextid and entryid. Must be used in conjunction with the clickvalue parameter to indicate which value should be provided for the key.
clickvalue RDF property indicates which property from the metadata graph to use as value for the clickkey. If "resource" is given it is interpreted to mean that the resoureURI of the entry should be used as value.
content text template If provided it allows controlling the name of the link in the same way as for the text block. A string is constructed by replacing variables in the template. A variable should correspond to a property by being expressed via a namespace, e.g. foaf:name. The variables title and description are built in and corresponds to well known title and description properties. If multiple values exist for title and description the best are selected based on language preferences, all others are choosen arbitrary.
fallback string Used together with the content parameter by providing a default value for variables that cannot be resolved.

Note: several of the examples below can be accomplished by using the template block, both example 4 and 5 falls in this category. However, the link block does come in handy when there is a special logic in how to insert fragment parameters or advanced construction of the link based on the resourceURI.

link example 1 - simple use of the click parameter

<span data-entryscape="link" data-entryscape-click="/otherpage"></span>

Remeber that the link to "/otherpage" will have page parameters referencing the current entry appended.

link example 2 - using a global click definition

<span data-entryscape="link" data-entryscape-namedclick="artist"></span>

Here the assumtion is that there is a global level click definition for the named click artist. The resulting link will be the same as if the click parameter where provided directly in this block.

link example 3 - using clickkey parameter

Sometimes you want to provide another kind of page parameters, for instance a filter to a search oriented page or provide the lookup of an entry via another identifier than the combination of contextid and entryid.

<span data-entryscape="link"
      data-entryscape-click="/otherpage"
      data-entryscape-clickkey='org'
      data-entryscape-clickvalue='dct:publisher'></span>

The resulting link will go to /otherpage with the fragment esc_org=publisherurl where publisherurl is discovered by taking the value of dct:publisher in the metadata.

link example 4 - link with the resourceURI as clickvalue

<span data-entryscape="link"
      data-entryscape-click="/otherpage"
      data-entryscape-clickkey='org'
      data-entryscape-clickvalue='resource'></span>

Similar to example 3, but the value is the resourceURI of the entry instead, i.e. the fragment will be esc_org=resourceURI.

link example 5 - link via property

<span data-entryscape="link"
      data-entryscape-property="rdf:seeAlso"
      data-entryscape-fallback="No link found"
      data-content="${label}"></span>

In this example the link is taken directly from the value of a specific property.

link example 6 - patterned link If you want to link to a certain url where the contextid and/or entryid is provided as part of the link, not inserted in the fragment.

<span data-entryscape="link"
      data-entryscape-click="esb:/artist{context}_{entry}"></span>

link example 7 - masked patterned link

<span data-entryscape="link"
      data-entryscape-click="esb:/artist/${1}"
      data-entryscape-clickmask="https://example.com/artist/(.*)"></span>

The clickmask always works against the resourceURI of the entry and extracts one or several values from it via regexp capturing groups (indicated with parantheses). The values can then be referenced (via the capturing group number) in the paterened url (provided in the click parameter).

date

entry dependant, filter condition

parameter value explanation
property RDF property may be an RDF property (namespaced or not) or one of the special values modified and issued, if nothing is provided modified is assumed.
format text a date formating option according to the moment library, uses the 'l' as default corresponding to a localized date.
tooltipformat text same as format but used for a tooltip, uses the 'LLLL' as default corresponding to a more explicit localized date an time expression.

multiSearch example 1 - modification date of an entry

<span data-entryscape="date"></span>

multiSearch example 2 - explicit date in metadata, only the year

<span data-entryscape="date"
      data-entryscape-property="dcterms:date"
      data-entrycape-format="YYYY"></span>

template

entry dependant (for some templates), filter condition

parameter value explanation
template handlebar template See the separate section on handlebar templates
class string adds a provided html class to the node where the template is inserted.
relation RDF property entry reachable via relation (requires entry given, see section on entries)
relationinverse RDF property entry inversely reachable via relation (requires entry given, see section on entries
rdftype RDF class entry will have to be instances of this class, may be array
constraints object use when the rdftype is not enough, the key value pairs corresponds to predicate value pairs. Indicate that a value is a uri by surrounding it with < and >. If the value is an array the members are combined as a disjunction (or:ed together). Add a ~ before the key to negate "~key":"value" => NOT key:value.
sortOrder string a sort order specified according to the Entrystore documentation on sorting

This block allows you to write handlebar templates which may contain:

  • Regular HTML
  • Build in handlebar directives
  • Entryscape Blocks extra handlebar directives like prop, eachprop, ifprop etc..
  • All the Entryscape Blocks (exposed as handlebar directives)

Note that if the template contains the use of blocks like text or link or the blocks-handlebar specific directives prop, ifProp, or eachProp it will require an entry to work. In that case, see the entries page for how to specify it.

template example 1 - simple template

<span data-entryscape="template"
      data-entryscape-template='{{#ifprop "dcterms:title"}}{{text}}{{/ifprop}}'></span>

template example 2 - collect multiple blocks in a template

<script type="text/x-entryscape-handlebar">
    Given name: {{prop foaf:firstName}}<br>
    {{ifprop foaf:givenName}}Family name: {{prop foaf:familyName}}{{/ifprop}}
    <hr>
    {{viewMetadata rdformsid="PersonOrGroup_RDFormsId"}}
</script>

Note that this example uses the special script syntax as it allows line breaks and makes the template simpler to read.

image

entry dependant

parameter value explanation
property RDF property the property to use for loading the image
fallback url a fixed URL to use as fallback if there is no value for the indicated property parameter
width number a width to set on the image
height number a height to sen on the image
alt string a text to show as alt text
altproperty RDF property let the alt value be drawn from the indicated property, if multiple values with different values exist only the most appropriate is shown
altcontent string template any values are expected to correspond to namespaced properties, alternatively the hardcoded title and description can be provided.

image example 1 - an image with a fallback and width

<span data-entryscape="image"
      data-entryscape-property="foaf:depiction"
      data-entryscape-fallback="http://example.com/empty_picture.png"
      data-entryscape-width="300px"></span>

slider

entry dependant

parameter value explanation
property RDF propery images are detected on the current entry via this property, if caption or captionTemplate are provided the values are loaded as entries.
src RDF property if entries are loaded based on the values in the property, the image is by default the resourceURI unless this src parameter is provided, in this case the image uri is detected via the src parameter in each loaded entry.
fallback uri if no images are found a fallback image is shown
headerTemplate handlebar template this header is rendered more at least one image are found
caption RDF property A caption is extracted from the metadata by using the value of the caption parameter as a property.
captionTemplate handlebar template in case the caption requires a combination of properties, then use the captionTemplate instead.

The slider block allows you to show multiple images in a slide-deck like canvas. The slide-deck is also possible to open into a lighbox like popup to provide a larger viewing area.

slider example 1 - images with captions and a fallback

    <div data-entryscape="slider" data-entryscape-property="schema:image"
         data-entryscape-caption="dc:rights"
         data-entryscape-fallback="http://example.com/empty_picture.png"></div>

view

entry dependant

Renders metadata of an entry with help of an RDForms template given by the parameter rdformsid (to avoid confusion with handlebar templates).

parameter value explanation
rdformsid string RDForms template id. If left empty, or the one given cannot be resolved an attempt will be made to find a template by inspecting the entrys metadata. More specifically, templates will be detected according to the global parameters type2template and entitypes. It is also possible to pass an array of ids of field level tamplates from which a larger form template will be constructed.
filterpredicates string or array Fields to exclude from the template as indicated by a comma separated list (or single value) of properties. This is very useful when you want to have special treatment of certain fields, e.g. have the dcterms:title in the title and not in the complete metadata view.
onecol boolean If set to true, fieldnames will be one row and the value beneth. The alternative (and default) is to have the first level fields on the same row as the fieldname to make the rendering more vertically compact.
twocolbreak number the breaking width where two column view are replaced with a single column, by default this is set to 400.
label boolean if set to false and the template being shown corresponds to a single field the label in front of the value will be suppressed.
showLanguage boolean if set to false all the language markers on free text fields will be suppressed
filterTranslations boolean filters all multilingual fields so that only the value with the most correct language will be shown. By default this is set to true.

view example 1 - relying on global template config

<span data-entryscape="view">

view example 2 - specifying the template

<span data-entryscape="view"
      data-entryscape-rdformsid="dcat:OnlyDataset"
      data-entryscape-filterpredicates="dcterms:title,dcterms:description"
      data-entryscape-onecol="true"></span>

In this example parts of the template is supressed by providing the predicates, also forcing a one column view.

view example 3 - constructing a template inline

<span data-entryscape="view"
      data-entryscape-rdformsid="foaf:givenName,foaf:familyName">

Note that the template in this example is constructed from ids of field-level templates not by identifying predicates. This can be confusing, especially when ids are named similar or even identical to the corresponding predicates like in this example.

list

Is entry dependant if the relation or relationinverse properties are specfied.

Renders a list of entries given a query. Here are all the parameters that list supports:

parameter value explanation
relation RDF property list entries reachable via relation (requires entry given, see section on entries), see also example below
relationinverse RDF property list entries inversely reachable via relation (requires entry given, see section on entries
limit number number of entries shown before list is paginated
rdftype RDF class entries in list will have to be instances of this class, may be array
constraints object use when the rdftype is not enough, the key value pairs corresponds to predicate value pairs. Indicate that a value is a uri by surrounding it with < and >. If the value is an array the members are combined as a disjunction (or:ed together). Add a ~ before the key to negate "~key":"value" => NOT key:value.
dependencyproperties RDF property see explanation below
rdformsid text RDForms template for showing each entry in the list, see example below
click url if provided makes each row clickable, clicking on the row will open the indicated url with the entry as parameter
clickExpand boolean if set to true clicking anywhere on the row will expand it, otherwise expand will be triggered by clicking at an arrow at the end of the row
expandButton boolean Controls if the expandbutton should be visible or not. By default the button will be visible if the rowexpand template is given or if an RDForms template is given via the rdformsid parameter, set to false to override this behaviour. The opposite is not true, you cannot force an expandbutton if there is nothing to show in the expanded section. To make a custom expand button / link, add the class esbExpandButton to the element that should respond to a click.
expandTooltip text Tooltip on arrow for expanding row
unexpandTooltip text Tooltip on arror for unexpanding row
listhead template shown at the top of the list if it is not empty
listplaceholder template shown if the list is empty
rowhead template rendered for each list result (entry)
rowexpand template rendered on expand for each row, if provided there will be an expand button at the end of each row
listbody template wrapper template for the rows, use the {{body}} directive to indicate where the list rows should go
randomize boolean if set to true the order of the search results will be randomized rather than shown according to the sorting order (default is latest).
sortOrder string a sort order specified according to the Entrystore documentation on sorting

List example 1 - persons in a certain context

Each person will be displayed using the default label, see the global labelProperties configuration. The amount of results are capped to 8, if there are more matching results there will be pagination.

<span data-entryscape="list"
      data-entryscape-context="1"
      data-entryscape-limit="8"
      data-entryscape-rdftype="foaf:Person"></span>

List example 2 - all persons X knows

If an entry (X) is given to the list, (e.g. via a page parameter, see section on entries) it is possible to trigger a search based on that entry by following a relation. The following example shows all people that a given person claim to know:

<span data-entryscape="list"
      data-entryscape-relation="foaf:knows"></span>

List example 3 - all persons knowing X

The people that claims to know the given person (X) can be listed via:

<span data-entryscape="list"
      data-entryscape-relationinverse="foaf:knows" ></span>

List example 4 - expandable list of persons

We can see the details of a row (entry) in the list by providing an rdforms template in the rdformsid parameter. This will make each row expandable and by default use the view block to render it on expand.

<span data-entryscape="list"
      data-entryscape-rdftype="foaf:Person"
      data-entryscape-rdformsid="rdformsTemplateIdForFoaf"
      data-entryscape-expand-tooltip="More information"
      data-entryscape-unexpand-tooltip="Less information"></span>

List example 5 - related entries in rowhead

Care has to be taken when writing rowhead templates to avoid causing too many requests, e.g. if you need to load additional entries per row. The following example shows how to render a list of documents with their creators and publisher visible directly in a clever way using the parameter dependencyproperties. In the example below we use the special handlebar type of script to avoid complicated escaping of the template.

<script type="text/x-entryscape-handlebar"
      data-entryscape-rdftype="foaf:Document"
      data-entryscape-dependencyproperties="dcterms:creator,dcterms:publisher"
      data-entryscape-limit="8">
  <h4>{{text}}</h4><br>
  Creator: {{text relation="dcterms:creator"}} <br>
  Publisher: {{text relation="dcterms:publisher"}}
</script>

The dependencyproperty causes the list to look through all the retrieved entries, follow the indicated properties and load all those related entries in one request before trying to render the list. It is best to use dependencyproperties parameter together with a conservative limit, otherwise we may end up with to large queries (100 search results with no overlapping dependencies would in this scenario cause a query of 200 entries).

List example 6 - custom expand button To make a custom expand button we need to have a list that allows each row to expand, here we do that by providing a RDForms template id, e.g. the rdformsid parameter. Second, we need to hide the default expand button, this is done by setting the parameter expandButton to false. Third and last, we need to add an element in the rowhead template that will act as button by adding the special class esbExpandButton.

<span data-entryscape="list"
      data-entryscape-rdftype="foaf:Person"
      data-entryscape-rdformsid="rdformsTemplateIdForFoaf"
      data-entryscape-expand-button="false"
      data-entryscape-rowhead="{{text}} <button class='esbExpandButton'>Expand</button>"></span>

When a row is expanded the class esbRowExpanded is added to the row, this is to allow specific styling on both the rowhead and the expanded section. For instance, this might be used to provide specific styling on buttons or even have two buttons and make sure only one is visible at a time, i.e. one for expanding and one for un-expanding the row.

searchList

The searchList block is a version of the list block that also accepts user interactions via other search enabled blocks. Supported parameters on searchList include all those listed on the list block in addition to the following:

parameter value explanation
facets boolean force requesting for facets when searching, neccessary if using with collections with type facet, see page on collections. That is, if not set to true there will be no numbers indicating how many results there are per facet.
visible boolean if set to false the list is deactivated. The purpose of this flag is to allow to allow several searchLists on the same page that can be switched between, e.g. list or icon mode. This is accomplished by letting the visible state be remote controlled via a click block that sends the searchList-open signal. The signal includes a value corresponding to the list name (given by the define parameter). If a signal is sent with a value that does not correspond to the name the searchList visible state is set to false.

The searchList maintains a page wide search filter that is also reflected in the page parameters, allowing a search to be bookmarked and also be revisited in a browser history. The search filter can range from a free text query to a quite complex expression combining multiple search criteria in a boolean expression. The expression is constructed by providing input in other blocks like facets, simpleSearch, multiSearch, searchFilter, clear or rangeSearch. See sections below for documentation and examples for how to use these blocks in combination with the searchList block. You should also read about how the global level parameter collections provides a central configuration mechanism for the filter.

There should only be one searchList block visible at a time per page (see parameter visible).

simpleSearch

Aria support

Provides a detached search field for a searchList that can be positioned anywhere on the page. The simpleSearch searches automatically on keypress (with a small delay) and is always used together with a searchList block. The simpleSearch block supports the following parameters:

parameter value explanation
search-button boolean if set to trye there will be a serch icon to the right of the input field
placeholder text the placeholder of the input field
collection text a collection that indicates that the simpleSearch is searching against a certain property

simpleSearch example 1 - default search

In the simplest case the simpleSearch uses the global query configuration (or its default setting).

<span data-entryscape="simpleSearch"
      data-entryscape-search-button="true"
      data-entryscape-placehoder="Search for..."></span>
<span data-entryscape="searchList" data-entryscape-rdftype="foaf:Person"></span>

simpleSearch example 2 - collection search

It is possible to force the simpleSearch block to search against a certain property. This is achieved by referring to a collection that provides the definition of that property, i.e. the property and wether it is a literal or a uri.

<span data-entryscape="simpleSearch"
      data-entryscape-collection="familyname"></span>
<span data-entryscape="searchList" data-entryscape-rdftype="foaf:Person"></span>

searchFilter

Aria support, filter condition

The searchFilter block allows you to choose values from a dropdown that helps narrow the search for entries shown in a searchList block. The values are drawn from a collection, i.e. they can be hardcoded, loaded as facets from a previous search, explicitly searched for or choices from a RDForms template.

parameter value explanation
placeholder text the placeholder of the input field
collection text a collection that indicates that the simpleSearch is searching against a certain property
width number set the width of the input field explicitly
allowEmptyOption boolean if true the dropdown will contain the empty value, this value is true by default
emptyLabel string if allowEmptyOption is true it is possible to provide a string that corresponds to the empty value, the default is the empty string
freeText boolean if true the user is allowed to do a free text search in addition to the exact matches provided in the dropdown.
freeTextTemplate string template if freeText is set to true a template can be provided that explains the free text search option, the default template is: Search for "${term}"
openOnFocus boolean if set to true the dropdown will open on focus rather than after some input have been provided. The default setting is false as it avoids the popup to show unneccassarily when using the keyboard to navigate the different input fields
invalidSearchFilter regexp regular expression (can be provided as text) to test if the query contains characters that are forbidden. The default regular expression looks like: [\^+\-[\]{}\\/!#~"]
invalidSearchMessage string if the query contains an unwanted character this message is displayed. The default message is: Search string not allowed to contain characters ^+-[]{}\\/!#"~.
matchStartOfWord boolean if set to true the query will match the options in the dropdown from the start of words only (not neccessarily the first word in an option).
limit number limits the number of options searched for when populating the dropdown.

searchFilter example 1 - filter documents based on publisher and topic

Two searchFilter blocks are used in combination with a searchList:

Publisher: <span data-entryscape="searchFilter"
                 data-entryscape-collection="publisher"></span><br>
Topic: <span data-entryscape="searchFilter" 
             data-entryscape-collection="topic"></span><br>
<span data-entryscape="searchList"></span>

Note that the searchFilter references two collections collections they could be defined like this in the global configuration:

collections: [
  {
    type: 'search',
    name: 'publisher',
    property: 'dcterms:publisher',
    nodetype: 'uri',
    rdftype: ['foaf:Agent', 'foaf:Organization', 'foaf:Person'],
  },
  {
    type: 'search',
    name: 'topic',
    property: 'dcterms:subject',
    nodetype: 'uri',
    rdftype: 'skos:Concept',
  }
]

rangeSearch

Aria support

The rangeSearch blocks allows range queries against metadata fields containing dates or integers.

parameter value explanation
collection text the collection containing information about which property the range query should use
pattern regexp a regular expression that allows restricting which values are valid to trigger the range query
to boolean if true the range query provides the upper bound of a range query
placeholder text text to show in input field when no value is yet provided

rangeSearch example 1 - date range query

 <label id="from">From:</label>
 <div data-entryscape="rangeSearch"
      data-entryscape-describedby="from"
      data-entryscape-collection="date"
      data-entryscape-placeholder="YYYY"
      data-entryscape-pattern="\\d\\d\\d\\d"></div>
 <label id="to">To:</label>
 <div data-entryscape="rangeSearch"
      data-entryscape-to="true"
      data-entryscape-describedby="to"
      data-entryscape-collection="date"
      data-entryscape-placeholder="YYYY"
      data-entryscape-pattern="\\d\\d\\d\\d"></div>

Where the corresponding collection is defined as:

collections: [
   {
      type: 'range',
      name: 'date',
      nodetype: 'date',
      property: 'xsd:date',
   }
]

checkboxFilter

The checkboxFilter blocks allows excluding entries with a specific property-value from the search results. The property, values, nodetype etc is specified in the collection. Giving the named collection for the checkboxFilter is mandatory. To include the filter in the query per default without the user clicking the checkbox use the global parameter baseFilter. If baseFilter is used and the checkboxType is add the checkbox will be checked on first load. If baseFilter is not used and the checkboxType is add the checkbox will be unchecked on first load.

parameter value explanation
collection string the collection containing information about which property the checkBox query should use
label string the visible label for the checkbox
checkboxType string should the checkbox add or remove the collection from the query. Possible values are add or remove. Default is add.
class string an optional class can be added to the checkbox and label element

checkboxFilter example

 <label></label>
 <div data-entryscape="checkboxFilter"
      data-entryscape-collection="title"
      data-entryscape-checkbox-type="add"
      data-entryscape-label="Exclude The Stand from results: "></div>

Where the corresponding collection is defined as:

collections: [
   {
      type: 'check',
      name: 'title',
      property: 'dcterms:title',
      nodetype: 'literal',
      values: "The Stand",
      modifier: 'not,

   }
]

multiSearch

Aria support

The multiSearch can be seen as a combination of the blocks simpleSearch and multiple searchFilter in a single input area. Typing a search term will trigger a dropdown where the first option (and default on enter) is to do a free text search. The rest of the dropdown contains filter options based on what is defined in the global collections configuration. The options are divided into sections in the dropdown corresponding to the collection they originate from, the number of options show per section is defined in the collection via the limit parameter.

The multiSearch block accepts the following parameters:

parameter value explanation
placeholder text the placeholder of the input field.
openOnFocus boolean opens dropdown on input field focus if true, otherwise opens after the user types something.
click text opens a new page rather than remote controlling a searchList.
namedclick text same as click, but look up exact page from global level parameter clicks.
include array or comma separated list of collectionnames to be searchable.
exclude array or comma separated list of collectionnames to exclude when searching.
freeSearchTemplate template a template that must contain the $1, by default the value "Search for $1" is used.
invalidSearchFilter regexp a regular expression to warn against faulty queries, by default [\^+-[]{}\/!#~"] is used.
invalidSearchMessage text a message that will be shown if the regular expression in the invalidSearchFilter parameter matches.

The click and namedclick can either be used in combination with a searchList block triggering clicks (or keyboard selection) leading to another page. The parameters click and namedclick can be provided either on the multiSearch block or on the collection being selected. The collection setting has higher priority and may be used to direct clicks to different pages depending on which collection option being clicked (selected).

multiSearch example 1 - together with a seachList

<span data-entryscape="multiSearch"></span>
<span data-entryscape="searchList"></span>

multiSearch example 2 - standalone, triggering opening another page

<span data-entryscape="multiSearch" data-entryscape-click="/otherpage"></span>
<span data-entryscape="searchList"></span>

facets

The facet block provides a list of facets divided into sections based on what is specified in the global collections configuration. Each facet is nothing more than a filter with a number indicating the number of search results that would be listed if selected. The limit parameter provided on a collection will limit the amount of facets, if more facets are available than the limit a button will appear to allow the user to "show more". The facet block must be used in conjunction with a searchList with the facets parameter set to true.

parameter value explanation
showmore text Text on button for showing more than the fixed amount of facets indicated by the limit parameter in the corresponding collection. Defaults to "Show more".
showless text Text on button for hiding facets shown by the "show more" button. Defaults to "Show less".
include text comma separated list of collections (by name) to include, cannot be used together with the exclude parameter
exclude text comma separated list of collections (by name) to exclude, cannot be used together with the include parameter
hl number the heading level to use for the facets, defaults to 3

facets example 1 - on the side of a simpleSearch and searchList

<div class="sidebar">
   <span data-entryscape="facets"></span>
</div>
<div class="main">
   <span data-entryscape="simpleSearch"></span>
   <span data-entryscape="searchList" data-entryscape-facets="true"></span>
</div>

limit

query parameter The limit block allows the user to adjust the number of results per page in a searchList block. Options in dropdown are based on the global level limitOptions parameter. The selected option triggers re-render on the list and is not reflected in the url and will not be rememberd on page reload. Be careful to set limit property on other list-blocks on the page that should not be affected. The limit property on list-block override the limit option.

parameter value explanation
class text a class that will be set on the select element.

limit example - limit options

<span data-entryscape="limit"></span>

sort

Aria support, filter condition The sort block allows the user to sort matches in a searchList block based on the global level sortOptions parameter.

parameter value explanation
class text a class that will be set on the select element, if none is provided the bootstrap class form-control will be set.

sort example - sort options

<span data-entryscape="sort"></span>

clear

The clear block allows the user to clear all filters added by one or several of the blocks simpleSearch, searchList, searchFilter, multiSearch and facets.

parameter value explanation
empty text can be one of hide, remove and disable. Correspondingly, if there is nothing to clear the button is either hidden (style="display:hidden"), removed (style="display: none;") or disabled (disabled="true"). All other values will be considered to be a class that will be added on the parent node of the block in case there is nothing to clear.

Note that the clear block does not provide a button itself as it relies on being added as the child of an element that will be considered the button. The reason is that it gives more flexibility to the developer/designer that uses blocks to do a custom design of the button or button like construction.

clear example 1 - bootstrap button with font awesome icon

<button class="btn btn-primary" type="button">
    <div data-entryscape="clear" data-entryscape-empty="remove"></div>
    <span>Clear filters</span>
    <i class="fas fa-times"></i>
</button>

results

The results must be used on the same page as a list or searchList and displays the number of results shown in the list.

parameter value explanation
use text connect to a list or searchList via the name given by the define parameter
template text if provided this template will always be used, if not provided the parameters templateNoFilter, templateFilter and templateFilterNoResults must be used instead.
templateNoFilter text template used when no filter is provided
templateFilter text template used when a filter is provided and there are matching results
templateFilterNoResults text template used when a filter is provided but there are are no matching results

In all the templates the following variables can be used:

variable|explanation :--- | :--- | :--- resultsize | amount of results currentpage | the page currently shown pagecount | the total number of pages available term | the current free text search string

results example - integration with a searchList block

<div data-entryscape="results" data-entryscape-use="mainList"
    data-entryscape-template-filter="{{resultsize}} matching items"
    data-entryscape-template-filter-no-results="No matching items for your query"
    data-entryscape-template-no-filter="{{resultsize}} apples in stock"></div>
<div data-entryscape="searchList" data-entryscape-define="mainList"></div>

filterResults

The filterResults block must be used on the same page as a searchList as it shows the filter that where applied to narrow down the result list. It can be considered a simplifed version of the multiSearch block as it shows the same sets of facets/constraints but not inside of a search bar. Hence, the filterResults should probably be used with simpleSearch a few searchFilter blocks or with the facets block rather than with multiSearch. The filterResults does provide a remove button on each facet/constraint.

filterResults example - together with facets, simpleSearch and a searchList block

<div class="sidebar">
   <span data-entryscape="facets"></span>
</div>
<div class="main">
   <span data-entryscape="simpleSearch"></span>
   <span data-entryscape="filterResults" use="mainSearchList"></span>
   <span data-entryscape="searchList" data-entryscape-facets="true" define="mainSearchList"></span>
</div>

collectionText

The purpose of the collectionText block is to render information dependent on how a specific collection is used in the filter. If the filter does not have any constraint based on the specified collection the template in the empty parameters will be used. Otherwise, if the filter contains a constraint for the specified collection the template in the template parameter will be used.

collectionText example - information for a conditional searchFilter block.

<span data-entryscape="collectionText"
      data-entryscape-empty="You must choose a document type before you can choose a category</div><br>"
      data-entryscape-template="<label>Choose a category for document type {{value}}:</label>"
      data-entryscape-collection="documenttype"></span>
<span data-entryscape="searchFilter"
     data-entryscape-if="documenttype"
     data-entryscape-collection="subject">
</span>

export

The export block works must always work in conjuction with a searchList block as it allows all the matches to be exported. The export currenlty only support the formats application/rdf+xml or application/json. The latter requires a transformation that is guided via a projection object provided on each entity type, see the global parameter entitytypes. The export block must always be placed inside of an clickable element, e.g. a link or a button. The user will be prompted for a download on click.

parameter value explanation
use text a named (via the define parameter) resultsList block, this is mandatory.
format text currently is only rdf or json supported.

Example export 1 - RDF/XML

<button><span data-entryscape="export"
        data-entryscape-use="listOfDocuments"
        data-entryscape-format="rdf"></span>Download as RDF/XML</button>

Example export 2 - JSON

<button><span data-entryscape="export"
        data-entryscape-use="listOfDocuments"
        data-entryscape-format="json"></span>Download JSON</button>

Asuming the list presents documents typed as foaf:Document, a projection inside of an antitytype could be:

entitytypes : {
  document: {
     rdftype: "foaf:Document",
     projection: {
       title: "dcterms:title",
       abstract: "dcterms:description",
       "*keyword": "dcterms:subject"
     }
  }
}

This projection would lead to the following json structure on download:

[{
    title: "Document 1",
    abstract: "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut ",
    keyword: ["keyword1", "keyword2"]
 }, ...
]

Note that the * in front of keyword in the projection forces an array, even if there is only a single value. If two values exists in the graph for a value that is not marked with an initial * only one of them will be picked at random and included in the json expression.

back

The purpose with the back block is to allow a "back to search" link on a landing page that preserves the search filters you had before clicking on a search result. The block works by going back in the browser history. If the browser history is wrong, e.g. when you arrived on the landing page via a link on another page the back link can take you back to a clean search interface. E.g. if you have been sent the link in an email, clicking on the link should not take you back to the email application.

parameter value explanation
test text should correspond to a regular expresion that will be used to test if the page you arrived via, the referrer, is the page you want to go back to. If the test parameter is not provided it is assumed that it is ok if the referrer has the same origin (domain) as the current page.
href url the page to go back to if the referrer does not fullfill the test
label text the label of the link
tooltip text the tooltip (the title attribute in HTML) to set
className text one or several classes to set (space separated) on the link element (a elment)

Note that the label, tooltip and className parameters will be ignored if the block is expressed on or directly within an a elment that provides these values. The parameters should only be used when defining custom back blocks that you want to use in many places and you do not want to repeat that information inline in an a element. In these cases the a will be created for you.

back example 1 - directly in html

<a href="http://example.com/search" data-entryscape="back">Back to search</a>

back example 2 - directly in html

<a href="search" data-entryscape="back" data-entryscape-test="example.com/search">Back to search</a>

back example 3 - inside of an a element

This is useful when you are inside handlebar templates as data attributes are not detected there.

<script type="text/x-entryscape-handlebar" data-entryscape="template">
   <a href="http://example.com/search">{{back}}Go back to search</a>
</script>

map

entry dependant

The map block provides a map view based on the Leaflet library with the current entry positioned, the position can either be detected from explicit positions in the metadata (provided via the wgs84:lat and wgs84:long, see basic geo) or via lookup of an address. (Currently the address information is hardcoded to be detected via a schema.org construction in the form of a schema:schema property pointing to a blank node with schema:streetAddress, schema:addressRegion and schema:addressLocality properties.)

parameter value explanation
tilelayer string a template URL for loading tiles, see example below. If nothing provided the openstreatmap will be used by default.
attribution string a text shown at the bottom of the map to provide attribution of the map information.
maxzoom number the maximal zoom allowed for the map
layers array an array of layers, each consisting of the layer name in the tilename attribute together with tilelayer, maxzoom and attribution per layer.
zoom number the initial zoom level of the map
height text the height of the map, default is 300px
popup text a template that will be rendered in a popup close to the pin on click
popupOnload boolean if set to true the popup will show directly without requiring a click on the pin

Example map 1 - one layer only

<script type="text/x-entryscape-json">
{
    tilelayer: 'https://api.lantmateriet.se/open/topowebb-ccby/v1/wmts/token/{yourkey}/1.0.0/topowebb/default/3857/{z}/{y}/{x}.png',
    maxzoom: '15',
    attribution: 'Map data © <a href="https://www.lantmateriet.se/">Lantmäteriet</a>',
    zoom: '11',
    height: '400px',
    popup: '<h2>{{text property="dcterms:title"}}</h2><p>{{text property="dcterms:description"}}</p>'
}
</script>

Example map 2 - information provided in a layers array

<script type="text/x-entryscape-json">
{
    layers: [
        {
          tilename: 'Lantmäteriet',
          tilelayer: 'https://api.lantmateriet.se/open/topowebb-ccby/v1/wmts/token/{yourkey}/1.0.0/topowebb/default/3857/{z}/{y}/{x}.png',
          maxzoom: '15',
          attribution: 'Map data © <a href="https://www.lantmateriet.se/">Lantmäteriet</a>',
        },
        {
          tilename: 'Open streetmap',
          tilelayer: 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png',
          maxzoom: '18',
          attribution: 'Map data © <a href="https://openstreetmap.org">OpenStreetMap</a> contributors, <a' +
            ' href="http://creativecommons.org/licenses/by-sa/2.0/">CC-BY-SA</a>',
        },
    ],
    zoom: '11',
    height: '400px',
    popup: '<h2>{{text property="dcterms:title"}}</h2><p>{{text property="dcterms:description"}}</p>'
}
</script>

mediaQuery

The mediaQuery blocks provides a simplified way of writing css media queries using blocks. The main usecase is to make it possible to provide an easy way to adapt custom blocks to different embedding circumstances, e.g. via a simple parameter control when to hide or show certain blocks.

parameter value explanation
media string the media in the media query, e.g. screen
max string a max width upon wich the media query will apply, e.g. 1024px
min string a min width upon wich the media query will apply, e.g. 1024px
rules object a set of rules expressed in an object where each key is a selector and each value is a set of comma separated styles
class string a css class to which the media query will apply it's styles
selector string a full selector to which the media query will apply it's styles, use when class is not enough
style string a set of styles expressed the way inline styles are expressed in html, e.g. display: block; border-width: 1px;.

Typically you use the rules parameter or a combination of either the class and style or the selector and style parameters.

Example hierarchy 1 - hide sidebar on small screens

<span data-entryscape="mediaQuery"
      data-entryscape-media="screen"
      data-entryscape-max="800px"
      data-entryscape-class="esb2Col__sidebar"
      data-entryscape-style="display: none;"></span>

hierarchy

entry dependant

The hierarchy blocks renders a hierarchical graph (left to right) from the current entry. Each entry is represented as a square with a label according to the labelProperties global parameter. The hierarchy is detected via the forward and backward properties provided per type. If an entry has children, as detected via the forward property, the square is marked and may be expanded. By default only one level is expanded.

parameter value explanation
relationByType object a mapping between forward and backward properties per rdf:type. Default is to support SKOS, i.e. skos:narrower respectively skos:broader for skos:Concept and skos:hasTopConcept respectively skos:topConceptOf for skos:ConceptScheme.
boxWidth number width of the box for each entry, default is 120
boxHeight number height of the box for each entry, default is 12
maxCharacter number number of characters before an ellipsis is shown, default is 20
scale decimal the scale expressed as a whole number or decimal, default is 1

Example hierarchy 1 - default SKOS hierarchy

<span data-entryscape="hierarchy"
      data-entryscape-scale="2"></span>

visualization

entry dependant

The visualization block is the only blocks that relies on special knowledge of how EntryScape express information. The entry provided must be Visualization entry which indicates the type of visualization to do, which data to load, how to treat the columns when constructing the visualization etc.

This blocks have no specific parameters.

chart

The chart block displays a chart with help of the library Chart.js based on either inline data or data loaded from a json file.

parameter value explanation
data object provide hardcoded data to be shown in the chart, see section below on accepted data-structures.
url url a url to a json file containing the data
legend text a suitable legend to show below the chart
type text bar, line, horizontalBar, pie or doughnut is supported and have some pre-set colors that can be overridden by adding moor colors via the backgroudColor property. Other charts like radar, bubble etc. have no pre-set colors.
backgroundColor color either a color like blue or a hexadecimal value like #fff
width text a width like 300px
height text a height like 600px
options object a set of options specific to each chart type, see Chart.js for more information on what you can provide here.
filterZeroValues boolean if true zero values are removed from the chart
limit number limit the number of data points shown in the chart
labelMaxLength number shortens or break labels that ar too long

There are two ways to express chart data in json, they will be auto-detected.

Data structure according to Chart.js

  1. The object must contain an array of labels in the labels attribute.
  2. The object must contain the datasets attribute which is an array of datasets represented as an array of individual values.

For example:

{
   "labels": ["Col1", "Col2"],
   "datasets": [[ 23, 45]]
}

Data structure according to an older format

  1. The object must contain an array of labels in the labels attribute (same as above).
  2. The object must contain the series attribute which is an array of individual values.

For example:

{
   "labels": ["Col1", "Col2"],
   "series": [ 23, 45]
}

chart example - a bar chart

<div data-entryscape="chart"
     data-entryscape-type="horizontalBar"
     data-entryscape-caption="Some example data" 
     data-entryscape-limit="7"
     data-entryscape-url="http://example.com/somechartdata.json">
</div>

table

entry dependant

The table block displays a CSV file in a table with an upper limit on the size of the loaded data.

parameter value explanation
property RDF property detect the url to the file via the given property
maxSize number amount of data that should be read in bytes from the file before giving up. Use this parameter to hinder that too big files are loaded and make the browser unresponsive

table example - show a file for a distribution

<div data-entryscape="table"
     data-entryscape-property="dcat:downloadURL"
     data-entryscape-max-size="1000000"></div>

click

The click block allows sending a signal, potentially with different values upon clicking or selecting among options.

parameter value explanation
signal text the signal that will be sent on click or select
template if a template is provided all input elements inside will be detected and all onchange events will cause a signal to be sent with the corresponding inputs elements value
class text a css class that will be added to the node, useful when adding the block in a handlebar template to avoid introducing an additional surrounding element just to provide a css class

click example 1 - button click to open image slider

<span data-entryscape="click" data-entryscape-signal="slider-lightbox-open">Open</span>

The slider block listens to the special signal slider-lightbox-open. This allows you to open the slider on another button than the default supported click on the image itself.

click example 2 - tabs for searchlist

<div data-entryscape="click"
  data-entryscape-signal="searchList-open"
  data-entryscape-template='<input type="radio" name="lt" value="rows"/>Rows&nbsp;<input type="radio" name="lt" value="cards" checked="checked"/>Cards'
</div>
<div data-entryscape="searchList" data-entrscape-define="cards" ...>
<div data-entryscape="searchList" data-entrscape-define="rows" 
     data-entryscape-visible="false" ...>

In the above code the signal searchList-open with the value rows will be sent when users select Rows and the signal searchList-open with the value cards will be sent when the user selects Cards. The two lists will be listening and show or hide each list respectively, note that the value is connected to the define parameter of the lists.

expand

filter condition

The expand blocks allows you to hide and show a section of the page which may or may not contain other blocks.

parameter value explanation
expandhead handlebar template a section that either displays a button or (if clickExpand is set to true) is clickable in it entirety. To make something act as a button inside of the template add the esbExpandButton class. Certain parts of the template may be hidden when collapsed (marked with the esbExpanded class) or when expanded (marked with the esbCollapsed class).
expandbody handlebar template a section that can be expanded, it may contain blocks
clickExpand boolean if true the entire expandhead template is clickable
class text a css class that will be added to the node, useful when adding the block in a handlebar template to avoid introducing an additional surrounding element just to provide a css class
initialExpandOn text the expand block will be expanded on inital render if any of the collections in this comma separated list has a value set

expand example 1 - clickable head template

<div data-entryscape="expand"
     data-entryscape-click-expand="true"
     data-entryscape-expandhead="Open or close"
     data-entryscape-expandbody="{{helloworld}}"></div>

expand example 2 - custom expand button

<div data-entryscape="expand"
     data-entryscape-expandhead="<button class="esbExpandButton esbCollapsed">Open</button><button class="esbExpandButton esbExpanded">Close</button>"
     data-entryscape-expandbody="{{helloworld}}"></div>

json

The json block is similar to the text block in the sense that it displays a simple value. The distinction is that fetches the data from a json file rather than from the metadata of an entry.

parameter value explanation
url url A URL to a json file to be loaded.
attribute string Picks the value for the given attribute in the loaded json object.
template lodash template A https://lodash.com/docs/4.17.15#template allowing picking out specific attributes as well as deeper substructures of the loaded json.
ondata function a function that will be called on load of the json, the function is passed the json object and the html node where the result is to be inserted.

json example 1 - single attribute

<span data-entryscape="json"
      data-entryscape-url="http://example.com/ex.json" data-entryscape-attribute="name"></span>

json example 2 - lodash template Lodash templates allows bringing out multiple values from the retrieved json object like this:

<span data-entryscape="text"
      data-entryscape-json="http://example.com/ex.json"
      data-entryscape-content="Mr. ${name} ${lastname}"></span>

error

This block provides a way to control where error messages are shown. If this block is not provided the default error dialog is used instead. To make sure that overall initialization of the page knows that there will be an error block (and avoids initializing the error dialog) the global level parameter errorBlock needs to be set to true.

parameter value explanation
delay number number of milliseconds to wait before displaying an error / warning text, default is 2000.
close text text that will be set as title and aria-label on the close button
inProgress text warning text that will show when requests are slow to complete
generic text generic error text that will show when something goes wrong
requireEntry boolean if true the block will show an error if the current page does not have a focused entry
missingEntry text error text that will show when the current page does not have a focused entry given that the parameter requireEntry is set to true

config

This block allows you to provide global level parameters that have no direct visual rendering at the point of insertion of the block. The global level parameters can be provided in several ways, see the section on syntax for more options.