Archive 1.x:StructDisplay Instruction Manual

This document provides step-by-step use of the structDisplay data templating System.

Overview of Process
First, refer to Figure 1 above for a simple flowchart for how to work with the system.

Strictly speaking, the Data Templating System is more akin to a WYSIWYM system (‘What You See Is What You Mean’) than a true WYSIWYG. While the starting presentation forms can be designed in WYSIWYG mode, the entering of layout fields and code by necessity needs to deal with markup.

The easiest way to start the process is to modify an existing template, which is also the order presented below. After a bit of familiarity with modifying an existing template, how to design a template from scratch will become a bit more obvious.

The basic design process begins with first choosing and understanding the particular instance record type and its attributes and metadata for which the template is being created. The general data form can then be designed in WYSIWYG mode using TinyMCE. To that form are then added the data layout areas.

At entry time, each layout area can be given a name and the system automatically assigns it a background color (for tracking and identity purposes). Once all layout areas are placed within the data form, it is time to switch to the code mode, which is the framework for actually adding the Smarty language markup to the template.

Each layout area when entered actually creates a simple table of two rows and one column, with one of the rows hidden. When you switch to code mode, that second row is now shown and is where the Smarty markup gets entered. This design makes initial layout design cleaner, but also provides a clear tracking mechanism for each layout area when in code mode.

In code mode, most starting Smarty markup is entered via dropdown lists and menus that are contextual for the instance record type at hand. These various options work off of the menu icons as shown for the fourth row of the TinyMCE editor as shown in Figure 2.

During design, you may  either  style (fonts, colors, sizes, formats, etc.) the starting data entry form  or  the variables used by the Smarty markup. You may also modify the code of the Smarty markup with styling as well to achieve your desired presentation effects.

At any time in this design process you may preview the resulting template form, with or without the layout area designations being shown. When the template is in actual use, the layout areas and their names are dropped from display, since they are only a heuristic used to assist the design process.

Any time you switch modes between layout and code or actively save, the template is saved to file. If you wish to see recent changes in preview mode, please make sure you have taken one of these steps to save the update prior to your preview.

[Note: when linked into the Drupal module system, users will also be able to save and select from multiple template names for a given instance type. This option is not active in the current version.]

Step 1: Access the Templating System
To begin the process, you must be logged in as an administrator, from which you then select the Manage Templates option under the BKN Admin Tools section:



Access the System as an Admin

Step 2: Modify an Existing Template
That selection takes you to the Manage Templates page within the BKN node. That page lists all of the available instance record types (the left-hand column entries) and also indicates whether that type has an existing template or not.

Step 2a: Select an Instance Type
If a template already exists, the display will show Update Template ; if one does not exist, the display will show Create Template. For now, let’s modify an existing one by choosing the Update Template option for the Document instance record type:



The remainder of this Part will use this same Document instance record type.

Step 2b: Modify Layout
Picking an Update Template or Create Template link takes you to the TinyMCE layout area design page. Note that the rainbow icon on the fourth menu line in TinyMCE shows as active. Also note that at the bottom of the page you have the link that allows you to switch to Code Mode as well. Remember this location because it is your toggle link switch between layout and code modes during template design.

Finally, also note that the ridged icon at the lower right of the TinyMCE display space allows you to drag-and-drop a larger display area for the editor, as well. (The screenshots that follow are all based on an expanded editor display.) These various areas with  highlights  are:



Note, since we are modifying an existing template that we have a number of colored layout areas already shown in the main editor display area.

(NOTE: At this juncture, we could make many changes, add text, style and configure the surrounding template form, etc., by simply interacting with the standard TinyMCE editor functions. However, since general editor functionality is not specifically a focus of this manual, we’ll stick strictly to the template functionality.)

Step 2c: Add New Layout Area
Adding a new layout area is simple.

First, place the cursor in the display area where the new layout is desired. Then, pick the rainbow icon on the TinyMCE menu. That will insert a new layout area on the screen, which you can then give a name for tracking purposes. In our case, well name this new layout area ‘Abstract’, which results in this transition from before to after in the editor:



Though the labels of layout areas are only used for heuristic purposes and never display on the final template, it is good practice to name them similar to the purpose or attribute(s) they represent.

In any event, each layout area is given its own unique color (if the color is undesired or has insufficient contrast, merely delete the area and enter a new one).

Nested Layout
Using this same technique, it is also possible to create nested layouts. To do so, simply place your cursor within an existing layout area (in the case below, the ‘Nested Layout Example’) before invoking the rainbow icon.

You can enter as many nested layout areas as you’d like; in this case, we have entered and then labeled two of them:



