Clickframes XML

From Clickframes

Clickframes XML is an XML-based format for describing the core functional requirements of a web application. This file is an application specification - or appspec - and is usually named appspec.xml or truth.xml. It's a very important file: Clickframes uses the appspec to generate Clickframes Interactive Previews (CLIPs), to build executable code via Clickframes Plugins, and to generate automated test scripts.

The appspec will evolve over the course of the application development process. At the start of a project, the appspec may be very simple - a few pages, a few relationships and a few miscellaneous requirements. As you proceed through the Clickframes Project Lifecycle the appspec will be fleshed out and used to generate new artifacts and regenerate old ones.

When designing the Clickframes XML format, we've been very careful to avoid modeling in a technology- or implementation-specific way. For instance, we don't allow you to specify things like Java package names in an appspec, because the application may not be generated in Java. The simple rule of thumb is that the only things that go into the appspec are the ones that users can see, and that users care about. In many software development processes, these are referred to as "testable requirements" - you should be able to confirm every requirement in the appspec by loading the final application in a web server and running through the pages.

If you will be using the appspec with a plugin, please check the Plugin Feature Matrix to verify that the appspec's features are supported by the plugin.

Contents

Appspec Element

An application to be specified by Clickframes XML is contained by the appspec element. At the very least, an appspec must have a title and at least one page.

Your title will most likely be the name of your application.

<appspec>
  <title>Crazy Al's Online Photo Organizer</title>
  ...
</appspec>

Page Element

The basic Clickframes XML building block is the page. Very simply, a page describes its purpose within the application and indicates where else the user may go from there.

Each page is labeled with a unique string identifier. This should be something brief but legible, similar to what you might name the page's HTML file.

 <page id="passwordReset"> ... </page>

A page must have a title and a description. The description should provide a casual narrative of what the user can do on the page.

 <page id="passwordReset">
   <title>Password Reset Request Form</title>
   <description>
     On this page, the user may enter a username
     to initiate the password reset process.  If
     the username does not exist, an error message
     will be displayed asking for a second try.
   </description>
 </page>

Remember, the description is casual, not canonical. Anything truly important in your description should ultimately be codified in actions, outcomes, and facts.

The Default Page

You may define a default destination when users first access your application, like a web site's "index" page. Use the defaultPage attribute in the appspec element.

<appspec defaultPage="home"> ... </appspec>

Links

The most basic means for connecting one page to another is by using the link element.

A link must have a title and a reference to another page, either internal to application or external. The title should reflect how the link would be displayed to the user.

Optionally, a link may contain a description, which could explain what will happen within the application when the link is clicked.

A page reference can take one of two forms. Internal page references require a pageRef tag, containing a valid page identifier (the id attribute of a page element). External page references require an href tag, containing a valid URL.

<link>
  <title>Open Inbox</title>
  <pageRef>messagingInbox</pageRef>
</link>
<link>
  <title>Terminate Account</title>
  <description>
    Sends the user to parent company's website where
    account termination information is displayed.
  </description>
  <href>http://www.megalomart.net/terminate.php</href>
</link>

User Input

When a page will gather data from the user, create a form containing fields defined by the input tag followed by actions which define how the system processes the data.

An input must have a type attribute, indicating what kind of form input is expected, and a title element, indicating the field label which will be displayed to the user. Optionally, you may use the description element to provide more information about the field.

Valid input types, which map to HTML form controls, are:

  • text: single-line input
  • textarea: multiple-line input
  • password: sensitive single-line input
  • checkbox: on/off switches toggled by the user
  • radio: mutually exclusive switches
  • dropdown: single-selection menu of options
  • multiple: multiple-selection menu of options (COMING SOON)
  • upload: file selector
<form id="editWikiForm">
  <input type="textarea">
    <title>Page Content</title>
    <description>User enters page content with wiki-text syntax.</description>
  </input>
  ...
  <action>
     ...
  </action>
</form>

Selection Input

Inputs of type checkbox, radio, dropdown, or multiple should contain one or more option elements, specifying the options available for the user to select.

