Skip to main content

Facets

Facets are used in multiple ways in hanami when the application need to search for "things". For information how how to configure them to be properly computed, please take a look at the related configuration in the collection's ext folders.

Here we we tackle configuration of facets in triples store in hanami:Collection graphs and how they can be leveraged.

Let's consider this sh:NodeShape.

ex:Person
    a                sh:NodeShape, rdfs:Class;
    sh:name          "Person"@en ;
    hanami:isRoot    "true"^^xsd:boolean;
    sh:property      [
      a        sh:PropertyShape ;
      sh:path  ex:maritalStatus ;
      sh:maxCount 1 ;
      sh:nodeKind sh:IRI ;
      sh:in ( ex:married, ex:single ) ;
    ] ;
    hanami:facet   [
      a                         hanami:Facet ;
      rdfs:label                "Status"@en ;
      dct:identifier            "status" ;
      hanami:filterType         hanami:TextFilter ;
    ]
.

We define here that a status facet will be used for text matching. If we look at the equivalent templated sparql query, it might look something like this

PREFIX ex:    <http://example.org#>

select distinct
  ('status' as ?facetName)
  ?status
{
  <#{[uri]}> ex:maritalStatus ?status.
}

Notice that the 'status' in the query is meant to match exactly the dct:identifier specified in the sh:NodeShape above!

With this setup, when doing a text search in the Person collection, a user will be able to type in the search bar @status=married to find all the married individuals. The matching here is happening on the full uri stored in the facet, so one could also type @status=org#married or @status=http://example.org#married. It is also to be noted that the status in @status need to perfectly match the same dct:identifier as specified above.

Facet on node shapes for displaying metadata​

Considering the same example as the previous section, let's consider the updated node shape like this:

ex:Person
    a                sh:NodeShape, rdfs:Class;
    sh:name          "Person"@en ;
    hanami:isRoot    "true"^^xsd:boolean;
    sh:property      [
      a        sh:PropertyShape ;
      sh:path  ex:maritalStatus ;
      sh:maxCount 1 ;
      sh:nodeKind sh:IRI ;
      sh:in ( ex:married, ex:single ) ;
    ] ;
    hanami:facet   [
      a                         hanami:Facet ;
      rdfs:label                "Status"@en ;
      dct:identifier            "status" ;
      hanami:filterType         hanami:TextFilter ; # not necessary in this context, could be removed
      hanami:presentationContext     [
        a              hanami:PresentationContext ;
        sh:order       1;
        hanami:purpose hanami:ResultCard;
      ],
      [
        a              hanami:PresentationContext ;
        sh:order       1;
        hanami:purpose hanami:ItemForm;
      ]
    ]
.

Here we added 2 presentation contexts:

  • hanami:ResultCard is meant to say that this facet will be displayed on results cards on the search page of the collection in the bottom right.
  • hanami:ItemForm is meant to say that this facet will be displayed on item forms in the top right, right to the label of the item being edited.

It is to be noted that since this facet is outputting a uri, the UI will try to automatically find a label fitting for that uri, making elastic search queries ot find an indexed node with that uri and a labelling property associated to it.