From 5a00104a28396f7d4120317d179c4e9218113878 Mon Sep 17 00:00:00 2001 From: jlukic Date: Fri, 10 Oct 2014 18:32:49 -0400 Subject: [PATCH] more iteration on API docs --- server/documents/modules/api.html.eco | 296 +++++++++++++++++- server/files/javascript/semantic.js | 2 +- server/files/stylesheets/semantic.css | 5 +- src/definitions/behaviors/api.js | 33 +- src/definitions/collections/grid.less | 7 + .../default/collections/grid.variables | 6 +- 6 files changed, 318 insertions(+), 31 deletions(-) diff --git a/server/documents/modules/api.html.eco b/server/documents/modules/api.html.eco index 983358799..1522d687a 100644 --- a/server/documents/modules/api.html.eco +++ b/server/documents/modules/api.html.eco @@ -148,9 +148,22 @@ type : 'UI Behavior' }) ; +

Keep in mind passing a new settings object will destroy all previously attached events. If you want to preserve the events, you can trigger a new request with the the query behavior

+
+ // set-up API button with events + $('.follow.button') + .api({ + action: 'follow user' + }) + ; + // do an immediate query + $('.follow.button') + .api('query') + ; +
-

Providing Data

+

Setting URL Variables

URL Variables

@@ -161,8 +174,8 @@ type : 'UI Behavior'
-

...automatically Routed Data

-

Some useful values are automatically included in every request

+

Automatically Routed Data

+

Some special values are available for routing without additional set-up

@@ -191,7 +204,9 @@ type : 'UI Behavior'
- // replaces /search?query={value} + $.fn.api.settings.api = { + 'search' : '/search/?query={value}' + }; $('.search input') .api({ action: 'search', @@ -203,8 +218,9 @@ type : 'UI Behavior'
-

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

+

Data Attributes

+

You can include url values as metadata inside the DOM. +

This is often easiest to include unique url data for each triggering element. For example, many follow buttons will trigger the same endpoint, but each will have its own user id.

-

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

+

...specified in beforeSend Callback

+

All run settings, not just url data, can be adjusted in a special callback beforeSend which occurs before the API request is sent.

+

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

+
+ $('.follow.button') + .api({ + action: 'follow user', + beforeSend: function(settings) { + settings.urlData = { + id: 22 + }; + return settings; + } + }) + ; +
+
+ +

Routing GET/POST Data

+ +
+

...specified in beforeSend Callback

+

All run settings, not just url data, can be adjusted in a special callback beforeSend which occurs before the API request is sent.

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

$('.follow.button') @@ -264,13 +301,14 @@ type : 'UI Behavior'

For example you might expect all successful JSON responses to return a top level property signifying the success of the response

