This document provides guidance on mapping ALPS descriptions to HTML representations. It is provided as a guide for those writing servers that will use ALPS profiles to generate HTML and for those writing client applications that will use ALPS profiles to "recognize" ALPS descriptors within the HTML document.
The Application-Level Profile Semantic(ALPS)[0] specification is designed to describe the data elements and state transitions that make up a problem domain (e.g. microblogging, accounting, etc.). ALPS documents are designed to be useful to both client and server implementors and can be used at both run-time and design-time to handle the generation and interpretation of response representations. ALPS description documents are referred to as profiles or profile documents.
Since the aim is to support a wide set of use cases (clients, servers, run-time, design-time, etc.), ALPS profiles do not describe the runtime behavior of any single system. Instead ALPS profiles describe the problem domain boundaries (e.g. the possible data elements and possible state transitions). It is up to implementors to decide how they wish to use ALPS profliesin order to create an actual instance of a service or client application.
For server implementors, ALPS profiles establish the list of possible identifiers for data values (givenName, familyName, etc.) and transitions (publish, createUser, etc). ALPS profiles also provide additional description information for state transitions including whether the transition is safe or idempotent and, in some cases, whether there are any possible arguments that can be passed with each transition.
For client implementors can use the same ALPS document to as a guide for what to expect from a service which advertises support for an ALPS profile. For example, if a service announces that it uses the ALPS profile for microblogging, then any client application that was built to support the microblogging profile SHOULD be able to recongize all the important data elements and state transitions emitted by that service.
Servers returning HTML responses can advertise the ALPS profiles they support using the following methods:
- Link Header
-
Responses can include the
Linkheader[2] with thehrefvalue set to the URL of the ALPS profile document and therelvalue set to "profile."
Link: http://alps.io/profiles/microblogging; rel="profile" - HTML4
profileattribute -
HTML4 documents can use the
profile[3] attribute on theHTML.HEADelement. theprofileattribute value SHOULD be set to the URL of the ALPS profile document.
<head profile="http://alps.io/profiles/microblogging">…</head> - HTML5
linkelement -
HTML5 documents can use the
Linkelement[4] with thehrefvalue set to the URL of the ALPS profile document and therelvalue set to "profile."
<link href="http://alps.io/profiles/microblogging" rel="profile" />
|
Note
|
It is valid for a service to advertise support for more than one ALPS profile for the same response. For example, a single response from a server might include the following LINK: <http://alps.io/profiles/finance>;rel="profile", <http://alps.io/profiles/accounting>;rel="profile" In the above case, The client application has been informed that the response MAY contain data elements and state transitions from both the finance and the accounting ALPS profiles. |
Clients accepting HTML responses SHOULD look for the ALPS profile in each of these places as appropriate to the response. If an ALPS profile reference appears in more than one location (e.g. LINK header, HTML.HEAD@profile attribute, and/or HTML.LINK element) all profiles SHOULD be considered valid.
The following are the basic rules for rendering ALPS profile information into valid HTML representations.
The ALPS.descriptor.id SHOULD be transformed into an HTML class property. Below are several valid examples:
descriptor.id to HTML elements<!-- ALPS document --> <descriptor id="abc" ... /> <!-- HTML read-only elements --> <div class="abc">...</div> <span class="abc">...</div> <li class="abc">...</li> <p class="abc">...</p> <!-- HTML state transition elements --> <input type="text" class="abc" /> <a href="..." class="abc" /> <img src="..." class="abc" />
The exception to this rule is when the ALPS descriptor.name property is present. In that case the class property of the HTML element should be set to the value of the descriptor.name property in the ALPS document. The ALPS descriptor.id SHOULD also be included in the HTML representation using an HTML5 Custom Data Attribute[1] data-alpsid. Below are several valid examples:
descriptor.name to HTML elements<!-- ALPS document --> <descriptor id="abc" name="xyz" ... /> <descriptor id="abc2" name="xyz" ... /> <!-- HTML read-only elements --> <div class="xyz" data-alpsid="abc">...</div> <span class="xyz" data-alpsid="abc2">...</div> </div> <!-- HTML state transition elements --> <input type="text" class="xyz" data-alpsid="abc2"/> <a href="..." class="xyz" data-alpsid="abc"/>
The descriptor.type value is used to determine whether the HTML element should be rendered as a value element (e.g. span, input, etc.) or a ‘transition’ element (e.g. form, a. img, etc.). Below is a table showing the various possibilities:
descriptor.type Value |
HTML Element |
|---|---|
safe |
HTML.A|IMG|IFRAME|FORM@mmethod="get" |
unsafe |
HTML.FORM@method="post" |
idempotent |
HTML.FORM@method="post"1 |
semantic |
HTML.SPAN|DIV|P|INPUT|LI|DT|DD|SECTION|…|FORM@method="get"2 |
|=============================== |
1. Since HTML does not support idempontent transitions |
the HTML.FORM element with the |
2) using an additional |
etc. |
2. In some cases |
servers MAY use a "safe" transition to express a |
a server might represent a |
. However |
if the result is not yet computed |
the server may represent |
== Mapping Examples |
Below are some examples to use as guides when mapping between ALPS and HTML. |
=== Search Example |
This is a very simple ALPS profile that defines a single semantic descriptor ("text") and a single safe descriptor ("search"). This profile describes the essence of the front end of any simple web-based search engine. Mapping this ALPS profile to an HTML4 document is rather straight-forward. |
---- |
<!-- ALPS Profile -→ |
<alps> |
<link rel="self" href="http://alps.io/profiles/search" /> <1> |
<descriptor id="text" type="semantic"> <2> |
<descriptor id="search" type="safe"> <3> |
</alps> |
<!-- HTML4 Representation -→ |
<html> |
<head profile="http://alps.io/profiles/search"> <1> |
</head> |
<body> |
<form action="…" method="get"> |
<input type="text" name="q" class="text" value=" /> <2> |
<input type="submit" class="search" /> <3> |
</form> |
</body> |
</html> |
---- |
=== User Account Example |
This example shows an ALPS profile that describes both reading and writing operations on a user account. It is also structured as a ‘flat’ ALPS document. The data elements (<2>) are listed separately from the transition elements (<3>). The profile does not constrain any server implementations to specific parameters for transitions; each server can select the data elements that best fit that server’s use cases. |
.ALPS User Account Profile |
---- |
<alps> |
<link rel="self" href="http://alps.io/profiles/useraccount" /> <1> |
<!-- data elements -→ <2> |
<descriptor id="user" type="semantic" /> |
<descriptor id="accessCode" type="semantic" /> |
<descriptor id="givenName" type="semantic" /> |
<descriptor id="familyName" type="semantic" /> |
<descriptor id="email" type="semantic" /> |
<descriptor id="telephone" type="semantic" /> |
<!-- transitions -→ <3> |
<descriptor id="list" type="safe" /> <4> |
<descriptor id="detail" type="safe" /> <5> |
<descriptor id="login-link" type="safe" name="login" /> <6> |
<descriptor id="login-form" type="unsafe" name="login" /> <7> |
<descriptor id="create-link" type="safe" name="create"/> <7> |
<descriptor id="create-form" type="unsafe" "name="create/> <8> |
<descriptor id="update-link" type="safe" name="update"/> <9> |
<descriptor id="update-form" type="idempotent" name="update" /> <10> |
<descriptor id="remove-link" type="safe" name="remove" /> <11> |
<descriptor id="remove-form" type="idempotent" name="remove" /> <12> |
</alps> |
---- |
.HTML5 Representation of a list of users (with link to login and creating new accounts) |
---- |
<html> |
<head> |
<title>User List</title> |
<link rel="profile" href="http://alps.io/profiles/useraccount" /> <1> |
</head> |
<body> |
<h1>User List</h1> |
<h2>Menu</h2> |
<ul> |
<li><a href="…" rel="collection" class="list">Refresh List</a></li> <4> |
<li><a href="…" rel="http://example.org/rels/login" class="login" data-alspid="login-link">Login</a></li> <6> |
<li><a href="…" rel="create-form" class="create" data-alpsid="create-link">Create Account</a></li> <7> |
</ul> |
<h2>Currrent Users</h2> |
<ul> |
<li><a href="…" rel="item" class="detail">Mary</a></li> <5> |
<li><a href="…" rel="item" class="detail">Mark</a></li> <5> |
<li><a href="…" rel="item" class="detail">Mandy</a></li> <5> |
<li><a href="…" rel="item" class="detail">Manfred</a></li> <5> |
<li><a href="…" rel="item" class="detail">Michelle</a></li> <5> |
<li><a href="…" rel="item" class="detail">Michael</a></li> <5> |
</ul> |
</body> |
</html> |
---- |
In the above HTML5 example |
the Menu section shows the use of the |
The following HTML5 representation is an example of what might be returned when a client application activates the |
.HTML5 Representation for creating a new user account. |
---- |
<html> |
<head> |
<title>Create Account</title> |
<link rel="profile" href="http://alps.io/profiles/useraccount" /> <1> |
</head> |
<body> |
<h1>Create Account</h1> |
<form action="…" method="post"> |
<label>User Name:<input name="user" class="user" /></label> |
<label>First Name:<input name="firstname" class="givenName" /></label> |
<label>Last Name:<input name="lastname" class="familyName" /></label> |
<label>Email:<input name="email" class="email" /></label> |
<label>SMS:<input name="sms" class="telephone" /></label> |
<input type="submit" value="Save" class="create" data-alpsid="create-form" /> <8> |
</form> |
</body> |
</html> |
---- |
What follows is an HTML response that might be returned when activating a |
.HTML5 Representation for updating an existing user account. |
---- |
<html> |
<head> |
<title>Update Account</title> |
<link rel="profile" href="http://alps.io/profiles/useraccount" /> <1> |
</head> |
<body> |
<h1>Update Account</h1> |
<form action="…" method="post"> |
<input type="hidden" name="etag" value="q1w2e3r4t5y6" /> <13> |
<label>User Name:<span class="user">mamund</span></label> |
<label>First Name:<input name="firstname" class="givenName" /></label> |
<label>Last Name:<input name="lastname" class="familyName" /></label> |
<label>Email:<input name="email" class="email" /></label> |
<label>SMS:<input name="sms" class="telephone" /></label> |
<input type="submit" value="Save" class="update" data-alspid="update-form"/> <10> |
</form> |
</body> |
</html> |
---- |
Note that the |
The same approach is used to support an idempotent "remove" operation in this next HTML representation: |
.HTML5 Representation for removing an existing user account. |
---- |
<html> |
<head profile="http://alps.io/profiles/useraccount"> <1> |
<title>Remove Account</title> |
</head> |
<body> |
<h1>Remove Account</h1> |
<form action="…" method="post"> |
<input type="hidden" name="etag" value="q1w2e3r4t5y6" /> <13> |
<input type="submit" value="Remove" class="remove" data-alpsid="remove-form" /> <12> |
</form> |
</body> |
</html> |
---- |
== References |
[[0]] 0. http://alps.io/spec |
[[1]] 1. http://www.w3.org/TR/2011/WD-html5-20110525/elements.html#attr-data |
[[3]] 3. http://www.w3.org/TR/html4/struct/global.html#adef-profile |