Table Layout
Another example shows how a general data form entered via the standard TinyMCE can also be used. In this case, we have entered a two-column table, where we have attribute labels in the first row, with the actual data variables (layout areas) in the second row.

Note in this example that we can readily style these attribute labels – bold, italics, centered, etc. – directly using the TinyMCE editor:



Use of tables such as this can create structured data reports similar to the infoboxes in Wikipedia articles or other structured displays. These are the preferred means to precisely control the areas in which data actually appears in your final templates

(Note that the tables used to create the heuristic layout areas do not themselves affect the actual display dimensions used in the template; they only affect the relative placement on the page.)

Delete a Layout
Deleting a layout area is quite easy. Simply right click on the applicable layout area table and then pick the Delete table option:



Note, immediately after entry you can also use the Undo icon on the TinyMCE menu to delete a layout area (though sometimes you have to invoke Undo multiple times because of the number of steps taken when in either layout or code modes).

Step 2d: Switch to Code Mode; Fill in Code Details
Once you are satisfied with the general layout, it is time to enter the specific template markup. This is likely where you will spend most of your design time, and there are considerable options available for invoking, entering and styling the Smarty code.

To switch to code mode, pick that icon at the bottom right of the TinyMCE application. Recall this is the standard toggle area for switching between layout and code modes.

A number of change when in code mode. First, the rainbow icon for the layout mode is grayed out, and the four adjacent code icons on the fourth row of the TinyMCE icons become active. Second, the layout areas expand to now show the markup code areas. And, third, a new Save template icon appears in the application footer:



Step 2d-1: Enter Attribute Information
The first set of tasks when in code mode is to enter the Smarty markup invoking the various attributes for that instance record type. This is done via the first code icon (or the second icon from the left on the last row of TinyMCE icons), the green plus icon with the dropdown arrow marker. That icon calls up a list of available attributes:



Recall what we said earlier: by virtue of selecting an instance type, the system knows what attributes are available for a record of that type, which is shown in the dropdown list in the figure above.

Each attribute may be selected for values, description or label; in most cases, values will be the preferred choice.

Since there are a number of menu choices for this Attribute option, here’s a bit more definition as to use and purpose:


 * Attribute value – this is the actual menu path for entering the markup code to display the appropriate attribute value(s) on the template form, as shown next:




 * Attribute label – this option enters the attribute’s “preferred label” at the cursor point, useful when you are prefacing the actual data values with a readable label for the attribute (such as in an attribute-value pair)
 * Attribute description – as shown in Figure 11 above, this option merely provides an online help aid with a longer description of the given attribute
 * Value – this submenu option arises for the Attribute value and acts to insert the actual data value for the given attribute at the cursor position
 * Link – this submenu option only applies to attributes that might also have a resource URI associated with them (as opposed to a literal value); if invoked, link enters a live HTML link at the cursor position with a link URL based on the attribute’s name
 * Iterate values – this option brings up and embeds the foreach loop, useful when there are multiple values for a given attribute and you desire to iterate the presentation of results over them. This option is helpful when you want to create value lists or populate a table when therer are multiple values for that attribute.



In all of these cases, the complete Smarty variable expression is entered at the cursor point, as shown in the figure directly above.

This process of working with the Attribute option should be repeated until all desired attribute code is entered into the template.

Step 2d-2: Enter Control Structures (loops, if-then, etc.)
The next icon to the right is where some pre-assembled Smarty control structures can be entered at the cursor point:



In this example we are entering code at the cursor entry point for the foreach control structure, which governs looping behavior over multiple values for a given attribute. Other control structures that may be invoked are:


 * If – is a conditional structure that sets if a value exists or has a certain value, then a particular action is conducted
 * If-else – is also a conditional structure that sets a similar conditions to the if structure, but if the condition fails then other else conditions can also be tested with particular actions in a cascading format.



Final variable declarations and other code markup adjustments are necessary after entry of these structures. See Part 4 for further information regarding the Smarty language.

Step 2d-3: Use Direct (HTML Edit) Mode as Necessary
When in code mode, of course, it is often necessary to write or edit the actual code.

At any time when working with TinyMCE it is possible to invoke the edit HTML code option, which also appears on the same row with the other Data Template System icons:



Invoking this option brings up the standard TinyMCE HTML code editor popup:



Note this literal code view shows all markup: HTML + Smarty + the temporary markup used by the Data Templating System during design mode.

Choosing Update saves the changes and returns to the standard TinyMCE view.

Step 2e: Style the Template Code and Variables
In Step 2c we saw how the presentation template can be styled when in standard TinyMCE mode. But, styling can also be applied when in code mode, too.

Before Styling
For example, here is the full attribute code with a loop for a layout area that includes both authors and created dates for an article:



