Archive 1.x:StructDisplay

The structDisplay tool to create OSF-Drupal templates using some user interfaces has been deprecated.

structDisplay is OSF-Drupal's data display and templating system, available as a separate Drupal module. structDisplay combines the unique strengths of four contributing components, in the process overcoming some of their individual weaknesses:


 * Smarty – a fast, productive, and extensible templating language
 * TinyMCE – WYSIWYG data forms design (also used for Drupal WYSIWYG editing)
 * Drupal – a flexible and powerful deployment framework, and
 * RDF – a data model that helps pre-define the structure for any given template.

Their combination leads to faster development and deployment, with many of the standard template development steps automated. The structDisplay Instruction Manual complements this document.

What is a Template?
A template is a structured format for information presentation that is dynamically populated (“driven”) by individual data records. The source of such data is most often a database of one form or another. Templates are all around us and include such structures as recipes, calendars, business cards, search engine results pages, or any patterned way to present data.

Templates are thus a presentation framework for underlying data. They can be designed and styled and used separately from the actual data that drives them. A generic product “template”, for example, might be the basis for a very specific variant presenting music album or car product information.

Over time, good architectural design has showed the wisdom of keeping presentation design and frameworks separate from the data that drives them. This design philosophy is central to structDisplay.

Basic Workflow
A central pivot to structDisplay is the Smarty templating language. Smarty is a simplified way to represent data access via variables from underlying datastores. It has specific functionality and language for handling data processing flows such as cycling through multiple records, filtering, conditional presentation, etc. Smarty is an addition to HTML and is layered on top of it. Thus, Smarty markup, like PHP the scripting language in which it is written, is designed to be combined with HTML.

The RDF model allows various instance records to be organized into hierarchical classes of types with associated attributes. Once a given instance type is selected, its available attributes and metadata are automatically known and used by the system. Moreover, the classification of the types themselves allows the inheritance of template designs and uses from parental types.

This structural knowledge of instance types allows the Smarty templating language to be pre-populated with applicable attributes when designing templates. In turn, this knowledge also allows WYSIWYG design elements to be presented in dropdown lists during template form design using TinyMCE.

This basic workflow is as follows:

'''Figure 1. Simple structDisplay System Workflow'''

Once an instance type is selected, its report template can be designed in WYSIWYG (“layout”) mode. Each layout area is given a name and is presented on screen as layout “blocks”. Since the input structural vocabulary from the input data is also known, specialized markup and processing plugins to TinyMCE can be invoked during the design and coding stages; this markup is then later stripped after template design completion in order to drive the standard Smarty templating engine.

Actual template design by the user is first done at a gross layout design mode and then in a coding mode. Successful template construction does require some minimal coding skills (similar to HTML or scripting languages), though re-use and modification of existing templates helps aid this process.

Templates are automatically saved with necessary hooks generated at every step of the design process. This enables the templates-in-design to be previewed at any stage for what the eventual dynamic report of the data might look like.

The internal system, then, combines the HTML forms design with Smarty templating code markup to produce a TinyMCE view of the form, that when saved is converted to the final templating form. The system automatically generates queries to the RDF datastore via SPARQL for the population of initial attributes listings used during the design phase, then for the actual instance record data retrievals that then populate the template presentation form.

Integration with TinyMCE WYSIWYG Editor
Basically, any HTML page with simple to complex design components – including tables and HTML forms – may be used as the input basis for a structDisplay data template.

The TinyMCE RTE (rich-text editor) is a popular framework for doing such HTML design in “what-you-see-is-what-you-get" mode (WYSIWYG). It is also a common RTE for the Drupal system.

TinyMCE is a JavaScript application that presents text editing capabilities similar to a standard word processor, only with specific applicability to HTML. Fonts and paragraphs can be styled; images and links may be inserted; and more complex structures such as tables may be entered and edited. The result of such editing is properly formed HTML markup.

structDisplay adds further plugins to the TinyMCE editor, resulting in some new menu icons to the system, as this figure shows:

'''Figure 2. Integration with the TinyMCE WYSIWYG Editor'''

This fourth row of buttons adds this functionality:

This additional functionality provides a design and coding bridge between the standard HTML of TinyMCE and the templating language and conventions of Smarty. Note that the table indicates two main modes of working with the editor: Layout and Code. These modes are also described in Part 2.

In these modes, all existing functionality of TinyMCE is available to you. Thus, you can edit and design your data form as you would any Web page. But, via these added functions, you can now enter and edit Smarty markup as well.

Basic Smarty Constructs Used in the Design
In its normal standalone use, Smarty is a bit challenging to install and use. In fact, most online manuals and tutorials on Smarty are premised on such standalone use.

However, structDisplay's design takes care of most of the messy details in the background. Many fewer Smarty commands and conventions need be known to work effectively with the system. (Though all of the power of the full Smarty template language, and indeed PHP itself, can also be applied to the templates.)

Smarty variables are the means by which actual data gets entered into the right slots within a data presentation template (as well as for record identifiers and record metadata, too). By convention, Smarty variables start with a $ sign and are enclosed within curly brackets (or braces). In structDisplay, the variable name is already preassigned with the requisite $ sign (e.g., ). Because our template data is coming from instance records that may have multiple values for a given attribute, the sequence number in bracket is just a counter for the array value (starting with zero, thus, ).

About the only thing you need to know when entering variable information is whether your variable is a literal value (such as a string name or number) or may be a link to a referenced resource.

Generally, templates are useful when a patterned results presentation is desired for a given instance type. However, structDisplay also uses Smarty control structures within a template when there may be multiple values for a given attribute that need to be looped over or to only present results that meet certain filters or conditions.

While there are a number of such ‘control structures’ in Smarty, the three most commonly used are,  and. The  is a looping structure; the other two are conditional.

Finally, there are some other ‘standard’ actions that might be taken against a Smarty template – such as ignoring empty variable (or attribute) fields or listing what links to a given record or listing all variables that have not been explicitly included in a template – are provided as simple inclusions that can be entered into a given template.

Limitations of Current Version
In its first release versions, structDisplay does have a number of limitations:


 * Only a single template design may be defined and active at a given time for a single instance type (such as ‘Document’ or ‘Organization’). The temporary fix to get around this limitation is to define a new instance type
 * The templates may not be assigned to blocks within a Drupal page layout, thus limiting flexibility somewhat, and
 * Styling (CSS) is not tied in with the standard Drupal templating system.

structDisplay revisions are underway that will address parts of these limitations.