{ - success: true - data: { - proprietaryData: + "success": true, + "message": "We've retreived your data from the server" + "data": { + // payload here } }
-

Your success test recieves the servers json response, and should return true or false on whether the result should be considered successful. Succesful results will trigger onSuccess unsuccesful results onFailure but not onError, this is reserved for responses which return XHR errors.

+

The success test function recieves the servers json response, and returns whether the result should be considered successful. Succesful results will trigger onSuccess unsuccesful results onFailure but not onError, this is reserved for responses which return XHR errors.

$('.follow.button') .api({ @@ -336,6 +374,7 @@ type : 'UI Behavior'
$('.follow.button') + .api('setting', 'on', 'auto') .state({ text: { inactive : 'Follow', @@ -423,9 +462,238 @@ type : 'UI Behavior'
-
-

Needs to be written still...

+
+

+ API +

+ +

+ Behavior +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
DefaultDescription
onautoWhen API event should occur
filter +
+ .disabled +
+ 		Selector filter for elements that should not be triggerable
stateContextthis (selector/DOM element)UI state will be applied to this element, defaults to triggering element.
defaultDatatrueWhether to include default data like {value} and {text}
serializeForm(true, false)Whether to serialize closest form and include in request
throttle0If a request is pending, additional requests will be throttled by this duration in ms. (Setting above 0 will allow multiple simultaneous requests)
regExp +
+ regExp : { + required: /\{\$*[A-z0-9]+\}/g, + optional: /\{\/\$*[A-z0-9]+\}/g, + } +
+ 		Regular expressions used for finding variables in templated urls
+ +

+ Request Settings +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
DefaultDescriptionPossible Values
actionNamed API action for query, originally specified in $.fn.settings.apiString or false
urlfalseTemplated URL for query, will override specified actionString or false
urlDatafalseVariables to use for replacement
methodgetMethod for transmitting request to serverpost, get
dataTypeJSONExpected data type of response xml, json, jsonp, script, html, text
data{}POST/GET Data to Send with Request
filter +
+ .disabled +
+ 		Selector filter for elements that should not be triggerable
stateContextthis (selector/DOM element)UI state will be applied to this element, defaults to triggering element.
+ +

+ Callbacks +

+ + + + + + + + + + + + + + + + + + + + + + + + +
ContextDescription
onOpenactive contentCallback on element open
onCloseactive contentCallback on element close
onChangeactive contentCallback on element open or close
+ +

+ Module +

+ +

These settings are native to all modules, and define how the component ties content to DOM attributes, and debugging settings for the module.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
DefaultDescription
nameAccordionName used in log statements
namespaceaccordionEvent namespace. Makes sure module teardown does not effect other events attached to an element.
selector +
+ selector : { + accordion : '.accordion', + title : '.title', + content : '.content' + } +
+ 		Selectors used to find parts of a module
className +
+ className : { + active : 'active' + } +
+ 		Class names used to determine element state
debugfalseDebug output to console
performancefalseShow console.table output with performance metrics
verbosefalseDebug output includes all internal behaviors
errors +
+ error : { + method : 'The method you called is not defined.' + } +
+
diff --git a/server/files/javascript/semantic.js b/server/files/javascript/semantic.js index 25c55af40..9be832c0e 100755 --- a/server/files/javascript/semantic.js +++ b/server/files/javascript/semantic.js @@ -324,7 +324,7 @@ semantic.ready = function() { $rail = $('
') .addClass('ui close right rail') .html($sticky) - .appendTo($container) + .prependTo($container) ; $followMenu .accordion({ diff --git a/server/files/stylesheets/semantic.css b/server/files/stylesheets/semantic.css index eee1d95b1..ce1f93bc3 100755 --- a/server/files/stylesheets/semantic.css +++ b/server/files/stylesheets/semantic.css @@ -613,6 +613,9 @@ body#example.hide { padding: 3em 0em 0em; -webkit-tap-highlight-color: transparent; } +#example .example:last-child { + margin-bottom: 5em; +} /* Header */ #example .example > h4:first-child { @@ -1444,7 +1447,7 @@ body.progress.animated .ui.progress .bar { border-left: 1px solid #DDDDDD; border-right: 1px solid #DDDDDD; border-bottom: 1px solid #DDDDDD; - padding: 2em 2em 8em; + padding: 2em 2em; z-index: 1; } #example .wide.main.container { diff --git a/src/definitions/behaviors/api.js b/src/definitions/behaviors/api.js index ddabe6676..f649f1a02 100755 --- a/src/definitions/behaviors/api.js +++ b/src/definitions/behaviors/api.js @@ -113,8 +113,8 @@ $.api = $.fn.api = function(parameters) { return; } // determine if an api event already occurred - if(module.is.loading() && !settings.allowMultiple) { - module.debug('Request cancelled previous request is still pending'); + if(module.is.loading() && settings.throttle === 0 ) { + module.debug('Cancelling request, previous request is still pending'); return; } @@ -181,9 +181,17 @@ $.api = $.fn.api = function(parameters) { module.verbose('Creating AJAX request with settings', ajaxSettings); - // request provides a wrapper around xhr - module.request = module.create.request(); - module.xhr = module.create.xhr(); + if( !module.is.loading() ) { + module.request = module.create.request(); + module.xhr = module.create.xhr(); + } + else { + // throttle additional requests + module.timer = setTimeout(function() { + module.request = module.create.request(); + module.xhr = module.create.xhr(); + }, settings.throttle); + } }, @@ -745,32 +753,29 @@ $.api.settings = { // event binding on : 'auto', filter : '.disabled', - context : false, stateContext : false, // templating action : false, url : false, - regExp : { - required: /\{\$*[A-z0-9]+\}/g, - optional: /\{\/\$*[A-z0-9]+\}/g, - }, - // data urlData : {}, - // ui defaultData : true, serializeForm : false, - throttle : 100, - allowMultiple : false, + throttle : 0, // state loadingDuration : 0, errorDuration : 2000, + regExp : { + required: /\{\$*[A-z0-9]+\}/g, + optional: /\{\/\$*[A-z0-9]+\}/g, + }, + // jQ ajax method : 'get', data : {}, diff --git a/src/definitions/collections/grid.less b/src/definitions/collections/grid.less index 023914e65..283830bf4 100755 --- a/src/definitions/collections/grid.less +++ b/src/definitions/collections/grid.less @@ -882,6 +882,13 @@ table-layout: fixed; width: @tableWidth; } +.ui[class*="equal height"].relaxed.grid { + width: @relaxedTableWidth; +} +.ui[class*="equal height"][class*="very relaxed"].grid { + width: @veryRelaxedTableWidth; +} + .ui[class*="equal height"].grid > .row, .ui[class*="equal height"].row { display: table; diff --git a/src/themes/packages/default/collections/grid.variables b/src/themes/packages/default/collections/grid.variables index e15561b3c..b3b64861d 100755 --- a/src/themes/packages/default/collections/grid.variables +++ b/src/themes/packages/default/collections/grid.variables @@ -18,9 +18,9 @@ @gutterWidth: 2rem; @rowSpacing: 2rem; +@tableWidth: ~"calc(100% + "@gutterWidth~")"; @columnMaxImageWidth: 100%; -@tableWidth: ~"calc(100% + "@gutterWidth~")"; /******************************* Variations @@ -53,6 +53,10 @@ @relaxedGutterWidth: 3rem; @veryRelaxedGutterWidth: 5rem; +@relaxedTableWidth: ~"calc(100% + "@relaxedGutterWidth~")"; +@veryRelaxedTableWidth: ~"calc(100% + "@veryRelaxedGutterWidth~")"; + + /*-------------- Divided ---------------*/