<input type="radio">
  <title>Your Favorite Ice Cream Flavor</title>
  <option value="chocolate">Double Chocolate Chunk</option>
  <option value="vanilla">French Vanilla Bean</option>
  <option value="strawberry">Sweet Summer Strawberry</option>
  <default value="chocolate" />
</input>

Use the default tag to specify an option to be selected by default. For inputs of type dropdown and radio, Clickframes will assume the first option is default if a default is not explicitly specified.

Data Validation

User-supplied data may be validated against rules you define within each input element using the validation tag. Validations must define a type attribute:

  • required: input is required
  • url: input must be in the form of a URL
  • email: input must be in the form of an e-mail address
  • length: input must fulfill the specified length requirements
  • regex: input must satisfy the specified regular expression
<input type="text">
  <title>Your E-mail Address</title>
  <validation type="required" />
  <validation type="email" />
</input>

Each validation may also include a description attribute to specify the message to display when the validation fails.

<input type="password">
  <title>New Password</title>
  <validation type="required" description="Please enter a new password." />
</input>

Validations of type length and regex require additional parameters provided within parentheses as part of the type definition. Length validations may include the min or max parameters, or both. Regular expression validators must include a regular expression within the parentheses.

<input type="text">
  <title>Username</title>
  <validation type="regex(/^[a-z0-9_\.-]+$/i)"
    description="Username must contain only alphanumeric characters, underscores, dots, and dashes" />
</input>
<input type="password">
  <title>Password</title>
  <validation type="length(min=6,max=12)"
    description="Password must be between six and twelve characters." />
</input>
<input type="textarea">
  <title>Enter Description of Task</title>
  <validation type="length(max=255)"
    description="Keep your description within 255 characters, please." />
</input>

Unbounded Input

There are occasions when you might like to record an uncertain number of input elements, e.g. names and e-mail addresses of people you'd like to invite to a party. The inputMany element groups one or more input elements and specifies their cardinality.

<inputMany minOccurs="0" maxOccurs="unbounded">
  <title>Invite people to your party</title>
  <input type="text">
    <title>Recipient's Name</title>
    <validation type="required" description="Please enter your recipient's name." />
  </input>
  <input type="text">
    <title>Recipient's E-mail</title>
    <validation type="email" description="Please enter your recipient's e-mail address." />
  </input>
</inputMany>

Actions & Outcomes

An action represents something the user can do on a page that may have one or more consequences, the most obvious example of which is form submission.

An action is made up of a title and at least one outcome.

An outcome must contain an id, a title and an internal or external page reference (see previous section on links). Optionally, an outcome may have a description to provide any additional detail related to the performance of the action. An outcome may also be modified by the negative attribute to indicate that outcome is a negative case, e.g. form submission failure.

An outcome may include a message to be displayed to the user when it occurs.

 <action>
   <title>Submit login form</title>
   <outcome id="valid">
     <title>Username and password are valid</title>
     <pageRef>systemDashboard</pageRef>
     <message>Welcome, user!</message>
   </outcome>
   <outcome id="invalid" negative="true">
     <title>Combination of username and password are invalid</title>
     <description>
       User is shown an explanatory error message
       and asked to try again.
     </description>
     <pageRef>login</pageRef>
     <message>Login failed. Please try again.</message>
   </outcome>
 </action>

Navigation

A linkSet defines a group of links that can be displayed together on any number of pages.

<linkSet id="projectNavigation">
  <link>
     <title>Start new project</title>
     <pageRef>newProject</pageRef>
  </link>
  <link>
     <title>See all projects</title>
     <pageRef>projects</pageRef>
  </link>
  <link>
     <title>Send feedback</title>
     <href>mailto:projectfeedback@clickframes.org</href>
  </link>
</linkSet>

Referencing Linksets

Once defined, a linkSet must be referenced on each page it will appear.

<page id="newProject">
  ...
  <linkSetRef id="projectNavigation" />
</page>
<page id="projects">
  ...
  <linkSetRef id="projectNavigation" />
</page>

Global Navigation

You may define a linkSet that will appear on every page in your application, known as global navigation, by adding the global attribute.

