Okay/Spec: Difference between revisions

Line 32:

== spaces ==

A '''~~space~~''' is a ~~container~~ for ~~rooms and accounts. In practical terms~~, a ~~space is a HTML document that contains links to resources associated with the space; this document is known as the space's '''root'''. Each space root <span class="must">must</span> meet all~~ [[Okay#~~discovery~~|~~discovery requirements~~]] ~~and <span class="must">must</span> provide some metadata for clients to display, a~~ [[Okay#~~rooms~~|~~room directory~~]], and ~~preferences page~~.

A '''Space''' is a HTML element providing URIs that clients can send requests to (for example, a [[Okay#rooms|room directory]] or [[Okay#initiation|registration page]]). Conceptually, spaces are isolated containers for rooms and user data.

=== discovery ===

For a client to recognise a ~~URI~~ as a space, it <span class="must">must</span>:

For a client to recognise a document as containing a space, it <span class="must">must</span>:

* Respond with 200 OK upon a GET request;

Line 42:

* Respond with a valid HTML document, -- TODO: define valid;

* Have the Access-Control-Allow-Origin header set to <code>*</code>;

* Contain a valid [[Okay#the element thereof|~~discovery element~~]].

* Contain valid [[Okay#the element thereof|ok-space]] markup.

If multiple ~~discovery elements are present on a page~~, the client <span class="should">should</span> ~~ask~~ the user to select which space it should use.

If a document contains multiple spaces, the client <span class="should">should</span> prompt the user to select which space it should use.

==== ~~the element thereof~~ ====

==== ok-space ====

~~The~~ '''~~discovery element~~''' ~~provides a list of resources associated with the space~~. ~~They look~~ like this:

Spaces are defined with the '''ok-space''' format. It looks like this:

<h1>This is an Okay space</h1>

<a href=“/rooms/” rel=“ok-rooms”>Rooms</a>

<a href=“/register/” rel=“ok-register”>Registration</a>

Line 56:

Line 57:

</nav></syntaxhighlight>

~~The discovery~~ element ~~is defined as any element with the~~ <code>ok-~~discover~~</code> ~~class. Any~~ non-void element ~~can be the discovery element, but it really <span class="should">should</span> be~~ a <code><nav /></code> ~~if you can help it. The discovery element <span class="must">must</span>~~ contain ~~a number of~~ anchor ~~(<code><a /></code>)~~ elements with valid ~~<code>~~rel~~</code>~~ and ~~<code>~~href~~</code>~~ attributes. Any invalid anchors <span class="must">must</span> be ignored by the client. The inner text of the anchor elements is not significant and <span class="must">must</span> be ignored by clients.

For an element to be valid <code>ok-space</code> markup, it must be a non-void element (ideally a <code><nav /></code>) and contain anchor elements with valid rel and href attributes. Any invalid anchors or elements not specified in the format <span class="must">must</span> be ignored by the client. The inner text of the anchor elements is not significant and <span class="must">must</span> be ignored by clients.

A list of valid anchor <code>rel</code> attributes and their purposes is described below:

Line 75:

Line 76:

|The space's preferences page.

|}

==== linking to other spaces ====

Clients can discover

== initiation ==

@@ Line 32: / Line 32: @@
 == spaces ==
-A '''space''' is a container for rooms and accounts. In practical terms, a space is a HTML document that contains links to resources associated with the space; this document is known as the space's '''root'''. Each space root <span class="must">must</span> meet all [[Okay#discovery|discovery requirements]] and <span class="must">must</span> provide some metadata for clients to display, a [[Okay#rooms|room directory]], and preferences page.
+A '''Space''' is a HTML element providing URIs that clients can send requests to (for example, a [[Okay#rooms|room directory]] or [[Okay#initiation|registration page]]). Conceptually, spaces are isolated containers for rooms and user data.
 === discovery ===
-For a client to recognise a URI as a space, it <span class="must">must</span>:
+For a client to recognise a document as containing a space, it <span class="must">must</span>:
 * Respond with 200 OK upon a GET request;
@@ Line 42: / Line 42: @@
 * Respond with a valid HTML document, -- TODO: define valid;
 * Have the Access-Control-Allow-Origin header set to <code>*</code>;
-* Contain a valid [[Okay#the element thereof|discovery element]].
+* Contain valid [[Okay#the element thereof|ok-space]] markup.
-If multiple discovery elements are present on a page, the client <span class="should">should</span> ask the user to select which space it should use.
+If a document contains multiple spaces, the client <span class="should">should</span> prompt the user to select which space it should use.
-==== the element thereof ====
+==== ok-space ====
-The '''discovery element''' provides a list of resources associated with the space. They look like this:
+Spaces are defined with the '''ok-space''' format. It looks like this:
-<syntaxhighlight lang="html"><nav class=“ok-discover”>
+<syntaxhighlight lang="html"><nav class=“ok-space”>
+  <h1>This is an Okay space</h1>
    <a href=“/rooms/” rel=“ok-rooms”>Rooms</a>
    <a href=“/register/” rel=“ok-register”>Registration</a>
@@ Line 56: / Line 57: @@
 </nav></syntaxhighlight>
-The discovery element is defined as any element with the <code>ok-discover</code> class. Any non-void element can be the discovery element, but it really <span class="should">should</span> be a <code><nav /></code> if you can help it. The discovery element <span class="must">must</span> contain a number of anchor (<code><a /></code>) elements with valid <code>rel</code> and <code>href</code> attributes. Any invalid anchors <span class="must">must</span> be ignored by the client. The inner text of the anchor elements is not significant and <span class="must">must</span> be ignored by clients.
+For an element to be valid <code>ok-space</code> markup, it must be a non-void element (ideally a <code><nav /></code>) and contain anchor elements with valid rel and href attributes. Any invalid anchors or elements not specified in the format <span class="must">must</span> be ignored by the client. The inner text of the anchor elements is not significant and <span class="must">must</span> be ignored by clients.
 A list of valid anchor <code>rel</code> attributes and their purposes is described below:
@@ Line 75: / Line 76: @@
 |The space's preferences page.
 |}
+==== linking to other spaces ====
+Clients can discover
 == initiation ==