Configuration: Images Layout

From OSF Wiki
Jump to: navigation, search

The Images layout is built around the Image Gallery widget. It is a means for presenting groups of related images, with the basis for the groupings determined by a site administrator (and often linked to a specific Drupal menu item or link).

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.

Preparation of the Images

For images used in this layout, see the Image Datasets document on preparation and other instructions.

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 image 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 Image fields also shown at the top ("Above") the form:
Image select 1.png
  1. 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.
    Image select 2.png

    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.

    You should not need to make any further changes to your edit form;[1] so, go ahead and Save.
  2. 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:
Image content type.png
  1. 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:
    Image manage fields.png

    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:

    Image configure field.png

    Note we changed the widget basis to a simple text area (which will work better with auto-completion; see below).

  2. We repeat this 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). 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:
    Image display fields.png
  3. 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 theme 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 OSF Web Service
    • 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 OSF Web Service endpoints, etc.
    • For general guidance on these template (*.tpl) steps, see the Anatomy of a Page Template File document.
  4. 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.
  5. 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 Image layout.

Layout Template Code

The example layout code for this template is found in the Sample Image Template for the page-image.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, this Image layout has requirements for these two fields:

  1. Topic URIs
    • Widget type: Text area
    • Values: 10
    • Text processing: Plain text
  2. Relates to Entity URIs
    • Widget type: Text area
    • Values: 10
    • Text processing: Plain text.


  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.