jlukic
10 years ago
1 changed files with 311 additions and 0 deletions
Split View
Diff Options
@ -0,0 +1,311 @@ |
|||
--- |
|||
layout : 'default' |
|||
css : 'api' |
|||
|
|||
title : 'API' |
|||
description : 'API allows UI elements to send events to the server' |
|||
type : 'UI Behavior' |
|||
--- |
|||
|
|||
<script src="/javascript/library/sinon.js"></script> |
|||
<script src="/javascript/api.js"></script> |
|||
|
|||
<%- @partial('header', { tabs: 'behavior' }) %> |
|||
|
|||
<div class="main container"> |
|||
<div class="ui active tab" data-tab="overview"> |
|||
<div class="ui two column stackable grid"> |
|||
<div class="row"> |
|||
<div class="sixteen wide column"> |
|||
<p>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.</p> |
|||
</div> |
|||
</div> |
|||
<div class="row"> |
|||
<div class="column"> |
|||
<div class="content"> |
|||
<div class="ui header"><i class="green check icon"></i>Already Knows Your UI</div> |
|||
<p>Attach an API event to an input, by default, it will occur <code>oninput</code>. Attach an API event to a button, <code>onclick</code>. State management is built in: rate throttling, UI state changes like active, loading, disabled, min/max request lengths and more.</p> |
|||
</div> |
|||
</div> |
|||
<div class="column"> |
|||
<div class="content"> |
|||
<div class="ui header"><i class="green check icon"></i>Deal with resources not URLs</div> |
|||
<p> Store all your API endpoints as templated URLs in one place inside your code, and then trigger named <em>human readable</em> API actions like <code>'get tweet'</code>. </p> |
|||
<div class="ui button">See example</div> |
|||
</div> |
|||
</div> |
|||
</div> |
|||
<div class="row"> |
|||
<div class="column"> |
|||
<div class="content"> |
|||
<div class="ui header"><i class="green check icon"></i>URL Templating built In</div> |
|||
<p>API is made for REST. Store your API endpoints with url variables that are replaced at run-time.</p> |
|||
</div> |
|||
</div> |
|||
<div class="column"> |
|||
<div class="content"> |
|||
<div class="ui header"><i class="green check icon"></i>Server Traces For Humans</div> |
|||
<p>View your API request as it occurs, get errors if required url variables are missing, and other useful performance metrics.</p> |
|||
</div> |
|||
</div> |
|||
</div> |
|||
</div> |
|||
</div> |
|||
|
|||
<div class="ui tab" data-tab="usage"> |
|||
<div class="fixed column"> |
|||
<div class="content"> |
|||
<h2 class="ui header">Demo</h2> |
|||
<div class="ui items"> |
|||
<div class="item"> |
|||
<div class="image"> |
|||
<img src="/images/demo/highres3.jpg"> |
|||
</div> |
|||
<div class="content"> |
|||
<div class="ui fluid adopt toggle button" data-id="5209"> |
|||
<i class="checkmark icon"></i> |
|||
<span class="text">Adopt</span> |
|||
</div> |
|||
</div> |
|||
</div> |
|||
</div> |
|||
</div> |
|||
</div> |
|||
<div class="examples"> |
|||
|
|||
<h3 class="ui header">1. Define Your API</h3> |
|||
<p><b>API</b> 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.</p> |
|||
<p>To do this you must include a list of named endpoints before calling <code>$.api</code> on any page. The easiest way to do this is to have it available in a stand-alone configuration file.</p> |
|||
|
|||
<p>For the sake of this example we will use Github's public API as an example</p> |
|||
<div class="evaluated code"> |
|||
/* "Config.js" - Define API endpoints once globally */ |
|||
$.fn.api.settings.api = { |
|||
'follow user' : '/api/follow/{$id}', |
|||
'user info' : '/api/user/{$id}' |
|||
}; |
|||
</div> |
|||
<div class="code" data-type="html"> |
|||
<!-- Include on any page using API !--> |
|||
<script src="/config.js"></script> |
|||
</div> |
|||
|
|||
<h3 class="ui header">2. Attach an API event to an element</h3> |
|||
|
|||
<p>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 <code>click</code> or an input <code>oninputchange</code></p> |
|||
|
|||
<div class="evaluated code"> |
|||
$('.adopt.button') |
|||
.api({ |
|||
action: 'follow user' |
|||
}) |
|||
; |
|||
</div> |
|||
|
|||
<h3 class="ui header">2. Specify state changes to text or appearance (optional)</h3> |
|||
<p>API couples well with <a href="#">ui state</a>, a component used for managing text state and class names of elements.</p> |
|||
<p>State will automatically apply the class <code>active</code> 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.</p> |
|||
<div class="evaluated code"> |
|||
$('.adopt.button') |
|||
.state({ |
|||
text: { |
|||
inactive : 'Adopt', |
|||
active : 'Adopted', |
|||
deactivate : 'Undo', |
|||
flash : 'Success' |
|||
} |
|||
}) |
|||
; |
|||
</div> |
|||
|
|||
<h3 class="ui header">4. Make sure metadata is set for an element before event occurs</h3> |
|||
|
|||
<p>When an API action occurs, templated url data is replaced with data you specify to be sent to the server.</p> |
|||
<div class="code" data-type="html"> |
|||
<div class="ui adopt button" data-id="5209"></div> |
|||
</div> |
|||
<div class="ui horizontal divider">Or</div> |
|||
<p>Alternatively you can modify the data before sending to server</p> |
|||
<div class="code"> |
|||
$('.adopt.button') |
|||
.api('setting', 'beforeSend', function(settings) { |
|||
settings.urlData.id = 5209; |
|||
return settings; |
|||
}) |
|||
; |
|||
</div> |
|||
</div> |
|||
|
|||
</div> |
|||
|
|||
<div class="ui tab" data-tab="examples"> |
|||
|
|||
<div class="no example"> |
|||
<h4 class="ui header">Overlay</h4> |
|||
<p>A api can overlay page content instead of pushing it to the side</p> |
|||
<div class="code" data-demo="true"> |
|||
$('.overlay.api') |
|||
.api({ |
|||
overlay: true |
|||
}) |
|||
.api('toggle') |
|||
; |
|||
</div> |
|||
</div> |
|||
|
|||
</div> |
|||
|
|||
<div class="ui tab" data-tab="settings"> |
|||
|
|||
<h3 class="ui header"> |
|||
API Settings |
|||
<div class="sub header">Form settings modify the api behavior</div> |
|||
</h3> |
|||
<table class="ui celled sortable definition table segment"> |
|||
<thead> |
|||
<th>Setting</th> |
|||
<th class="four wide">Default</th> |
|||
<th>Description</th> |
|||
</thead> |
|||
<tbody> |
|||
<tr> |
|||
<td>overlay</td> |
|||
<td>false</td> |
|||
<td>Whether api should overlay page instead of pushing page to the side</td> |
|||
</tr> |
|||
<tr> |
|||
<td>exclusive</td> |
|||
<td>true</td> |
|||
<td>Whether multiple apis can be open at once</td> |
|||
</tr> |
|||
<tr> |
|||
<td>useCSS</td> |
|||
<td>true</td> |
|||
<td>Whether to use css animations or fallback javascript animations</td> |
|||
</tr> |
|||
<tr> |
|||
<td>duration</td> |
|||
<td>300</td> |
|||
<td>Duration of side bar transition animation</td> |
|||
</tr> |
|||
</tbody> |
|||
</table> |
|||
|
|||
<div class="ui horizontal section icon divider"><i class="icon setting"></i></div> |
|||
<h4 class="ui header">Callbacks</h4> |
|||
<p>Callbacks specify a function to occur after a specific behavior.</p> |
|||
|
|||
<table class="ui celled sortable definition table segment"> |
|||
<thead> |
|||
<th class="four wide">Setting</th> |
|||
<th>Context</th> |
|||
<th>Description</th> |
|||
</thead> |
|||
<tbody> |
|||
<tr> |
|||
<td>onShow</td> |
|||
<td>API</td> |
|||
<td>Is called when a api is shown.</td> |
|||
</tr> |
|||
<tr> |
|||
<td>onHide</td> |
|||
<td>API</td> |
|||
<td>Is called when a api is hidden.</td> |
|||
</tr> |
|||
<tr> |
|||
<td>onChange</td> |
|||
<td>API</td> |
|||
<td>Is called after a api changes visibility</td> |
|||
</tr> |
|||
</tbody> |
|||
</table> |
|||
|
|||
<div class="ui horizontal divider"><i class="icon setting"></i></div> |
|||
|
|||
<h3 class="ui header"> |
|||
DOM Settings |
|||
<div class="sub header">DOM settings specify how this module should interface with the DOM</div> |
|||
</h3> |
|||
<table class="ui celled definition table segment"> |
|||
<thead> |
|||
<th>Setting</th> |
|||
<th class="six wide">Default</th> |
|||
<th>Description</th> |
|||
</thead> |
|||
<tbody> |
|||
<tr> |
|||
<td>namespace</td> |
|||
<td>api</td> |
|||
<td>Event namespace. Makes sure module teardown does not effect other events attached to an element.</td> |
|||
</tr> |
|||
<tr> |
|||
<td>className</td> |
|||
<td> |
|||
<div class="code"> |
|||
className: { |
|||
active : 'active', |
|||
pushed : 'pushed', |
|||
top : 'top', |
|||
left : 'left', |
|||
right : 'right', |
|||
bottom : 'bottom' |
|||
} |
|||
</div> |
|||
</td> |
|||
<td>Class names used to attach style to state</td> |
|||
</tr> |
|||
</tbody> |
|||
</table> |
|||
|
|||
<div class="ui horizontal divider"><i class="icon setting"></i></div> |
|||
|
|||
<h3 class="ui header"> |
|||
Debug Settings |
|||
<div class="sub header">Debug settings controls debug output to the console</div> |
|||
</h3> |
|||
|
|||
<table class="ui celled sortable definition table segment"> |
|||
<thead> |
|||
<th>Setting</th> |
|||
<th class="four wide">Default</th> |
|||
<th>Description</th> |
|||
</thead> |
|||
<tbody> |
|||
<tr> |
|||
<td>name</td> |
|||
<td>API</td> |
|||
<td>Name used in debug logs</td> |
|||
</tr> |
|||
<tr> |
|||
<td>debug</td> |
|||
<td>True</td> |
|||
<td>Provides standard debug output to console</td> |
|||
</tr> |
|||
<tr> |
|||
<td>performance</td> |
|||
<td>True</td> |
|||
<td>Provides standard debug output to console</td> |
|||
</tr> |
|||
<tr> |
|||
<td>verbose</td> |
|||
<td>True</td> |
|||
<td>Provides ancillary debug output to console</td> |
|||
</tr> |
|||
<tr> |
|||
<td>errors</td> |
|||
<td colspan="2"> |
|||
<div class="code"> |
|||
error : { |
|||
method : 'The method you called is not defined.', |
|||
notFound : 'There were no elements that matched the specified selector' |
|||
} |
|||
</div> |
|||
</td> |
|||
</tr> |
|||
</tbody> |
|||
</table> |
|||
</div> |
|||
|
|||
</div> |
|||
</body> |
|||
</html> |
|||
Write
Preview
Loading…
Cancel
Save