Configuration Workflow

From OSF Wiki
Jump to: navigation, search
Important yellow.pngThis page needs to be updated to OSF v. 3.0; terminology and perhaps images are out of date !!!

Configuring an OSF portal involves both basic configuration of portal components with presentation, which is based on the styling and layout of eventual Web pages. The portal components specifically included in this configuration include Drupal, related OSF-Drupal modules, and the individual OSF widgets for data visualization and management.

The presentation workflow fits within the overall OSF workflow as follows:

Configure icon.png

To understand this workflow in more detail, we first provide a general overview and then attend to the specific parts.

Workflow Overview

Configuration and presentation involves the interaction of four main components:

  • Design applies to the theme and styles of all presentation objects and pages in the system
  • Content Structure applies to the menus, their stubs, and the various standard pages in the system; this structure is reflected in what would appear in a site map, for example
  • Modules are the added functionality plugged into Drupal in order to provide the overall functionality of the site, and
  • Users reflect the idea that different users (as contained within variously defined groups) may and should have different access and rights with respect to the content and structure of an OSF installation.

These four components all interact with one another. Combined, they represent the overall look-and-feel and functionality and use of the system.

Development and refinement of these components is not sequential. Portions can be worked on for a time, then returned to later. However, by the time of initial release, all of the components should have at least gone through basic set-up and configuration.

See further Configuration Tools for some of the tools that are useful for configuration and presentation purposes.

Design and Presentation

Drupal Theming

A theme is a pre-packaged means of manipulating and describing (to Web browser applications) how you want your content displayed to your visitors. Theme elements include header, footer, blocks, menus, layouts, icons, colors, fonts, blocks, node display, etc. See further the presentation glossary regarding many of these terms.

A Drupal theme is a file or (usually) collection of files (PHP templates, CSS, images and perhaps JavaScript) that together to define the basic look-and-feel of your site. These files are often used by one of the theme engines available for Drupal, which turn PHP arguments into HTML markup. Many Drupal modules define theme-able functions that can be overridden by the theme file.

There are hundreds of off-the-shelf Drupal themes, some which allow great flexibility in choice of color schemes or layouts. Many of these are also open source. We have reviewed and can recommend some suitable themes for consideration in your OSF instance.

Many site owners are perfectly willing to use standard themes. It is also possible using open source themes to make your own minor to major modifications, given your comfort and skills with PHP and CSS. Most high-profile sites, however, engage professional design firms to give their sites a unique look or presence. Specific guidance on theme development and modification is beyond the scope of this wiki.

In any case, after installation, likely the first step you will need to take is to decide on your site's theme and design. There are some helpful sites that showcase exemplary designs for your edification, such as:

and many others that you can find through simple Web searches.


A template is a unique, non-executable file format intended specifically for a particular application. In the case of the OSF portal based on Drupal, a template may refer either to a specific node (content) type with a specified layout or a data presentation format provided via Smarty or an Infobox within an OSF widget. See also A Zoology of Templates for still further elaboration in this area.

Drupal Templates

Drupal (and its themes) come pre-packaged with a number of standard page and node templates, all noted with the *.tpl.php extension. The base page template is called page.tpl.php and the base node template is called node.tpl.php. There are often other standard templates.

A Drupal template is a PHP code file that contains instructions about how to dynamically create an HTML page or insert based on the parameters passed to it. The PHP code sets calls and variables for populating certain aspects of the result; this code is matched with HTML code that sets the display and styles for the dynamically rendered page. Sites that choose to have a different entry page design than the standard layout, for example, make those changes into the page-front.tpl.php template.

In the context of an OSF installation, most of the template changes occur via the layouts (see below), for which a few examples are provided.

OSF-Drupal (Data) Templates

OSF-Drupal templates are used to create different HTML page layouts to present information about instance records depending on their type. The present design utilizes Smarty as the baseline templating framework.

The general idea is that depending on the type of the instance record you want to display information about, you will want your system to display the information you have about that instance record differently depending on the type of that instance record. For example, if you want to present information about a neighborhood, the information will be displayed differently than if you want to present information about a person.

Detailed information on working with the Smarty templating engine is provided in the Building OSF-Drupal Templates document.

Infobox (Data) Templates


Sometimes it is useful to include attributions to external data suppliers in results templates. See the related Suggested Dataset Attribution document.


A layout is a specific page presentation format with specific design, components and ordering and sizing of those components. See further the document on Overview of Layouts and Design.

Drupal Template Layouts

In the case of the OSF portal based on Drupal, a layout is a specialization of a template dedicated to a specific node (content type). A Drupal layout 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.

A separate Anatomy of a Page Template File document describes in broad terms how to actually OSF-Drupal a Drupal layout and the common options available for them. There are also a number of existing example layouts, including:

The code associated with these provides more concrete guidance on how to construct and modify these templates.

OSF Widget Layouts

OSF widgets are Flex or JavaScript components or widgets that take record results from queries to OSF Web Service endoints and renders them as reports or visualization. Depending on the nature of these results, different or multiple widgets might be indicated for such displays. A specific sComponent ontology defines this logic.

