richard
/
SemanSemantic-UItic-UI
mirror of https://github.com/Semantic-Org/Semantic-UI.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Begin API docs

pull/1177/head
jlukic 10 years ago
parent
a0c1f98300
commit
d677eef3f5
1 changed files with 311 additions and 0 deletions
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 311
      server/documents/modules/api.html.eco

311
server/documents/modules/api.html.eco
View File

@ -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