# Directories
Contents:
# Introduction
Directories provide a way for editors to present content as a list which can be searched and filtered by end-users. They are a part of the LocalGovDrupal distribution.
# Examples in the wild
# How to log issues
# When to use Directories
- You have a type of content with a large volume of variations. Car parks, sports facilities or parks are good examples.
- Users are looking for content based on their needs and these can be described as a series of attributes such as price range or sports catered for.
- Your content is related to a specific geographical location which is relevant to users.
# Concepts
# Directory Facets
Facets are groups of attributes users will filter by when searching for a Directory Item(s). Each Facet type should be made up of at least 2 Facets, each of which can apply to 1 or more Directory Items. As an example, when searching for a school, there are a variety of attributes which users will be interested in when looking for one that fits their needs. This is illustrated well by Croydon's Secondary school Directory (opens new window):
Note that not all Facet types are made up of mutually-exclusive Facets; in the case of gender most schools are applicable to both Girls and Boys where as other schools are only applicable to one gender.
There are also often cases where Facets will be mutually exclusive such the maximum length of stay for car parks:
Maximum stay (Directory Facet type)
- 1 hr (Directory facet)
- 2 hrs (Directory facet)
- 4 hrs (Directory facet)
- 6 hrs (Directory facet)
# Directory Channels
Directory Channels can be thought of as the Directory itself; it's the page where users will be presented with a list of Directory Items the the UI to filter by Facets or perform a free text search. Additionally, Channels automatically provide a logical information architecture. For example, consider a Directory Channel with a URL of /schools/find-a-school/secondary-schools and a breadcrumb of Schools > Find a school > Secondary schools; each Directory Item will then have a URL and breadcrumb based on it's Primary Channel, e.g. St. Example High School would have the URL /schools/find-a-school/secondary-schools/st-example-high-school and breadcrumb Schools > Find a school > Secondary schools > St. Example High School.
As an editor, Channels give you the flexibility to compose a Directory made up of 1 or more types of Directory Item which can be filtered by 1 or more Directory Facet types.
# Directory Items
Directory Items are pieces of content, and pages, in their own right but also a member of 1 or more Directory Channels. For example, a School content type could allow editors to publish detailed information on individual schools and belong to the Secondary schools Channel. LocalGov Drupal comes with some generic Directory Item types which can be used as-is or can be extended to meet your needs:
| Type | Uses |
|---|---|
| Page | General purpose. |
| Venue | Sports facilities; parks. Provides location integration. |
| Organisation | Libraries; Schools; Provides location integration. |
Alternatively, LocalGov Directories provides site-builders with a toolkit to create bespoke Directory Item types without having to write any code. More information about customizing Directory Items can be found in the Directories Technical documentation.
As a minimum a Directory Item must belong to a Primary Channel, and this can be any Channel which accepts Directory Items of that type e.g. School. The Primary Channel is required as it is the basis for the inferred URL and breadcrumb (as described above). Items may also belong to multiple Other Channels, these additional Channels do not influence the URL or breadcrumb but will include the Item in it's list and do still impact the available Facets (as described below).
In order to allow users to filter Directory Items by Directory Facets, Items must be 'tagged' with the appropriate Facets. When creating\editing an Item, the available Facets is determined by the Channels it belongs to. For example, consider the following Channels:
Sports facilities
- Facet types: Sports, Location
- Content types: Sports venue
Secondary schools
- Facet types: Age, Location
- Content types: School
When creating\editing Sports venue Directory Items Sports and Location facets can be selected while with Schools the Age and Location facets will be available.
# How-to
# Create a Directory of schools
In this guide we'll step through the process to create a Directory of secondary schools using features which come out-of-the-box with LocalGov Drupal.
# Pre-requisites
- You'll need to have access to a Drupal installation based on the LocalGov install profile.
- The following Drupal modules will need to be installed: LocalGov Directories, LocalGov Directories Location and LocalGov Directories Organisation.
- You'll need to be able to log in with a user which has editorial rights.
# Creating the Facet types
We'll create two Facets types which allow users to filter secondary schools by the type of school and the age range.
Once you've logged in navigate to the Facets types overview page via the menu items Content > Directory Facets > Add directory facet type
From this screen, enter 'Age' into the Label field and click Save directory facets type. You'll be taken to the types overview page where you can see your new type.
From here, click Add directory facets type button to create another. This time, enter 'Location' into the Label field and click the save button.
# Creating the Facets
With our Types in place, it's time to create the Facets which users can use to filter our list of schools. Using the admin menu, choose Content > Directory Facets > Add directory facet
From the next screen choose the previously created Age Type and, finally, enter '11 to 16 years' into the Title field and click the Save button. You'll be taken to the Facet overview screen.
From here, click the Add directory facets button and repeat the process until you have the following:
| Age | Location |
|---|---|
| 11-16 years | North Somewhere |
| 11-18 year | South Somewhere |
# The Channel
OK we're getting somewhere. Next up let's create a 'Channel'. Remember, the purpose of this channel is to allow users to filter a list of secondary schools by age and location so they can find a school which meets their criteria. Here we're going to make use of the Directory organisation content type, that comes out-of-the-box with LocalGov Drupal, to represent a school.
Using the admin menu, navigate to Add content > Directory > Directory channel:
From this screen, enter 'Secondary schools' into the Title field and then scroll down the page and check all the boxes under Enabled Content types and Enabled facets.
Finally, click Save to create your new Channel.
# Directory Items
With the Channel and Facets in place we are ready to start creating some Directory Items, in this case secondary schools.
Using the admin menu, navigate to Add content > Directory > Directory organisation:
From here, enter 'Example high school' into the Title field then select the Channels and facets tab. After selecting 'Secondary schools' as the Primary Channel you will be presented with some Facets for selection. Choose some Facets, in this case it probably doesn't make sense to have more than one Facet per Type:
# Item location
Finally, we can harness the power of the LocalGov Drupal location integration so users can browse the schools by using a map interface. Open the Venue tab and click the Select location button. From the popup, choose the Create new address tab. Populate the fields within the Address tab with an address familiar to you:
The address should autocomplete if your site is configured to do so, and it will place the point on the map. If this is incorrect, or not found, you can place the point manually.
Finally, scroll to the bottom fo the popup and click the Save address button and then save the venue.
You'll probably want to repeat this process a few times, choosing different combinations of Facets and different addresses, in order to better understand how Directories work.
# Using the Channel
With your newly entered Directory Items it's time to experiment with the Channel to see what it can do. Navigate to the content overview page via the admin menu. From here, you'll be able to see your Channel and Items. Click on the Channel name to view the Channel page:
As you'll see, by choosing Facets and entering a location the Directories module has automatically generated the filters and map visualisation. Try selecting different facets to see how it effects the listed schools.