dist/jsUtils-0.2.4.js @@ -3,107 +3,14 @@ JSUtils is a lightweight javascript library, built to encourage modular code design. -* [Download][7] - [latest][8] | [0.1.1][9] -* [Source @ GitHub][10] +* [Download][1] +* [API Docs][2] +* [Tests][3] +* [Source @ GitHub][4] -[7]: http://projects.linode.gandrew.com/jsUtils/dist/ +[1]: http://projects.gandrew.com/jsUtils/dist/ +[2]: http://projects.gandrew.com/jsUtils/docs/ +[3]: http://projects.gandrew.com/jsUtils/test/AllTests.html +[4]: http://github.com/gingerhendrix/jsutils -[8]: http://projects.linode.gandrew.com/jsUtils/dist/jsUtils.js - -[9]: http://projects.linode.gandrew.com/jsUtils/dist/jsUtils-0.1.1.js - -[10]: http://github.com/gingerhendrix/jsutils - -## API Reference - -### Utils.namespace - -`<Object namespace> Utils.namespace(<String namespace> [, extensions ])` - -`namespace` creates a new global namespace object. It takes a namespace -argument which is a dot separated string containing the name of the namespace -to be created eg. `Utils.namespace("some.name.space")`. If the named global -object or any of the objects in the chain are not defined, it will create an -empty object with that name i.e. if no objects are defined the above code is -equivalent to `var some = {}; some.name = {}; some.name.space = {};` - -Any additional arguments are passed to `extend` which is called with the -namespace object as the source. - - Utils.namespace("some.name.space", function(){ - // Private scope - return { - someFunction : function(){ /* ... */ } - }; - }); - -### Utils.extend - -`<Object source> Utils.extend(<Object source>, extension [, extensions ])` - -`extend` takes a source argument which is the object to be extended, and at -least one extension argument. If the extension argument is an `Object` then -the properties of the extension are copied to the source argument. If the -extension argument is a `Function` then the the function is called and the -source is extended with the return value of the function. If the extension -argument is an `Array` or there are more than one extension arguments, the -source is extended with each of the elements in the array. - - Utils.extend(someObject, function(){ - // ... - return { - someFunction : function(){ /* ... */ } - }; - }); - -### Utils.replaceNamespace - -`<Object namespace> Utils.replaceNamespace(<String namespace> [, extensions])` - -`replaceNamespace` is a destructive version of `namespace`. `replaceNamespace` -will replace the namespace object (but not it's predecessors in the chain) if -it is already defined. `replaceNamespace` also records the original value of -the namespace object, so that it can be recovered with `revertNamespace`. - - Utils.replaceNamespace("SomeNamespace") - -### Utils.revertNamespace - -`<Object namespace> Utils.revertNamespace(<String namespace>)` - -`revertNamespace` allows the namespace to be renamed in case of conflict. -This method only works if the namespace was initially created with -`replaceNamespace`. - - var NewNamespace = Utils.revertNamespace("SomeNamespace") - -### Utils.Extendable - -`<Extendable>.extend(extension [, extensions])` - -`Extendable` is a mixin object which adds extend abilities to any object. - - Utils.extend(someObject, Utils.Extendable); - someObject.extend({ someFunc : function(){} } ); - -### Utils.Namespaceable - -`<Namespaceable>.namespace(name [, extensions])` - -`Namespaceable` is a mixin object which adds namespace abilities to any -object. - - Utils.namespace("SomeNamespace", Utils.Namespaceable); - SomeNamespace.namespace("Utils"); - // SomeNamespace.Utils.someFunc = ... - -### Utils.Revertable - -`<Revertable>.revertNamespace()` - -`Revertable` is a mixin object which adds `revertNamespace` to a namespace -object created with `replaceNamespace`. - - Utils.replaceNamespace("SomeNamespace", Utils.Revertable) - var NewNamespace = SomeNamespace.revertNamespace() README.markdown @@ -1,18 +1,7 @@ - -== 0.2.0 - -* Create signals library -* Add databean class from mushub -* Add basic cross-platform http requests -* Add datasource library - -== 0.2.1 - -* Add script tag based JSONP support - -== Future - -* Add JSBeans library from Pierrot - and refactor databean -* Add package dependencies or use those from Base2 +0.2.5 + Add querystring +0.3 + Add JSBeans library from Pierrot - and refactor databean + Add package dependencies or use those from Base2 TODO @@ -215,12 +215,30 @@ return Utils.revertNamespace(this.__NAMESPACE__); } } - + /** + * The main jsUtils signals helpers namespace. + * Signals are a method for asynchronous notification. + * Signals are sent to a slot which is made up of a source object + * and a signal name. Listeners can connect to slot to receive any + * signals sent there. + * + * @class Utils.signals + * @static + * @global + */ Utils.namespace("Utils.signals", (function(){ var observers = []; return { + + /** + * Send an asynchronous signal to a slot. + * + * @method signal + * @param src {Object} the source of the slot + * @param signal {String} the name of the slot + */ signal : function(src, signal){ for(var i=0; i<observers.length; i++){ var ob = observers[i]; @@ -234,16 +252,37 @@ Utils.namespace("Utils.signals", (function(){ } }, + /** + * Connect a listener to a slot. + * + * @method connect + * @param src {Object} the source of the slot + * @param signal {String} the name of the slot + * @param listener {Function} the function to be called when a signal is sent to this slot. + */ connect : function(src, signal, listener){ var ident = { source : src, signal : signal, listener : listener}; observers.push(ident); } } })() ); + /** + * The main jsUtils http helpers namespace. + * + * @class Utils.http + * @static + * @global + */ Utils.namespace("Utils.http"); - +/** + * A low-level utility method for obtaining a new XMLHttpRequest + * in a cross-browser manner. + * + * @method createXMLHttpRequst + * @return {XMLHttpRequest} an implementation of XMLHttpRequest +*/ Utils.http.createXMLHttpRequest = function(){ //Borrowed form Ajax Cookbook - http://ajaxcookbook.org/xmlhttprequest/ //Might be better off a fully-fledged wrapper like Sergey Illinsky's @@ -257,7 +296,14 @@ Utils.http.createXMLHttpRequest = function(){ } }; - +/** + * A simple method for performing an asynchonous GET request via xhr + * + * @method get + * @param uri {String} the uri to retrieve + * @param callback {Function} the function to call when the data is available, the function will be called with xhr object as its first argument. + * @param errback {Function} the function to call an error occurs or the request.status != 200, the function will be called with xhr object as its first argument. +*/ Utils.http.get = function(uri, callback, errback){ var req = Utils.http.createXMLHttpRequest(); req.open('GET', uri, true); @@ -297,6 +343,17 @@ Utils.http.get = function(uri, callback, errback){ scriptRequests[scriptId].errback(); }; +/** + * A simple method for performing an asynchonous jsonp GET request via the script tag. + * This can be used for loading data cross-domain. The data provider must support json requests. + * + * @method scriptRequest + * @param uri {String} the uri to retrieve + * @param jsonp {String} the request-parameter to use to provide the jsonp callback to the service + * @param callback {Function} the function to call when the data is available, the function will be called with the deserialized json as its first argument. + * @param errback {Function} the function to call when an error occurs + * @param timeout an optional time before the scriptRequest gives up and calls the errback. +*/ Utils.http.scriptRequest = function(uri, jsonp, callback, errback, timeout){ timeout = timeout || 2000; var scriptEl = document.createElement("script"); @@ -321,14 +378,39 @@ Utils.http.get = function(uri, callback, errback){ })(); - Utils.namespace("Utils", { + +Utils.namespace("Utils", { + /** + * A simple value-object, with functions for property accessors and mutators. + * Mutator also fires a signal when the property changes. + * + * @class Utils.DataBean + * @constructor + * @global + */ DataBean : function(){ this.properties = {}; - this.connect = function(name, obj, method){ - Utils.signals.connect(this, name, obj, method); + /** + * Connect to a properties slot. + * + * @method connect + * @param name {String} the name of the property + * @param listener {Function} the function to call when the signal is fired. + */ + this.connect = function(name, method){ + Utils.signals.connect(this, name, method); } + /** + * Add a property to this object. + * After calling dataBean.makeProp('attribute'), the dataBean will have a new method dataBean.attribute(), + * this method when called with no-args acts as an accessor, and when called with args it acts like a mutator. + * The mutator will also fire a signal (with the name of the attribute) when the value changes. + * + * @method makeProp + * @param attribute {String} the name of the attribute to create + */ this.makeProp = function(prop){ this[prop] = function(val){ @@ -342,24 +424,6 @@ Utils.http.get = function(uri, callback, errback){ } } }); - //Get artist name from URL -function QueryString(qs){ - this.parts = {}; - var self = this; - - if(qs.indexOf("?")==0){ - qs = qs.substring(1); - } - - qs.split("&").forEach(function(pair){ - var bits = pair.split("="); - self.parts[bits[0]] = bits[1]; - }); - -} -QueryString.fromLocation = function(){ - return new QueryString(window.location.search); -} })(); \ No newline at end of file dist/jsUtils.js @@ -5,7 +5,7 @@ require 'bluecloth' desc 'Generate website files' -task :website_generate do +task :website_generate => [:docs, :dist] do # Stolen/Adapted from newgem and its txt2html script # @@ -38,7 +38,7 @@ task :website_generate do title= "#{APP_NAME} #{APP_VERSION}" version = APP_VERSION - download = "/dist/#{APP_NAME}-#{APP_VERSION}.js" + download = "dist/#{APP_NAME}-#{APP_VERSION}.js" stat = File.stat(src) created = stat.ctime @@ -47,7 +47,15 @@ task :website_generate do File.open('website/index.html', "w") do |out| out << template.result(binding) end - + + sh 'rm -rf website/dist' + sh 'rm -rf website/docs' + sh 'rm -rf website/test' + sh 'rm -rf website/src' + sh 'cp -r dist/ website/' + sh 'cp -r docs/generator website/docs' + sh 'cp -r test website/test' + sh 'cp -r src website/src' end desc 'Upload website files to gandrew.com' tasks/website.rake @@ -100,7 +100,7 @@ new TestSuite("Http Tests", { var scriptEl = document.getElementById(scriptId); t.assert(scriptEl, "scriptEl is undefined"); t.assert(scriptEl.getAttribute('type') == 'text/javascript', "Wrong type - " + scriptEl.getAttribute('type')); - t.assert(scriptEl.getAttribute('src') == 'URI&jsonp=Utils.http.scriptRequestCallback('+scriptId+')', "Wrong src - " + scriptEl.getAttribute('src')); + t.assert(scriptEl.getAttribute('src') == 'URI&jsonp=Utils.http.scriptRequestCallback("'+scriptId+'")', "Wrong src - " + scriptEl.getAttribute('src')); }, 100); window.setTimeout(continuation, 1); }, test/unit/http_test.js @@ -1 +1,5 @@ index.html +docs +dist +test +src website/.gitignore website/dist/jsUtils.js website/index.html 5900ddc30d2d0d456d56b74032cc9f3367c6918c Gareth Andrew gingerhendrix@hotmail.com http://github.com/gingerhendrix/jsutils/commit/df6a6eb21ad7ed40e204138f3900cc39f90f4871 df6a6eb21ad7ed40e204138f3900cc39f90f4871 2009-04-23T09:10:06-07:00 2009-04-23T09:10:06-07:00 Prepped for 0.2.4 release 9d112d37bb832589bb285de7ff18a2a56851ded7 Gareth Andrew gingerhendrix@hotmail.com