Directories: Technical

Introduction

For an overview of Directories it's worth familiarising yourself with the Content Designer's Documentation.

Directories are built around the Directory Channel node content type and Directory Items that are content types with an entity reference field to a Directory Channel. As outlined in the Content Designer's Documentation there are three preconfigured Directory Item content types: Directory Page, Directory Venue and Directory Organisation.

In addition to the node content types directories provides Directory Facets. This is a simple entity type used for categorization, search facets. Unlike Taxonomy, Directory Facet types do not export configuration by default and can be treated as content to be managed by Content Editors.

Permissions

Normal Drupal permissions exist for the node content types. The module additionally provides permissions to administer Directory Facets Types and edit, create, view the Directory Facet entities. If installed as part of a LGD distribution these are given to the Editor role by default.

Related permissions that need configuration for Directory Venue and any other content type that uses Location are the permissions from the LocalGov Geo module. These again should already be configured for the Editor role if installed as part of the LGD distribution.

Installation

This module is included in the LGD distribution. For the most simple configuration you can enable LocalGov Directories module and one for an Item content type, for example LocalGov Directories Page.

The installation of an Item content type automatically configures the Search API Index.

There is configuration for placing the Directory channel search and Directory facets blocks in the LGD theme. The search is placed on all directory related content types, the facets on the Channel content type. If you are using another theme you will have to enable these blocks. Alternatively the blocks are available as 'fields' on the Channel and Item content types and can be configured in the Content Type Manage display.

Configuration

Channels and Facets can be configured as content as outlined in the Content Designer's Documentation.

The automatically enabled Facets are their own entity type. They are intended for creation and management by content editors on the production site. Adding a facet type will automatically make it available on Directory Channels, and add any values to the Facet block on the page, without any additional site building. As such by design they are excluded from configuration export, see Staging 'Directory facet types' below. If you want to control the facets for example they are a fixed taxonomy, or imported from elsewhere, using a Taxonomy with a Directory may be preferable.

Adding Fields to existing Directory Item types

You can add your fields to a supplied Item types, like Directory Venue. Fields supplied by LGD have a machine name that is always prefixed localgov_, it is advised you prefix your additional fields with a 'namespace' unique to your site.

If you want the content of the field to be found in the full text search make sure it is included in the Directory Search Index view display, see below.

Directory Search Index View Display

The Search API Directories Index will include the content of the Directory Items in the full text. For this it will use the Directory Search Index display. If you would like to add, remove fields, or change their output you can do this on the content type Manage display page for example: Administration > Structure > Content types > Directory organisation > Manage display selecting the Directory search index tab.

If you have created your own Directory Item type you may have to enable the 'view mode', this can be found in the same Manage display section under the Default tab in Custom settings.

Enabling Open Referral

Open Referral integration with Directories makes it easy to provide information about Services in an open standards format that can be shared and reused.

The standard requires at least 'Services' and 'Organisations' to be present. To make this possible the default implementation maps Directory Venue to 'Service' and Directory Organisation to Organisation.

Enable the LocalGov Directories Venue Open Referral module. This will install the mappings for Venue to Service, and enable the Directory Organisation if it is not yet. If there is existing Directory Venue content it will also create 'stub' Organisations for each venue that are only used for the purpose of the Open Referral output, so you will want to test this.

Advanced configuration

Adding a custom Directory Item content type

The chances are your Information Architecture won't exactly map to the default Directory Item content types. While you can extend them, it will often be better to create seperate content types that better fit your requirements.

Once you have made a Content Type and added the fields you require you need to add the fields to include it in a Directory:

Add field form selecting the existing field Entity Reference: localgov_directory_channels

The essential field is the Directory channels (localgov_directory_channels) which uses the 'Reference Method' LocalGov: Directories channels selection. Adding this field will also automatically add the content type to the Directories search index.

You should probably also add the Facets (localgov_directory_facets_select) field.

It is best to also configure the Display view for the search index, see Directory Search Index View Display above. If you don't do this it will use the 'Default' display.

Mapping a custom content type to Open Referral

Administration > Configuration > Web services > Open Referral Entity Mapping configuration

In the Web services Open Referral section you will find existing mappings from Drupal Entity Bundles (for example Node Content Types) to Open Referral Types (for example Service). Here you can also + Add Open Referral Mapping.

Add open referral mapping

Once you have selected the Entity Type (probably Node), the Bundle (the Content Type you are adding) and the Open Referral Type (probably an Organisation or a Service) you can pre-populate the mappings with the Populate mappings button. This will make a best guess of the mappings. So if, for example, you have an entity reference restricted to something that is already mapped to an Open Referral location type on something to be a Service it will make it a service_at_location. The mapping might miss fields, you will then need to add the manually. Note: To validate Services must reference an Organisation.

There is a Validation service you can test your feeds against if they are on a URL accessible to the internet. Your feed will be at http://example.com/openreferral/v1/services where http://example.com is the URL of the base of your LocalGov Drupal site.

Adding a custom Taxonomy to a Directory

As an addition, or alternative, to the Directory Facet entity type, you might want to include a Taxonomy Vocabulary. These have the opportunity to include for example, heirarchy. Taxonomy is however not automatically added to the Directories index, nor is it included in the Directories Facet Block. You will need to:

Create the Taxonomy vocabulary.
Add a reference field from your Directory Item Content Type to the new vocabulary.
Add the new field to the index, this can be done at: Administration > Configuration > Search and metadata > Search API > Directories > Manage fields for search index Directories.
Create a facet for that field for the Directory view: Configuration > Search and metadata > Search API Directories > Manage fields for search index Directories. You should already see localgov_directories_facets under search_api:views_embed__localgov_directory_channel__node_embed, it is for this 'Source' you need to add your facet.
Place the Facet Block that is then created.

One reason to do this would be to import controlled vocabularies like OpenActive or the LGAs lists. There is an experimental module LocalGov Vocab that could help to syncronise these.

By default facet types are not exported to configuration and are treated as content an administrator user can create on production. Normally if you want to control Facet types you will be using Taxonomy term. If you want the Facet Types additionally in configuration set: $settings['localgov_directories_stage_site'] = TRUE; They will be then exported with other configuration. Any types that exist in configuration will be imported.

Useful links

Contributors

@ekes
@Adnan-cds
@stephen-cox
@finnlewis
@mattrfletcher
@danchamp