Specification: XML Sapiens (SAPI) 1.1 Second editions Red Graphic Systems March 22, 2005 Current version: www.xmlsapiens.org/spec/ (in PDF) Author: Dmitry Sheiko, Red Graphic Systems Reviewers: Maxim Baryshnikov, Red Graphic Systems Pavel Levkovich, Red Graphic Systems © 2004-2005 Red Graphic Systems www.redgraphic.com Abstract This specification defines XML Sapiens (SAPI - Simple Application Programming Interface) version 1.1 — the language describing programming interfaces for CMS- powered websites. XML Sapiens (hereinafter SAPI) – is an SGML application conforming to International Standard ISO 8879 — Standard Generalized Markup Language [ISO8879]. The language complies with the XML specification (http://www.w3.org/TR/2004/REC- xml11-20040204/). Document Status Version 1.1 Public discussion on SAPI takes place at http://xmlsapiens.org/board/. Available Formats SAPI 1.1 Specification is also available in the following formats: Text file: http://xmlsapiens.org/spec/sapi11.txt (121 Êb), GZIP TAR-file containing HTML-documents: http://xmlsapiens.org/spec/sapi11.tgz (260 Êb), ZIP-file containing HTML-documents (ZIP, not EXE): http://xmlsapiens.org/spec/sapi11.zip (260 Êb), PDF-file: http://xmlsapiens.org/spec/sapi11.pdf (2.5 Ìb). In the event there is a discrepancy between the printed version and the electronic version of SAPI specification, the electronic version shall prevail. Available Languages The English version of this specification is the only normative version. However, for translations of this document, see http://xmlsapiens.org/spec/. Errata The list of known errors in this specification is available at http://xmlsapiens.org/spec/error/ Please report errors in this document to editor@xmlsapiens.org. Contents 1 Introduction 5 2 About SAPI Specification 5 2.1 Specification Structure 5 2.2 Document Conventions 6 2.2.1 Conventions 6 2.2.2 Elements and Attributes 6 2.2.3 Notes and Examples 6 2.3 Acknowledgements 7 2.4 Copyright Notice 7 3 SAPI Architecture 8 3.1 Introduction 8 3.1.1 What is SAPI? 8 3.1.2 What Is Site Functionality? 9 3.1.3 Brief History of the Language 9 3.1.4 How to Use SAPI? 9 3.1.5 SAPI and XSLT 9 3.1.6 SAPI and interface markup languages 12 3.2 SAPI Model of Data Presentation 13 3.2.1 Presentation Template 14 3.2.2 Presentation Code 14 3.2.3 SAPI Document 14 3.3 Objects of SAPI Documents 14 3.3.1 Query Containers 14 3.3.2 Static Data Containers 15 3.3.3 Dynamic Data Containers 15 3.3.4 Objects Identification 15 3.4 DDC Call Parameters 17 3.5 DDC Stream Redirection 18 3.6 SAPI Expressions 18 3.7 Inclusion of SAPI Documents 19 3.7.1 Inclusions of CMS System Language Code 19 3.8 SAPI-based CMS 19 3.8.1 Model of Managed Site 19 3.8.2 Structure of a SAPI-based CMS 21 3.8.3 SAPI Parser 23 3.8.4 Recommended CMS Environment Variables 25 3.8.5 Recommended CMS Applications 27 3.8.6 SAPI Namespace 34 4 Document Structure 35 4.1 Introduction 35 4.2 SGML Constructs Used in SAPI 35 4.2.1 Elements 35 4.2.2 Attributes 36 4.2.3 Character References 37 4.2.4 Comments 37 4.3 How to Read the SAPI DTD 37 4.3.1 DTD Comments 38 4.3.2 Parameter Entity Definitions 38 4.3.3 Element Declarations 38 4.3.4 Attribute Declarations 39 4.4 Basic Data Types 40 4.4.1 Case Information 40 4.4.2 Basic Data Types 40 4.4.3 Text Strings 41 4.4.4 URIs 41 4.4.5 Single Characters 41 4.4.6 Character Data 41 4.4.7 Dates and Times 41 5 Global Structure of a SAPI Document 42 5.1 Introduction to the SAPI Document Structure 42 5.2 SAPI Version Information 43 5.3 The SAPI Element 44 5.3.1 Attribute version 44 5.3.2 Attribute xmlns:sapi 45 5.3.3 Attribute encoding 45 5.3.4 Attribute cache 45 5.3.5 Attribute mdate 45 5.4 SAPI Document Namespace 45 5.4.1 Element SAPI:NAMESPACES 46 5.4.2 Element SAPI:NAMESPACE 46 5.4.3 Element SAPI:SITE 47 5.4.4 Element SAPI:SITE-LANG 47 5.4.5 Element SAPI:SITE-ITEM 48 5.4.6 Element SAPI:CONTAINER 48 6 Body of the SAPI Document 50 6.1 Code Owner Information 50 6.1.1 Element SAPI:AUTHOR 50 6.1.2 Element SAPI:NAME 50 6.1.3 Element SAPI:EMAIL 50 6.1.4 Element SAPI:URI 51 6.2 Comments 51 6.2.1 Element SAPI:COMMENTS 51 6.3 Data Containers 51 6.3.1 Query Container (Element SAPI:QC) 52 6.3.2 Static Data Container (Element SAPI:SDC) 55 6.3.3 Dynamic Data Container (SAPI:DDC) 57 6.4 Pointers 67 6.4.1 Data Pointer (Element SAPI:VALUE-OF) 67 6.4.2 Data Pointer (Attribute SAPI:%Attribib) 68 6.4.3 Container Pointer (Element SAPI:VALUE-OF) 68 6.5 Additional Operands 69 6.5.1 SQL Query Selection (Element SAPI:SQL) 69 7 XML Reference Information for SAPI 70 7.1 Document Validation 71 8 References 71 8.1 Normative References 71 8.2 Informative References 73 9 Index 75 9.1 Index of Elements 75 9.2 Index of Attributes 76 10 Conclusion 77 1 Introduction XML Sapiens is an XML based language for user interface form algorithm descriptions. XML Sapiens is aimed to help at cutting down time expenses in a web-project development thus lowering project's cost and to minimize laborious system programming in web-site development. It is achieved by providing tools for user interface form logics management. By user interface forms here we mean fragments of a document able to change its state depending on user's actions. XML Sapiens concept presumes division of a document into abstract layers: data, presentation and algorithms for user interface forms. 2 About SAPI Specification 2.1 Specification Structure The specification consists of the following sections: Sections 2 and 4: Introduction to SAPI The introduction gives overview of SAPI, provides a brief history of the development of the SAPI language and provides some tips on SAPI usage. «Documentation Structure» contains guidelines on how to read SAPI Document Type Definitions (DTD). Sections 5 - 6: SAPI Reference Manual The major part of the reference manual is the SAPI language reference, which defines all elements and attributes of the language. This document has been designed by topics rather than by the grammar of SAPI. The language reference consists of the following information: Objects that make up a logical model of a website document: › Interaction of these objects. › Definition of managed content queries. › Description of functional scenarios. Formal SGML-definition of SAPI: SGML-definition of SAPI DTD: http://xmlsapiens.org/spec/sapi11.dtd. References A list of normative and informative documents. Indexes Two indexes provide users rapid access to the definition: elements and attributes. 2.2 Document Conventions 2.2.1 Conventions This specification is intended to help a wide range of CMS-developers to organize user interface management using SAPI. The specification allows its readers to become familiar with the SAPI language, to master it and use it in various projects. The specification can be approached in several ways: › Read from beginning to end. The specification begins with a general presentation of the SAPI language and becomes more technical and specific towards the end. › Quick access to information. In order to get information about syntax and semantics as quickly as possible, the electronic version of the specification includes the following features: o Every reference to an element or attribute is linked to its definition in the specification. o The front pages of the three sections of the specification extend the initial table of contents with more detail about that section. 2.2.2 Elements and Attributes Names of the elements are written in uppercase letters (for example, SAPI:COMMENTS). Names of the attributes are written in lowercase letters (for example, title). Please note that in SAPI the names of elements and attributes are not case-sensitive. The convention is meant to encourage readability. Element and attribute names in this document have been marked up and may be rendered specially by some user agents. Each attribute definition specifies the type of its value. If the type allows a small set of possible values, the definition lists the set of values separated by a bar (|). After the type information, each attribute definition indicates the case-sensitivity of its values in square brackets ("[]"). See Section 4.4.1 for details. 2.2.3 Notes and Examples Informative notes are emphasized to stand out from the surrounding text and may be rendered specially by some user agents. The examples and notes have been marked up and may be rendered specially by some user agents. 2.3 Acknowledgements Thanks to everyone who has helped to author the SAPI specification. Special thanks to the management of Red Graphic Systems (http://www.redgraphic.com) for project support, financial and technical assistance. Many thanks to the project team: Author of the specification: Dmitry Sheiko (d@redgraphic.com) Reviewers: Maxim Baryshnikov (mb@redgraphic.com) and Pavel Levkovich (pl@redgraphic.com) Thanks to Irina Znosok (i@redgraphic.com) for the design of the project www.xmlsapiens.org. Thanks to Pavel Levkovich (pl@redgraphic.com) for the layout of the project www.xmlsapiens.org and HTML-version of the specification. Special thanks to Maxim Baryshnikov for the development of the SAPI-parser and demo SAPI-oriented CMS (SAPID). Many thanks to the members of the working group HTML 4 for the sample and template of a high-class structure and contents of the language specification (Copyright © World Wide Web Consortium, http://www.w3.org/TR/html401). 2.4 Copyright Notice Copyright © 2004 Red Graphic Systems, (www.redgraphic.com). All rights reserved. The documents available at http://xmlsapiens.org are provided by their respective copyright holders according to the following license. By obtaining, using and/or copying this document or the document from xmlsapiens.org containing a reference to the present notice, you agree that you have read, understood, and will comply with the following terms and conditions: Permission to use, copy and distribute any part of this document or the document from xmlsapiens.org containing a reference to the present notice, by any means and for any purpose and without fee or royalty is hereby granted, provided that the following information appears on all copies of the document or portions thereof: › Reference to the original document of xmlsapiens.org or its URL. › Copyright notice of the original author, if available. Otherwise, the following notice shall be provided: "Copyright © Red Graphic Systems. All rights reserved." › Document status, if available. › If space permits, the full text of the NOTICE below shall be included. › Besides, any software or document based on or derived from this document or its parts should include a Thank you notice to the copyright holders. This license grants no permissions to modify the original document or create any documents on its basis. THIS DOCUMENT IS PROVIDED "AS IS"; COPYRIGHT HOLDERS GIVE NO WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, COPYRIGHT HOLDERS GIVE NO WARRANTIES OF MERCHANTIBILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THIS DOCUMENTS WILL NOT INFRINGE ANY THIRD-PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS. COPYRIGHT HOLDERS WILL BEAR NO LIABILITY FOR ANY DAMAGE OR LOSS, DIRECT, INDIRECT, INTENTIONAL OR REGULAR, CAUSED BY THE USE OF THIS DOCUMENT OR PORTIONS THEREOF. The name and trademarks of copyright holders may NOT be used in advertising pertaining to this document or its contents without specific, written prior permission. Title to copyright in this document will at all times remain with copyright holders. 3 SAPI Architecture 3.1 Introduction 3.1.1 What is SAPI? SAPI (Simple Application Programming Interface for CMS) is a user interface description language for CMS-powered sites. The official name of the technology is XML Sapiens. SAPI is aimed to help at cutting down time expenses in a web-project development thus lowering project's cost and to minimize laborious system programming in web-site development. It is achieved by providing tools for user interface form logics management. By user interface forms here we mean fragments of a document able to change its state depending on user's actions. SAPI is an XML-based language that allows authors to manage the objects of the site document and their interaction, to detach the functional level of the site from the presentation and data levels (see section 3.8.1). SAPI unifies the description of user interfaces for CMS and enables free interchange of such through "SAPI Works Gallery" (http://xmlsapiens.org/lib/). 3.1.2 What Is Site Functionality? The functionality of a site, its part or a separate document is, in the context of this document, a user interface that enables interaction between the user and the site. The most typical examples of functional solutions are the following: navigation site menu, document path indicator, news module, dynamic authorization form, etc. Any functional solution can be defined in a SAPI-document and used on the site. A functional solution can be also imported from the "SAPI Works Gallery" (http://xmlsapiens.org/lib/), tailored to specific needs and then implemented in a project. 3.1.3 Brief History of the Language In the CMS market there are two popular approaches to the management of site functionality: modular and XSLT transformation. The modular approach implies that the presentation of site documents (see section 3.2.1) contains pointers to CMS modules. It is obvious that in this case document presentation is defined by the CMS modules. Adjustment of document objects returned by the CMS modules is not that flexible. In case of XSLT templates, there is a possibility to work with structured meta-data. However, XSL programming requires additional developer's skills. In both cases there is no unique concept on how to detach functionality from data presentation. In the middle of 2003, Red Graphic Systems faced the task to create an environment for web-application development that could enable efficient management of web-project content, as well as of the presentation and functionality (see section.3.8.1). As a result, the Site Sapiens platform (http://www.sitesapiens.com) was developed, which derived from a SAPI language prototype. On the basis of the platform a number of projects have been implemented for well-known Russian brands (http://job.cocacola.ru, http://www.kdo.ru, http://www.amsgroup.ru, etc.), which allows us to speak about success of the SAPI technology. 3.1.4 How to Use SAPI? In order to use SAPI in your CMS you will need a SAPI parser. You can use an available solution of Red Graphic Systems for PHP or develop your own parser based on the recommendations of the SAPI working group (for details please refer to section 3.8.1). 3.1.5 SAPI and XSLT Any web document can be logically divided into data and their presentation. Besides, a web document as a rule contains elements of user interface (navigation, forms for information input, ect.). In compliance with W3C recommendations, document presentation - in spite of its data - is managed by XSLT technology (http://www.w3.org/TR/xslt). Document's data are placed in an XML file and changed according to XSLT template rules. With the help of XSLT it is also possible to assign presentation for user interface forms, but initial data of these forms in the XML file are necessary for such a change. SAPI allows defining data source for each user interface form as well as describing the forms' logics. SAPI' processor will analyze developer's instructions and will broaden the initial XML file with user interface forms' data for the current environment state. Based on the data received from the XML file, XSLT transformer will create the final form of the document. Thus SAPI helps to separate abstract constituents of a web-site: data, presentation and user interface. Initial XML data1 data2 <sapi:apply name="qc.title.value"> SAPI file script interface.sapi Final XML data1 data2 /intro/ Introduction /chapter1/ Chapter 1 /chapter2/ Chapter 2 <![CDATA[Introduction]]> Content

]]> 3.1.6 SAPI and interface markup languages SAPI can be used for declaration of user interface rendering, but in doesn't contain API to access a component library at client side like XAML, XUL, MXML (Flex) do. SAPI can be used in tandem with (www.uiml.org) for dynamic creation of skeleton for application area and element definition list (content of APP/DEFINE elements). SAPI may also help to improve initial documents XUL (http://www.mozilla.org/projects/xul/), XAML (http://msdn.microsoft.com/library/default.asp?url=/library/en- us/dnintlong/html/longhornch03.asp), Flex (http://www.macromedia.com/software/flex/), Web Applications 1.0 (http://www.whatwg.org/specs/web-apps/current-work/) to define editable areas and to define models of user interface forms. 3.2 SAPI Model of Data Presentation For better understanding of the SAPI technology, let's analyze the process of document generation in a SAPI-based CMS. The input data for the process are the presentation definition documents for the given document group. Based on the functional scheme of the project requirements specification and graphical design, the presentation code is generated. The presentation code is converted to a document named "presentation template". The presentation code corresponds to the syntax of the selected markup language (HTML, XHTML, SVG, etc.). A SAPI document is also generated describing the maintenance interface for this site document. The presentation code contains pointers to SAPI objects, which implies substitution of code returned by these objects when generating site documents. Both documents are processed by a SAPI parser and, as a consequence, a site document is generated. Figure 1. SAPI model of data presentation The SAPI-parser analyzes the presentation code and, when finding the pointers to SAPI objects, refers to the corresponding SAPI document for description. Pointers to the query containers define the interface of the managed content queries in the CMS administration area. At the presentation level (see section 3.8.1.3) a CMS pointer to a query container returns the corresponding content – the same that was provided by an operator in the CMS administration area. Data containers return the code in accordance with the functional scenario preset in their definition. 3.2.1 Presentation Template Within the concept of SAPI-based management of website content, for any type of document or a group of documents a template can be defined, which specifies the layout of the document displayed on the website. The presentation template contains a presentation code and pointers to SAPI document objects. 3.2.2 Presentation Code To define the layout of the document displayed in the browser or in any other client-based user software for interaction with the site, the code of the selected markup language is used. SAPI has no limitations for the list of allowed markup languages. However, it is recommended to use XML-based languages or HTML. 3.2.3 SAPI Document A SAPI document is a code that contains elements of the specification and a valid SAPI- DTD. A SAPI document defines the interfaces of the site documents. 3.3 Objects of SAPI Documents Data containers form the basis of the SAPI language. It is the content of the containers that defines the scenarios of functional solutions for a document of a SAPI-based CMS. There are three types of containers in the SAPI language: query containers (SAPI:QC), static data containers (SAPI:SDC), and dynamic data containers (SAPI:DDC). 3.3.1 Query Containers Query containers (see section 6.3.1) refer to the fragments of the document displayed on the site; the content of these fragments can be modified by the CMS administrator. The containers contain the code of user data queries and related formatting. The query code is provided in the syntax of the markup language of the presentation code. For example: In the example above, the markup element HTML INPUT is used. The pointer in the SAPI:VALUE attribute (see section 0) indicates that while generating the interface in the administrative area the value of the VALUE attribute of the INPUT element will contain the data that correspond to the query. Though the form naming system is out of the scope of the SAPI specification, it should be considered that when transmitting the CMS form data, the data must be identified and saved. 3.3.2 Static Data Containers Static data containers (see section 6.3.3) refer to the recurring static data fragments of the document displayed on the website. These containers contain the presentation code of the fragments they refer to. 3.3.3 Dynamic Data Containers Dynamic data containers (see section 6.3.4) refer to the fragments of the document displayed on the website. The content of these containers is based on a functional algorithm. These containers contain the description of functional algorithms. 3.3.3.1 Categories of Dynamic Data Containers SAPI implies the classification of dynamic data containers by categories determined by specific functionality. The category of the container communicates the processing peculiarities for the container to the CMS parser. The category of the container is specified in the CATEGORY attribute of the SAPI:DDC element; it classifies the functional solution during exchange in the "SAPI Works Gallery" (http://xmlsapiens.org/lib/). Category Description Processing Peculiarities Information Channel infochannel.news News lines Interface in the administrative area infochannel.articles Article lines Interface in the administrative area infochannel.custom Custom lines Interface in the administrative area infochannel.periodical Periodical lines Interface in the administrative area Navigation navigation.calendar «Calendar» navigation form for information channels - navigation.menu Document structure navigation - navigation.track Path navigation to the current page - navigation.custom Other navigation - Forms form.custom Any dynamic forms - Other custom Other solutions that do not come under any of the categories mentioned above. - 3.3.4 Objects Identification A SAPI object can be called through the SAPI:APPLY pointer, or directly in the condition expression. Objects identifiers have the following syntax: object_name.object_attribute SAPI objects have the following attributes: Category Description value Value returned by the object name Name of the object type Type of the object (query container, dynamic data container, static data container, CMS environment variable) value.length Length of the value string returned by the object value.date[format_string] Transformation of the UNIXSTAMP date into a given format Syntax of the Format String for value.date Character Description a "am" or "pm" A "AM" or "PM" B Swatch Internet time d Day (date) of the month, 2 digits with leading zero, if needed; i.e. from "01" to "31" D Day of the week, alphabetical, 3 characters; e.g. "Fri" F Month, alphabetical, e.g. "January" (according to the regional settings) g Hour, 12-hours format without leading zeros; i.e. from "1" to "12" G Hour, 24- hours format without leading zeros; i.e. from "0" to "23" h Hour, 12- hours format; i.e. from "01" to "12" H Hour, 24- hours format; i.e. from "00" to "23" i Minutes, i.e. from "00" to "59" I (uppercase i) "1", if Daylight Savings Time, otherwise "0". j Day (date) of the month without leading zeros; i.e. from "1" to "31" l (lowercase 'L') Day of the week, alphabetical, long; e.g. "Friday" L Indicates if the year is a leap year: "0" or "1" m Month; i.e. from "01" to "12" M Month, alphabetical, 3 characters; e.g. "Jan" n Month without leading zeros; i.e. from "1" to "12" O GMT time difference, in hours; i.e. "+0200" s Seconds; i.e. from "00" to "59" S English ordinal suffix for days (dates) of the month, 2 characters; i.e. "st", "nd", "rd" or "th" t Number of days in the month; i.e. from "28" to "31" T Time zone settings on the computer; i.e. "EST" or "MDT" U Unix Epoch seconds (starting with January 1 1970 00:00:00 GMT) w Day of the week, digital, i.e. from "0" (Sunday) to "6" (Saturday) Y Year, 4 digits; i.e. "1999" y Year, 2 digits; i.e. "99" z Day of the year; i.e. from "0" to "365" Z Time zone shift, in seconds (i.e. from "-43200" to "43200"). Time zone shift to the west of the UTC is always negative, and to the east of the UTC is always positive. Sample output of static data container content, where the name of the container is var1: Sample content output of a node of the CMS applications nodes set (see section 3.8.5.1) in the body of a dynamic data container (name of the container implies "this", name of the set implies "this", name of the set variable is "envar"): Sample expression of a dynamic data container condition in the body of the container (name of the container implies "this", name of the set implies "this", name of the set variable is envar): Sample content output of a CMS environment variable, where the name of the variable is var1: 3.3.4.1 Properties of the Node of the CMS Application Nodes Set A node of the set (see section 3.8.5.1) returned by a CMS application has the following properties: Command Description position Returns the position of the current node within the nodes set (starting with 1). count Returns the number of nodes within the nodes set. length Returns the number of nodes within the nodes set. The number of nodes in the CMS application nodes set can be found out in the following way: 3.4 DDC Call Parameters If it is necessary to use in templates one and the same DDC, but differently, depending on its position, it is possible to indicate DDC call parameters for further analysis of they values in DDC conditions. Delivery of DDC parameters is performed in the following way: Value of param 1 Value of param 2 Values of DDC parameters will be available in DDC conditions in the following variables: this.param.pvar1.value and this.param.pvar2.value 3.5 DDC Stream Redirection If representation template projecting requires to start CMS-application of particular DDC, but not return DDC source code into the template immediately it is necessary to use the DDC stream redirection into environment variable. Thus a new variable will be created which will take the DDC code. Further this variable can be shown once or several times in the template by the SAPI:APPLY element. DDC stream redirection syntaxes is as follows: ... ... 3.6 SAPI Expressions SAPI expressions can be used to describe the logic of functional solutions in dynamic data containers. While developing the expression operands the constructions of the XML script language XEXPR (http://www.w3.org/TR/2000/NOTE-xexpr-20001121/) where used. The SAPI specification supports expressions of comparison. There expressions can return one of the two values (0 or1), meaning respectively either FLASE or TRUE In the content of attributes SAPI specification allows the following expression operands: lt(A, B, C) (less), leq(A, B, C) (less or equal), geq(A, B, C) (more or equal), eq(A, B, C) or == (equal), neq(A, B, C) or != (not equal), gt(A, B, C) (more). A B C – values, separated by commas. For grouping the expressions, it is allowed to use round brackets, and logic operands as well: and(A, B, C) or AND(A, B, C) and or(A, B, C) or OR(A, B, C). It is also allowed to use mathematic operands: add(A, B, C) or + (add – for numerals, merge – for strings), subtract(A, B, C) or - (substraction), multiply(A, B, C) or * (multiplication), divide(A, B, C) (division). SAPI expressions allow direct reference CMS environment variables. E.g. The expressions can be used in the EXP attribute of the SAPI:WHEN element, in the SELECT attribute of the SAPI:FOR-EACH element, in the EXP attribute of the SAPI:APPLY element or in the attributes of SAPI:%Attrib format If it is necessary to get the executive result of the SAPI expression, the following syntaxes can be used in container code (SAPI:CODE element) 3.7 Inclusion of SAPI Documents 3.7.1 Inclusions of CMS System Language Code In certain cases a direct access to the code of CMS development language is required. SAPI supports inclusions of system language code of the following syntax: When a SAPI data container contains inclusions of external language code, it should be specified in the SYSTEM container attribute. System language inclusions are not recommended, since they cause loss of system solutions portability. 3.8 SAPI-based CMS 3.8.1 Model of Managed Site A site managed by CMS can be represented by four logical levels. The data level defines the infrastructure of incoming content. The functional level describes the models of interactions between various user groups from data presentation interfaces. The presentation level is a mature user interface that enables delivery of the requested media data to the Internet/Intranet users. The management level is an interface of CMS administrative area; it allows users to manage data, functionality and presentation levels. Figure 2. Four-level model of a managed site 3.8.1.1 Data Level The infrastructure of the data arriving at the site can have various implementations. However, SAPI contains guidelines on using the query containers (see section 6.3.1), which define the management interface by the contents provided in the CMS administrative area. When saying that the CMS is used in the site administration mode, the administrative level or the administrative area is implied. 3.8.1.2 Functional Level The functional level of a site is described in the SAPI document. 3.8.1.3 Presentation Level This document describes the following data presentation model: When displaying any part of the site, according to the parameters of the requested document (URI), CMS determines the environment variables compatible with the SAPI specification. Then the system identifier of the requested site document and its related definition are determined, including the pointers to the document presentation template and the SAPI document. These parameters are transferred to the SAPI parser for generation of the site document presentation. The CMS mode in the process of visitors looking through the site implies the presentation level or the presentation area. Figure 3. Model of the data presentation process 3.8.2 Structure of a SAPI-based CMS According to the SAPI specification, CMS contains a prehandler that analyzes the current URL and defines the environment variables (see section 3.8.4). CMS also contains a sufficient number of presentation templates (see section 3.2.1), a SAPI document (see section 3.2.3), a data repository and a parser that generates the document. Figure 4. Structure of a SAPI-based CMS MVC paradigm of XML Sapiens 3.8.2.1 CMS Data Repository The CMS data repository stores the managed content of the site. Each document of the site has its own unique identifier. Each element of the site can have an unlimited number of query containers, which act as content fragments in the process of document presentation. The content provided in a certain query container for a certain document in the administrative area is placed in the data repository so that it could be restored by the same parameters when viewing the site at the presentation level. RDBS is the most frequently used data repository. 3.8.3 SAPI Parser The SAPI specification does not limit the developers to one platform or one technological solution for CMS documents assembling. To get a general idea of the SAPI concept, considering the principle of document generation in a SAPI-based CMS during site viewing is suggested. 3.8.3.1 SAPI-Transformations during Site Viewing At the initial stage of the process, according to the URL typed in the address bar or bound to a link, CMS environment variables (see section 3.8.4) are determined. Variable this.template contains the pointer to the presentation template for the current document. The parser uses this pointer to access the presentation template and check for the presence of SAPI objects pointers (SAPI:APPLY, section 6.4). To ensure full compliance with the SAPI specification, the presence of constructs should be analyzed, since their content is transmitted to the system language for further execution. Using the pointers in the presentation template, the parser calls the SAPI document for objects content (see section 3.3). The SAPI document can be converted into a database table: in this case the reference to the object description can be represented as a SQL query. The parser generates a copy of the template, which is a document prototype. During SAPI processing, the parser replaces the pointers of the objects with the obtained content. 3.8.3.1.1 Analysis of Data Pointers When the parser refers to a SAPI document through a data pointer, it returns to the document prototype a value of the CMS environment variable with the name specified in the SELECT attribute of the SAPI:APPLY element. 3.8.3.1.2 Analysis of Query Containers When the parser refers to a SAPI document through a pointer to a query container, it generates a query to the CMS data repository. Its parameters are the current values of the environment variables that identify the document or its part in the data repository and the name of the query container. The parser receives the content for the current query from the data repository and returns it to the document prototype. Let's consider a query container pointer: The content will be transferred to the document prototype. It will correspond to the CMS data repository container newsbody (news content) of the document with identifier "this.id". 3.8.3.1.3 Analysis of Static Data Containers When the parser refers to a SAPI document through a pointer to a static data container (see section 6.3.2), it returns the content of this container to the document prototype. Pointers to SAPI objects and constructs found in the container must be processed by the same pattern. 3.8.3.1.4 Analysis of Dynamic Data Containers When the parser refers to a SAPI document through a pointer to a dynamic data container (see section 6.3.3), it analyzes the content of the container. First of all, the conditions of the root element SAPI:CHOOSE are analyzed. The condition expressions SAPI:EXP are parsed in the syntax specified in part 3.6. The content of the conditions, the expressions of which are TRUE, are added to the returned value thread. If the condition contains the SAPI:FOR-EACH construct, the application specified in the SELECT attribute is called. A similar condition analysis will be carried out as many times as there are values in the returned nodes set (see section 3.8.5.1). As soon as all instructions of the dynamic data container are implemented, the parser returns to the document prototype the returned value thread. Pointers to SAPI objects and constructs found in the container must be processed by the same pattern. 3.8.3.1.5 Analysis of Additional Elements When the parser finds the SAPI:SQL element with the TYPE attribute equal to «fetch- array», it executes the SQL query specified in the QUERY attribute. The result of the query is put into the CMS environment variable with the name specified in the NAME attribute. Pointers to SAPI objects and constructs found in the container must be processed by the same pattern. 3.8.3.1.6 Analysis of System Language Inclusions When the parser finds constructs, it sends their content to the CMS system language for execution. The result of implemented instructions is returned into the document prototype. 3.8.3.2 SAPI-Transformation during Site Administration Administration area is the interface for document content management. A document may contain an unlimited number of query containers, which will be represented in the interface by corresponding forms. Types of the forms are defined in the query container. In the administration area the parser operates the same way as in the presentation area, except that the query containers are processed differently. When the parser finds a query container pointer, it displays the code of its content. At that, the content of the query, if provided, is transmitted from the data repository and inserted into the query code. It is implied that a form is specified (e.g. ) in the query container body. Form attribute SAPI:attribute indicates to the parser where (in which attribute of the form element) to insert the query content when generating the administrative interface. Example: 3.8.4 Recommended CMS Environment Variables CMS environment variables are the variables created in the process of site document generation. Environment variables are mostly defined at the beginning of the process based on address string parameters (URL). Environment variables contain all the necessary information about the selected document and about the executed interface command. The meaning of SAPI:EXP expressions is in comparative operations with the CMS environment variables. Starting at 1.1 version of XML Sapiens specification, environment variables represented as object tree. Root element of this tree is abstract element "project". It defines interface of entire information area. "Project" objects set unite all site definition objects. Objects' names correspond to variables, identifying sites or language versions of sites in information area structure. Each of these site objects contains own set of objects. As a result, to get value of configuration record "feedback_email" can be called in the following way: project.sitea_en.config.feedback_email.value which is equivalent to sitea_en.config.feedback_email.value If this value belongs to current site, syntax simplifies: config.feedback_email.value Below site objects collection is listed Namespace variable.value Variable of the site http_path.value URL of the site root_path.value Absolute address Navigation date_start.value Selection starting date date_finish.value Selection finishing date limit_start.value Starting element of the selection list limit_finish.value Finishing element of the selection list Address String (URI) REQUEST_URI.value Content of REQUEST_URI argv_string.value Content of the address string (URI) without navigation part. Supposed, that first part of address string defines document location, and the second part defines specific part of a document. I.e. navigation inside a document is built using this (second) part of address string. argv[el_index].value Content of the given address string argument len_argv.value Number of address string arguments last_argv.value Content of the last address string argument prev_last_argv.value Content of the last but one address string argument argv_nav[el_index].value Contents of given argument of navigation part of address string len_argv_nav.value Count of arguments in navigation part of address string argv_virtual.year.value The value of "year" filter in address string argv_virtual.month.value The value of "month" filter in address string argv_virtual.day.value The value of "day" filter in address string argv_virtual.id.value The value of "id" filter in address string Current Document document.id.value Identifier of the current document document.variable.value Variable (object name) of the current document document.title.value Title of the current document document.id_parent.value Identifier of the parent section/document document.template.value Identifier of the presentation template document.flag_children.value Flag indicating the availability of children for the current document document.meta_description.value Document description document.meta_keywords.value Document keywords document.printversion The variable contains the TRUE value, if the requested document is a document print version. document.error404 The variable contains the TRUE value, if the requested document is not found. Path to the Current Document trackinfo[el_index].href.value URI of the given path element trackinfo[el_index].title.value Title of the given path element Configuration config.variable_name.value Value of the given configuration variable Other user.name Authorized user's name user.group[group_name] Flag which defines current user's membership in a group user.role Authorized user's role user.astatus Authorized user's status keywords.value User retrieval request timestamp.value Current time in the TIMESTAMP format error_message.value Content of the error message 3.8.5 Recommended CMS Applications SAPI does not describe functional solutions at the system level. The structure of the data repository and interaction with it are designed at the discretion of CMS developers. However, for description unification and exchange of functional solutions (see "SAPI Works Gallery" http://xmlsapiens.org/lib/) the specification provides a list of recommended applications to be referred to in dynamic data containers. The list contains applications (functions of the CMS programming language), their descriptions, parameters and variables of returned nodes sets (see section 3.8.5.1). The SAPI specification provides no recommendations on the content of the functions, but recommends input data (parameters) and output data (nodes properties of the CMS application nodes set). The most recent list of recommended applications for SAPI-based CMS is available at: http://xmlsapiens.org/spec/functionlist/ Information Channels get_infochannel() Description: Information channel: news line, article line, special line Parameters: ( [string additional_command_string]) Additional command string may contain the following values, separated by a white space: _LIMIT(n1,n2)_ - nodes_amount_limitation _CURRENTYEAR_ - filter list by a current year _SELECTEDYEAR_ - filter list by a year, defined in URI _SELECTEDMONTH_ - filter list by a month, defined in URI _SELECTEDDAY_ - filter list by a day, defined in URI _ALLITEMS_ - children for all nodes _PARENTNAME_ - name of a parent node _RELATION(A,B,C)_ - filter list by one or more relation characteristic, where A, B, C – identifiers of these characteristics. _ORDER(RANDOM)_ - randomize list _ORDER(NAME,ASC)_ - order list by node names ascending _ORDER(NAME,DESC)_ - order list by node names descending _ORDER(DATEC,ASC)_ - order list by node creation date ascending _ORDER(DATEC,DESC)_ - order list by node creation date descending List variables: this.this.value.leght - number of elements in the list this.this.ñount.value – current number of the list element this.this.title.value – title of the list element this.this.announce.value – abstract of the element this.this.id.value - identifier of the list element this.this.variable.value - variable of the list element (part of URI) this.this.href.value - reference of the list element Periodicals get_rubriclist() Description: List of periodicals' rubrics Parameters: ( [int nodes_amount_limitation, string additional_command_string]) List variables: this.this.value.leght - number of elements in the list this.this.ñount.value – current number of the list element this.this.title.value – title of the list element this.this.announce.value – abstract of the element this.this.id.value - identifier of the list element this.this.variable.value - variable of the list element (part of URI) this.this.href.value - reference of the list element get_issueslist() Description: Periodical issues list Parameters: ( [int nodes_amount_limitation, string additional_command_string]) List variables: this.this.value.leght - number of elements in the list this.this.ñount.value – current number of the list element this.this.title.value – title of the list element this.this.announce.value – abstract of the element this.this.id.value - identifier of the list element this.this.variable.value - variable of the list element (part of URL) this.this.href.value - reference of the list element Navigation get_tree() Description: Get tree of structure Parameters: ([int home_page_URL, string additional_command_string]) Additional command string may contain the following values, separated by a white space: _ALLITEMS_ - children for all nodes _RELATION(A,B,C)_ - filter list by one or more relation characteristic, where A, B, C – identifiers of these characteristics. _ORDER(RANDOM)_ - randomize list _ORDER(NAME,ASC)_ - order list by node names ascending _ORDER(NAME,DESC)_ - order list by node names descending _ORDER(DATEC,ASC)_ - order list by node creation date ascending _ORDER(DATEC,DESC)_ - order list by node creation date descending List variables: this.this.value.leght - number of elements in the list this.this.ñount.value – current number of the list element this.this.title.value – title of the list element this.this.level.value – nesting level of the element this.this.id.value - identifier of the list element this.this.variable.value - variable of the list element (part of URL) this.this.var_parent.value - variable of the parent list element this.this.href.value - reference of the list element get_track() Description: Path to the current document Parameters: ([int home_page_URL, string additional_command_string]) Ïåðåìåííûå ïåðå÷èñëåíèÿ: List variables: this.this.value.leght - number of elements in the list this.this.ñount.value – current number of the list element this.this.title.value – title of the list element this.this.level.value – nesting level of the element this.this.variable.value - variable of the list element (part of URL) this.this.var_parent.value - variable of the parent list element this.this.href.value - reference of the list element get_pagesnavigation() Description: This function generates linear navigation links and titles for per- page navigation, if required. Parameters: ( [int home_page_URL, string additional_command_string]) List variables: this.this.value.leght - number of elements in the list this.this.ñount.value – current number of the list element this.this.prev_count.value – link for «page back» this.this.next_count.value - link for «page forward» this.this.href.value – link of the linear navigation this.this.item10_20.value – page pointers in format 10-20 this.this.item.value - page pointers in format 1 2 get_infochannelfilter() Description: This function generates links and selection titles for the given container by years, months or days. Parameters: ([string container_name, string selection_pointer, string additional_command_string]) Available values for the selection pointer: year, month, day List variables: this.this.value.leght - number of elements in the list this.this.ñount.value – current number of the list element this.this.title.value – title of the list element this.this.href.value – reference of the list element get_searchresults() Description: This function generates links and titles search results. Parameters: ([string additional_command_string]) List variables: this.this.value.leght - number of elements in the list this.this.ñount.value – current number of the list element this.this.title.value – title of the list element this.this.announce.value – abstract of the element this.this.counter.value – title of the list element this.this.href.value - reference of the list element Comments: The additional application parameter is the search request string returned to POST. get_calendar() Description: Navigation calendar form Parameters: ([string target_container_name, string additional_command_string]) List variables: this.this.value.leght - number of elements in the list this.this.ñount.value – current number of the list element On-line Catalog get_goodslist() Description: List of on-line catalog articles (goods) Parameters: ([int articles_amount_limitation, string additional_command_string]) Additional command string may contain the following values, separated by a white space: _ALLITEMS_ - children for all nodes _PARENTNAME_ - name of a parent node _RELATION(A,B,C)_ - filter list by one or more relation characteristic, where A, B, C – identifiers of these characteristics. _ORDER(RANDOM)_ - randomize list _ORDER(NAME,ASC)_ - order list by node names ascending _ORDER(NAME,DESC)_ - order list by node names descending _ORDER(DATEC,ASC)_ - order list by node creation date ascending _ORDER(DATEC,DESC)_ - order list by node creation date descending _ORDER(catalogue_field, ASC or DESC)_ - sort list by given catalogue field (ascending or descending) List variables: this.this.value.leght - number of elements in the list this.this.ñount.value – current number of the list element this.this.title.value –title of the list element this.this.level.value – nesting level of the element this.this.id.value - identifier of the list element this.this.variable.value - variable of the list element (part of URL) this.this.href.value - reference of the list element this.this.var_parent.value - variable of the parent list element Services get_survey() Description: Survey content Parameters: ([string query_point_name]) List variables: this.this.value.leght - number of elements in the list this.this.ñount.value – current number of the list element this.this.title.value – survey title this.this.answer_title.value – title of answer variant this.this.votes.value - number of votes for the variant this.this.percent.value - percentage of votes for the variant this.this.length.value - total votes Other get_childrenpages() Description: Children documents of the current document including content Parameters: ( [int home_page_URL , int page_amount_limitation, string additional_command_string]) List variables: this.this.value.leght - number of elements in the list this.this.ñount.value – current number of the list element this.this.title.value –title of the list element this.this.level.value – nesting level of the element this.this.id.value - identifier of the list element this.this.variable.value - variable of the list element (part of URL) this.this.href.value - reference of the list element this.this.var_parent.value - variable of the parent list element this.this.query_container_name.value - content get_parentpage() Description: Description of the parent page Parameters: ( [string additional_command_string]) List variables: this.this.value.leght - number of elements in the list this.this.ñount.value – current number of the list element this.this.title.value –title of the list element this.this.level.value – nesting level of the element this.this.id.value - identifier of the list element this.this.variable.value - variable of the list element (part of URL) this.this.href.value - reference of the list element this.this.var_parent.value - variable of the parent list element this.this.query_container_name.value - content Table 1. Recommended CMS applications Additional string in the application parameters (additional_command_string) may contain one of the following commands: Command Description first Function returns the first node of the nodes set only. last Function returns the last node of the nodes set only. id[string_id] Function returns a set of nodes according to the transmitted string of identifiers separated by commas. 3.8.5.1 CMS Application Nodes Set When in the element a reference to the system programming language application is provided, it is implied that the application will return to the CMS parser a set of nodes, the elements of which will be sequentially transmitted to the content of the element and become the list content. Each node of the returned nodes set contains the attributes defined in the Table of recommended CMS applications (see section 3.8.5). Sample reference to CMS application nodes attributes: 3.8.5.2 Peculiarities of SAPI Information Channels Description In the context of the SAPI specification, an information channel is an information structure that contains a navigation interface with a list of document summaries. The summaries may contain document references. For implementation of such a structure, a dynamic data container interacting with the CMS application get_infochannel should be created. The container may contain the description of output conditions for the list or for the document content. To enable the CMS parser to create the interface for information channel content management, the query containers generating the information channel document content should be defined in the container at least once. The default parent page in the documented CMS structure for an information channel is the page containing the document with a channel navigation list. When a reference to the given information channel is required, attribute PARENT-ID of the SAPI:DDC element is used. To enable the parser to determine query containers corresponding to the entries of the administration interface lists, attributes INDEXDATE, INDEXTITLE and INDEXDESC of the SAPI:DDC element should be used (see section 6.3.3) Example of dynamic data container describing the news line: Dmitry Sheiko sheiko@cmsdevelopment.com www.cmsdevelopment.com Date


3.8.6 SAPI Namespace Conventional site document structure is a hierarchical tree with information area in its root. Each site of the space is the basis of its own structure branch. The next tree level is represented by language versions of sites, each containing pages (sections). The SAPI specification allows describing the "visibility" scope for SAPI objects in the common document structure of the information space. For this purpose, the namespace for referencing during data container generation is defined by the SAPI:NAMESPACE element. The namespace definition describes the way it is connected to the areas of common document structure of information space. 4 Document Structure 4.1 Introduction The Extensible Markup Language (XML) is a subset of SGML (http://www.w3.org/TR/2004/REC-xml11-20040204/). SGML is a system for defining markup languages. It allows authors to mark up their documents by representing structural, presentational, and semantic information alongside content (http://www.w3.org/MarkUp/SGML/). SAPI is one of the examples of a SGML markup language. SAPI is compatible with XML. SAPI definitions are provided in this document with the SGML syntax. Names of SAPI elements mostly correspond to related XSL objects (http://www.w3.org/Style/XSL/). 4.2 SGML Constructs Used in SAPI 4.2.1 Elements A SGML document type definition declares element types that represent structures or desired behavior. SAPI includes element types that represent data containers, comments, functions, etc. Each element type declaration generally describes three parts: a start tag, content, and an end tag. The element's name appears in the start tag (written ) and the end tag (written ); note the slash before the element name in the end tag. For example, the start and end tags of the element type delimit the items in a list: Dmitry Sheiko sheiko@cmsdevelopment.com www.cmsdevelopment.com Some SAPI element types have no content (SAPI:APPLY, SAPI:SQL, etc.). Such element types should be defined in the syntax of the «empty element tag» (see http://www.w3.org/TR/2004/REC-xml11-20040204/#sec-starttags): Correctness restrictions: Unique attribute specification An attribute name cannot be used more than once within one start tag (or an empty element tag). Correctness restrictions: Absence of character < in attribute values Characters < and > are not allowed in attribute values. All element types mentioned in this specification are listed in the Elements Reference. 4.2.2 Attributes Elements may have associated properties, called attributes, which may have values (by default, or set by authors or scripts). Attribute/value pairs appear before the final ">" of an element's start tag. Any number of (legal) attribute value pairs, separated by spaces, may appear in an element's start tag. They may appear in any order. In this example the NAME attribute is set for the SDC element (see section 6.3.2): html… By default, SGML requires that all attribute values be delimited using either double quotation marks (ASCII decimal 34) or single quotation marks (ASCII decimal 39). Single quotation marks can be included within the attribute value when the value is delimited by double quotation marks, and vice versa. Authors may also use numeric character references (see section 4.2.3) to represent double quotes (") and single quotes ('). For double quotes authors can also use the the character entity reference ". The attribute value may only contain letters (a-z and A-Z), digits (0-9), hyphens (ASCII decimal 45) and periods (ASCII decimal 46). Using quotation marks is strongly recommended. Attribute names are never case-sensitive. Attribute values are generally case-sensitive. The definition of each attribute in the attributes list indicates whether its value is case-sensitive. List of all attributes defined in this specification is provided in the Attributes Reference (see section 9.2). 4.2.3 Character References Character references are numeric or symbolic names for characters that may be included in a SAPI document. They are useful for referring to rarely used characters, or those that authoring tools make it difficult or impossible to enter. You will see character references throughout this document; they begin with a "&" sign and end with a semi-colon (;). Some common examples include the following: ? "<" represents the < sign. ? ">" represents the > sign. ? """ represents the " mark. ? "å" (in decimal) represents the letter "a" with a small circle above it. ? "И" (in decimal) represents the Cyrillic capital letter "I". ? "水" (in hexadecimal) represents the Chinese character for water. SAPI character references are discussed in detail later in this section on the "List of SAPI Document Characters". According to the XML specification, using the   reference is not allowed; you can get a non-breaking space using the   reference. 4.2.4 Comments SAPI comments have the following syntax: White space is not permitted between the markup declaration open delimiter(""). A common error is to include a string of hyphens ("---") within a comment. Authors should avoid putting two or more adjacent hyphens inside comments. Information that appears between comments has no special meaning (for example, character references (see section 4.2.3) are not interpreted as such). 4.3 How to Read the SAPI DTD Each element and attribute declaration in this specification is accompanied by its document type definition fragment. We have chosen to include the DTD fragments in the specification rather than seek more approachable, but longer and less precise means of describing properties of an element. The following tutorial should allow readers unfamiliar with SGML to read the DTD and understand the technical details of the SAPI specification. 4.3.1 DTD Comments In DTDs, comments may spread over one or more lines. In the DTD, comments are delimited by a pair of "--" marks, e.g. Here, the comment "named property value" explains the use of the SAPI:APPLY element type. Comments in the DTD are informative only. 4.3.2 Parameter Entity Definitions The SAPI DTD begins with a series of parameter entity definitions. A parameter entity definition defines a kind of macro that may be referenced and expanded elsewhere in the DTD. These macros may not appear in SAPI documents, only in the DTD. Other types of macros, called character references (see section 4.2.3), may be used in the text of a SAPI document or within attribute values. When a parameter entity is referred to by name in the DTD, it is expanded into a string. A parameter entity definition begins with the keyword . Instances of parameter entities in the DTD begin with "%", then the parameter entity name, and followed by an optional ";". The following example defines the string that the "%sample;" entity will expand to: The string the parameter entity expands to may contain other parameter entity names. These names are expanded recursively. 4.3.3 Element Declarations A SAPI DTD consists of element type declarations and their attributes. The character ends it. Between these the following are specified: 1. The element name. 2. Whether the element tag is optional. Two hyphens that appear after the element name mean that the start and end tags are mandatory. One hyphen followed by letter "O" indicates that the end tag can be omitted. A pair of "O" letters indicate that both the start and end tags can be omitted. 3. The element content, if any. The allowed content for an element is called its content model. Element types that are designed to have no content are called empty elements. The content model for such element types is declared using the keyword "EMPTY". The following example demonstrates a declaration of an empty element type: ? The element type being declared is SAPI:APPLY. ? The hyphen and the following "O" indicate that the end tag can be omitted, but together with the content model "EMPTY", this is strengthened to the rule that the end tag must be omitted. ? The "EMPTY" keyword means that instances of this type must not have content. 4.3.3.1 Content Model Definitions The content model describes what may be contained by an instance of an element type. Content model definitions may include: ? The names of allowed or forbidden element types. ? DTD entities. ? Document text (indicated by the SGML construct "#PCDATA"). The text may contain character references (see section 4.2.3). Note that they begin with "&" and end with a semicolon (e.g., "Hergé's adventures of Tintin" contains the character entity reference for the "e acute" character). The content model of an element is specified with the following syntax: ( ... ) Delimits groups. A | B Either A or B must occur, but not both. A , B Either A or B must occur, in that order. A & B Both A and B must occur, in any order. A? A must occur zero or one time. A* A must occur zero or more times. A+ A must occur one or more time. Here is a sample SAPI DTD: The SAPI:EXP element (see section 6.3.3.17) may only contain text and character references (see section 4.2.3); - this is indicated by the SGML data type CDATA. Some SAPI element types use an additional SGML feature to exclude elements from their content model. Excluded elements are preceded by a hyphen. Explicit exclusions override permitted elements. 4.3.4 Attribute Declarations The . Each attribute definition is a triplet that defines: ? The name of an attribute. ? The type of the attribute's value or an explicit set of possible values. Values defined explicitly by the DTD are case-insensitive. ? Whether the default value of the attribute is implicit (keyword "#IMPLIED"), in which case the default value must be supplied by the user agent (in some cases via inheritance from parent elements); always required (keyword "#REQUIRED"); or fixed to the given value (keyword "#FIXED"). Some attribute definitions explicitly specify a default value for the attribute. 4.3.4.1 DTD Entities in Attribute Definitions Attribute definitions may also contain parameter entity references. 4.3.4.2 Boolean Attributes Some attributes play the role of boolean variables. Their presence in the start tag of an element implies that the value of the attribute is "TRUE". Their absence implies the "FALSE" value. Boolean attributes may legally take a single value: the name of the attribute itself. 4.4 Basic Data Types This section of the specification describes the basic data types that may appear as an element's content or an attribute's value. 4.4.1 Case Information Each attribute definition includes information about case-sensitivity of its values. The case information is presented with the following keys: CS The value is case-sensitive (i.e., user agents interpret "a" and "A" differently). CI The value is case-insensitive (i.e., user agents interpret "a" and "A" as the same). CN The value is not subject to case changes, e.g., because it is a number or a character from the document character set. CA The element or attribute definition itself provides case information. CT Refer to the type definition for details about case-sensitivity. If an attribute value is a list, the keys apply to each value in the list, unless otherwise indicated. 4.4.2 Basic Data Types The document type definition specifies the syntax of SAPI element content and attribute values using SGML tokens (e.g., PCDATA, CDATA, NAME, ID, etc). See [ISO8879, http://www.iso.ch/cate/d16387.html] for their full definitions. The following is a summary of key information: CDATA is a sequence of characters from the document character set and may include character references (see section 4.2.3). User agents should interpret attribute values as follows: › Replace character references (see section 4.2.3) with characters; › Ignore line feeds; › Replace each carriage return or tab with a single space. 4.4.3 Text Strings A number of attributes (%Text; in the DTD) take the text that is meant to be "human readable". Introductory information about attributes can be found in the tutorial discussion of attributes. 4.4.4 URIs This specification uses the term URI as defined in [URI] (see [RFC1630, http://ds.internic.net/rfc/rfc1630.txt]). Note that URIs include URLs (as defined in [RFC1738, http://ds.internic.net/rfc/rfc1738.txt] and [RFC1808, http://ds.internic.net/rfc/rfc1808.txt]). URIs are represented in the DTD by the parameter entity %URI;. URIs in general are case-sensitive. There may be URIs, or parts of URIs, where case doesn't matter (e.g., machine names), but identifying these may not be easy. Users should always consider URIs case-sensitive (to be on the safe side). 4.4.5 Single Characters Certain attributes call a single character from a set of document characters. These attributes take the %Character type in the DTD. Single characters can be specified using character references (e.g. "&"). 4.4.6 Character Data Certain attributes call single document characters. These attributes take the %Text type in the DTD. 4.4.7 Dates and Times [ISO8601] allows many options and variations in the presentation of dates and times. The current specification uses one of the formats described in the [DATETIME] profile for its definition of legal date/time strings ( %Datetime in the DTD). The format is: YYYY-MM-DDThh:mm:ssTZD where: YYYY four-digit year ÌÌ two-digit month (01=January, etc.) DD two-digit day of month (01 through 31) hh two digits of hour (00 through 23) (am/pm NOT allowed) mm two digits of minute (00 through 59) ss two digits of second (00 through 59) TZD time zone designator Time zone designators: Z indicates UTC (Coordinated Universal Time). The "Z" must be uppercase. +hh:mm indicates that the time is a local time which is hh hours and mm minutes ahead of UTC. -hh:mm indicates that the time is a local time which is hh hours and mm minutes behind of UTC. Exactly the components shown here must be present, with exactly this punctuation. Note that the "T" letter appears literally in the string (it must be uppercase), to indicate the beginning of the time element, as specified in [ISO8601] If a generating application does not know the time to the second, it may use the value "00" for seconds (and minutes and hours, if necessary). Note. [DATETIME] does not address the issue of leap seconds. 5 Global Structure of a SAPI Document 5.1 Introduction to the SAPI Document Structure A SAPI document consists of three parts: 1. Lines containing the SAPI DTD version being used (see section 5.2); 2. Lines indicating that the language belongs to the XML language group; 3. Root section containing the body of the document. The body can be implemented by the SAPI element. White space (spaces, newlines, tabs, and comments) may appear before or after each section. Here is an example of a simple SAPI document:

Hello world!

 5.2 SAPI Version Information A valid SAPI document declares what version of SAPI is used in the document. Document type declaration names the document type definition (DTD) in this document (see [ISO8879]). To date, only one version of the SAPI language is available, and accordingly – only one DTD: (http://www.xmlsapiens.org/spec/sapi11.dtd). 5.3 The SAPI Element Start tag: mandatory, End tag: mandatory Attribute definitions version = %Text [CN] Mandatory. The value of this attribute specifies which SAPI DTD version governs the current document. xmlns:sapi = %URI [CN] Optional. Formal XML NS definition. encoding = %Charset [CI] Recommended. The value of this attribute specifies the language encoding used in the document. cache = %Charset [CI] Optional. The value of this attribute shows to the parser, whether caching of the current document is allowed. mdate = %Datetime [CN] Optional. This attribute contains the date and time of the latest document modification. After document type declaration, the remainder of an HTML document is comprised in the SAPI element. Thus, a typical SAPI document has the following structure: ... 5.3.1 Attribute version Attribute definitions version = %Text [CN] Mandatory. The value of this attribute specifies which SAPI DTD version governs the current document. This attribute indicates to the parser, according to which version of the SAPI language the document should be analyzed. The DTD pattern for the SAPI version of the current document is specified in the xmlns:sapi attribute. 5.3.2 Attribute xmlns:sapi Attributes definition xmlns:sapi = %URI [CN] Optional. Formal definition of SAPI XML Namespaces (http://www.w3.org/TR/REC-xml-names) 5.3.3 Attribute encoding Attributes definition encoding = %Charset [CI] Optional.The value of this attribute specifies the language encoding used in the document. 5.3.4 Attribute cache Attributes definition cache = %Charset [CI] Optional. Value "nocache" of this attribute indicates to the parser, whether caching of the current document is allowed. Example of this document: ... 5.3.5 Attribute mdate Attributes definition mdate = %Datetime [CN] Optional. This attribute contains the date and time of the latest document modification. Though this attribute is optional for the SAPI element, the availability of date and time of modifications can help to organize the version control of SAPI documents in a SAPI-based CMS. 5.4 SAPI Document Namespace SAPI allows binding of SAPI document objects and logical site areas. For this purpose an element describing namespaces for SAPI objects is created. 5.4.1 Element SAPI:NAMESPACES Start tag: mandatory, End tag: mandatory The SAPI namespace is defined in the document body (the SAPI element). Sample document: ... 5.4.2 Element SAPI:NAMESPACE Start tag: mandatory, End tag: mandatory Attributes definition name = %Text [CN] Mandatory. The value of this attribute specifies the namespace name. This name is the identifier of the namespace in SAPI objects attribute. Example: ... 5.4.2.1 Attribute name Attributes definition name = %Text [CN] Mandatory. The value of this attribute specifies the namespace name. This name is the identifier of the namespace in SAPI objects attribute. 5.4.3 Element SAPI:SITE Start tag: mandatory, End tag: ommited Attributes definition id = %Text [CN] Mandatory. The value of this attribute specifies the identifier of the displayed site. 5.4.3.1 Attribute id Attributes definition id = %Text [CN] Mandatory. The value of this attribute specifies the identifier of the displayed site. This attribute contains the site identifier in the CMS-specific syntax. In case the CMS maintains one site of information space, the function of this element has no meaning. 5.4.4 Element SAPI:SITE-LANG Start tag: mandatory, End tag: ommited Attributes definition id = %Text [CN] Mandatory. The value of this attribute specifies the language version of the displayed site. 5.4.4.1 Attribute id Attributes definition id = %Text [CN] Mandatory. The value of this attribute specifies the identifier of the language version of the displayed site. This attribute contains the identifier of the site language version in the CMS-specific syntax. In case the CMS maintains one language version of the site information space, the function of this element has no meaning. 5.4.5 Element SAPI:SITE-ITEM Start tag: mandatory, End tag: ommited Attributes definition id = %Text [CN] Mandatory. The value of this attribute specifies the identifier of the section of the displayed site. 5.4.5.1 Attribute id Attributes definition id = %Text [CN] Mandatory. The value of this attribute specifies the identifier of the section of the displayed site. This attribute contains a site section identifier in the CMS-specific syntax. In case the CMS maintains just one section of site information space, the function of this element has no meaning. 5.4.6 Element SAPI:CONTAINER Start tag: mandatory, End tag: ommited Attributes definition name = %Text [CN] Mandatory. The value of this attribute specifies the SAPI document container. 5.4.6.1 Attribute name Attributes definition name = %Text [CN] Mandatory. The value of this attribute specifies the name of SAPI container. This attribute allows describing the namespace of a certain container. 6 Body of the SAPI Document 6.1 Code Owner Information One or more authors may be assigned to a SAPI document or to a data container (see section 6.3). To assign a group of authors, the SAPI:AUTHOR element is created for each author in the document body. To assign authors to a data container, the SAPI:AUTHOR elements are also created in the document body. Information about the authors provides feedback to the authors in "SAPI Works Gallery" (http://xmlsapiens.org/lib/) 6.1.1 Element SAPI:AUTHOR Start tag: mandatory, End tag: mandatory The SAPI:AUTHOR element contains information about the author of the document or of the data container. Example: Dmitry Sheiko sheiko@cmsdevelopment.com www.cmsdevelopment.com 6.1.2 Element SAPI:NAME Start tag: mandatory, End tag: mandatory The SAPI:NAME element contains the name of the author the document or of the data container. 6.1.3 Element SAPI:EMAIL Start tag: mandatory, End tag: mandatory The SAPI:EMAIL element contains the e-mail address of the author of the document or of the data container. 6.1.4 Element SAPI:URI Start tag: mandatory, End tag: mandatory The SAPI:URI element contains the site URI of the author of the document or of the data container. 6.2 Comments The SAPI document or data container may be commented. Comments specify the purpose and specific details of functional solutions "SAPI Works Gallery" (http://xmlsapiens.org/lib/) 6.2.1 Element SAPI:COMMENTS Start tag: mandatory, End tag: mandatory The SAPI:COMMENTS element contains the author's comments and notes on the document or data container. Example: Comments content… 6.3 Data Containers Data containers form the basis of the SAPI language. This is the content of containers that defines the functional solutions scenarios for a document of a SAPI-based CMS. The SAPI language includes containers of three types: query containers (SAPI:QC), static data containers (SAPI:SDC), dynamic data containers (SAPI:DDC). Query containers (see section 6.3.1) refer to the fragments of a document displayed on a site. The content of the containers can be modified by the CMS administrator. These containers contain the code of user data queries and related formatting. Static data containers (see section 6.3.2) refer to repeatable static data fragments of the document displayed on the site. These containers contain the code of the fragments they refer to. Dynamic data containers (see section 6.3.3) refer to the fragments of the document displayed on the website. The content of these containers is based on a functional algorithm. These containers contain the description of functional algorithms. 6.3.1 Query Container (Element SAPI:QC) Start tag: mandatory, End tag: mandatory Attributes definition name = %Text [CN] Mandatory. The value of this attribute contains the data container name. title = %Text [CI] Optional. The value of this attribute contains the data container title specifying the container in the list. system = %Text [CN] Deprecated. If an element contains this attribute, its value specifies the CMS system programming language used in the body. ns = %Text [CN] Optional. The value of this attribute contains a pointer to the namespace, which the given data container is assigned to. status = %Text [CN] Optional. If an element contains this attribute, its value specifies the status of the container activity. mdate = %Datetime [CN] Optional. This attribute contains the date and time of the latest document modification. accessarea= %Text [CN] Not required. This attribute defines access modes of document, in which this element displayed. Value can be "edit", "view", "global". Query containers refer to the fragments of the displayed document. The content of these containers can be modified by the CMS administrator. A container can be called from the presentation template of the displayed site document, or from other containers through the SAPI:APPLY element (see section 6.4.3) or through the SAPI:%Attribib attribute (see section 6.4). These containers contain the code of user data queries and their related formatting. Example of a query container: 6.3.1.1 Attribute name Attributes definition name = %Text [CN] Mandatory. The value of this attribute contains the data container name. This attribute contains the data container name that identifies the object in a SAPI document (see section 3.3.4). The container content (the data it refers to) can be called using the SAPI:APPLY element. 6.3.1.2 Attribute title Attributes definition title = %Text [CI] Recommended. The value of this attribute contains the data container title that specifies the container in the list. This attribute should not be ignored. A short but an informal container description will help to avoid errors during site configuration. 6.3.1.3 Attribute system Attributes definition system = %Text [CN] Deprecated. If an element contains this attribute, its value specifies the CMS system programming language used in the body. In the body of data containers a direct reference to the programming language code (that governs the parser) is allowed. In some cases this feature may simplify the definition of functional algorithms. However, using a system programming language in a data container body may cause difficulties at functional solutions exchange through "SAPI Works Gallery" (http://xmlsapiens.org/lib/). Users of the CMS handled by a different programming language will not be able to utilize this functional solution. 6.3.1.4 Attribute ns Attributes definition ns = %Text [CN] Optional. The value of this attribute contains a pointer to the namespace assigned to the given data container. 6.3.1.5 Attribute status Attributes definition status = %Text [CN] Optional. If an element contains this attribute, its value specifies the status of the container activity. This attribute can be either omitted in an element or available with value "hidden". By default, and in case there is no attribute in the element, the container is processed by the parser. If attribute "hidden" is provided, the parser ignores the container. 6.3.1.6 Attribute mdate Attributes definition mdate = %Datetime [CN] Optional. This attribute contains the date and time of the latest document modification. 6.3.1.7 Guidelines on Query Forms Description Query containers contain the code of user data queries and their related formatting. The query code is specified in the syntax of the markup language of the presentation code. Example: In the example above, the markup element HTML INPUT is used. The pointer in the SAPI:VALUE attribute (see section 0) indicates that while generating the interface in the administrative area the value of the VALUE attribute of the INPUT element will contain the data that corresponds to the query. Though the form naming system is out of the scope of the SAPI specification, it should be considered that when transmitting the CMS form data, the data must be identified and saved. 6.3.2 Static Data Container (Element SAPI:SDC) Start tag: mandatory, End tag: mandatory Attributes definition name = %Text [CN] Mandatory. The value of this attribute contains the data container name. title = %Text [CI] Recommended. The value of this attribute contains the data container title that specifies the container in the list. system = %Text [CN] Deprecated. If an element contains this attribute, its value specifies the CMS system programming language used in the body. ns = %Text [CN] Optional. The value of this attribute contains a pointer to the namespace assigned to the given data container. status = %Text [CN] Optional. If an element contains this attribute, its value specifies the status of the container activity. mdate = %Datetime [CN] Optional. This attribute contains the date and time of the latest document modification. accessarea= %Text [CN] Not required. This attribute defines access modes of document, in which this element displayed. Value can be "edit", "view", "global". Static data containers refer to static data fragments of the document displayed on the site. The containers contain a code that will be inserted by the CMS parser into the document displayed on the site. A container can be called from the presentation template of the displayed site document, or from other containers through the SAPI:APPLY element (see section 6.4.3) or through the SAPI:%Attribib attribute (see section 6.4). Example of a static data container: html… 6.3.2.1 Attribute name Attributes definition name = %Text [CN] Mandatory. The value of this attribute contains the data container name. This attribute contains the data container name that identifies the object in a SAPI document (see section 3.3.4). The container content (the data it refers to) can be called using the SAPI:APPLY element. 6.3.2.2 Attribute title Attributes definition title = %Text [CI] Recommended. The value of this attribute contains the data container title that specifies the container in the list. This attribute should not be ignored. A short but an informal container description will help to avoid errors during site configuration. 6.3.2.3 Attribute system Attributes definition system = %Text [CN] Deprecated. If an element contains this attribute, its value specifies the CMS system programming language used in the body. In the body of data containers a direct reference to the programming language code (that governs the parser) is allowed. In some cases this feature may simplify the definition of functional algorithms. However, using a system programming language in a data container body may cause difficulties at functional solutions exchange through "SAPI Works Gallery" (http://xmlsapiens.org/lib/). Users of the CMS handled by a different programming language will not be able to utilize this functional solution. 6.3.2.4 Attribute ns Attributes definition ns = %Text [CN] Optional. The value of this attribute contains a pointer to the namespace assigned to the given data container. 6.3.2.5 Attribute status Attributes definition status = %Text [CN] Optional. If an element contains this attribute, its value specifies the status of the container activity. This attribute can be either omitted in an element or available with value "hidden". By default, and in case there is no attribute in the element, the container is processed by the parser. If attribute "hidden" is provided, the parser ignores the container. 6.3.2.6 Attribute mdate Attributes definition mdate = %Datetime [CN] Optional. This attribute contains the date and time of the latest document modification. 6.3.3 Dynamic Data Container (SAPI:DDC) Start tag: mandatory, End tag: mandatory Attributes definition name = %Text [CN] Mandatory. The value of this attribute contains a data container name. title = %Text [CI] Recommended. The value of this attribute contains the data container title that specifies the container in the list. category = %Text [CI] Recommended. The value of this attribute specifies the category of the dynamic data container (see section 3.3.3.1). system = %Text [CN] Deprecated. If an element contains this attribute, its value specifies the CMS system programming language used in the body. ns = %Text [CN] Optional. The value of this attribute contains a pointer to the namespace assigned to the given data container. status = %Text [CN] Optional. If an element contains this attribute, its value specifies the status of the container activity. parent-id = %Text [CN] Optional. Parent section identifier. mdate = %Datetime [CN] Optional. This attribute contains the date and time of the latest document modification. Attributes of information channel containers: indexdate = %Datetime [CN] Optional. This attribute contains the name of the query container that corresponds to the date of the information channel node. indextitle = %Text [CN] Optional. This attribute contains the name of the query container that corresponds to the title of the information channel node. indexdesc = %Text [CN] Optional. This attribute contains the name of the query container that corresponds to the abstract (summary) of the information channel node. mask = %Text [CN] Optional. This attribute contains the mask of access to the content of the information channel element. Dynamic data containers refer to the fragments of the document displayed on the site. The content of the containers is generated on the basis of a functional algorithm. These containers provide the description of functional algorithms. Dynamic data containers are the so-called functional solutions of a CMS site interface. A container can be called from the presentation template of the document displayed on the site, and from other containers using the SAPI:APPLY element (see section 6.4.3) or the SAPI:%Attribib attribute (see section 6.4). A dynamic data container contains elements SAPI:AUTHOR, SAPI:COMMENTS and SAPI:CHOOSE. The last element (SAPI:CHOOSE) is a handler of the CMS environment status condition. If an expression (Element SAPI:EXP or Attribute EXP) complies with the «TRUE» value, the content of the condition element (SAPI:WHEN) is executed. Conditions may contain the data presentation code (see section 3.2), pointers to containers or an enumeration handler (SAPI:FOR-EACH). The enumeration handler calls the CMS application, the name of which is specified in the SELECT attribute of the SAPI:FOR- EACH element. This application returns a set of nodes to the parser. The enumeration handler may contain a conditions processor. A condition handler is called as many times as there are elements in the nodes set returned by the application. Conditions may contain a data presentation code and data pointers. After each iteration of the enumeration handler the content of the "TRUE" value is returned. The nodes of the set contains the data returned by the application. The data is available in the nodes properties (see section 3.8.5.1). Example of a dynamic data container: Dmitry Sheiko sheiko@cmsdevelopment.com www.cmsdevelopment.com it serves to … Hello world! It's the home page! it's var1 - when value into the html-tas Display the enumeration string - arguments 6.3.3.1 Attribute name Attributes definition name = %Text [CN] Mandatory. The value of this attribute contains a data container name. This attribute contains the data container name that identifies the object in a SAPI document (see section 3.3.4). The container content (the data it refers to) can be called using the SAPI:APPLY element. 6.3.3.2 Attribute title Attributes definition title = %Text [CI] Recommended. The value of this attribute contains the data container title that specifies the container in the list. This attribute should not be ignored. A short but an informal container description will help to avoid errors during site configuration. 6.3.3.3 Attribute category Attributes definition category [CI] Recommended. The value of this attribute specifies the category of the dynamic data container. This attribute allows cataloguing a container (functional solution) in "SAPI Works Gallery" (http://xmlsapiens.org/lib/), and informs the CMS on the processing peculiarities for this container. A list of available categories for dynamic data containers is provided in section 3.3.3.1. 6.3.3.4 Attribute system Attributes definition system = %Text [CN] Deprecated. If an element contains this attribute, its value specifies the CMS system programming language used in the body. In the body of data containers a direct reference to the programming language code (that governs the parser) is allowed. In some cases this feature may simplify the definition of functional algorithms. However, using a system programming language in a data container body may cause difficulties at functional solutions exchange through "SAPI Works Gallery" (http://xmlsapiens.org/lib/). Users of the CMS handled by a different programming language will not be able to utilize this functional solution. 6.3.3.5 Attribute ns Attributes definition ns = %Text [CN] Optional. The value of this attribute contains a pointer to the namespace assigned to the given data container. 6.3.3.6 Attribute status Attributes definition status = %Text [CN] Optional. If an element contains this attribute, its value specifies the status of the container activity. This attribute can be either omitted in an element or available with value "hidden". By default, and in case there is no attribute in the element, the container is processed by the parser. In case attribute "hidden" is provided, the parser ignores the container. 6.3.3.7 Attribute parent-id Attributes definition parent-id = %Text [CN] Optional. Parent section identifier. The default parent section in a documented CMS structure for an information channel (see section 3.8.5.2) is the section that contains the document with the navigation channel list. This attribute is used to access the specified information channel. 6.3.3.8 Attribute cache Attributes definition cache = %Charset [CI] Optional. The value of this attribute shows to the parser, whether caching of the current document is allowed. 6.3.3.9 Attribute mdate Attributes definition mdate = %Datetime [CN] Optional. This attribute contains the date and time of the latest document modification. 6.3.3.10 Attribute indexdate Attributes definition indexdate = %Datetime [CN] Optional. This attribute contains the name of the query container that corresponds to the date of the information channel node. This attribute is used to indicate to the CMS administration area interface, the content of which query (query container) should be treated as the date of the information channel node. 6.3.3.11 Attribute indextitle Attributes definition indextitle = %Text [CN] Optional. This attribute contains the name of the query container that corresponds to the title of the information channel node. This attribute is used to indicate to the CMS administration area interface, the content of which query (query container) should be treated as the title of the information channel node. 6.3.3.12 Attribute indexdesc Attributes definition indexdesc = %Text [CN] Optional. This attribute contains the name of the query container that corresponds to the abstract (summary) of the information channel node. This attribute is used to indicate to the CMS administration area interface, the content of which query (query container) should be treated as the abstract of the information channel node. 6.3.3.13 Attribute mask Attributes definition mask = %Text [CN] Optional. This attribute contains the mask of access to the content of the information channel element. This attribute is used to indicate to the CMS administration area interface, which part of the URI specifies parameters of the information channel node content. The mask attribute may contain values in the syntax readable by the CMS parser. For example, the value of attribute "year/month/day/id" may indicate to the parser that the URI may contain parameters for filtering by year, month, day (e.g., http://site/infochannel_url/2004/05/15/2389). 6.3.3.14 Element SAPI:CHOOSE Start tag: mandatory, End tag: mandatory This element is a condition parser. A condition parser indicates that the CMS parser should process the «TRUE» conditions from those available in the body of the SAPI:CHOOSE element. 6.3.3.15 Element SAPI:WHEN Start tag: mandatory, End tag: mandatory Attributes definition title = %Text [CI] Recommended. The value of this attribute contains the title of the container condition. The title specifies the container condition title defining the site debugging condition. status = %Text [CN] Optional. If an element contains this attribute, its value specifies the status of the container activity. exp = = %Text [CI] Optional. This attribute contains condition expressions. In addition to the condition expression (see section 6.3.3.17), a condition of a dynamic data container may contain either the SAPI:CODE element (see section 6.3.3.16) or an enumeration handler (see section 6.3.3.18). Though a condition expression can be written in one line without characters (<>) that are not allowed for attributes, a condition expression can be placed within the EXP attribute. For example: HTML… Otherwise, a condition expression should be specified in the SAPI:EXP element. For example: or(eq('argv.0.value','home'),eq('argv.0.value','')) HTML… 6.3.3.15.1 Attribute title Attributes definition title = %Text [CI] Recommended. The value of this attribute contains the container condition title that specifies the condition during site debugging. 6.3.3.15.2 Attribute status Attributes definition status = %Text [CN] Optional. If an element contains this attribute, its value specifies the status of the container activity. 6.3.3.15.3 Attribute exp Attributes definition exp = = %Text [CI] Optional. This attribute contains a condition expression. This element allows to define condition expressions. A condition is treated as «TRUE» and is processed by the parser only in case its value is «TRUE». Using condition expressions in the syntax of SAPI expressions is allowed (see section 3.6). In certain cases using the syntax of the system language (see section 3.7.1) is also allowed. 6.3.3.16 Element SAPI:CODE Start tag: mandatory, End tag: mandatory This element contains the presentation code (see section 3.2.2). The code may contain pointers to data and data containers (see section 3.3). 6.3.3.17 Element SAPI:EXP Start tag: mandatory, End tag: mandatory This element allows to define condition expressions. A condition is treated as «TRUE» and is processed by the parser only in case its value is «TRUE». Using condition expressions in the syntax of SAPI expressions is allowed (see section 3.6). In certain cases using the syntax of the system language (see section 3.7.1) is also allowed. 6.3.3.18 Element SAPI:FOR-EACH Start tag: mandatory, End tag: mandatory Attributes definition select = %Text [CN] Mandatory. The value of this attribute contains a pointer to the CMS application. name = %Text [CN] Mandatory. The value of this attribute contains the enumeration name. title = %Text [CI] Mandatory. The value of this attribute contains the enumeration title specifying the enumeration during site debugging. status = %Text [CN] Optional. If an element contains this attribute, its value specifies the enumeration activity status. Conditions (SAPI:WHEN see section 6.3.3.15) may contain an enumeration handler (this element). An enumeration handler calls the CMS application, the name of which is specified in the SELECT attributes. The application returns a nodes set (see section 3.8.5.1) to the CMS parser. An enumeration handler may contain a condition processor, which is called as many times as there are nodes in the set returned by the application. Conditions, in their turn, may contain a data presentation code and data pointers. After each iteration of the enumeration handler the content of the "TRUE" value is returned. For example: | 6.3.3.18.1 Attribute select Attributes definition select = %Text [CN] Mandatory. The value of this attribute contains a pointer to the CMS application (see section 3.8.5). 6.3.3.18.2 Attribute name Attributes definition name = %Text [CN] Mandatory. The value of this attribute contains the enumeration name. 6.3.3.18.3 Attribute title Attributes definition title = %Text [CI] Recommended. The value of this attribute contains the enumeration title specifying it during site debugging. 6.3.3.18.4 Attribute status Attributes definition status = %Text [CN] Optional. . If an element contains this attribute, its value specifies the status of the enumeration activity. 6.4 Pointers SAPI pointers are used to call the objects content either in the data presentation code or in the data container body. Data pointers return the values of the CMS environment variables (see section 3.8.4). The value of a variable may be called through the SAPI:VALUE-OF element or the SAPI:%Attrib attribute. Container pointers return the content of data containers. 6.4.1 Data Pointer (Element SAPI:VALUE-OF) Start tag: mandatory, End tag: mandatory Attributes definition name = %Text [CN] Mandatory. The value of this attribute contains the name of the pointer to object properties (see section 3.3.4). exp = %Text [CN] The value of this attribute contains expressions. src = %Text [CN] Value of this attribute defines data source for object. Value can be: ? ref: reference address of source document ? id: system identifier of source document ? obj: source object The element referencing a data container through a pointer returns the value of this container. 6.4.1.1 Attribute name Attributes definition name = %Text [CN] Mandatory. The value of this attribute contains a pointer to object properties. exp = %Text [CN] Mandatory. The value of this attribute contains expressions. 6.4.2 Data Pointer (Attribute SAPI:%Attribib) Attributes definition %Attrib = %Text [CN] Mandatory. The value of this attribute contains the name of the parent element attribute into which the parser integrates the value of the CMS environment variable. In case the value of the CMS environment variable should be inserted in the element attribute, an additional attribute is used with the following syntax: SAPI:name_of_attribute_for_insertion. 6.4.2.1 Attribute %Attrib Attributes definition %Attrib = %Text [CN] Mandatory. The value of this attribute contains the name of the parent element attribute into which the parser integrates the value of the CMS environment variable. 6.4.3 Container Pointer (Element SAPI:VALUE-OF) Start tag: mandatory, End tag: mandatory Attributes definition name = %Text [CN] Mandatory. The value of this attribute contains an object properties pointer. src = %Text [CN] Value of this attribute defines data source for object. Value can be: ? ref: reference address of source document ? id: system identifier of source document ? obj: source object The element referencing a data container through a pointer returns the value of this container. 6.4.3.1 Attribute name Attributes definition name = %Text [CN] Mandatory. The value of this attribute contains an object properties pointer (see section 3.3.4). exp = %Text [CN] Mandatory. The value of this attribute contains expressions 6.5 Additional Operands 6.5.1 SQL Query Selection (Element SAPI:SQL) Start tag: mandatory, End tag: omitted Attributes definition query = %Text [CN] Mandatory. The value of this attribute contains a SQL query to the CMS data repository. type = %Text [CN] Mandatory. The value of this attribute contains the query type value. name = %Text [CN] Mandatory. The value of this attribute contains the name of the target CMS environment variable. title = %Text [CN] Mandatory. The value of this attribute contains the element title. SAPI can directly interact with a database. For this purpose a CMS environment variable containing an associated array of query values should be created using the SAPI:SQL element. The value of the variable can be returned by the SAPI:VALUE-OF element. For example: 6.5.1.1 Attribute query Attributes definition query = %Text [CN] Mandatory. The value of this attribute contains an SQL query to the CMS data repository (see section 3.8.2.1). 6.5.1.2 Attribute type Attributes definition type = %Text [CN] Mandatory. The value of this attribute contains the element type value. In the current SAPI version just one type of the «fetch-array» queries is allowed. This query returns into the target CMS environment variable an associated array with query results. 6.5.1.3 Attribute name Attributes definition name = %Text [CN] Mandatory. The value of this attribute contains the name of the target CMS environment variable (see section 3.8.4). 6.5.1.4 Attribute title Attributes definition title = %Text [CN] Mandatory. The value of this attribute contains the element title. 7 XML Reference Information for SAPI The following section contains the formal XML definition of the SAPI laguage. This file is also available in the ASCII format: (Default DTD: http://xmlsapiens.org/spec/sapi11.dtd 7.1 Document Validation To verify that a document conforms to the SAPI DTD, it should be validated with a SAPI grammar validator of the SAPID type. 8 References 8.1 Normative References [CSS1] "Cascading Style Sheets, level 1", H. W. Lie and B. Bos, 17 December 1996. Available at http://www.w3.org/TR/REC-CSS1-961217 [DATETIME] "Date and Time Formats", W3C Note, M. Wolf and C. Wicksteed, 15 September 1997. Available at http://www.w3.org/TR/NOTE-datetime [IANA] "Assigned Numbers", STD 2, RFC 1700, USC/ISI, Reynolds and J. Postel, October 1994. Available at http://ds.internic.net/rfc/rfc1700.txt [ISO639] "Codes for the presentation of names of countries", ISO 3166:1993. For details refer to http://www.iso.ch/cate/d4766.html. Also see http://www.sil.org/sgml/iso639a.html. [ISO3166] "Codes for the presentation of names of countries", ISO 3166:1993. [ISO8601] "Data elements and interchange formats - Information interchange - Presentation of dates and times", ISO 8601:1988. [ISO8879] "Information Processing - Text and Office Systems - Standard Generalized Markup Language (SGML)", ISO 8879:1986. Please refer to http://www.iso.ch/cate/d16387.html for information about the standard. [ISO10646] Information Technology - Universal Multiple-Octet Coded Character Set (UCS) - Part 1: Architecture and Basic Multilingual Plane", ISO/IEC 10646-1:1993. The first five amendments in ISO/IEC 10646-1:1993 are also taken into consideration in this specification. [ISO88591] "Information Processing -- 8-bit single-byte coded graphic character sets -- Part 1: Latin alphabet No. 1", ISO 8859-1:1987. [MIMETYPES] List of registered content types (MIME types). The registered content types can be downloaded from ftp://ftp.isi.edu/in-notes/iana/assignments/media-types/. [RFC1555] "Hebrew Character Encoding for Internet Messages", H. Nussbacher and Y. Bourvine, December 1993. Available at http://ds.internic.net/rfc/rfc1555.txt. [RFC1556] "Handling of Bi-directional Texts in MIME", H. Nussbacher, December 1993. Available at http://ds.internic.net/rfc/rfc1556.txt. [RFC1738] "Uniform Resource Locators", T. Berners-Lee, L. Masinter, and M. McCahill, December 1994. Available at http://ds.internic.net/rfc/rfc1738.txt. [RFC1766] "Tags for the Identification of Languages", H. Alvestrand, March 1995. Available at http://ds.internic.net/rfc/rfc1766.txt. [RFC1808] "Relative Uniform Resource Locators", R. Fielding, June 1995. Available at http://ds.internic.net/rfc/rfc1808.txt. [RFC2044] "UTF-8, a transformation format of ISO 10646", F. Yergeau, January 1998. Available at http://ds.internic.net/rfc/rfc2044.txt. [RFC2045] "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies", Freed and N. Borenstein, November 1996. Available at http://ds.internic.net/rfc/rfc2045.txt. Note that this RFC obsoletes RFC1521, RFC1522, and RFC1590. [RFC2046] "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types", N. Freed and N. Borenstein, November 1996. Available at http://ds.internic.net/rfc/rfc2046.txt. Note that this RFC obsoletes RFC1521, RFC1522, and RFC1590. [RFC2068] "HTTP version 1.1 ", R. Fielding, J. Gettys, J. Mogul, H. Frystyk Nielsen and T. Berners-Lee, January 1997. Available at http://ds.internic. net/rfc/rfc2068.txt. [RFC2119] "Keywords for use in RFCs to Indicate Requirement Levels", S. Bradner, March 1997. Available at http://ds.internic.net/rfc/rfc2119.txt. [RFC2141] "URN Syntax", R. Moats, May 1997. Available at http://ds.internic.net/rfc/rfc2141.txt. [SRGB] "A Standard Default Color Space for the Internet", version 1.10, M. Stokes, M. Anderson, S. Chandrasekar, and R. Motta, 5 November 1996. Available at http://www.w3.org/Graphics/Color/sRGB [UNICODE] "The Unicode Standard, Version 2.0", The Unicode Consortium, Addison-Wesley Developers Press, 1996. Errors in http://www.unicode.org/unicode/uni2errata/bidi.htm are taken into consideration in this specification. For more details on the Unicode Consortium refer to http://www.unicode.org/ [URI] "Uniform Resource Identifiers (URI): Generic Syntax and Semantics", T. Berners- Lee, R. Fielding, L. Masinter, 18 November 1997. Available at http://www.ics.uci.edu/pub/ietf/uri/draft-fielding-uri-syntax-01.txt. The document is still under development, for amendments refer to the addresses of [RFC1738] and [RFC1808]. [WEBSGML] "TC Suggestions on WebSGML Adaptation for SGML", C. F. Goldfarb, ed., 14 June 1997. Available at http://www.sgmlsource.com/8879rev/n1929.htm 8.2 Informative References [BRYAN88] "SGML: An Author's Guide to the Standard Generalized Markup Language", M. Bryan, Addison-Wesley Publishing Co., 1988. [CALS] Continuous Acquisition and Life-Cycle Support (CALS). CALS is a Department of Defense strategy for achieving effective creation, exchange, and use of digital data for weapon systems and equipment. More information can be found on the CALS page at http://navysgml.dt.navy.mil/cals.html. [CHARSETS] Registered charset values. Download a list of registered charset values from ftp://ftp.isi.edu/in-notes/iana/assignments/character-sets. [CSS2] "Cascading Style Sheets, level 2", B. Bos, H. W. Lie, C. Lilley, and I. Jacobs, November 1997. Available at http://www.w3.org/TR/WD-CSS2/ [DCORE] The Dublin Core: for more information refer to http://purl.org/metadata/dublin_core [ETHNO] "Ethnologue, Languages of the World", 12th Edition, Barbara F. Grimes editor, Summer Institute of Linguistics, October 1992. [GOLD90] "The SGML Handbook", C. F. Goldfarb, Clarendon Press, 1991. [HTML30] "HuperText Markup Language Specification Version 3.0", D. Raggett, September 1995. Available at http://www.w3.org/MarkUp/html3/CoverPage. [HTML32] "HTML 3.2 Reference Specification", D. Raggett, 14 January 1997. Available at http://www.w3.org/TR/REC-html32 [HTML3STYLE] "HTML and Style Sheets", B. Bos, D. Raggett, and H. Lie, 24 March 1997. Available at http://www.w3.org/TR/WD-style [LEXHTML] "A Lexical Analyzer for HTML and Basic SGML", D. Connolly, 15 June 1996. Available at http://www.w3.org/TR/WD-html-lex [PICS] Platform for Internet Content (PICS). For more information refer to http://www.w3.org/PICS/ [RDF] Resource Description Language. For more information refer to http://www.w3.org/Metadata/RDF/ [RFC822] "Standard for the Format of ARPA Internet Text Messages", Revised by David H. Crocker, August 1982. Available at http://ds.internic.net/rfc/rfc822.txt. [RFC850] "Standard for Interchange of USENET Messages", Ì. Horton, June 1983. Available at http://ds.internic.net/rfc/rfc850.txt. [RFC1468] "Japanese Character Encoding for Internet Messages", Murai, M. Crispin, and E. van der Poel, June 1993. Available at http://ds.internic.net/rfc/rfc1468.txt. [RFC1630] "Universal Resource Identifiers in WWW: A Unifying Syntax for the Expression of Names and Addresses of Objects on the Network as used in the World-Wide Web", T. Berners-Lee, June 1994. Available at http://ds.internic.net/rfc/rfc1630.txt. [RFC1866] "HyperText Markup Language 2.0", T. Berners-Lee and D. Connolly, November 1995. Available at http://ds.internic.net/rfc/rfc1866.txt. [RFC1867] "Form-Based File Upload in HTML", E. Nebel and L. Masinter, November 1995. Available at http://ds.internic.net/rfc/rfc1867.txt. RFC1867 must be updated through ftp://ftp.ietf.org/internet-drafts/draft-masinter-form-data-01.txt, still under development. [RFC1942] "HTML Tables", Dave Ragget, May 1996. Available at http://ds.internic.net/rfc/rfc1942.txt. [RFC2048] "Multipurpose Internet Mail Extension (MIME) Part Four: Registration Procedures", N. Freed, J. Klensin, and J. Postel, November 1996. Available at http://ds.internic.net/rfc/rfc2048.txt. Note that this RFC obsoletes RFC1521, RFC1522, and RFC1590. [RFC2070] "Internationalization of the HyperText Markup Language", F. Yergeau, G. Nicol, G. Adams, and M. Durst, January 1997. Available at http://ds.internic.net/rfc/rfc2070.txt. [SGMLOPEN] SGML Consortium. Please refer to the SGML Consortium page at http://www.sgmlopen.org/ [SP] SP is a public domain SGML parser. Available at ftp://ftp.jclark.com/pub/sp/. Further information is available at http://www.jclark.com. [SQ91] "The SGML Primer", 3rd Edition, SoftQuad Inc., 1991. [TAKADA] "Multilingual Information Exchange through the World-Wide Web", Toshihiro Takada, Computer Networks and ISDN Systems, Vol. 27, No. 2, pp. 235-241, November 1994. [WAIGUIDE] Guidelines for designing accessible HTML documents are available on the Web Accessibility Initiative (WAI) Web site: http://www.w3.org/WAI/. [VANH90] "Practical SGML", E. van Herwijnen, Kluwer Academic Publishers Group, Norwell and Dordrecht, 1990. 9 Index 9.1 Index of Elements Legend: Mandatory, Optional, Recommended, Deprecated Name Properties Description cache O Value "nocache" of this attribute indicates to the parser, whether caching of the current document is allowed. category OR The value of this attribute specifies the container category. mdate O This attribute contains the date and time of the latest container modification. encoding OR The value of this attribute specifies the language encoding used in the document. exp O This attribute contains the condition expression. id M The value of this attribute specifies the identifier of the displayed site. indexdate O This attribute contains the query container name that corresponds to the information channel node date. indexdesc O This attribute contains the query container name that corresponds to the abstract (short summary) of the information channel node. indextitle O This attribute contains the name of the query container that corresponds to the title of the information channel node. mask O This attribute contains the mask of access to the content of the information channel element. name M The value of this attribute contains the data container name. ns O The value of this attribute contains the pointer to the namespace assigned to the given data container. parent-id O The value of this attribute contains the ID of the parent section for the information channel. query M The value of this attribute contains a SQL query to the CMS database. select M The value of this attribute contains a CMS application pointer. status O If an element contains this attribute, its value specifies the enumeration activity status. system OD If an element contains this attribute, its value specifies the CMS system programming language used in the body. title OR The value of this attribute contains the data container title that specifies the container in the list. type M The value of this attribute contains a query type value (see section 6.5.1.2). version O The value of this attribute specifies the SAPI DTD version managing the document (see section 5.3.1) xmlns:sapi O Formal XML NS definition. 9.2 Index of Attributes Name Elements Attributes Description sapi sapi:qc, sapi:sdc, sapi:ddc, sapi:author version, xmlns:sapi, encoding, cache, mdate Declares the root section of a SAPI document. sapi:author sapi:name, sapi:email, sapi:uri - Contains information about the author of the document or of the data container. sapi:choose sapi:when - Decl