Okay/Spec: Difference between revisions

Line 9:

* A room is just a special URI which you can POST messages to and GET them back from at a later date.

* You can use WebSockets to get a real-time feed of events that you’re interested in.

* Pretty much everything is represented as HTML over the wire. This allows most client implementations skip the bit where they convert every message into HTML, while providing a stable format for non-web platforms to convert into their own inferior representations. ~~This also has other~~ benefits~~, such as~~ allowing users to browse most spaces with just their web browser, and letting you do really really stupid things with your messages.

* Pretty much everything is represented as HTML over the wire. This allows most client implementations skip the bit where they convert every message into HTML, while providing a stable format for non-web platforms to convert into their own inferior representations. Other benefits include allowing users to browse most spaces with just their web browser, and letting you do really really stupid things with your messages.

* Authentication works by just signing every request with a key that gets generated by the client on first use.

Line 49:

==== ok-space ====

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

Spaces are declared using the '''ok-space''' micro-format. Upon retrieving a document, the client must scan for elements with the <code>ok-space</code> class, as well as links or anchors with the <code>ok-space</code> rel attribute. Here's an example of valid <code>ok-space</code> markup:

Line 58:

</nav></syntaxhighlight>

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.

For an element to be considered valid <code>ok-space</code> markup, it must be a non-void element (ideally a <code><nav /></code>) with the <code>ok-space</code> class and contain anchor elements with valid <code>rel</code> and <code>href</code> 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 78:

|}

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

A document can direct a client to another document containing a space using an <code><a /></code> or <code><link /></code> element with the <code>rel="ok-space"</code> attribute. The client must scan the linked document for valid <code>ok-space</code> markup, but it must not follow any further links or anchors with the <code>rel="ok-space"</code> attribute.

The URI provided may include a fragment component to specify which element the client should treat as [[Okay#ok-space|ok-space]] markup (e.g., <code><nowiki>https://example.com/#my-elem</nowiki></code>). The linked element must be valid <code>ok-space</code> markup. If the fragment is specified and the corresponding element is present in the linked document, the client must not scan any other part of the document for <code>ok-space</code> markup. <syntaxhighlight lang="html">

<!-- anchors work, too. this one forces the client to rummage around

for spaces like an animal -->

chat in the official Ben Folds Five space!!!

</a></syntaxhighlight>

==== metadata ====

Spaces can provide metadata about themselves to help users identify them.<syntaxhighlight lang="html"><nav class="ok-space">

</nav></syntaxhighlight>

== initiation ==

Line 116:

Line 134:

== pagination ==

Many lists can be '''paginated''' when it would be impractical to send its entire contents. This is common in message lists and room directories if you're getting a bit silly with it.

== critical reception ==

@@ Line 9: / Line 9: @@
 * A room is just a special URI which you can POST messages to and GET them back from at a later date.
 * You can use WebSockets to get a real-time feed of events that you’re interested in.
-* Pretty much everything is represented as HTML over the wire. This allows most client implementations skip the bit where they convert every message into HTML, while providing a stable format for non-web platforms to convert into their own inferior representations. This also has other benefits, such as allowing users to browse most spaces with just their web browser, and letting you do really really stupid things with your messages.
+* Pretty much everything is represented as HTML over the wire. This allows most client implementations skip the bit where they convert every message into HTML, while providing a stable format for non-web platforms to convert into their own inferior representations. Other benefits include allowing users to browse most spaces with just their web browser, and letting you do really really stupid things with your messages.
 * Authentication works by just signing every request with a key that gets generated by the client on first use.
@@ Line 49: / Line 49: @@
 ==== ok-space ====
-Spaces are defined with the '''ok-space''' format. It looks like this:
+Spaces are declared using the '''ok-space''' micro-format. Upon retrieving a document, the client must scan for elements with the <code>ok-space</code> class, as well as links or anchors with the <code>ok-space</code> rel attribute. Here's an example of valid <code>ok-space</code> markup:
 <syntaxhighlight lang="html"><nav class=“ok-space”>
@@ Line 58: / Line 58: @@
 </nav></syntaxhighlight>
-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.
+For an element to be considered valid <code>ok-space</code> markup, it must be a non-void element (ideally a <code><nav /></code>) with the <code>ok-space</code> class and contain anchor elements with valid <code>rel</code> and <code>href</code> 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 78: / Line 78: @@
 |}
 ==== linking to other spaces ====
+A document can direct a client to another document containing a space using an <code><a /></code> or <code><link /></code> element with the <code>rel="ok-space"</code> attribute. The client must scan the linked document for valid <code>ok-space</code> markup, but it must not follow any further links or anchors with the <code>rel="ok-space"</code> attribute.
+The URI provided may include a fragment component to specify which element the client should treat as [[Okay#ok-space|ok-space]] markup (e.g., <code><nowiki>https://example.com/#my-elem</nowiki></code>). The linked element must be valid <code>ok-space</code> markup. If the fragment is specified and the corresponding element is present in the linked document, the client must not scan any other part of the document for <code>ok-space</code> markup. <syntaxhighlight lang="html"><!-- link to a space with the id "space" -->
+<link rel="ok-space" href="https://example.ok/#space" />
+<!-- anchors work, too. this one forces the client to rummage around
+     for spaces like an animal -->
+<a rel="ok-space" href="https://benfoldsfive.example/">
+    chat in the official Ben Folds Five space!!!
+</a></syntaxhighlight>
+==== metadata ====
+Spaces can provide metadata about themselves to help users identify them.<syntaxhighlight lang="html"><nav class="ok-space">
+    <h1 class="title"></h1>
+    <p class="subtitle"></p>
+    <p class="description"></p>
+    <img class="icon" src="">
+    <!-- ... -->
+</nav></syntaxhighlight>
 == initiation ==
@@ Line 116: / Line 134: @@
 == pagination ==
+Many lists can be '''paginated''' when it would be impractical to send its entire contents. This is common in message lists and room directories if you're getting a bit silly with it.
 == critical reception ==