ACS Templating Requirements

by Karl Goldstein , Christian Brechbühler , Peter Su , and Yonatan Feldman

I. Introduction

The following is a requirements document for the ACS Templating System version 0.5. It has also been called Karl's Templates, the Dynamic Publishing System (DPS), and Stencil. The official package name for the system is now acs-templating .

II. Vision Statement

On websites of sufficient size, a consistent look and feel (the UI, or user interface) for users is important, while for site publishers and administrators, de-coupling the UI from programming allows for easier maintenance and more efficient workflow. Thus the ACS 4 Templating system provides mechanisms that allow programmers and graphic designers to work independently of each other. Templates specify the layout of the page separately from the dynamic content of the page. Graphic designers work primarily on the layout, that is the template, while programmers work primarily on a script or program that generates the dynamic content that fills the blanks in the template. In addition, the templating system provides a way to use a single layout specification for the majority - if not all - of a website's pages, so the overall layout of a site can be more easily administered.

III. System Overview

The templating system provides:

• A set of custom markup tags (using ADP, AOLserver Dynamic Pages) that are used to specify page layout, and to declare where dynamically generated content belongs in the layout.
• An API for specifying the content part of the page. This API is used by programmers to specify the script that generates the content in a page.
• A mechanism for combining the data (from a data source) with the layout (from a layout template) into a single dynamically generated HTML page.
• A mechanism for specifying a single master template to be used for multiple pages.

IV. Use-cases and User-scenarios

The template system is designed to be used by two classes of users: programmers and designers. In building a web site, programmers are generally responsible for defining and implementing the application logic of the site, while designers are more responsible for the presentation. Generally speaking, the application logic generates data for the presentation to display to the user. The template system must provide mechanisms that supports both of these tasks and allows the designer and programmer to work separately, but for their work to be combined at runtime into something that the user sees as a single page.

Thus, pages are naturally split into two parts. The logic part executes application logic and generates data, and the presentation part that specifies the layout of the page and so on.

What is needed is:

1. A notation and API for the programmer specify the application logic and to generate the data to be displayed. In ACS, we call the data that we wish to display a data source or page property. Application logic is driven by the inputs the page gathers from the user request (e.g. the HTTP request), and the computation that the page must perform on this input. This computation will generally create and populate the data sources and page properties. Data sources tend to be connected to database queries, while page properties can be defined by any arbitrary computation.
2. A notation and API for the designer to specify how the data sources and page properties will be presented to the user. This notation will generally take the form of some kind extended HTML.
3. A mechanism for communicating the data sources and page properties from the logic part of the page

Jane Programmer writes a page contract and a draft template, that uses the promised page properties. Joe Designer takes that template and makes it look nice, using his design skills and HTML literacy. Meanwhile Jane Programmer writes code to generate the page properties, typically by querying the database. When both are done, the page is ready for Jim User, who requests it using his web browser.

Alternate scenario: Judy Designer is familiar with the template system. She starts directly from a defined page contract, so Jane Programmer doesn't need to write the draft template.

V. Related Links

• Design document

VI.A Functional Requirements

