From a0e4dc930e03087cdae6009fdff519364398f21d Mon Sep 17 00:00:00 2001 From: jlukic Date: Thu, 9 Oct 2014 17:04:57 -0400 Subject: [PATCH] Iteration on API docs --- server/documents/collections/grid.html.eco | 2 +- server/documents/modules/api.html.eco | 275 +++++++++++++++------ server/files/javascript/api.js | 7 +- server/files/javascript/semantic.js | 1 - server/files/stylesheets/semantic.css | 31 ++- server/layouts/default.html.eco | 3 - src/definitions/behaviors/api.js | 17 +- src/definitions/behaviors/state.js | 93 ++++--- 8 files changed, 284 insertions(+), 145 deletions(-) diff --git a/server/documents/collections/grid.html.eco b/server/documents/collections/grid.html.eco index c22aa897c..3f5fc5abd 100755 --- a/server/documents/collections/grid.html.eco +++ b/server/documents/collections/grid.html.eco @@ -198,7 +198,7 @@ themes : ['Default']

Page Grid Breakpoints

Semantic's page grid, by default, uses percentage values for page gutters. This means your page container will constantly adjust as the browser width changes, giving you the largest possible space for each breakpoint.

Grids, rows, and columns can receive responsive classes to make them appear only on a particular device.

- +
diff --git a/server/documents/modules/api.html.eco b/server/documents/modules/api.html.eco index 9f8bdae3a..6eb3fa758 100644 --- a/server/documents/modules/api.html.eco +++ b/server/documents/modules/api.html.eco @@ -3,8 +3,8 @@ layout : 'default' css : 'api' title : 'API' -description : 'API allows UI elements to send events to the server' -type : 'UI Behavior' +description : 'API allows elements to trigger actions on a server' +type : 'Draft' --- @@ -17,7 +17,7 @@ type : 'UI Behavior'
-

Semantic API helps attach server events to UI elements. There a few key features which make API more useful then jQuery AJAX or and simpler than MVC patterns.

+

There a few key features which make API more useful then jQuery AJAX or and simpler than MVC patterns.

@@ -37,8 +37,8 @@ type : 'UI Behavior'
-
URL Templating built In
-

API is made for REST. Store your API endpoints with url variables that are replaced at run-time.

+
State Management
+

Easily tie server events like AJAX loading elements using intuitive defaults based on the context inside your interface. Set maximum and minimum request times, toggle between UI states, and easily sync state between multiple elements with the same API actions.

@@ -70,42 +70,54 @@ type : 'UI Behavior'
-

Creating an API

+

Defining Your API

-

Define Your API

-

API works best by defining named API actions which can be converted to URLs for each request/

-

To do this you must define your endpoints once in your application before making requests. Usually this is done in a central configuration file included on each page.

+

Creating Server Actions

+

API works best by defining named API actions which can be converted to URLs for each request.

+

You must define your endpoints once in your application before making requests. Usually this is done in a central configuration file included on each page.

URLs listed in your API can include required parameters and optional parameters which may be adjusted for each call.

-

Required Parameters will abort the request if they cannot be replaced when triggered.

-

Optional Parameters will be removed from the url if are not included when triggered. In addition, any trailing slashes before an optional parameter will also be removed from the URL, allowing you to include them in resource paths.

-
- $.fn.api.settings.api = { - 'endpoint': 'api/{required}/{/optional}/{/optional2}' - }; +
+
+
Required Parameters
+
+
Uses format {variable}
+
Will abort the request if they cannot be found.
+
+
+
+
Optional Parameters
+
+
Uses format {/variable}
+
Will abort the request if they cannot be found.
+
Will be removed from the url automatically if not available.
+
Any trailing slashes before optional parameters will also be removed from the URL, allowing you to include them in resource paths.
+
+
-
/* Define API endpoints once globally */ $.fn.api.settings.api = { - 'get user' : '/user/{id}', 'get followers' : '/followers/{id}?results={count}', 'follow user' : '/follow/{id}', - 'add user' : '/add/{id}', + 'search' : '/search/?query={value}' };
-

Calling API Actions

+

Querying API Actions

+
+
Open Your Web Console
+ The following examples work best while viewing logs in your web console. This experienced is optimized for Firebug, but will also appear in webkit browsers with minor issues. +
+
+ API requests for the following demos have been faked using SinonJS to avoid rate throttling from public APIs. No actual data is returned. +
-

