-
Notifications
You must be signed in to change notification settings - Fork 16
/
angular.javascript.txt
1964 lines (1774 loc) · 165 KB
/
angular.javascript.txt
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
ANGULAR
/=+===============================+=\
/ : : \
)==: MAIN :==(
\ :_______________________________: /
\=+===============================+=/
JAVASCRIPT FILE ==> #angular.js for core modules. There are CDN.
#Should use <script defer> for better responsiveness.
#Other modules are shipped in different JavaScript files, e.g. angular-route.js
#Version: 1.4.0-beta6
#Not compatible with IE<9.0
ANGULAR UI UTILS ==> |#angular-ui-utils (version 0.2.2)
|#Noted like this.
|#MODULE "ui.*". Can use MODULE "ui-utils" to include all sub-MODULE
GOAL ==> #Model-View-Controller separation.
#Goal:
# - put DOM manipulation ("view") in HTML, not JavaScript, using directives.
# - put dynamic data ("model") in JavaScript, not HTML, using partial
# templates and expressions.
STRUCTURE ==> #View-related logic (DOM Manipulation):
# - DIRECTIVE:
# - custom HTML tag, attribute or class
# - is compiled by COMPILER at bootstrap ("template" -> "views")
# - communicates with SCOPE by creating:
# - DOM -> SCOPE: DOM event listener, manipulating SCOPE
# - SCOPE -> DOM: SCOPE changes listener, manipulating DOM:
# - use SCOPE.$watch(), which should not evaluate DOM objects,
# only SCOPE and as simple as possible (for performance reasons)
# - some types:
# - partial templates: chunks of HTML templates, loaded
# dynamically according to "route" (pseudo-URL)
# - {{EXPR}}: dynamic SCOPE VAR put in HTML
# - {{EXPR | FILTER}}: FILTER applies modifications to EXPR
# Should use FILTER to parse HTML fragment output, not
# CONTROLLER.
# - dynamic CSS classes: automatically updated according to
# DOM/SCOPE change.
# - ANIMATION:
# - either CSS, or JavaScript separate unit
#Non-view-related logic (JavaScript):
# - Reusable (like a library): SERVICE, used by CONTROLLER:
# - Singleton VAL (usually OBJ or FUNC)
# - By convention called $VAR for Angular ones (not custom ones)
# - All components can use them by specifying them in their AFUNC
# - use dependency injection for easier mocks (see below)
# - Specific: SCOPE, an OBJ holding data for a HTML node and its children:
# - initialized/constructed by a CONTROLLER
# CONTROLLER can also be associated with specific forms/controls, in
# which case they implement the logic, but don't have a specific SCOPE.
# - root SCOPE is defined at bootstrap, and child SCOPE can be created,
# inheriting or not the data, but always inheriting events.
BEST PRACTICE ==> #It is very important to put some code away from CONTROLLER:
# - code used by several CONTROLLER -> SERVICE
# - DOM manipulation -> DIRECTIVE
# - DOM animation -> ANIMATION
# - HTML output parsing -> FILTER
ORGANIZATION ==> #MODULE:
# - components (SERVICE, SERVICEPROVIDER, CONTROLLER, DIRECTIVE, FILTER) are
# bundled into modules, generally a file or a library.
# - should put for each feature, a FEATURE_DIR/ while files:
# - FEATURE.js: module declaration
# - FEATURE-controller|directive|service|filter|animation[_test].js
#Dependency injection:
# - components declaration is through factory methods registration AFUNC, not
# instantiation, which are called runtime by the INJECTOR
# - a MODULE must depend on MODULE2 in order to use/refer to its components
# Dependencies MODULE_STR_ARR must always start with root dependencies
# - instead of declare dependencies as constructed arguments to constructors,
# register them as STR IDs to factory functions, which permits:
# - easy use of mock dependencies
# - control of dependencies' dependencies by injector
# - control of instantiation (singleton, lazy loading, etc.) by injector
OTHER UTILITIES ==> # - client-side routing
# - client-side forms validation
# - dynamic lists (ng-repeat, ng-options)
# - AJAX|REST calls
# - testing (clock, AJAX mocks)
# - conditions HTML attributes (ng-show|if|switch|messages)
# - mobile swipe event
# - localization
/=+===============================+=\
/ : : \
)==: INJECTOR AND MODULES :==(
\ :_______________________________: /
\=+===============================+=/
angular.bootstrap(ELEM[, MODULE_STR_ARR]) #Does the initialization, i.e.:
# //Load MODULE and create INJECTOR
# var INJECTOR = angular.injector(MODULE_STR_ARR);
# //Sets $rootElement to ELEM and ELEM.injector() to INJECTOR
# ...
# //Compile
# INJECTOR.invoke(function($rootScope, $compile) {
# $compile(ELEM)($rootScope);
# $rootScope.$digest();
# });
# return INJECTOR;
#Timing:
# - it throws an error when called twice.
# - Should be called after DOMContentLoaded is fired, e.g. in:
# angular.element( document ).ready( FUNC() )
# - if window.name starts with 'NG_DEFER_BOOTSTRAP!', it waits for
# angular.resumeBootstrap(MODULE_STR_ARR) to complete (MODULE are added).
# Used by plugins (e.g. Chrome extensions) to add modules on Angular pages
<any> #Does angular.bootstrap(<any>, [MODULE])
ng-app[=MODULE] #Usually <html> but not necessarily.
angular.injector(MODULE_STR_ARR) #Returns an INJECTOR loading all components of MODULE_STR_ARR.
AJQ.injector() #Returns element root scope's INJECTOR.
#Usually done on $rootElement
$injector #Same as a SERVICE
INJECTOR.get(SERVICE_STR) #Returns SERVICE.
INJECTOR.invoke(AFUNC(SERVICE...)[, this][,OBJ])#Similar but here fires AFUNC and provides SERVICE... as arguments.
#OBJ can overwrite SERVICE..., e.g. { $SERVICE: MOCK_OBJ }
INJECTOR.instantiate(...) #Same but fires and returns new AFUNC.
INJECTOR.has(SERVICE_STR) #Returns true if exists.
AFUNC ==> #FUNC(SERVICE...).
#INJECTOR will automatically provide SERVICE... (through INJECTOR.get())
#SERVICE argument name should be SERVICE name.
#To specify them while still being able to minimize the code, must use either:
# - after FUNC declaration:
# FUNC["$inject"] = STR_ARR
# - or during FUNC declaration, instead of AFUNC(...):
# [ STR..., AFUNC(...) ]
#Where STR[_ARR] are the FUNC arguments names as STR.
#Can use <any ng-app ng-strict-di> to force using [ STR..., AFUNC(...) ]
#instead of AFUNC(...), or angular.bootstrap(..., { strictDi: true })
#Can put just FUNC() if no SERVICE.
ng-annotate FILE ##Prints to stdout FILE (JavaScript) (can be - for stdin):
## - if --remove, [ STR..., AFUNC(...) ] -> AFUNC(...)
## - if --add, inverse
## - can do --add --remove to rebuild everything
##Goal is not to have annotations in source, and have it in production.
##If problem with specific line of code, use /* @ngInject */ or ngInject(AFUNC)
##Version 0.10.1
--single_quotes ##Uses '$SERVICE' instead of "$SERVICE"
--regexp REGEXP_STR ##Excludes matching SERVICE name (full match)
--sourcemap
--sourceroot DIR ##Inline source map
GULP-NG-ANNOTATE([OBJ]) ##OBJ: single_quotes BOOL, remove BOOL, add BOOL, regexp, sourcemap, sourceroot
##Version 0.3.6
ng #Main MODULE, including all core services and components.
angular.module( MODULE_STR, MODULE2_STR_ARR #Registers factory method for a MODULE depending on MODULE2_STR_ARR, and
[, AFUNC([SERVICE...])]) #returns it. "ng" is implicitely added.
#Using AFUNC(...) is like calling MODULE.config(...)
angular.module( MODULE_STR ) #Returns a MODULE.
MODULE.name #MODULE_STR
MODULE.requires #MODULE2_STR_ARR passed at construction.
MODULE.run(AFUNC([SERVICE...])) #Will run AFUNC every time MODULE is finished being loaded by an INJECTOR.
$rootElement #SERVICE AJQ, representing the root element of angular.bootstrap()
COMPILE-TIME CHANGES ==> #Modifying SERVICE:
# - Service providers (called $SERVICEProvider): API provided by SERVICE
# - Decorators: adding your own changes to SERVICE
RUNTIME CHANGES ==> #Possible runtime changes:
# - adding directives or EXPR
# -> compile again the element, with:
# AJQ.injector().invoke(function($compile) {
# $compile(ELEM|HTML_STR)(AJQ.scope());
# AJQ.scope().$digest();
# })
# - modifying SERVICE
# -> INJECTOR.get|invoke()
# - overridden if new angular.injector() call
# - not with MODULE.value|constant()
# -> MODULE.config or PROVIDE.decorator()
# - must call angular.injector() again to load them
# - adding MODULE components (except PROVIDE.decorator())
# -> call angular.injector() again to load them
/=+===============================+=\
/ : : \
)==: SERVICE :==(
\ :_______________________________: /
\=+===============================+=/
RIGHT TYPE OF SERVICE ==> #If SERVICE:
# - must encapsulate members:
# - that can be configured by client -> MODULE.provider()
# - otherwise:
# - SERVICE inherits from another object -> MODULE.service()
# - otherwise -> MODULE.factory()
# - otherwise:
# - can be configured by client -> MODULE.constant()
# - otherwise -> MODULE.value()
#All components are actually SERVICE
MODULE.provider(SERVIC_STR,AFUNC #Registers factory method for SERVICE and SERVICEPROVIDER.
([SERVICEPROVIDER2...])) #AFUNC must return an OBJ:
# - it must have a member $get FUNC() returning VAL: this is the SERVICE
# - OBJ is the SERVICEPROVIDER:
# - can be manipulated in MODULE.config() as SERVICE_STRProvider
# - members other than $get are encapsulated for SERVICE, but available
# in SERVICEPROVIDER. They must change the way SERVICE will operate
# (so $get() should reference to them)
MODULE.factory(SERVICE_STR,AFUNC([SERVICE2...]))#Same but:
# - AFUNC must return a VAL: the SERVICE.
# - can use SERVICE2, not only SERVICEPROVIDER2
#Easier but no SERVICEPROVIDER is defined.
#Variables defined in AFUNC but not returned are encapsulated, but cannot be
#configured.
MODULE.service(SERVICE_STR,AFUNC([SERVICE2...]))#Same but AFUNC must set this: the SERVICE (AFUNC will be called with new).
MODULE.value|constant(SERVICE_STR, VAL) #Same but with a VAL.
#Difference between both is the way they can be modified:
# - constant can be used in config() as a SERVICEPROVIDER
# - value can be used in PROVIDE.decorator(), or using MODULE.value() again.
GULP-NG-CONSTANT(OBJ) #Creates a file containing a definition:
# angular.module(SERVICE_STR, MODULE_ARR)
# .constant(SERVICE2_STR, VAL)
# ...
#Where:
# - source IOSTREAM is a JSON of SERVICE2_STR/VAL
# - dest IOSTREAM is the file containing definition
#OBJ:
# - name SERVICE_STR
# - deps MODULE_ARR
# - constants OBJ: to merge to JSON
# - wrap "amd|commonjs" (def: null) ("commonjs" adds "module.exports =")
# - space STR (def: "\t"): for JSON.stringify()
# - template[Path]: for further customization (should not be needed)
#Can also put OBJ directly in JSON file
#Version 0.1.1
MODULE.config(AFUNC(SERVICEPROVIDER...)) #Returns a SERVICEPROVIDER with AFUNC(), in order to configure the
#underlying SERVICE.
$provide #SERVICEPROVIDER, used to create services and components:
# - MODULE.provider(...) is an alias of:
# MODULE.config(AFUNC($provide){ $provide.provider(...) })
# - Other functions, or SERVICEPROVIDER
# $animateProvider,$filterProvider,$controllerProvider,$compileProvider,etc.
# exist but are not referenced here because useless.
PROVIDE.decorator(SERVICE_STR, #Substitute original SERVICE:
AFUNC([SERVICE2...])) # - return a VAL which is the new SERVICE
# - original SERVICE is available in service $delegate.
# Usually add|substitute some members, then return it
#Used to change a SERVICE outside what's allowed in its SERVICEPROVIDER, or
#implement mocks.
/=+===============================+=\
/ : : \
)==: SCOPE :==(
\ :_______________________________: /
\=+===============================+=/
$exceptionHandler #SERVICE FUNC, fired when an exception is thrown by Angular.
EXPRESSIONHANDLER(ERROR, STR) #STR is ERROR.name for example.
#Default behavior does $log.error(ERROR, STR)
$rootScope #SERVICE, pointing at the root SCOPE.
$scope #SERVICE, used only in CONTROLLER
SCOPE.id #STR
AJQ.scope() #Returns element's non-isolated SCOPE (first non-isolated one if current is
#isolated).
AJQ.isolateScope() #Returns element's isolated SCOPE (if current is non-isolated, returns null).
SCOPE.$new(BOOL[, SCOPE3]) #Creates and returns a child SCOPE2:
# - parent is SCOPE3 (def: SCOPE)
# - $digest() called on parent, call it too on children.
# - $broadcasted events are sent to children.
# - if BOOL false (déf), is non-isolated, i.e.:
# - inherits by reference variables declared in parent
# - but child changes create a child-specific copy
SCOPE.$parent #
SCOPE.$root #
SCOPE.$eval(EXPR|FUNC(SCOPE)[, OBJ]) #Evaluates EXPR in SCOPE context, i.e. does $parse(EXPR)(SCOPE[, OBJ]), and
#returns result.
#Can also use FUNC(SCOPE), which execute any code, and can return result.
#EXPR doesn't have access to DOM or to angular.* but FUNC(SCOPE) does, and is
#XSS-safer.
SCOPE.$evalAsync(EXPR_STR|FUNC(SCOPE)[, OBJ]) #Same but executes async., which implies:
# - executes at least after current FUNC returns
# - $digest() will be called after it executes
# - doesn't return anything.
SCOPE.$watch(EXPR_STR|FUNC(SCOPE), #At each $digest(), if current $eval(ARG1) != previous $eval(ARG1), fires
STR2|FUNC(VAL,VAL2,SCOPE)[, BOOL]) #$evalAsync(ARG2) (VAL is new value, VAL2 old one).
#!= is:
# - if false !== (déf)
# - if true: ! angular.equals(VAL, VAL2): like VAL === VAL2, but:
# - also compare OBJ recursively (except DOM elements), except members
# FUNC or with key starting with "$"
# - NaN and REGEXP returns true when same (as opposed to JavaScript)
#If $evalAsync() changes ARG1 again, call recursively (up to 10 times).
#Listener is fired async. right away when $watch() is called too.
#Can check VAL === VAL2, to be sure listener is called because of change and
#not initialization.
#Watched expression should be as simple as possible for performance reason.
#Returns FUNC(), which turns it off.
SCOPE.$watchCollection(...) #Same but ARG1 and ARG2 use OBJ, and $watches all members.
#Not exactly same arguments: ARG2 must be FUNC, and BOOL is always false.
SCOPE.$watchGroup(...) #Same for ARR
SCOPE.$digest() #Triggers $watch listening
#Prefer using $apply()
SCOPE.$apply([EXPR_STR|FUNC(SCOPE)]) #Every JavaScript EXPR evaluated in SCOPE must use SCOPE.$apply(EXPR) in order
#to:
# - call $eval(EXPR) and return result.
# - catch exceptions with $exceptionHandler()
# - call $digest() in the end
#Angular expressions, e.g. JavaScript in CONTROLLER AFUNC or call to
#SERVICE.FUNC() don't need it (usually $apply() is used underneath)
SCOPE.$applyAsync(...) #Same as SCOPE.$apply(), but only called at the next $apply() or after short
#timeout (around 10ms).
#Allows queuing $apply() together for better performance.
SCOPE.$on(AEVENT_STR, FUNC(AEVENT[, ...])) #As opposed to DOM events, are limited to SCOPE, and can provide arguments.
#AEVENT has members:
# - name STR
# - targetScope and currentScope SCOPE: similar to DOM target and
# currentTarget
# - stopPropagation FUNC, preventDefault FUNC and defaultPrevented BOOL:
# like DOM, but for Angular events, and stopPropagation() can only be
# called for $emitted events.
#Returns a FUNC2(), which turn off the event listener.
SCOPE.$emit|$broadcast(AEVENT_STR[, ...]) #Fires event and propagate to siblings then parents, or siblings then children.
#Returns AEVENT (see above).
SCOPE.$destroy() #Will emit a $destroy AEVENT.
#There should be an event listener if some cleanup has to be done
MODULE.controller(CONTROLLER_STR, #Registers factory method for a CONTROLLER.
AFUNC([SERVICE...]) #AFUNC doesn't return anything but must initialize a SCOPE.
#Can use special CONTROLLER services:
# - $scope SCOPE
# - $element AJQ: current element
# - $attrs ATTRS (see below)
#CONTROLLER will be called when compiling <any ng-controller=CONTROLLER_STR>
#HTML tag will have class="ng-[isolate-]scope" then.
<any> #If SCOPE_VAR:
ng-controller="CONTROLLER[ as SCOPE_VAR]" # - CONTROLLER_AFUNC access SCOPE with this, not $scope
# - EXPR uses SCOPE_VAR.VAR2, not VAR2, which is more verbose, doesn't allow
# inheritance, but allow manually selecting the SCOPE
AJQ.controller([DIRECTIVE_STR]) #Returns a CONTROLLER, only for:
# - FORM|NGMODELCONTROLLER
# - directive if DIRECTIVE_STR
<any> #Evaluates EXPR at compile time (usually "VAR = VAL")
ng-init="EXPR" #Should be avoided (use CONTROLLER instead)
/=+===============================+=\
/ : : \
)==: DIRECTIVES :==(
\ :_______________________________: /
\=+===============================+=/
COMPILATION ==> #Compiler looks for following in HTML:
# <my-dir></my-dir> (prefer for new entity/functionality)
# <any my-dir="VAL"> (prefer for adding functionality)
# <any class="my-dir=VAL"> (deprecated)
#And fires myDir DIRECTIVE.
#Transform HTML (AJQ to AJQ2). Detailed steps:
# - compile FUNC(AJQ, ATTRS):
# - fired by $compile(ELEM|HTML_STR)
# - non-SCOPE specific tasks: change DOM content
# - returns link FUNC(...), so cannot specify together with link FUNC
# - link FUNC(SCOPE, AJQ, ATTRS):
# - returns new AJQ2
# - SCOPE specific tasks: setup DOM event listeners and/or SCOPE $watch()
# - SCOPE.$digest() is not called automatically if done manually, but
# is done when bootstrapping.
# - can divide between a pre and post link phases:
# - must use { pre|post FUNC(...) } instead of link FUNC or compile
# return value
# - if not specified, assumes post link
# - pre link is when no DOM manipulation, post link when there is.
#Controllers are called between compile and link.
MODULE.directive(DIRECTIVE_STR, #Tells the compiler to modify current HTML tag children and/or execute some
AFUNC([SERVICE...])) #JavaScript if its tag, element or class names are matching DIRECTIVE_STR.
#TAG refer to the element.
#AFUNC can return FUNC (same as { link: FUNC }) or OBJ with members:
# - compile FUNC(TAG_AJQ, ATTRS)->FUNC(...): see above
# - link FUNC(SCOPE, TAG_AJQ, ATTRS)->AJQ2: see above
# - template HTML_STR|FUNC(TAG_AJQ, ATTRS)->HTML_STR: simpler syntax for
# compile FUNC which replaces TAG children by HTML_STR.
# If specified with compile|link, run as a sort of pre-compile function.
# Uses SCE.RESOURCE_URL
# - templateUrl URL|FUNC(TAG_AJQ, ATTRS)->URL
# - templateNamespace "html|svg|math" (def: "html"): type of template
# - restrict "[A][E][C]" (def: "EA"): what to match among "A" (attribute),
# "E" (tag), "C" (class).
# - multiElement BOOL: if true:
# - TAG will include several elements (possibly empty text nodes), i.e.
# anything between DIRECTIVE-start[="..."] and DIRECTIVE-end
# - can also only use DIRECTIVE for single element
# - link|compile functions will be called once for all elements, but
# template[Url] which are called once for each.
# - scope true: creates a non-isolated SCOPE for TAG.
# - scope { VAR: "sym[ATTR]" ... }: creates an isolated SCOPE for TAG.
# ATTR (def: "VAR") refers to the element HTML attribute ATTR, which can be,
# according to "sym":
# - "@": "VAL"
# - "=[*][?]": "EXPR"
# - "?": exceptions are not propagated (e.g. missing VAR)
# - "*": use $watchCollection(), not $watch()
# - "&": "EXPR", where VAR([OBJ]) will fire EXPR. If OBJ, merges to scope.
# - controller AFUNC
# - controllerAs CONTROLLER_STR: register controller AFUNC, providing SCOPE
# OBJ is used
# - bindToController BOOL|OBJ (def: false): if true and controllerAs STR used,
# make scope OBJ relative to CONTROLLER's this, not SCOPE
# Using OBJ is shortcut for bindToController true, scope OBJ
# - require DIRECTIVE_STR[_ARR]:
# - current element must have DIRECTIVE[_ARR] or throws exception (unless
# STR starts with "?"
# - look into parent elements too|only if STR begins with ^|^^
# - DIRECTIVE[_ARR] must have a controller FUNC:
# - FUNC's this is passed as last arg OBJ[_ARR] to link FUNC
# - OBJ is null if using "?DIRECTIVE" and DIRECTIVE doesn't exist.
# - This is the preferred way to communicate to children DIRECTIVE
# without polluting current SCOPE, and bypassing isolated scopes.
# - transclude true|"element":
# - after compile FUNC, replace ... of <TAG ng-transclude>...</TAG>
# by original TAG and its children.
# - if "element", targets also <TAG ng-tranclude> itself
# - ... gets a new non-isolated child SCOPE2
# If directive creates an isolated scope, it will not cover ...
# - can also use $tranclude([SCOPE2, ]FUNC(AJQ, SCOPE2)[, AJQ2])->AJQ
# SERVICE in a CONTROLLER or fifth argument $tranclude(...) in link
# function
# - usually not needed for most cases
# - FUNC() should attach AJQ (is a copy) to new place
# - SCOPE2 can be overriden with first arg. By def, it is a new
# non-isolated scope.
# - AJQ2 is AJQ parent (def: current parent)
# - type "html|svg|math": type of the children (déf: "html")
#There can be:
# - several calls to same DIRECTIVE_STR: appends, do not overwrite.
# Use same priority as below.
# - AJQ with several DIRECTIVE, which behaves according to OBJ:
# - priority INT (déf: 0): lower are first called. If same, last declared
# first called.
# - terminal BOOL: if true, do not do any DIRECTIVE with lower priority
# (make sure it is called last).
<any>
ng-non-bindable #Does not compile. Used e.g. to show Angular.js snippets inside an Angular app.
uiAliasConfig |#Redefining ANGULAR.constant(DIRECTIVE_STR, HTML_STR) creates a DIRECTIVE with
|#{ template: HTML_STR, replace: true }
|#MODULE "ui.alias"
ATTRS #OBJ representing the HTML attributes of a tag.
#Used in directives and controllers.
#Should use them to manipulate attributes, since they fire ANIMEVENT
ATTRS.ATTR #For each HTML attribute.
ATTRS.$set(STR, VAL) #Changes an attributes VAL
ATTRS.$add|removeClass(CLASS_STR)
ATTRS.$updateClass(CLASS_STR, CLASS2_STR) #Add/remove CSS classes by calling ANIMATE.add|removeClass()
ATTRS.$observe(ATTR_STR, FUNC2(ATTR_VAL)) #Like $watch listener on attribute change but is notified not by $digest() but
#by ATTRS.$set()
#Automatically done in an attr="{{EXPR}}"
ATTRS.$normalize(STR) #Gets camelcase from dash-based attribute
$compileProvider.debugInfoEnabled(BOOL) #If true (def), adds CSS class .ng-binding to elements with {{EXPR}} and class
#.ng-scope to elements with scopes.
#They are used by tools like Batarang or Protactor.
#Setting to false provides performance boost.
angular.reloadWithDebugInfo() #Reload page but calls $compileProvider.debugInfoEnabled(true) at beginning
/=+===============================+=\
/ : : \
)==: EXPRESSIONS AND FILTERS :==(
\ :_______________________________: /
\=+===============================+=/
EXPR #STR like JavaScript, which use native objects, but:
# - only those native operators/keywords: NaN, Infinity, + - * / % ! && ||
# - Doesn't throw exception when accessing properties of null|undefined, e.g.
# "VAR.VAR2" when VAR is null.
# - cannot access the DOM
# - Can use FILTER
$parse #SERVICE FUNC, used to evaluate EXPR
PARSE(EXPR) #Returns FUNC2, with must be fired as FUNC2([{VAR: VAL ...}[, OBJ2]]), which
#evaluates EXPR with environment { VAR: VAL ... } and returns result.
#OBJ2 is used to overwrite OBJ.
#Can also:
# - use FUNC2.parse|literal BOOL: whether top-level|all expressions in
# STR are pure JavaScript (not referencing SCOPE or the DOM).
# - use FUNC2.assign(OBJ, VAL), which assign VAL to a member of OBJ according
# to EXPR, e.g. PARSE("a.b").assign({a:{b: 3}}, 4) will turn 3 to 4
# (in OBJ, not in EXPR)
$interpolate #SERVICE FUNC, used to evaluate {{EXPR}}
INTERPOLATE(STR[, BOOL[, CONTEXT[, BOOL2]]]) #Same as $parse, but with start and end symbols.
#If BOOL true and doesn't contain {{...}}, returns undefined.
#If CONTEXT, will then wrap with SCE.getTrusted(CONTEXT, ...), and STR can't
#have interlaced {{EXPR}}
#If BOOL2 true and one embedded expression returns undefined, the whole returns
#undefined.
INTERPOLATE.start|endSymbol() #"{{" or "}}". Can be changed by $interpolateProvider.start|endSymbol([STR])
{{EXPR}} #Sets up a $watch for EXPR, and replaces it with $interpolate(EXPR)(SCOPE)
#every time it changes.
#Can be used in text nodes or in most attribute values.
#Parent node will get class ng-binding.
#Can be interlaced {{EXPR}} in normal STR, i.e. "...{{...}}...{{...}}", where
#the parts not in {{}} will be treated as STR.
{{::EXPR}} #Same but does not update anymore after the first evaluation (static) that
#does not evaluate to undefined.
#To use only for performance reasons.
<any> #Same as <any>{{EXPR}}</any>
ng-bind="EXPR" #{{EXPR}} actually compile to <span ng-bind="EXPR"></span>
ng-bind-template="STR" #Same but a STR containing {{EXPR}}, e.g. "...{{...}}...{{...}}"
#Useful in <option> and <title> (cannot have {{EXPR}})
<any> #Put "display: none" from end of angular.js loading to end of compilation.
ng-cloak #Goal is to avoid seeing uncompiled {{EXPR}} while loading the app.
#Should not be put once at the root, but many times at the lowest levels
#possible.
EXPR[ | FILTER[:ARG[:...]]] #FILTER post-process EXPR:
# - can chain them
# - can take arguments (STR must be enclosed with "")
# - can also be used as a FUNC in an AFUNC:
# - as a SERVICE with name FILTERFilter, (not $FILTERFilter)
# - with $filter(FILTER_STR)
# - should be stateless
MODULE.filter(FILTER_STR, #Registers factory method for a FILTER
FILTER_AFUNC([SERVICE...]) #AFUNC returns FUNC2(VAL[, ...]), which returns VAL2.
lower|uppercase(STR) #FILTER
json(OBJ[, NUM]) #Calls JSON.sringify(OBJ, null, NUM). NUM is 2 by def.
#Automatically used by {{EXPR}}
number(NUM[, NUM2]) #FILTER that returns NUM as STR, with NUM2 decimals (def: 3), according to
#current LOCALE.
#If not NUM, returns ""
currency(NUM[, STR[, NUM2]]) #FILTER that adds STR to end|beginning of a NUM, and return "" if not NUM.
#NUM2 is number of decimals (def: 2)
date(DATE[, STR[, STR2]]) #FILTER that returns DATE as STR3 according to format string STR which can
#also be:
# - "medium": "MMM d, y h:mm:ss a"
# - "short": "M/d/yy h:mm a"
# - "fullDate": "EEEE, MMMM d, y"
# - "longDate": "MMMM d, y"
# - "mediumDate": "MMM d, y" (déf)
# - "shortDate": "M/d/yy"
# - "mediumTime": "h:mm:ss a"
# - "shortTime": "h:mm a"
#STR2 is timezone (def: locale)
format(STR, ARR|OBJ) |#If ARR, replace $NUM in STR by ARR[NUM]
|#If OBJ, replace :VAR in STR by ARR.VAR
|#MODULE "ui.format"
inflector(STR[, STR2]) |#Change case/spaces according to STR2:
|# - "humanize" (def): One Two Three
|# - "underscore": one_two_three
|# - "variable": oneTwoThree
|#MODULE "ui.inflector"
highlight(STR, STR2[, BOOL]) |#Look for STR2 in STR and wrap it in <span class="ui-match">
|#If BOOL true, case sensitive.
|#Returns HTML as is, so must use ng-bind-html
|#MODULE "ui.highlight"
linky(STR, STR2) #FILTER that wrap links (everything starting with a protocol) with
#<a href="URL">...</a>, then use SANITIZE(STR2) (requires module ngSanitize)
/=+===============================+=\
/ : : \
)==: SECURITY :==(
\ :_______________________________: /
\=+===============================+=/
<any> #Put ng-csp to bypass CSP restrictions (e.g. in Chrome extensions):
ng-app ng-csp # - will be 30% slower
# - must also inlude angular-csp.css
$compileProvider. #When compiling, links in <a href="EXPR"> and <img src="EXPR"> are sanitized:
aHref|imgSrcSanitizationWhitelist([REGEXP]) # - relative path -> absolute
# - if not match REGEXP (whitelist), prefixed with "unsafe:".
# Déf REGEXP: HTTP/HTTPS/FTP/FILE protocols (<a href> and <img src>),
# data:image (<img src>) and mailto|tel (<a href>)
$sanitize #From module ngSanitize.
SANITIZE(STR) #Returns HTML code STR, with:
# - JavaScript code removed
# - links not matching COMPILEPROVIDER.aHref|imgSrcSanitizationWhitelist
# removed
$sce[Delegate] #Sanitize web content.
#Used by core features:
# - SCE.HTML: ng-bind-html
# - SCE.RESOURCE_URL: ng-include, [ng-]src, templateUrl in MODULE.directive()
# and routeProvider.
# - <a href>, <img src> don't use it: see aHref|imgSrcSanitizationWhitelist()
#Should be used by any code which inject links/HTML/CSS/JS.
#Use $sce to execute, $sceDelegate to configure (through $sceDelegateProvider).
SCE[DELEGATE].getTrusted(CONTEXT, STR) #According to CONTEXT:
# - SCE.CSS|URL|JS: throw exception
# - SCE.HTML: returns SANITIZE(STR)
# - SCE.RESOURCE_URL: throw exception if:
# - in SCEDELEGATEPROVIDER.resourceUrlBlacklist([VAL_ARR]) (déf: [])
# It is good idea to block redirect URL from own domain to other
# domain, as other domain could be used to bypass security.
# - not in same domain, unless in
# SCEDELEGATEPROVIDER.resourceUrlWhitelist([VAL_ARR]) (déf: ["self"])
# - VAL:
# - matches the whole URL
# - be careful, especially with REGEXP and **
# - can be:
# - STR: can use wildcards * (matches /[^:/.?&;]*/) and **
# (matches /.*/, to use only at end of URL, because in domain it
# can be dangerous)
# - REGEXP: flags are ignored.
# - "self": same as CURRENT_PROTOCOL://CURRENT_DOMAIN/**
# Browse still does the same origin policy/CORS.
#Can bypass this by using an OBJ instead of STR:
# - returned by SCE[DELEGATE].trustAs(CONTEXT, STR), which wraps it.
# - OBJ can be unwrap with SCE[DELEGATE].valueOf(CONTEXT, OBJ|STR), which
# return underlying STR2 in OBJ, or as is if STR.
SCE.parseAs(CONTEXT, EXPR) #Like SCE.getTrusted(CONTEXT, $parse(EXPR))
SCE.isEnabled() #If SCE can be used (déf: true)
#Can be disabled with SCEPROVIDER.enabled([BOOL])
/=+===============================+=\
/ : : \
)==: ANIMATION :==(
\ :_______________________________: /
\=+===============================+=/
$animate #Depends on ngAnimate module. If not included:
# - only perform the action (DOM/CSS) but not the temporary CSS classes
# (.ng-animate, etc.) nor JavaScript handlers.
# - ANIMATE.animate() not dispo
#Goal is to dissociate:
# - animation declaration:
# - DIRECTIVE calls ANIMATE.ANIMEVENT(...) which:
# - perform an action (DOM or CSS class manipulation)
# - temporarily adds some CSS classes during the manipulation:
# - in order:
# 1) .ng-animate
# 2) .ng-ANIMEVENT or .CLASS-add|remove
# 3) .ng-ANIMEVENT-active or .CLASS-add|remove-active
# 4) then removes all three
# - transitions|animations:
# - must be performed from 2) to 2+3) (not only 3))
# - must consider the state before|after transitions to avoid
# weird glitching
# - triggers JavaScript handlers registered with MODULE.animation()
# - enter|leave|move() only fire after SCOPE.$digest, but not
# add|remove|setClass()
# - already defined in some core directives (especially enter|leave|move())
# - animation consumption:
# - in CSS, transitions/animations using temporary CSS classes
# - in JavaScript, MODULE register event handlers with MODULE.animation().
# Event handlers perform animation using e.g. JQ.animate(), etc.
#Staggering:
# - if several siblings fire the same ANIMEVENT, instead of having animation
# on all of them at same time, can delay start of animation of one after
# the other according to a delay.
# - to do so, add (not remove any) a CSS rule with selector
# .ng-ANIMEVENT-stagger (not .ng-ANIMEVENT nor .ng-ANIMEVENT-active) and
# with property transition|animation-delay: TIME.
# - no support yet in JavaScript
#Children:
# - wait for parent to finish animation, unless parent has directive
# ng-animate-children
ANIMATE.enter(AJQ, AJQ2, AJQ3[, CSS_OBJ]) #Append AJQ comme enfant de AJQ2, before sibling AJQ3 (null for last).
#Uses .ng-enter[-active] on AJQ.
#Returns PROMISE resolved when all animations are finished performing.
#CSS_OBJ is CSS styles added during the action.
ANIMATE.move(AJQ, AJQ2, AJQ3[, CSS_OBJ]) #Similar but:
# - move AJQ
# - uses .ng-move[-active]
ANIMATE.leave(AJQ[, CSS_OBJ]) #Similar but:
# - remove AJQ
# - uses .ng-leave[-active]
ANIMATE.add|removeClass(AJQ,CLASS_STR[,CSS_OBJ])#Similar but:
# - adds|remove CLASS_STR on AJQ
# - uses .CLASS_STR-add|remove[-active]
# - is alias to ATTRS.$add|removeClass(CLASS_STR)
ANIMATE.setClass(AJQ, CLASS_STR, CLASS2_STR #Calls removeClass then addClass().
[, CSS_OBJ] #Returns PROMISE resolved when all animations are finished performing.
ANIMATE.animate(AJQ, OBJ, OBJ2[, CLASS_STR] #Similar as above but:
[, CSS_OBJ]) # - use CLASS_STR (def: .ng-inline-animate) instead of .ng-ANIMEVENT[-active]
# - perform CSS transition from OBJ to OBJ2, e.g.
# { color: "red" }, { color: "blue" }
ANIMATE.enabled([BOOL[, AJQ]]) #Enable|disable animations.
ANIMATE.cancel(PROMISE) #Cancels an animation
$animateProvider #Only performs animations on elements whose class name matches REGEXP.
ANIMATEPROVIDER.classNameFilter(REGEXP) #Done to decrease animation on low-performance devices.
MODULE.animation(CLASS_STR, AFUNC([SERVICE...]))#Register event handlers for ANIMATE.ANIMEVENT(AJQ, ...) for AJQ matching
#CSS selector CLASS_STR (class selector only).
#AFUNC returns { ANIMEVENT: FUNC(AJQ, ..., FUNC2) ... }, where FUNC:
# - is called when ANIMEVENT is fired
# - must perform the animation in JavaScript, e.g.:
# JQ.animate|effect|toggleClass|etc.(...)
# - must call FUNC2 when animation is done (async.)
# - must return FUNC3(BOOL), which is fired when animation stops,
# BOOL being true if cancelled, false if normal end.
# Not always called if false.
# If cancelled and jQuery animation, should JQ.stop()
# - for add|removeClass ANIMEVENT:
# - only them can use CLASS2_STR
# - can be beforeANIMEVENT: same function, but before the actual action.
/=+===============================+=\
/ : : \
)==: TEMPLATES :==(
\ :_______________________________: /
\=+===============================+=/
<any> #Same but:
ng-bind-html="HTML_STR" # - with HTML_STR, not a file
# - $sanitize HTML (must include ngSanitize)
<script type="text/ng-template" id="ID"> #Content (inline or through src="") can used as ID_STR, which will look like an
#external HTML file, anywhere a partial template link is expected.
#Can be in <body>
$templateCache #template CACHE automatically filled in by any partial template used through
#templateUrl STR (not template STR) (including directives) or <script>, and
#used afterwards.
#Key is URL|ID
#Value is ARR: NUM (status code), STR (content), OBJ (cache options),
#STR2 (status text)
$templateRequest(STR[, BOOL]) #Calls URL STR, and fills $templateCache.
#If error and BOOL false (def), throw errors.
GULP-NG-HTML2JS(OBJ) #Creates JavaScript file that loads MODULE that loads $templateCache with
#HTML_FILES. OBJ:
# - moduleName STR (déf: current file, i.e. one file/MODULE per HTML_FILE):
# if STR, use only one module for all, and gets the module instead of
# creating it.
# - rename FUNC(STR)->STR2: change template ID (déf: file relative path)
# - prefix|stripPrefix STR: same by prepending|substracting prefix
#There is also a karma plugin karma-ng-html2js-preprocessor (but prefer Gulp)
GULP-ANGULAR-TEMPLATECACHE() #Essentially same as GULP-NG-HTML2JS (prefer later).
<ng-include> #Applies a partial template. Creates a SCOPE.
#Uses enter and leave ANIMEVENT.
#Uses SCE.RESOURCE_URL if ngSanitize is loaded.
src="EXPR" #Template is changed every time EXPR (which evaluates to URL_STR) is changed.
onload="EXPR" #Evaluated when a new partial template is loaded.
SCOPE.$on("$includeContentRequested|Loaded", #Fired when content is going to be|is reloaded.
FUNC(AEVENT, URL)) #Emitted from ng-include SCOPE.
SCOPE.$on( "$includeContentError",
FUNC(AEVENT, URL)) #Status 4** or 5**
<ui-include> |#Same as <ng-include> except:
|# - no $includeContentRequested|Error event
|# - support HTML attribute fragment="SELECTOR", which filters partial template
|# to only matching parts.
|#MODULE "ui.include". Requires jQuery.
/=+===============================+=\
/ : : \
)==: ROUTING :==(
\ :_______________________________: /
\=+===============================+=/
NAVIGATION ==> #There are two ways URL is manipulated in order to reload the page:
# - HTML5 mode: AURL is the full path
# - must use a <base> URI if requireBase true (see below)
# - angularjs will use the HTML5 history API underneath.
# - Server must redirect all related AURL to underlying real file URL
# - Fires security exceptions with file:///
# - links are rewritten unless $locationProvider.rewriteLinks(false)
# - non-HTML5 mode: AURL is the hash part, excluding # + hashPrefix:
# - # is followed by an optional $locationProvider.hashPrefix(STR)
# (déf: "", should use "!"), then a mandatory "/"
# e.g: URL/index.html#!/PATH/TO/FILE?VAR=VAL#HASH
# - Easier to setup, but not pretty URL.
# - must use <meta name="fragment" content="!"> for web crawlers.
#Difference between both modes:
# - is in the interpretation of AURL, the "path" that is changed without
# reloading the page, by $location and SERVICE depending on $location, like
# $route.
# - but not in the resolution of links. As a reminder in HTML:
# - absolute link are resolved as is
# - relative link starting with "/" are appended to hostname
# - otherwise, appended to base URI (déf: ".")
# For example, links with non-HTML5 mode must use #, while HTML mode links
# must look like real links.
# - so if HTML5 mode, will reload the page if $routeProvider not used
# - Decided by $locationProvider.html5Mode(BOOL|OBJ) where OBJ is:
# - enabled BOOL (déf: false).
# - requireBase BOOL (def: true)
#In HTML5 mode, there is a fallback to other mode when browser doesn't
#support it:
# - going to a relative link will convert it to hash version
# - everything else will be like non-HTML5 mode
# - so hashPrefix should always be set.
#AURL changes (combined with $routeProvider) (including parent DIR change in
#HTML5 mode) doesn't reload page, but can:
# - Have a hash and search string.
# - Update history when changed, so can go backward/forward.
# - With routing, change current page and provide URL to come back to same
# point ("deep linking").
# - For redirection, should change AURL then call LOCATION.replace()
#Reload is still forced in those cases:
# - link using target="", including target="_self" (forced reload)
# - link pointing to different base URI
# - absolute links
# - changing URL manually (e.g. in omnibox or manual refresh) instead of
# following a link
#AURL is percent-encoded|decoded by getter|setters (except LOCATION.url(), but
#not LOCATION.url(STR))
$location #Gets URL/AURL, and sets AURL.
#AURL changes apply once a $digest() is called.
#Setters returns LOCATION.
LOCATION.absUrl() #Returns URL as STR
LOCATION.protocol() #Returns e.g. "http"
LOCATION.host() #Returns e.g. "www.google.fr"
LOCATION.port() #Returns e.g. 80. null if Unix socket.
LOCATION.url() #Returns AURL
LOCATION.url(STR) #Sets AURL
LOCATION.path([STR]) #Same without search string and hash.
LOCATION.hash([STR]) #Same for hash in AURL
LOCATION.search() #Returns AURL GET variables as OBJ.
LOCATION.search(OBJ) #Replaces AURL GET variables by OBJ.
LOCATION.search(STR, VAL2) #Replaces AURL GET variable STR value by VAL2 (null to remove, true for no
#value)
LOCATION.replace() #Make current AURL changes replace history entry instead of adding new one.
#Should call just after AURL change, before $digest()
LOCATION.state() #Manually get/set HTML5 history through pushState()/replaceState() (usually
LOCATION.state(OBJ) #not needed)
SCOPE.$on("$locationChangeStart|Success", #Broadcasted from root SCOPE when AURL is about to change|is done.
FUNC(AEVENT, NEW_URL, OLD_URL)) #Fired also at page load.
$anchorScroll #SERVICE FUNC().
#Emulate hash anchors with AURL (when $location.hash() changes, auto scoll).
#Can be disabled with:
# - ANCHORSCOLLPROVIDER.disableAutoScrolling()
# - <ng-view|include autoscroll="BOOL_EXPR">
#Adds extra scrolling (e.g. when there is a fixed header) with
#$anchorScroll = VAL, where VAL can be:
# - NUM|FUNC()->NUM (px)
# - AJQ: takes distance from top of page to AJQ bottom, using
# ELEM.getBoundingClientRect().bottom
# Must be position: fixed. Can e.g be fixed header.
#In which case can be manually called as FUNC()
$route #SERVICE to apply partial templates to <ng-view> according to AURL when it
#changes
ROUTE.current #OBJ with members:
# - loadedTemplateUrl STR: URL of current partial template
# - locals OBJ: CONTROLLER arguments. Also contains special variables
# $scope, and $template STR (initial uncompiled HTML code)
# - params OBJ: location.search()
# - pathParams OBJ: ROUTEPARAMS (see below)
# - scope SCOPE
ROUTE.updateParams(OBJ) #Modifies ROUTE.current.[path]params (must call $rootScope.$digest())
ROUTE.routes #All routes defined by ROUTEPROVIDER, as an OBJ whose keys are the URL
#(null for otherwise()), and members are controller STR, originalPath STR,
#regexp REGEXP, reloadOnSearch BOOL and templateUrl STR.
ROUTE.reload() #Force reloading partial templates, which means:
# - ROUTEPROVIDER.when(...) are called
# - SCOPE and CONTROLLER in partial templates are reinitialized
SCOPE.$on("$routeChangeStart|Success", #Broadcasted from root SCOPE when AURL is about to change|is done and
FUNC(AEVENT, OLD_URL_OBJ, NEW_URL_OBJ)) #routing is gonna happen.
#URL_OBJ has same members as ROUTE.current.
SCOPE.$on("$viewContentLoaded", FUNC(AEVENT)) #Emitted from <ng-view> SCOPE when a routing happened to it.
$routeProvider #SERVICEPROVIDER, depending on ngRoute MODULE.
ROUTEPROVIDER.when(AURL, OBJ) #On $locationChangeStart AEVENT, does some actions on all <ng-view>,
#when current AURL is exactly AURL.
#Action depends on OBJ:
# - templateUrl URL|FUNC(OBJ): applies partial template URL (not a AURL, more
# like a href attribute) to all children of <ng-view>
# FUNC(OBJ) must return URL_STR, and OBJ are the ROUTEPARAMS
# - template STR|FUNC(OBJ): same with a STR
# - redirectTo STR|FUNC(OBJ, STR2, OBJ2): changes current AURL.
# "" means no change of AURL.
# FUNC(OBJ) must return URL_STR, and OBJ are the ROUTEPARAMS, STR2
# $location.path() and OBJ2 $location.search()
# - controller CONTROLLER_STR|AFUNC: use CONTROLLER in partial template.
# - resolve OBJ: pass each VAR of { VAR:VAL ... } as potential argument to
# CONTROLLER AFUNC. VAL can be:
# - SERVICE_STR
# - SERVICE AFUNC, which can return:
# - a normal VAL
# - a PROMISE: $location will be changed only once PROMISE is
# resolved (and not if rejected), and final VAL will be the one used
# in resolve(VAL)
# If rejected, fires SCOPE.$on("$routeChangeError",
# FUNC(AEVENT, OLD_URL_OBJ, NEW_URL_OBJ) broadcasted from root SCOPE.
# Make the page change once some async. work has been performed.
# - reloadOnSearch BOOL: if false (déf: true), doesn't do anything if
# only $location.search() or $location.hash() was changed, except firing
# SCOPE.$on("$routeUpdate", FUNC(AEVENT, NEW_URL_OBJ)) broadcasted from
# root SCOPE.
# - caseInsensitiveMatch BOOL (déf: false): for AURL
#AURL:
# - can contain:
# - :VAR, meaning anything up until the next / or . will be stored in VAR,
# which can be accessed through ROUTEPARAMS.VAR.
# - :VAR*: same but is not stopped by next /
# - :VAR*? or :VAR?: same but can be empty (otherwise cannot)
# - can be used as SERVICE $routeParams.VAR, refering to :VAR (see above) or
# to any current AURL GET variable in:
# - controller AFUNC above (next $routeParams, after AURL change)
# - resolve SERVICE AFUNC (current $routeParams, before AURL change)
#Returns ROUTEPROVIDER.
ROUTEPROVIDER.otherwise(STR|OBJ) #Same when no AURL matches.
#STR is same as { redirectTo: STR }
#Good idea to put one with redirectTo: to avoid wrong AURL (although user can
#bypass it by forcing page reload).
<any> |#Sets VAR BOOL === whether STR matches LOCATION.path():
ui-route[="STR"] |# - VAR is ng-model="VAR", or route-model="VAR", or SCOPE.$uiRoute
|# - STR is [ng-]href value by def.
|# - If [ng-]href, "matches" means STR is included in LOCATION.path()
|# Otherwise it is /^REGEXP_STR$/i
|#MODULE "ui.route"
<ng-view> #Uses enter and leave ANIMEVENT. Creates a SCOPE.
onload="EXPR" #Fires EXPR in current SCOPE everytime ng-view changes
UI ROUTER ==> ##MODULE "ui.router". Version 0.2.13
UI-ROUTER-EXTRAS ==> ###Plugin to UI-router. MODULE "ct.ui.router.extras". Version 0.0.13
STATES ==> ##Provides states:
## - current place in the UI
## - associated with STATE_CONF, i.e. actions fired when this state or a
## children is on.
## - has a name STATE_STR
STATES HIERARCHY ==> ##States can have children:
## - noted "[STATE][.SUBSTATE]":
## - STATE can be omitted to mean current one
## - STATE can "^" to mean parent one
## - can also specify STATE_CONF.parent STATE_STR|CONF instead, which will
## make SUBSTATE_STR relative to STATE_STR (i.e. writing "SUBSTATE"
## instead of "STATE.SUBSTATE")
## - the states hierarchy corresponds to the hierarchy of <ui-view> containing
## each other: when an <ui-view> contains another one, the other one is
## activated by the substate.
## - each SUBSTATE inherits from parent (but can be overwritten):
## - STATE_CONF.data|resolve
## - STATE_CONF.url (prepends parent AURL, unless starts with "^")
## - STATE_PARAM is inherited. However documentation says it is not and
## that STATE_CONF.resolve must be used to fix this
## - a SUBSTATE can modify a parent state with STATE_CONF.views.VIEW@STATE
## (see below)
TABS ==> ##To implement tabs, use:
## - tab:
## li(ng-class="{ active: $state.includes('STATE') }")
## a(ui-sref="STATE")
## - content: one <ui-view> content sibling for each tab, with:
## ng-show="$state.includes('STATE')"
##And use sticky + deepStateRedirect
AURL BINDING ==> ##Using STATE_CONF.url:
## - AURL and state are bound: changing one updates the other.
## - STATE_PARAM are bound according to either:
## - AURL pattern (optional always, defaults to ""), including in query
## string:
## - *VAR: up to end
## - :VAR or {VAR}: up to next /
## - ?VAR or &VAR: same as ?{VAR} or &{VAR}
## - {VAR:REGEXP_STR} (e.g. {VAR:[0-9]*})
## - {VAR:TYPE} (e.g. {VAR:int})
## - STATE_PARAM is accessible via $stateParams SERVICE (preferred) or
## STATE.params.
## - "STATE({ VAR: STR_EXPR })" allows to specify STATE_PARAM in STATE_STR
$urlMatcherFactoryProvider.caseInsensitive(BOL)##Changes whether AURL patterns are case insensitive (def: false)