OSF widgets use a cascading layout mechanism that ensures that specific data and structure (schema) get rendered with their most tailored component, with a fallback step that directs the rendering to the next appropriate tier of presentation display. Application developers can specify what control should be bound to what attribute in this layout using the SCO ontology. The application developer also has the control and latitude to re-define the schema that comes with the data source or to redefine the behavior directly in the application layout based on its the bound variables.

More specifics on controlling OSF widgets is provided in the OSF Widget Layout document.

Widget Theming

The various tools, or widgets, within an OSF installation include the OSF-Drupal tools and OSF widgets. The OSF-Drupal tools are standard Drupal modules written in PHP and mostly styled with standard CSS. The OSF widgets are written in either Flex or JavaScript. Most theming for those occur via CSS, but some of the styling requirements are embedded in the actual code.

OSF-Drupal Module (Tool) Theming

As noted, OSF-Drupal tools are standard Drupal modules written in PHP and mostly styled with CSS. The stylesheets are separate for each tool, and are located in different directories on the hosting server depending on tool.

The Styling OSF-Drupal (Tools) Modules document presents a number of before-and-after examples of how to style some of the more prominent tools in the suite. These examples also provide code examples. These examples mostly focus on changing colors, fonts, and more-or-less standard CSS options for the sample tools discussed.

Component Theming

The OSF widgets may be themed and styled similar to Web pages (Flex uses styles similar to CSS). Their are some notable differences from straight HTML in specific commands available or not. But, the biggest difference in Flex/Flash styling is that the code needs to be compiled before the revised objects in the code can be rendered. This means that a development environment, such as Flash Builder, must be employed to make and then compile the changes for the Flex widgets.

Also, there are Flash themes similar to CSS stylesheets. These can be invoked for overall changes across tools.

More detailed information on component theming is found in the Styling OSF Widgets document.


The core functionality of Drupal is pretty basic, which is why it is called a "framework". In its raw state, Drupal actually has very little functionality. The actual functionality of a Drupal site comes from its modules, which are PHP plug-ins that conform to a given confirmation and architecture for extending the system.

Basic material on how to categorize, install and which modules are presently used within OSF is provided in the Configuration: Drupal Modules document.

Content Structure

In addition to the structured data and general content that populates a site, there are some basic content configuration steps that must be pursued during initial set-up. This content structure is also a key determinant of the related theming and module requirements as described under other sections.

Menu Structure

An excellent place to start configuring your site is with its menu structure. Defining this is like working out the skeletal basis of a site map or a outline in spreadsheet form for the site. In figuring out this structure, it is useful to keep in mind some basic questions:

  • What content is to be captured and presented by the site?
  • Who is the audience for the site, and what emphases make best sense for them?
  • How can you balance the scope related to the purpose of the site and split it into meaningful chunks, manageable in number?
  • What kind of standard info and links does your site need to provide (such as links to external sites, standard help and about content, descriptive material, etc.)?
  • How can you best describe and guide access to site content via short words or phrases?

Answers to these questions enable you to provide a hierarchical structuring of site content, reflected through main links and menu options. Continuing to flesh out these main options on paper will help indicate whether your structural decisions and splits are balanced and making sense.

The key point is that working these questions out on paper is always easier than backtracking on structure that you have already undertaken on the site.

Stubbing the Portal

A unique aspect of an OSF installation (as opposed to a standard Web portal) is its use for providing faceted access and presentation to structured information. The structure of this information -- or its "dimensions" if you will -- can often take the form of key perspectives or slices through the structured information. These slices or dimensions then help inform the possible layouts of widgets or other options by which the information presentation can be varied.

The various widgets or presentation options in an OSF installation can include:

  • tables
  • maps
  • charts
  • topic graphs
  • narratives
  • images
  • labels
  • streaming media

When these, in turn, are matched against the major types or kinds in the system, the clustering of natural layouts begins to emerge. For example, we might show maps by geographic area or charts by indicator or images by type of entity.

The variations posed against a given layout type can be expressed by varying certain kinds of things or record types. The presentation layout remains rather fixed, while the actual filter or specification conditions varies option by option or record by record.

In these patterned areas it is possible to "stub" the links under menu options for a specific layout type (content type), which can then be refined by query or filter condition to request the specific data with which to populate the layout when the link is invoked. "Stubbing" the content allows these placeholders to be specified within the overall content structure of the Drupal site.

Workbench Dashboards

Dashboards created using the OSF Workbench capability represent a combination of multiple widgets and various slices or filter conditions through the data, be they selections by records or types. These combinations can be saved and re-used persistently as a "dashboard".

Since the workbench and its dashboard products can be themed, it is naturally a part of the Design and Presentation section. On the other hand, the process of creating dashboard views is a structured content activity as well. Since the persistent and nameable dashboards can themselves be embedded in Web pages, the possible set-up and assembly of such dashboards can be an important configuration activity in its own right.

User Groups and Permissions

User access, viewing and CRUD (create - read - update - delete) rights occur at two levels within an OSF installation: modules and datasets. The OSF-Drupal OSF modules also have these standard module settings.

User and group settings are accomplished in a Drupal OSF setting using the Organic Groups (OG) module. The combination between tool and dataset CRUD rights leads to a very powerful and flexible basis for controlling who is able to do what with your OSF site. Further information on this topic is provided in the Configuration: Groups and Permissions document.

Other Configurations

A number of other configurations are available for the system: