This repository has been archived by the owner on Dec 16, 2023. It is now read-only.
/
sammy.js
1838 lines (1692 loc) · 65.1 KB
/
sammy.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
// name: sammy
// version: 0.6.2
(function($, window) {
var Sammy,
PATH_REPLACER = "([^\/]+)",
PATH_NAME_MATCHER = /:([\w\d]+)/g,
QUERY_STRING_MATCHER = /\?([^#]*)$/,
// mainly for making `arguments` an Array
_makeArray = function(nonarray) { return Array.prototype.slice.call(nonarray); },
// borrowed from jQuery
_isFunction = function( obj ) { return Object.prototype.toString.call(obj) === "[object Function]"; },
_isArray = function( obj ) { return Object.prototype.toString.call(obj) === "[object Array]"; },
_decode = decodeURIComponent,
_encode = encodeURIComponent,
_escapeHTML = function(s) {
return s.replace(/&/g,'&').replace(/</g,'<').replace(/>/g,'>');
},
_routeWrapper = function(verb) {
return function(path, callback) { return this.route.apply(this, [verb, path, callback]); };
},
_template_cache = {},
loggers = [];
// `Sammy` (also aliased as $.sammy) is not only the namespace for a
// number of prototypes, its also a top level method that allows for easy
// creation/management of `Sammy.Application` instances. There are a
// number of different forms for `Sammy()` but each returns an instance
// of `Sammy.Application`. When a new instance is created using
// `Sammy` it is added to an Object called `Sammy.apps`. This
// provides for an easy way to get at existing Sammy applications. Only one
// instance is allowed per `element_selector` so when calling
// `Sammy('selector')` multiple times, the first time will create
// the application and the following times will extend the application
// already added to that selector.
//
// ### Example
//
// // returns the app at #main or a new app
// Sammy('#main')
//
// // equivilent to "new Sammy.Application", except appends to apps
// Sammy();
// Sammy(function() { ... });
//
// // extends the app at '#main' with function.
// Sammy('#main', function() { ... });
//
Sammy = function() {
var args = _makeArray(arguments),
app, selector;
Sammy.apps = Sammy.apps || {};
if (args.length === 0 || args[0] && _isFunction(args[0])) { // Sammy()
return Sammy.apply(Sammy, ['body'].concat(args));
} else if (typeof (selector = args.shift()) == 'string') { // Sammy('#main')
app = Sammy.apps[selector] || new Sammy.Application();
app.element_selector = selector;
if (args.length > 0) {
$.each(args, function(i, plugin) {
app.use(plugin);
});
}
// if the selector changes make sure the refrence in Sammy.apps changes
if (app.element_selector != selector) {
delete Sammy.apps[selector];
}
Sammy.apps[app.element_selector] = app;
return app;
}
};
Sammy.VERSION = '0.6.2';
// Add to the global logger pool. Takes a function that accepts an
// unknown number of arguments and should print them or send them somewhere
// The first argument is always a timestamp.
Sammy.addLogger = function(logger) {
loggers.push(logger);
};
// Sends a log message to each logger listed in the global
// loggers pool. Can take any number of arguments.
// Also prefixes the arguments with a timestamp.
Sammy.log = function() {
var args = _makeArray(arguments);
args.unshift("[" + Date() + "]");
$.each(loggers, function(i, logger) {
logger.apply(Sammy, args);
});
};
if (typeof window.console != 'undefined') {
if (_isFunction(window.console.log.apply)) {
Sammy.addLogger(function() {
window.console.log.apply(window.console, arguments);
});
} else {
Sammy.addLogger(function() {
window.console.log(arguments);
});
}
} else if (typeof console != 'undefined') {
Sammy.addLogger(function() {
console.log.apply(console, arguments);
});
}
$.extend(Sammy, {
makeArray: _makeArray,
isFunction: _isFunction,
isArray: _isArray
})
// Sammy.Object is the base for all other Sammy classes. It provides some useful
// functionality, including cloning, iterating, etc.
Sammy.Object = function(obj) { // constructor
return $.extend(this, obj || {});
};
$.extend(Sammy.Object.prototype, {
// Escape HTML in string, use in templates to prevent script injection.
// Also aliased as `h()`
escapeHTML: _escapeHTML,
h: _escapeHTML,
// Returns a copy of the object with Functions removed.
toHash: function() {
var json = {};
$.each(this, function(k,v) {
if (!_isFunction(v)) {
json[k] = v;
}
});
return json;
},
// Renders a simple HTML version of this Objects attributes.
// Does not render functions.
// For example. Given this Sammy.Object:
//
// var s = new Sammy.Object({first_name: 'Sammy', last_name: 'Davis Jr.'});
// s.toHTML() //=> '<strong>first_name</strong> Sammy<br /><strong>last_name</strong> Davis Jr.<br />'
//
toHTML: function() {
var display = "";
$.each(this, function(k, v) {
if (!_isFunction(v)) {
display += "<strong>" + k + "</strong> " + v + "<br />";
}
});
return display;
},
// Returns an array of keys for this object. If `attributes_only`
// is true will not return keys that map to a `function()`
keys: function(attributes_only) {
var keys = [];
for (var property in this) {
if (!_isFunction(this[property]) || !attributes_only) {
keys.push(property);
}
}
return keys;
},
// Checks if the object has a value at `key` and that the value is not empty
has: function(key) {
return this[key] && $.trim(this[key].toString()) != '';
},
// convenience method to join as many arguments as you want
// by the first argument - useful for making paths
join: function() {
var args = _makeArray(arguments);
var delimiter = args.shift();
return args.join(delimiter);
},
// Shortcut to Sammy.log
log: function() {
Sammy.log.apply(Sammy, arguments);
},
// Returns a string representation of this object.
// if `include_functions` is true, it will also toString() the
// methods of this object. By default only prints the attributes.
toString: function(include_functions) {
var s = [];
$.each(this, function(k, v) {
if (!_isFunction(v) || include_functions) {
s.push('"' + k + '": ' + v.toString());
}
});
return "Sammy.Object: {" + s.join(',') + "}";
}
});
// The HashLocationProxy is the default location proxy for all Sammy applications.
// A location proxy is a prototype that conforms to a simple interface. The purpose
// of a location proxy is to notify the Sammy.Application its bound to when the location
// or 'external state' changes. The HashLocationProxy considers the state to be
// changed when the 'hash' (window.location.hash / '#') changes. It does this in two
// different ways depending on what browser you are using. The newest browsers
// (IE, Safari > 4, FF >= 3.6) support a 'onhashchange' DOM event, thats fired whenever
// the location.hash changes. In this situation the HashLocationProxy just binds
// to this event and delegates it to the application. In the case of older browsers
// a poller is set up to track changes to the hash. Unlike Sammy 0.3 or earlier,
// the HashLocationProxy allows the poller to be a global object, eliminating the
// need for multiple pollers even when thier are multiple apps on the page.
Sammy.HashLocationProxy = function(app, run_interval_every) {
this.app = app;
// set is native to false and start the poller immediately
this.is_native = false;
this._startPolling(run_interval_every);
};
Sammy.HashLocationProxy.prototype = {
// bind the proxy events to the current app.
bind: function() {
var proxy = this, app = this.app;
$(window).bind('hashchange.' + this.app.eventNamespace(), function(e, non_native) {
// if we receive a native hash change event, set the proxy accordingly
// and stop polling
if (proxy.is_native === false && !non_native) {
Sammy.log('native hash change exists, using');
proxy.is_native = true;
window.clearInterval(Sammy.HashLocationProxy._interval);
}
app.trigger('location-changed');
});
if (!Sammy.HashLocationProxy._bindings) {
Sammy.HashLocationProxy._bindings = 0;
}
Sammy.HashLocationProxy._bindings++;
},
// unbind the proxy events from the current app
unbind: function() {
$(window).unbind('hashchange.' + this.app.eventNamespace());
Sammy.HashLocationProxy._bindings--;
if (Sammy.HashLocationProxy._bindings <= 0) {
window.clearInterval(Sammy.HashLocationProxy._interval);
}
},
// get the current location from the hash.
getLocation: function() {
// Bypass the `window.location.hash` attribute. If a question mark
// appears in the hash IE6 will strip it and all of the following
// characters from `window.location.hash`.
var matches = window.location.toString().match(/^[^#]*(#.+)$/);
return matches ? matches[1] : '';
},
// set the current location to `new_location`
setLocation: function(new_location) {
return (window.location = new_location);
},
_startPolling: function(every) {
// set up interval
var proxy = this;
if (!Sammy.HashLocationProxy._interval) {
if (!every) { every = 10; }
var hashCheck = function() {
var current_location = proxy.getLocation();
if (!Sammy.HashLocationProxy._last_location ||
current_location != Sammy.HashLocationProxy._last_location) {
window.setTimeout(function() {
$(window).trigger('hashchange', [true]);
}, 13);
}
Sammy.HashLocationProxy._last_location = current_location;
};
hashCheck();
Sammy.HashLocationProxy._interval = window.setInterval(hashCheck, every);
}
}
};
// Sammy.Application is the Base prototype for defining 'applications'.
// An 'application' is a collection of 'routes' and bound events that is
// attached to an element when `run()` is called.
// The only argument an 'app_function' is evaluated within the context of the application.
Sammy.Application = function(app_function) {
var app = this;
this.routes = {};
this.listeners = new Sammy.Object({});
this.arounds = [];
this.befores = [];
// generate a unique namespace
this.namespace = (new Date()).getTime() + '-' + parseInt(Math.random() * 1000, 10);
this.context_prototype = function() { Sammy.EventContext.apply(this, arguments); };
this.context_prototype.prototype = new Sammy.EventContext();
if (_isFunction(app_function)) {
app_function.apply(this, [this]);
}
// set the location proxy if not defined to the default (HashLocationProxy)
if (!this._location_proxy) {
this.setLocationProxy(new Sammy.HashLocationProxy(this, this.run_interval_every));
}
if (this.debug) {
this.bindToAllEvents(function(e, data) {
app.log(app.toString(), e.cleaned_type, data || {});
});
}
};
Sammy.Application.prototype = $.extend({}, Sammy.Object.prototype, {
// the four route verbs
ROUTE_VERBS: ['get','post','put','delete'],
// An array of the default events triggered by the
// application during its lifecycle
APP_EVENTS: ['run',
'unload',
'lookup-route',
'run-route',
'route-found',
'event-context-before',
'event-context-after',
'changed',
'error',
'check-form-submission',
'redirect',
'location-changed'],
_last_route: null,
_location_proxy: null,
_running: false,
// Defines what element the application is bound to. Provide a selector
// (parseable by `jQuery()`) and this will be used by `$element()`
element_selector: 'body',
// When set to true, logs all of the default events using `log()`
debug: false,
// When set to true, and the error() handler is not overriden, will actually
// raise JS errors in routes (500) and when routes can't be found (404)
raise_errors: false,
// The time in milliseconds that the URL is queried for changes
run_interval_every: 50,
// The default template engine to use when using `partial()` in an
// `EventContext`. `template_engine` can either be a string that
// corresponds to the name of a method/helper on EventContext or it can be a function
// that takes two arguments, the content of the unrendered partial and an optional
// JS object that contains interpolation data. Template engine is only called/refered
// to if the extension of the partial is null or unknown. See `partial()`
// for more information
template_engine: null,
// //=> Sammy.Application: body
toString: function() {
return 'Sammy.Application:' + this.element_selector;
},
// returns a jQuery object of the Applications bound element.
$element: function(selector) {
return selector ? $(this.element_selector).find(selector) : $(this.element_selector);
},
// `use()` is the entry point for including Sammy plugins.
// The first argument to use should be a function() that is evaluated
// in the context of the current application, just like the `app_function`
// argument to the `Sammy.Application` constructor.
//
// Any additional arguments are passed to the app function sequentially.
//
// For much more detail about plugins, check out:
// http://code.quirkey.com/sammy/doc/plugins.html
//
// ### Example
//
// var MyPlugin = function(app, prepend) {
//
// this.helpers({
// myhelper: function(text) {
// alert(prepend + " " + text);
// }
// });
//
// };
//
// var app = $.sammy(function() {
//
// this.use(MyPlugin, 'This is my plugin');
//
// this.get('#/', function() {
// this.myhelper('and dont you forget it!');
// //=> Alerts: This is my plugin and dont you forget it!
// });
//
// });
//
// If plugin is passed as a string it assumes your are trying to load
// Sammy."Plugin". This is the prefered way of loading core Sammy plugins
// as it allows for better error-messaging.
//
// ### Example
//
// $.sammy(function() {
// this.use('Mustache'); //=> Sammy.Mustache
// this.use('Storage'); //=> Sammy.Storage
// });
//
use: function() {
// flatten the arguments
var args = _makeArray(arguments),
plugin = args.shift(),
plugin_name = plugin || '';
try {
args.unshift(this);
if (typeof plugin == 'string') {
plugin_name = 'Sammy.' + plugin;
plugin = Sammy[plugin];
}
plugin.apply(this, args);
} catch(e) {
if (typeof plugin === 'undefined') {
this.error("Plugin Error: called use() but plugin (" + plugin_name.toString() + ") is not defined", e);
} else if (!_isFunction(plugin)) {
this.error("Plugin Error: called use() but '" + plugin_name.toString() + "' is not a function", e);
} else {
this.error("Plugin Error", e);
}
}
return this;
},
// Sets the location proxy for the current app. By default this is set to
// a new `Sammy.HashLocationProxy` on initialization. However, you can set
// the location_proxy inside you're app function to give your app a custom
// location mechanism. See `Sammy.HashLocationProxy` and `Sammy.DataLocationProxy`
// for examples.
//
// `setLocationProxy()` takes an initialized location proxy.
//
// ### Example
//
// // to bind to data instead of the default hash;
// var app = $.sammy(function() {
// this.setLocationProxy(new Sammy.DataLocationProxy(this));
// });
//
setLocationProxy: function(new_proxy) {
var original_proxy = this._location_proxy;
this._location_proxy = new_proxy;
if (this.isRunning()) {
if (original_proxy) {
// if there is already a location proxy, unbind it.
original_proxy.unbind();
}
this._location_proxy.bind();
}
},
// `route()` is the main method for defining routes within an application.
// For great detail on routes, check out: http://code.quirkey.com/sammy/doc/routes.html
//
// This method also has aliases for each of the different verbs (eg. `get()`, `post()`, etc.)
//
// ### Arguments
//
// * `verb` A String in the set of ROUTE_VERBS or 'any'. 'any' will add routes for each
// of the ROUTE_VERBS. If only two arguments are passed,
// the first argument is the path, the second is the callback and the verb
// is assumed to be 'any'.
// * `path` A Regexp or a String representing the path to match to invoke this verb.
// * `callback` A Function that is called/evaluated whent the route is run see: `runRoute()`.
// It is also possible to pass a string as the callback, which is looked up as the name
// of a method on the application.
//
route: function(verb, path, callback) {
var app = this, param_names = [], add_route, path_match;
// if the method signature is just (path, callback)
// assume the verb is 'any'
if (!callback && _isFunction(path)) {
path = verb;
callback = path;
verb = 'any';
}
verb = verb.toLowerCase(); // ensure verb is lower case
// if path is a string turn it into a regex
if (path.constructor == String) {
// Needs to be explicitly set because IE will maintain the index unless NULL is returned,
// which means that with two consecutive routes that contain params, the second set of params will not be found and end up in splat instead of params
// https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/RegExp/lastIndex
PATH_NAME_MATCHER.lastIndex = 0;
// find the names
while ((path_match = PATH_NAME_MATCHER.exec(path)) !== null) {
param_names.push(path_match[1]);
}
// replace with the path replacement
path = new RegExp("^" + path.replace(PATH_NAME_MATCHER, PATH_REPLACER) + "$");
}
// lookup callback
if (typeof callback == 'string') {
callback = app[callback];
}
add_route = function(with_verb) {
var r = {verb: with_verb, path: path, callback: callback, param_names: param_names};
// add route to routes array
app.routes[with_verb] = app.routes[with_verb] || [];
// place routes in order of definition
app.routes[with_verb].push(r);
};
if (verb === 'any') {
$.each(this.ROUTE_VERBS, function(i, v) { add_route(v); });
} else {
add_route(verb);
}
// return the app
return this;
},
// Alias for route('get', ...)
get: _routeWrapper('get'),
// Alias for route('post', ...)
post: _routeWrapper('post'),
// Alias for route('put', ...)
put: _routeWrapper('put'),
// Alias for route('delete', ...)
del: _routeWrapper('delete'),
// Alias for route('any', ...)
any: _routeWrapper('any'),
// `mapRoutes` takes an array of arrays, each array being passed to route()
// as arguments, this allows for mass definition of routes. Another benefit is
// this makes it possible/easier to load routes via remote JSON.
//
// ### Example
//
// var app = $.sammy(function() {
//
// this.mapRoutes([
// ['get', '#/', function() { this.log('index'); }],
// // strings in callbacks are looked up as methods on the app
// ['post', '#/create', 'addUser'],
// // No verb assumes 'any' as the verb
// [/dowhatever/, function() { this.log(this.verb, this.path)}];
// ]);
// })
//
mapRoutes: function(route_array) {
var app = this;
$.each(route_array, function(i, route_args) {
app.route.apply(app, route_args);
});
return this;
},
// A unique event namespace defined per application.
// All events bound with `bind()` are automatically bound within this space.
eventNamespace: function() {
return ['sammy-app', this.namespace].join('-');
},
// Works just like `jQuery.fn.bind()` with a couple noteable differences.
//
// * It binds all events to the application element
// * All events are bound within the `eventNamespace()`
// * Events are not actually bound until the application is started with `run()`
// * callbacks are evaluated within the context of a Sammy.EventContext
//
// See http://code.quirkey.com/sammy/docs/events.html for more info.
//
bind: function(name, data, callback) {
var app = this;
// build the callback
// if the arity is 2, callback is the second argument
if (typeof callback == 'undefined') { callback = data; }
var listener_callback = function() {
// pull off the context from the arguments to the callback
var e, context, data;
e = arguments[0];
data = arguments[1];
if (data && data.context) {
context = data.context;
delete data.context;
} else {
context = new app.context_prototype(app, 'bind', e.type, data, e.target);
}
e.cleaned_type = e.type.replace(app.eventNamespace(), '');
callback.apply(context, [e, data]);
};
// it could be that the app element doesnt exist yet
// so attach to the listeners array and then run()
// will actually bind the event.
if (!this.listeners[name]) { this.listeners[name] = []; }
this.listeners[name].push(listener_callback);
if (this.isRunning()) {
// if the app is running
// *actually* bind the event to the app element
this._listen(name, listener_callback);
}
return this;
},
// Triggers custom events defined with `bind()`
//
// ### Arguments
//
// * `name` The name of the event. Automatically prefixed with the `eventNamespace()`
// * `data` An optional Object that can be passed to the bound callback.
// * `context` An optional context/Object in which to execute the bound callback.
// If no context is supplied a the context is a new `Sammy.EventContext`
//
trigger: function(name, data) {
this.$element().trigger([name, this.eventNamespace()].join('.'), [data]);
return this;
},
// Reruns the current route
refresh: function() {
this.last_location = null;
this.trigger('location-changed');
return this;
},
// Takes a single callback that is pushed on to a stack.
// Before any route is run, the callbacks are evaluated in order within
// the current `Sammy.EventContext`
//
// If any of the callbacks explicitly return false, execution of any
// further callbacks and the route itself is halted.
//
// You can also provide a set of options that will define when to run this
// before based on the route it proceeds.
//
// ### Example
//
// var app = $.sammy(function() {
//
// // will run at #/route but not at #/
// this.before('#/route', function() {
// //...
// });
//
// // will run at #/ but not at #/route
// this.before({except: {path: '#/route'}}, function() {
// this.log('not before #/route');
// });
//
// this.get('#/', function() {});
//
// this.get('#/route', function() {});
//
// });
//
// See `contextMatchesOptions()` for a full list of supported options
//
before: function(options, callback) {
if (_isFunction(options)) {
callback = options;
options = {};
}
this.befores.push([options, callback]);
return this;
},
// A shortcut for binding a callback to be run after a route is executed.
// After callbacks have no guarunteed order.
after: function(callback) {
return this.bind('event-context-after', callback);
},
// Adds an around filter to the application. around filters are functions
// that take a single argument `callback` which is the entire route
// execution path wrapped up in a closure. This means you can decide whether
// or not to proceed with execution by not invoking `callback` or,
// more usefuly wrapping callback inside the result of an asynchronous execution.
//
// ### Example
//
// The most common use case for around() is calling a _possibly_ async function
// and executing the route within the functions callback:
//
// var app = $.sammy(function() {
//
// var current_user = false;
//
// function checkLoggedIn(callback) {
// // /session returns a JSON representation of the logged in user
// // or an empty object
// if (!current_user) {
// $.getJSON('/session', function(json) {
// if (json.login) {
// // show the user as logged in
// current_user = json;
// // execute the route path
// callback();
// } else {
// // show the user as not logged in
// current_user = false;
// // the context of aroundFilters is an EventContext
// this.redirect('#/login');
// }
// });
// } else {
// // execute the route path
// callback();
// }
// };
//
// this.around(checkLoggedIn);
//
// });
//
around: function(callback) {
this.arounds.push(callback);
return this;
},
// Returns `true` if the current application is running.
isRunning: function() {
return this._running;
},
// Helpers extends the EventContext prototype specific to this app.
// This allows you to define app specific helper functions that can be used
// whenever you're inside of an event context (templates, routes, bind).
//
// ### Example
//
// var app = $.sammy(function() {
//
// helpers({
// upcase: function(text) {
// return text.toString().toUpperCase();
// }
// });
//
// get('#/', function() { with(this) {
// // inside of this context I can use the helpers
// $('#main').html(upcase($('#main').text());
// }});
//
// });
//
//
// ### Arguments
//
// * `extensions` An object collection of functions to extend the context.
//
helpers: function(extensions) {
$.extend(this.context_prototype.prototype, extensions);
return this;
},
// Helper extends the event context just like `helpers()` but does it
// a single method at a time. This is especially useful for dynamically named
// helpers
//
// ### Example
//
// // Trivial example that adds 3 helper methods to the context dynamically
// var app = $.sammy(function(app) {
//
// $.each([1,2,3], function(i, num) {
// app.helper('helper' + num, function() {
// this.log("I'm helper number " + num);
// });
// });
//
// this.get('#/', function() {
// this.helper2(); //=> I'm helper number 2
// });
// });
//
// ### Arguments
//
// * `name` The name of the method
// * `method` The function to be added to the prototype at `name`
//
helper: function(name, method) {
this.context_prototype.prototype[name] = method;
return this;
},
// Actually starts the application's lifecycle. `run()` should be invoked
// within a document.ready block to ensure the DOM exists before binding events, etc.
//
// ### Example
//
// var app = $.sammy(function() { ... }); // your application
// $(function() { // document.ready
// app.run();
// });
//
// ### Arguments
//
// * `start_url` Optionally, a String can be passed which the App will redirect to
// after the events/routes have been bound.
run: function(start_url) {
if (this.isRunning()) { return false; }
var app = this;
// actually bind all the listeners
$.each(this.listeners.toHash(), function(name, callbacks) {
$.each(callbacks, function(i, listener_callback) {
app._listen(name, listener_callback);
});
});
this.trigger('run', {start_url: start_url});
this._running = true;
// set last location
this.last_location = null;
if (this.getLocation() == '' && typeof start_url != 'undefined') {
this.setLocation(start_url);
}
// check url
this._checkLocation();
this._location_proxy.bind();
this.bind('location-changed', function() {
app._checkLocation();
});
// bind to submit to capture post/put/delete routes
this.bind('submit', function(e) {
var returned = app._checkFormSubmission($(e.target).closest('form'));
return (returned === false) ? e.preventDefault() : false;
});
// bind unload to body unload
$(window).bind('beforeunload', function() {
app.unload();
});
// trigger html changed
return this.trigger('changed');
},
// The opposite of `run()`, un-binds all event listeners and intervals
// `run()` Automaticaly binds a `onunload` event to run this when
// the document is closed.
unload: function() {
if (!this.isRunning()) { return false; }
var app = this;
this.trigger('unload');
// clear interval
this._location_proxy.unbind();
// unbind form submits
this.$element().unbind('submit').removeClass(app.eventNamespace());
// unbind all events
$.each(this.listeners.toHash() , function(name, listeners) {
$.each(listeners, function(i, listener_callback) {
app._unlisten(name, listener_callback);
});
});
this._running = false;
return this;
},
// Will bind a single callback function to every event that is already
// being listened to in the app. This includes all the `APP_EVENTS`
// as well as any custom events defined with `bind()`.
//
// Used internally for debug logging.
bindToAllEvents: function(callback) {
var app = this;
// bind to the APP_EVENTS first
$.each(this.APP_EVENTS, function(i, e) {
app.bind(e, callback);
});
// next, bind to listener names (only if they dont exist in APP_EVENTS)
$.each(this.listeners.keys(true), function(i, name) {
if (app.APP_EVENTS.indexOf(name) == -1) {
app.bind(name, callback);
}
});
return this;
},
// Returns a copy of the given path with any query string after the hash
// removed.
routablePath: function(path) {
return path.replace(QUERY_STRING_MATCHER, '');
},
// Given a verb and a String path, will return either a route object or false
// if a matching route can be found within the current defined set.
lookupRoute: function(verb, path) {
var app = this, routed = false;
this.trigger('lookup-route', {verb: verb, path: path});
if (typeof this.routes[verb] != 'undefined') {
$.each(this.routes[verb], function(i, route) {
if (app.routablePath(path).match(route.path)) {
routed = route;
return false;
}
});
}
return routed;
},
// First, invokes `lookupRoute()` and if a route is found, parses the
// possible URL params and then invokes the route's callback within a new
// `Sammy.EventContext`. If the route can not be found, it calls
// `notFound()`. If `raise_errors` is set to `true` and
// the `error()` has not been overriden, it will throw an actual JS
// error.
//
// You probably will never have to call this directly.
//
// ### Arguments
//
// * `verb` A String for the verb.
// * `path` A String path to lookup.
// * `params` An Object of Params pulled from the URI or passed directly.
//
// ### Returns
//
// Either returns the value returned by the route callback or raises a 404 Not Found error.
//
runRoute: function(verb, path, params, target) {
var app = this,
route = this.lookupRoute(verb, path),
context,
wrapped_route,
arounds,
around,
befores,
before,
callback_args,
path_params,
final_returned;
this.log('runRoute', [verb, path].join(' '));
this.trigger('run-route', {verb: verb, path: path, params: params});
if (typeof params == 'undefined') { params = {}; }
$.extend(params, this._parseQueryString(path));
if (route) {
this.trigger('route-found', {route: route});
// pull out the params from the path
if ((path_params = route.path.exec(this.routablePath(path))) !== null) {
// first match is the full path
path_params.shift();
// for each of the matches
$.each(path_params, function(i, param) {
// if theres a matching param name
if (route.param_names[i]) {
// set the name to the match
params[route.param_names[i]] = _decode(param);
} else {
// initialize 'splat'
if (!params.splat) { params.splat = []; }
params.splat.push(_decode(param));
}
});
}
// set event context
context = new this.context_prototype(this, verb, path, params, target);
// ensure arrays
arounds = this.arounds.slice(0);
befores = this.befores.slice(0);
// set the callback args to the context + contents of the splat
callback_args = [context].concat(params.splat);
// wrap the route up with the before filters
wrapped_route = function() {
var returned;
while (befores.length > 0) {
before = befores.shift();
// check the options
if (app.contextMatchesOptions(context, before[0])) {
returned = before[1].apply(context, [context]);
if (returned === false) { return false; }
}
}
app.last_route = route;
context.trigger('event-context-before', {context: context});
returned = route.callback.apply(context, callback_args);
context.trigger('event-context-after', {context: context});