Commit c9ec6e62 authored by Sven Franck's avatar Sven Franck

add functional descriptions (partial)

parent 1ec0842a
...@@ -11,35 +11,6 @@ ...@@ -11,35 +11,6 @@
// active on the page // active on the page
// -> for browser history, we would have to change the URL with a hash // -> for browser history, we would have to change the URL with a hash
// DISCUSSION POINTS:
// (1)
// (2) If not used for interactions or routing, what's the purpose of
// gadgetIndex?
// (3) Do we dumb-store in the index or perform some sort of validation
// before adding a gadget to an index?
// (4)
// (5) Should findGadget() = find recursive gadgets, also work with a single
// gadget id, like findGadget({"id":"1ewnel73"}), I guess not as we
// are using random uuids internally only
// (6)
// (7)
// (8)
// (9) When hard-coding services (see content.html), the "url" parameter can
// be omitted which would default to current iFrame (window) or root?
// (10)
// (11)is passing the root URL through the URL a security vulnerablity?
// (12)should findGadget and findService be API methods? They will scan the
// DOM for services/gadgets, but this should actually be done (and is done)
// automatically
// (13)we need to use an id to identify <frames> on a page, currently set as
// uuid by renderJs. We could also use data-id or remove the id and try
// to match by src (url), but this will be worse in terms of performance
// (14)what do to about service parameters. A service that requires parameters
// a and b passed to return c should somewhere also specify this. Do we
// need a service JSON/HAL API? or where should this information be made
// availabel
// Info: // Info:
// iframe communication: // iframe communication:
// http://bit.ly/11gjl1e // http://bit.ly/11gjl1e
...@@ -66,7 +37,7 @@ ...@@ -66,7 +37,7 @@
var priv = {}, var priv = {},
that = {}; that = {};
// ================== utility methods ================== // ================== helpers (needed) ==================
// extend $.deferred to allow multiple calls and resolves // extend $.deferred to allow multiple calls and resolves
// thx router.js // thx router.js
...@@ -145,6 +116,8 @@ ...@@ -145,6 +116,8 @@
priv.removeWhiteSpace = /\s+/mg; priv.removeWhiteSpace = /\s+/mg;
priv.removeWhiteSpaceBetweenElements = />\s+</mg; priv.removeWhiteSpaceBetweenElements = />\s+</mg;
// ================ ===== helpers (remove asap) ============================
// TODO: make renderJs work without these!
// => convert all URLs to absolute URLs // => convert all URLs to absolute URLs
// thx JQM - http://code.jquery.com/mobile/latest/jquery.mobile.js // thx JQM - http://code.jquery.com/mobile/latest/jquery.mobile.js
...@@ -1031,7 +1004,14 @@ ...@@ -1031,7 +1004,14 @@
// ================ public API (call on renderJs and $(elem) =========== // ================ public API (call on renderJs and $(elem) ===========
// => public API to map a URL via Ajax and run the result through a callback /**
* convert an url with ?file=base64 into object
* @method mapUrl
* @param {string} url/searchstring > window.location.search
* @param {function} callback
* @param {boolean} internal > if function was called internally
* @return {div} ajax data|jqXHR, textStatus, jqXHR|errorThrown | undefined
*/
that.mapUrl = function (url, callback, internal) { that.mapUrl = function (url, callback, internal) {
var queryString = typeof url === "string" ? url : url.search; var queryString = typeof url === "string" ? url : url.search;
...@@ -1050,23 +1030,33 @@ ...@@ -1050,23 +1030,33 @@
} }
}; };
// => publish a service to this instance (and root instance) /**
* add a service to the parent (and root) renderJs.gadgetService.map
* @method addService
* @param {object} options > addService will be called internally, too!!
*/
that.addService = $.fn.addService = function (options) { that.addService = $.fn.addService = function (options) {
var addressArray = window.location.href.split("?"), targetUrl; var addressArray = window.location.href.split("?"), targetUrl;
options.src = priv.makeUrlAbsolute(priv.decodeURI(options.src)) || addressArray[0]; options.src = priv.makeUrlAbsolute(priv.decodeURI(options.src)) || addressArray[0];
// posts to URL passed (need for CORS?) // posts to URL passed (need for CORS?)
// otherwise window.top.location.href) would also work // otherwise window.top.location.href) would also work
// TODO: clean this up
if (addressArray.length === 1) { if (addressArray.length === 1) {
targetUrl = priv.decodeURI(addressArray[0]); targetUrl = priv.decodeURI(addressArray[0]);
} else { } else {
targetUrl = priv.decodeURI(addressArray[1].split("=")[1]); targetUrl = priv.decodeURI(addressArray[1].split("=")[1]);
} }
// TODO: this should be a URL link // TODO: make this a link, ajaxPOST, which will then be called from dispatch()
window.top.postMessage(options, targetUrl); window.top.postMessage(options, targetUrl);
}; };
// => request a service to be run /**
* request a service to be run
* @method addService
* @param {options} options identifying service and parameters
* @param {function} callback, stored in $.deferred(!) to allow firing a postMessage returns answer
*/
that.requestService = $.fn.requestService = function (options, callbackFunction) { that.requestService = $.fn.requestService = function (options, callbackFunction) {
var deferred = new $.StatelessDeferred(), var deferred = new $.StatelessDeferred(),
callbackId = priv.generateUuid(), callbackId = priv.generateUuid(),
...@@ -1089,10 +1079,15 @@ ...@@ -1089,10 +1079,15 @@
options.type = "request/any"; options.type = "request/any";
} }
// TODO: make this a link, ajaxPOST, which will then be called from dispatch()
window.top.postMessage(options, window.location.href); window.top.postMessage(options, window.location.href);
}; };
// => add a gadget /**
* add a gadget to the DOM
* @method addGadget
* @param {options} options > addGadget will be called internally, too!!
*/
that.addGadget = $.fn.addGadget = function (options) { that.addGadget = $.fn.addGadget = function (options) {
var element = this[0]; var element = this[0];
...@@ -1114,18 +1109,18 @@ ...@@ -1114,18 +1109,18 @@
// set cors // set cors
// ======================== LOADING ======================== // ======================== gadget loading ========================
// module/requireJs // module/requireJs (nothing done)
if (options.module && require !== undefined) { if (options.module && require !== undefined) {
require([priv.extractModuleName(options.src)], function (response) { require([priv.extractModuleName(options.src)], function (response) {
priv.appendGadget(response, options); priv.appendGadget(response, options);
}); });
// iFrame // iFrame (working)
} else if (options.iframe) { } else if (options.iframe) {
priv.appendGadget(undefined, options); priv.appendGadget(undefined, options);
// straight ajax (default) // straight ajax (default, working)
} else { } else {
$.ajax({ $.ajax({
url: options.src, url: options.src,
...@@ -1140,7 +1135,11 @@ ...@@ -1140,7 +1135,11 @@
} }
}; };
// => find gadgets inside a newly added gadget /**
* recursively find hardcoded gadgets
* @method findGadget
* @param {object} sentRoot object in which new gadgets should be found
*/
that.findGadget = $.fn.findGadget = function (sentRoot) { that.findGadget = $.fn.findGadget = function (sentRoot) {
var root = sentRoot || this, var root = sentRoot || this,
spec = {}; spec = {};
...@@ -1153,7 +1152,11 @@ ...@@ -1153,7 +1152,11 @@
priv.findGadgetinHTML(spec, root); priv.findGadgetinHTML(spec, root);
}; };
// => recursive call - find services inside newly added gadget /**
* recursively find hardcoded services/methods
* @method findService
* @param {object} sentRoot object in which new services should be found
*/
that.findService = $.fn.findService = function (sentRoot) { that.findService = $.fn.findService = function (sentRoot) {
var root = sentRoot || this, var root = sentRoot || this,
spec = {}; spec = {};
...@@ -1166,20 +1169,23 @@ ...@@ -1166,20 +1169,23 @@
priv.findServiceInHTML(spec, root); priv.findServiceInHTML(spec, root);
}; };
// ================== ENTRY =============
// => start here // ======================== entry point ========================
// don't use doc.ready, but otherwise cannot load references to elements in // don't use doc.ready, but otherwise cannot load references to elements in
// body from <SCRIPT> in <HEAD> // body from <SCRIPT> in <HEAD>
$(document).ready(function() { $(document).ready(function() {
// prevent renderJs reloads from different URLs! // prevent renderJs reloads from different URLs!
// this does not solve the problem of re-requesting dependencies // this does not solve the problem of re-requesting dependencies
// with ?timestamp=_123241231231 when injecting elements into a page // with ?timestamp=_123241231231 when injecting elements into a page
// without iFrame // with plain AJAX!
if (window.renderJs === undefined) { if (window.renderJs === undefined) {
priv.initialize(); priv.initialize();
} }
}); });
// ======================== stuff done with Romain ========================
// TODO: integrate
////////////////////////////////////////////// //////////////////////////////////////////////
// Fake xhr to access local resource // Fake xhr to access local resource
////////////////////////////////////////////// //////////////////////////////////////////////
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment