Archive 1.x:Configuration: Topics Layout

The Topic layout is built around the sRelationBrowser widget. It is a means for enabling pre-selected filters to be presented as the focus for the dynamic subject browser as linked to a specific Drupal menu item or link. In the example case herein, we are setting these filters by certain top-level topics or subjects, but any topic or attribute within your current OSF instance may be used for filtering.

There are two perspectives required for any layout. The first perspective is that of the site administrator, the individual responsible for menu linking to stubs and filling in fields such that the actual layout page is live and displays properly using Drupal on the OSF installation.

The second perspective is that of the developer, the individual responsible for creating the shell layout in the first place. This perspective is less fully explained below, because it requires developer-level knowledge (including PHP, Web design and SPARQL familiarity).

Overview of Layout Operation
A layout is a specific content type in Drupal that has fields for each page, the specific entries for which inform queries to OSF Web Service. The results from these queries are what determines the actual data to display on a specific page. The page presentation layout and the widgets on it are defined within the layout specifications.

A layout thus has a code specification that covers presentation and widgets, plus one or more field specifications that can be filled in to specify the exact basis of the query to get the data for that page. The developer sets the code and content type definitions for the layout (including the fields that need to be filled in); a site administrator enters the actual field information on a page-by-page basis to fill in the various page stubs.

Site Administrator Perspective
The site administrator, or the designated representative, is the individual responsible for menu linking to stubs and filling in the fields to make the layout active and live. The specific steps this individual must follow for the WebMap layout includes:


 * 1) Be logged in as an administrator
 * 2) Go to the active menu stub for the item under consideration; click on the stub link.
 * 3) Pick Edit; you will see the standard edit form, but now with the relevant Topic field also shown at the top ("Above") the form:



Note that the field entry forms have a active circle to the right of the text entry form. By typing in a few letters, you can get appropriate auto-completion for the field at hand; search using the standard logical name (label) for your item of interest:

Multiple options might be presented based on the partial string match; pick the one you want and it will enter (along with its actual record id) into the entry field.

Note, this is a handy feature because the actual record names that get entered are based on the ; auto-complete means we only need worry about the human-readable label.

Also note in this example that we entered two different records: one for a community area (cluster of neighborhoods) and one for a neighborhood. Via multiple selections such as this multiple regions can be mapped in relation to one another (in this case, a constituent neighborhood of a community area.)

You should not need to make any further changes to your edit form; so, go ahead and Save. Repeat for all stubbed items until complete. 

Developer Perspective
The developer is the individual responsible for creating the shell layout. We first present the general workflow for the developer, using the Image layout as our example, and then present the specific field requirements for this layout.

General Workflow
In general terms, the developer workflow proceeds as follows (using the Image layout example):


 * 1) Create a new  (or similarly named) content type. To do so, the developer must be logged in as an admin for the Drupal site and then:
 * 2) * Administer -> Content management -> Content types -> Add Content Type
 * 3) * Then, you must supply a Name (human-readable label), Type (lowercase with underscores, the same as the layout template name; see below) and a Description. Try to pattern these after the other specialty content types. Here, for example, are the entries for Images:



After the basic entry, the "fill-in" fields next need to be added to the content type. In this example (Images) we want to add two fields: one which relates to possible topics, the other which relates to possible entities. If the specification we provide for these fields for a specific page with this content type are met, then all images that meet those conditions will be selected for display in the gallery on that page.

To do so, we pick Manage Fields and then add a New Field, with our example being to add the topic field:



and then Save.

Note the field has been created for text entry over multiple lines. We can also further Configure this field, as this example shows:



Note we changed the widget basis to a simple text area (which will work better with auto-completion; see below).  We repeat such entries for all needed fields for this specific layout. Generally, all fields should be of the text type with single- or multiple-line entry (depending on whether more filter conditions are desired for the query and the use of auto-completion, which does not work with multiple-line entry). Once all fields are entered and completed, we can then arrange how they will appear to the site administrator during actual fill-in. These settings are found from the Display Fields link; generally, we only need set the display to the top ("Above") of the page:



 Separately from these steps undertaken within Drupal, we must also then create the template form used to configure the actual layout for this content type. This is done through a related  template page. This page will generate the HTML code of a given image page, given inputs in the fields defined for it. Here is a sample file showing the code for  The basis of the  page is the   core page of your theme The  page first checks if some values have been determined for the custom fields defined for this content type</li> It is the template file that will issue different kind of queries to OSF Web Service</li> Depending on the settings, and the layout, the remainder of the  template file will add different things into the page, such as JavaScript programs, embedded Flash movies, queries to OSF Web Service endpoints, etc.</li> For general guidance on these template steps, see the Anatomy of a Page Template File document.</li></ul> The page that is generated from the specifications above depends on the settings of the content type node, and the information retrieved from the OSF Web Service instance via the queries specified in the actual field entries.</li> Note: you have to create one  (or similar) file for each content type layout used within your installation.</li></ol>

Specifics for this Layout
Here are the specifics for this Topic layout.

Layout Template Code
The example layout code for this template is found in the Sample Topic Template for the  file. To help understand this file and to decipher how to modify your own, see Anatomy of a Page Template File.

Specific Fields
As defined, the Topic layout has requirements for a single field:


 * 1) Pre-selected Records
 * 2) * Widget type: Text area
 * 3) * Values: 1
 * 4) * Text processing: Plain text

In other words, as defined in this example, only a single URI topic may be entered into any given Topic stub.