<linkSet id="siteNavigation" global="true">
  ...
</linkSet>

Global navigation does not need per-page linkset references.

Page Parameters

Because URL parameters (e.g. foo?id=123) are exposed to the user through his browser, it is important to model them up front. REST-based web services especially have placed additional importance on the structure of an application's URLs.

If a page will accept URL parameters, define them with the param tag.

<page id="viewListing">
  ...
  <param type="text">
    <title>Listing ID</title>
    <description></description>
  </param>
</page>

E-mail

If your application will send e-mail, define each individual e-mail message with the email element.

<email id="newUserMessage">
  <title>Message sent to new users</title>
  <description>
    This message is sent to all new users once their account
    has been created.
  </description>
  <emailSubject>
    Your Issue Tracker account has been created!
  </emailSubject>
  <emailText>
  <![CDATA[
    Dear FIRSTNAME LASTNAME,
    Your account has been created.
    Please log in at APPLICATIONURL with your username USERNAME.
    Regards,
    Issue Tracker
  ]]>
  </emailText>
</email>

The title and description fields are your own reference -- they will not be displayed to a user. The emailSubject and emailText fields should be seen as the basis for the e-mail's content. When implemented, a developer can integrate any dynamic data or visual styling that should appear.

You may also add fact, link, and linkSetRef to an email.

Referencing E-mails

Declare when your application will send e-mail by associating an email element with an outcome.

<outcome>
  <title>New account created</title>
  <pageRef>dashboard</pageRef>
  <emailRef>newUserMessage</emailRef>
</outcome>

Facts

Facts provide a simple way to specify software requirements that aren't otherwise encoded in your appspec.

<fact>A tooltip shall appear when the user hovers over the image.</fact>

Occurrences of the word PAGE (all caps) will be converted to the relevant page's title in your generated artifacts (e.g. software requirements).

<fact>PAGE shall list the user's unread messages.</fact>

Facts may be placed within any of the following elements:

  • linkSet
  • page
  • email
  • input
  • outcome
  • link
  • entity list

Content

Specify content blocks that appear on a page with the content tag. Identify the content with an id attribute.

<content id="homepageIntro">
  Welcome to your home page.
</content>

Complex Content

Content may contain HTML-formatted text. Identify this type of content with a complex attribute set to "true".

 <content id="homepageIntro" complex="true">
   <![CDATA[<b>Welcome to your home page.</b>]]>
 </content>

Global Content

Content that will appear on multiple pages may be defined as a global content element as a child of the appspec element, using the same syntax as above. Pages that wish to display that content should reference it as follows:

<contentRef id="homepageIntro" />


User Authentication

Clickframes lets you specify login related details about your application via your Appspec XML file.

Page requires login

Add the attribute login-required="true" to the <page> tag.

<page id="dashboard" login-required="true">

The above tag indicates that the user must be logged in to view the 'dashboard' page.

Login form

If login is required in an application, usually there are one or more pages with input fields where the user can enter login and password and a button (usually called "Login") that they can click to login to the application.

Find all login username field, login password field and login action buttons in your app in the appspec.xml and add "annotate" them by adding "loginUsername", "loginPassword" and "loginAction" as follows.

<input id="user" loginUsername="true">
...
<input id="pass" type="password" loginPassword="true">
...
<action id="submit" loginAction="true">

The above indicates that the "user" and "pass" fields submitted by the user by performing the "submit" action should attempt a user login.

Remember, Clickframes XML just specifies the basic interaction requirements for security. The actual implementation will depend on many things, including the technology you choose (out of the box, that's JSF, WebFlow and PHP/CodeIgniter).

Login page

If the user lands on a page which requires login, the user should be redirected to a login page where the user will be presented with a login form. Upon successful login, the user will be taken back to the page that he/she was trying to access.

The login page is defined as the page that the user gets redirected to in order to login. You can specify the login page via an attribute on the <appspec> element.

<appspec loginPage="login" ...

Specifying a login page is optional. If you don't specify a login page, it is determined by finding the first page which has a login form.