After Styling
However, we can see that much of the information to be presented is in the form of variables. While standard TinyMCE styling can be applied to literals and structural elements, there is no ability to style variables.

The only way to style variables is directly in the Smarty markup.

Recall that Smarty combines its own markup with HTML. When HTML markup is added to Smarty markup, the HTML information is retained when the template is ultimately used.

In this case, what we have done is to italicize each of the variable listings. (If you go into HTML code view, you will see the  italics markup.) What is shown on screen are the WYSIWYG italicized values with some background highlighting added for emphasis:



After Code Styling with Italics (w/ added highlighting)

When entering such style information, care must be taken to inclusively bracket the curly braces that delimit the variable. (Actually, since the Smarty markup is eventually removed in the final step of template creation, the HTML styling can extend broader than these curly brace delimit boundaries and still work.)

Step 2f: Modify Other Template Aspects with Smarty Variables
Other template aspects might also be suitable to Smarty variable treatment, including template title, links, images and so forth, as this screenshot shows:



Code for these standard fields is invoked from the fourth button on the Data Templating System line of icons.

Instance Record Options
These three menu options mean:


 * Instance record label – enters a human readable label for the instance record. For example, for a person, it could be a name; for a document, it could be its title, etc.
 * Instance record type – displays the type of the instance record, and
 * Instance record description – a human readable description of the instance record type (or the “thing” at hand) if available. For a person, this could be a short biography; for a document, it could be its abstract.

Note that the instance record label is most often desired, since it is equivalent to a title to a templated record form. The other two options are less frequently invoked.

Titles
One of the common code fields is to display a default label (in this case ‘Untitled’) in the absence of an existing title for the record.

By picking the item in the dropdown, the code is inserted into the main display area. Then, the code should be cut and then pasted into the actual title field for the template:



Of course, any other text could be substituted for ‘Untitled’ as desired.

Links
A different trick can be played with links:



Invoking this option places this code at the cursor point:



Now, by next invoking the Add an attribute option, an existing variable can then be entered at the put-variable-here point, with the template result being a live link to the variable.

Step 2g: Preview Results
At any point during this design process, the template and how it will work with live data may be previewed. The preview is based on the last saved version, which occurs either by switching between layout and code modes or by invoking Save template when in code mode.

Preview with Layout Areas
The first of two preview options is to view with the heuristic layout areas included. This option is invoked by the second-lo-last icon on the Data Templating System row:



When invoked, this preview pulls up a live data record generated at random, but with the colored layout areas also included. It is useful during preliminary design when styling and layout designs are still being refined and a visible association with the layout areas is desired.

In this example, note in particular the styling and labels in the first and third layout areas that come directly from styling the Smarty markup code:



Clean Preview
The second preview option, invoked from the last button on the Data Templating System row of icons, presents the template as it would normally display:



Which then displays this sample record:



Step 3: Create a New Template
Working with an existing template gives us a basis for understanding the basics of the templating system. We can now explore some of the additional considerations that go into creating a new template.

Step 3a: Understand Instance Type and Attributes
Clearly, before beginning to design a template, it is important to understand the nature of the instance type and its records. What are the attributes? Metadata? Data types?

What are we trying to achieve with the template? A listing of items, whereby perhaps only titles and minimum information is desired? A complete record, with all attributes shown? Do many records have incomplete data, and therefore we want to be able to skip empty fields? Are there exemplary layout designs we would like to mimic? Does some data need to be searched or sorted? Any other specific requirements?

These types of questions and an understanding of the available data are important to consider before actual design and coding begins.

Step 3b: Set Basic Template Structure
Though by no means universal, some basic template structures are quite common.

Step 3b-1: Set Title Field
Every template begins with the {$InstanceRecordLabel} ; if provision for empty labels is important, see Step 2ef.

Step 3b-2: Set Standard Sections
A couple of code sections are quite common to templates. Code insertions for these may be found from the fifth button on the Data Templating System icon row:



The Unassigned variables section lists results for each of the instance type’s attributes that have not been defined in the main template body. The Links-to-section presents a listing of cross-links that the record points to in other records, with live links.

When clicked, each option has its code inserted at the cursor position. Here are the results:



Step 3c: Set Layout Structure
The basic template layout structure should then be designed; see Steps 2b and 2c above.

Step 3d: Set and Style Attribute Variables
As with modifying a template, the new template should have its attribute variables set, with possible style modifications; see Steps 2d and 2e.

Step 3e: Modify Other Fields and Preview
As with modifying a template, the new template may need additional fields added and the template refined; see Steps 2f and 2g.

Step 4: Use a Template within a Node
Data templates appear wherever an instance record is displayed under the Browse Resource and Search Resource links.