Configuration: Charts Layout

From TechWiki

The Chart layout is built around the sBarChart widget (though the design could easily use the sLinearChart and sPieChart widgets as well). It is a means for enabling pre-selected attributes to be charted in conjunction with a specific menu option. In the example herein, up to 10 attributes using census data is shown. With slight modifications, more attributes or different dataset sources may be readily substituted.

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).

Contents 1 Overview of Layout Operation 2 Site Administrator Perspective 3 Developer Perspective 3.1 General Workflow 3.2 Specifics for this Layout 3.2.1 Layout Template Code 3.2.2 Specific Fields 4 Endnotes

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 structWSF. 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:

4. 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 &id; auto-complete means we only need worry about the human-readable label. Also note in this example that we are entering multiple values related to land and population density. You should not need to make any further changes to your edit form;^[1] so, go ahead and Save.
5. 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 image (or similarly named) content type. To do so, the developer must be logged in as an admin for the Drupal site and then:
   • Administer -> Content management -> Content types -> Add Content Type
   • 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:

2. 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).

3. 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:
   
4. 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 page-image.tpl.php 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 page-image.tpl.php
   • The basis of the page-image.tpl.php page is the page.tpl.php core page of your theme
   • The page-image.tpl.php page first checks if some values have been determined for the custom fields defined for this content type
   • It is the template file that will issue different kind of queries to structWSF
   • Depending on the settings, and the layout, the remainder of the page-image.tpl.php template file will add different things into the page, such as JavaScript programs, embedded Flash movies, queries to structWSF Web service endpoints, etc.
   • For general guidance on these template (*.tpl) steps, see the Anatomy of a Page Template File document.
5. The page that is generated from the specifications above depends on the settings of the content type node, and the information retrieved from the structWSF instance via the queries specified in the actual field entries.
6. Note: you have to create one page-image.tpl.php (or similar) file for each content type layout used within your installation.

Specifics for this Layout

Here are the specifics for this Chart layout.

Layout Template Code

The example layout code for this template is found in the Sample Chart Template for the page-census.tpl.php 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
   • Widget type: Text area
   • Values: 10
   • Text processing: Plain text

In other words, as defined in this example, up to ten different display attributes may be entered into any given Chart stub.

Endnotes

1. ↑ This assumes you have path names set up for proper aliasing and logical labels for search engine optimization reasons; see further Path Name Aliasing.