• 10.0 A Common Solution

  Programmers and designers should only have to learn a single system that serves as a UI substrate for all the functionally specific modules in the toolkit.

  10.0.1

  The system should not make any assumptions about how pages should look or function.

  10.0.5

  Publishers should be able to change the default presentation of any module using a single methodology with minimal exposure to code.

  10.5 Programmer's API

  It must be easy to use/integrate the templating system with any application. This implies a stable, simple, and comprehensive API for programmers to use when writing or converting modules.

  10.5.1 Page Properties Publishing

  Programmers must be able to publish a page's data sources, so that a graphic designer knows what data sources are available.

  10.5.2 Page Contract Implementation

  Programmers must be able to generate and populate the page properties they promise. This includes page properties of types: onevalue, onerow, multirow, onelist, and multilist.

  10.10 Graphic Designer's API

  It must be simple for graphic designers to create and maintain templates that include dynamic data, and other templates. This requires a stable, simple, and comprehensive API for graphic designers to use when creating the layout pages for a site.

  • 10.10.1 Variable Substitution

    Much like the "mail merge" feature of a word processor, template authors must use special tags to position each piece of dynamic data within the layout. Each template is associated with a data dictionary that lists all available variables.

    10.10.2 Use of Components

    To speed development and ensure consistency of design, template authors are encouraged to assemble pages from distinct component templates that may be recycled in different contexts. One typical practice is to build a "master" template for an entire section of a site, with a common header, footer and sidebar layout. For each page request, the "content" template is incorporated dynamically into a specified area of the master template, usually a table cell.

    Another common practice is to build small reusable templates that may be included in other templates as logical components. This may be useful for common "widgets" such as search boxes or lists of related links, as well as for building configurable portal pages where users may assemble different types of content to their liking.

    10.10.3 Inter-Template Communication

    Template authors need a simple mechanism for declaring properties within templates. The most common use of such properties is for configuring elements of an enclosing master template, such as the title, navigation links, and whether to include a search box.

    10.10.4 Conditional Insertion

    Designers often need to tailor the layout depending on the specific data being presented. For example, when presenting a list of library books that a user has checked out, the designer might want to highlight the overdue ones in red. For this, designers must have the ability to write simple program logic (Note: We run the risk of inventing our own language here, we must be careful).

  • 10.10.5 Iteration

    Dynamic pages often present lists of values or records, each of which typically represents the results of a database query. Template authors must have a way to iterate over each value or record in such a list and format it appropriately. In the simplest scenario, the exact HTML is repeated with each iteration. However, template authors often need to vary the design depending on the context.

• 20.0 Separation of Code and Layout

  Programmers should be able to specify the page properties independently of the markup used to present the data in the template. Markup authors should be to able to write templates that reference the page properties without further intervention from the programmer to produce a finished page.

  20.5 Programmer - Graphic Designer Communication

  A graphic designer must be able to look at the documentation for a page in a documentation browser and find out what properties a page publishes and what types they are. This documentation should be available through the standard ACS documentation facilities.

• 30.0 Separation of Page Components

  There should be provisions so that pages can be broken into discrete components to simplify maintenance of the markup code and allow for reuse in different contexts. Examples of common page components include a navigation bar, a search box, or a section of a report or story.

• 40.0 Global Control Over Presentation

  There should be a way to define one or more standard master templates used by most pages on a site, so that changes to the overall look and feel of a site can be made in one place.

• 50.0 Dynamic Selection of Presentation Style

  Given that the same data may be presented in many different ways, there should be a general mechanism for selecting a specific presentation (including file format, layout, character set and language) for each page request, depending on characteristics such as user preference, location, browser type and/or device.

• 60.0 Usability

  Programmers should be able to develop template specifications using their standard tools for writing and maintaining code on the server. HTML authors should be able to access information about template specifications and work on templates remotely without needing shell access to the server.

VI.B Non-functional Requirements

• 100.0 Distribution

  The Templating System must be releasable as part of the ACS and as a separate product. When distributed as part of the ACS all documentation, examples, and source code must follow ACS standards. This includes but is not limited to: using the db_api, using ad_page_contract appropriately.

• 110.0 Performance

  The Templating System must not cause any performance problems to a site. It must be fast and efficient, and it must not slow down page load speed by more than 10% versus a Tcl page with inline HTML.

VII. Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	8/23/2000	Yonatan Feldman
0.2	Merge with previous docs	8/25/2000	Christian Brechbühler
0.3	Edited, reviewed, pending freeze	8/28/2000	Kai Wu

---

yon@arsdigita.com

Last modified: $‌Id: requirements.html,v 1.4 2018/03/24 00:14:57 hectorr Exp $