diff --git a/server/documents/modules/api.html.eco b/server/documents/modules/api.html.eco new file mode 100644 index 000000000..1d957a33a --- /dev/null +++ b/server/documents/modules/api.html.eco @@ -0,0 +1,311 @@ +--- +layout : 'default' +css : 'api' + +title : 'API' +description : 'API allows UI elements to send events to the server' +type : 'UI Behavior' +--- + + + + +<%- @partial('header', { tabs: '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.

+
+
+
+
+
+
Already Knows Your UI
+

Attach an API event to an input, by default, it will occur oninput. Attach an API event to a button, onclick. State management is built in: rate throttling, UI state changes like active, loading, disabled, min/max request lengths and more.

+
+
+
+
+
Deal with resources not URLs
+

Store all your API endpoints as templated URLs in one place inside your code, and then trigger named human readable API actions like 'get tweet'.

+
See example
+
+
+
+
+
+
+
URL Templating built In
+

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

+
+
+
+
+
Server Traces For Humans
+

View your API request as it occurs, get errors if required url variables are missing, and other useful performance metrics.

+
+
+
+
+
+ +
+
+
+

Demo

+
+
+
+ +
+
+
+ + Adopt +
+
+
+
+
+
+
+ +

1. Define Your API

+

API works best when using a named list of endpoints. This means you can maintain all of your website's API endpoints in a single location, without having to update them across the site.

+

To do this you must include a list of named endpoints before calling $.api on any page. The easiest way to do this is to have it available in a stand-alone configuration file.

+ +

For the sake of this example we will use Github's public API as an example

+
+ /* "Config.js" - Define API endpoints once globally */ + $.fn.api.settings.api = { + 'follow user' : '/api/follow/{$id}', + 'user info' : '/api/user/{$id}' + }; +
+
+ + +
+ +

2. Attach an API event to an element

+ +

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 on click or an input oninputchange

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

2. Specify state changes to text or appearance (optional)

+

API couples well with ui state, a component used for managing text state and class names of elements.

+

State will automatically apply the class active on API success, and update any text nodes with new values specified. This example updates the text of a follow button to "following" when the API action is successful, after flashing the text success.

+
+ $('.adopt.button') + .state({ + text: { + inactive : 'Adopt', + active : 'Adopted', + deactivate : 'Undo', + flash : 'Success' + } + }) + ; +
+ +

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; + }) + ; +
+
+ +
+ +
+ +
+

Overlay

+

A api can overlay page content instead of pushing it to the side

+
+ $('.overlay.api') + .api({ + overlay: true + }) + .api('toggle') + ; +
+
+ +
+ +
+ +

+ API Settings +
Form settings modify the api behavior
+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SettingDefaultDescription
overlayfalseWhether api should overlay page instead of pushing page to the side
exclusivetrueWhether multiple apis can be open at once
useCSStrueWhether to use css animations or fallback javascript animations
duration300Duration of side bar transition animation
+ +
+

Callbacks

+

Callbacks specify a function to occur after a specific behavior.

+ + + + + + + + + + + + + + + + + + + + + + + + +
SettingContextDescription
onShowAPIIs called when a api is shown.
onHideAPIIs called when a api is hidden.
onChangeAPIIs called after a api changes visibility
+ +
+ +

+ DOM Settings +
DOM settings specify how this module should interface with the DOM
+

+ + + + + + + + + + + + + + + + + + +
SettingDefaultDescription
namespaceapiEvent namespace. Makes sure module teardown does not effect other events attached to an element.
className +
+ className: { + active : 'active', + pushed : 'pushed', + top : 'top', + left : 'left', + right : 'right', + bottom : 'bottom' + } +
+ 		Class names used to attach style to state
+ +
+ +

+ Debug Settings +
Debug settings controls debug output to the console
+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SettingDefaultDescription
nameAPIName used in debug logs
debugTrueProvides standard debug output to console
performanceTrueProvides standard debug output to console
verboseTrueProvides ancillary debug output to console
errors +
+ error : { + method : 'The method you called is not defined.', + notFound : 'There were no elements that matched the specified selector' + } +
+
+
+ +
+ + \ No newline at end of file