Automatic Events

+

Attaching API to UI

-

Any element can have an API action attached, by default the action will occur on the most relevant event for the type of element. For example a button will use onclick or an input oninput.

- -
- AJAX requests for the following demos have been faked using SinonJS to avoid rate throttling from public APIs. -
+

Any element can have an API action attached directly to it. By default the action will occur on the most appropriate event for the type of element. For example a button will assume onclick or an input oninput, or a form onsubmit.

$('.follow.button') @@ -117,13 +129,13 @@ type : 'UI Behavior'
-

Manual Events

-

If you need to manually override what action an API event occurs on you can use the on parameter. In addition, using the special parameter on: 'now' will trigger the api event immediately.

+

Specifying Events

+

If you need to override what action an API event occurs on you can use the on parameter.

$('.follow.button') .api({ - action: 'get user', - on: 'hover' + action: 'follow user', + on: 'mouseenter' }) ;
@@ -131,7 +143,8 @@ type : 'UI Behavior'

Calling Immediately

-

If you need to manually override what action an API event occurs on you can use the on parameter. In addition, using the special parameter on: 'now' will trigger the api event immediately.

+

If you require API action to occur immediately use on: 'now'. This will still trigger the same state updates to the invoked element, but will occur immediately.

+

$('.follow.button') .api({ @@ -142,20 +155,81 @@ type : 'UI Behavior'
-

Setting Conditions

+

Providing Data

-

URL Variables For API Request

-

Templated variables set in your API are replaced during your request in three different ways.

+

URL Variables

+

If your API urls include templated variables they will be replaced during your request by one of four possible ways (listed in order of inheritance).

+
+ Only variables specified in your URL will be searched for in metadata. Adding metadata attributes will not be automatically included in GET or POST values. +
+
-
...by Data Attributes
-

If many elements trigger a similar function, it is often easiest to include data attribute for each instance with the specific url variables

+
+

...automatically Routed Data

+

Some useful values are automatically included in every request

+
Name
+ + + + + + + + + + + + + + + + + + + +
VariableDescriptionAvailable for
textcurrent text value of elementAll DOM elements
valuecurrent input value of elementAll input elements
+
+
+ + +
+
+
+ // replaces /search?query={value} + $('.search input') + .api({ + action: 'search', + // this setting will be explained later + stateContext: '.ui.input' + }) + ; +
+ + +
+

...by Data Attributes

+

If many elements trigger a similar function, it is often easiest to include unique url data in each triggering element. For example, many follow buttons will trigger the same endpoint, but each will have its own user id.

- - + +
-
....in Javascript
-

URL variables can be specified at run-time in the javascript object

+
+ $('.follow.button') + .api({ + action: 'follow user' + }) + ; +
+
+ +
+

....in Javascript

+

URL variables can be specified at run-time in the javascript object

$('.follow.button') .api({ @@ -166,7 +240,10 @@ type : 'UI Behavior' }) ;
-
...returned values from beforeSend Callback
+
+ +
+

...returned values from beforeSend Callback

In addition all parameters can be adjusted in a special callback beforeSend which occurs, quite intuitively, before the API request is sent.

You can also use this callback to adjust other settings before each API call

@@ -184,22 +261,101 @@ type : 'UI Behavior'
+

Controlling State

+
-

3. Defining UI State

+

UI State

Many elements like button, input, and form have loading, disabled, and active states defined.

-
Learn more about states
- -

API will automatically attach a Loading state when an API request is triggered, additional states can be attached using state behaviors, an optional component that couples well with API behaviors.

+

API will automatically attach a loading state when an API request is triggered, but makes no other assumptions about states.

+
-

If state is initialized, it will automatically apply the class active on API success, and update any text nodes with new values specified.

+
+

State Management

+

If state() is invoked after an API event is attached to an element, it will automatically toggle an active state on the element after a successful API request.

+

Basic included states

+ + + + + + + + + + + + + + + + + + + + + +
StateDescriptionAPI event
loadingIndicates a user needs to waitXHR has initialized
errorIndicates an error has occurredRequest returns error (does not trigger onAbort caused by page change)
+
-

State also includes other states:

+
+

UI State

+ +

Invoking state also includes additional states which can adjust text values:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
StateDescriptionOccurs on
inactiveUser has not selected
activeUser has selectedToggled on succesful API request
activateText explaining activating actionOn hover if inactive
deactivatedefault state
hoverText-only state explaining interactionOn hover if inactive or active
disabledIndicates element is disabledOnly triggered programatically
FlashText-only state used to display a temporary messageOnly triggered programatically
DisabledCannot receive user interaction
- -
-

4. Make sure metadata is set for an element before event occurs

- -

When an API action occurs, templated url data is replaced with data you specify to be sent to the server.

-
-
-
-
Or
-

Alternatively you can modify the data before sending to server

-
- $('.adopt.button') - .api('setting', 'beforeSend', function(settings) { - settings.urlData.id = 5209; - return settings; - }) - ; -
-
diff --git a/server/files/javascript/api.js b/server/files/javascript/api.js index 77241fb28..b5633e796 100755 --- a/server/files/javascript/api.js +++ b/server/files/javascript/api.js @@ -1,11 +1,11 @@ /* Define API endpoints once globally */ $.fn.api.settings.debug = true; +/* Define API endpoints once globally */ $.fn.api.settings.api = { - 'get user' : '/user/{id}', 'get followers' : '/followers/{id}?results={count}', 'follow user' : '/follow/{id}', - 'add user' : '/add/{id}', + 'search' : '/search/?query={value}' }; semantic.api = {}; @@ -28,6 +28,9 @@ semantic.api.ready = function() { server .respondWith(/\/follow\/(\d+)/, [responseCode, headers, body]) ; + server + .respondWith(/\/search\/(.*)/, [responseCode, headers, body]) + ; }; diff --git a/server/files/javascript/semantic.js b/server/files/javascript/semantic.js index b2e05ba67..79f3de366 100755 --- a/server/files/javascript/semantic.js +++ b/server/files/javascript/semantic.js @@ -901,7 +901,6 @@ semantic.ready = function() { mobileTransition : 'uncover' }) .sidebar('attach events', '.launch.button, .view-ui, .launch.item') - .sidebar('attach events', $hideMenu, 'hide') ; handler.createIcon(); diff --git a/server/files/stylesheets/semantic.css b/server/files/stylesheets/semantic.css index 171ef71eb..cf9658403 100755 --- a/server/files/stylesheets/semantic.css +++ b/server/files/stylesheets/semantic.css @@ -340,6 +340,13 @@ a:hover { Fixed Columns ---------------*/ +#example .fixed.column { + position: absolute; + right: 2em; + top: 0px; + width: 300px; +} + #example .tab.header.segment .fixed .tabular.menu { position: fixed; top: 50px; @@ -347,12 +354,8 @@ a:hover { #example .fixed .launch { display: none; } - -#example .fixed.column { - position: relative; -} #example .fixed.column .sticky { - padding-top: 3em; + padding-top: 4em; } @@ -668,8 +671,11 @@ body#example.hide { } -#example .intro .example h4 ~ p, -#example .intro .example h4 ~ .ignored { +#example .intro .example > h4 { + font-size: 1.2em; +} +#example .intro .example > h4 ~ p, +#example .intro .example > h4 ~ .ignored { margin: 1em 0em !important; font-size: 14px; } @@ -706,6 +712,9 @@ body#example.hide { clear: both; visibility: hidden; } +#example .example-group { + position: relative; +} #example .main.container .examples > h2, #example .main.container > h2, #example .main.container > .tab > h2{ @@ -1722,23 +1731,21 @@ body.progress.animated .ui.progress .bar { } @media only screen and (max-width : 998px) { #example .examples { - margin-right: 220px; + margin-right: 230px; padding: 1px; } #example .fixed.column, #example .fixed.column .fixed { - float: right; width: 200px; } } @media only screen and (min-width : 998px) { #example .examples { - margin-right: 320px; + margin-right: 280px; padding: 1px; } #example .fixed.column, #example .fixed.column .fixed { - float: right; - width: 300px; + width: 250px; } } \ No newline at end of file diff --git a/server/layouts/default.html.eco b/server/layouts/default.html.eco index 4d05c1ddb..96484334b 100755 --- a/server/layouts/default.html.eco +++ b/server/layouts/default.html.eco @@ -179,9 +179,6 @@