|
1 | | -By default, Ember.js will extend the prototypes of native JavaScript |
2 | | -objects in the following ways: |
3 | | - |
4 | | -* `Array` is extended to implement the `Ember.Enumerable`, |
5 | | - `Ember.MutableEnumerable`, `Ember.MutableArray` and `Ember.Array` |
6 | | - interfaces. This polyfills ECMAScript 5 array methods in browsers that |
7 | | - do not implement them, adds convenience methods and properties to |
8 | | - built-in arrays, and makes array mutations observable. |
9 | | -* `String` is extended to add convenience methods, such as |
10 | | - `camelize()` and `fmt()`. |
11 | | -* `Function` is extended with methods to annotate functions as |
12 | | - computed properties, via the `property()` method, and as observers, |
13 | | - via the `observes()` or `observesBefore()` methods. |
14 | | - |
15 | | -This is the extent to which Ember.js enhances native prototypes. We have |
16 | | -carefully weighed the tradeoffs involved with changing these prototypes, |
17 | | -and recommend that most Ember.js developers use them. These extensions |
18 | | -significantly reduce the amount of boilerplate code that must be typed. |
19 | | - |
20 | | -However, we understand that there are cases where your Ember.js |
21 | | -application may be embedded in an environment beyond your control. The |
22 | | -most common scenarios are when authoring third-party JavaScript that is |
23 | | -embedded directly in other pages, or when transitioning an application |
24 | | -piecemeal to a more modern Ember.js architecture. |
25 | | - |
26 | | -In those cases, where you can't or don't want to modify native |
27 | | -prototypes, Ember.js allows you to completely disable the extensions |
28 | | -described above. |
29 | | - |
30 | | -To do so, simply set the `EXTEND_PROTOTYPES` flag to `false`: |
31 | | - |
32 | | -```javascript |
33 | | -window.EmberENV = {}; |
34 | | -EmberENV.EXTEND_PROTOTYPES = false; |
35 | | -``` |
36 | | - |
37 | | -Or you can choose class which you want to disable prototype extension. |
38 | | -```javascript |
39 | | -EmberENV.EXTEND_PROTOTYPES = { |
40 | | - String: false, |
41 | | - Array: true |
42 | | -}; |
43 | | -``` |
44 | | - |
45 | | -Note that the above code must be evaluated **before** Ember.js loads. If |
46 | | -you set the flag after the Ember.js JavaScript file has been evaluated, |
47 | | -the native prototypes will already have been modified. |
48 | | - |
49 | | -### Life Without Prototype Extension |
50 | | - |
51 | | -In order for your application to behave correctly, you will need to |
52 | | -manually extend or create the objects that the native objects were |
53 | | -creating before. |
54 | | - |
55 | | -#### Arrays |
56 | | - |
57 | | -Native arrays will no longer implement the functionality needed to |
58 | | -observe them. If you disable prototype extension and attempt to use |
59 | | -native arrays with things like a template's `{{#each}}` helper, Ember.js |
60 | | -will have no way to detect changes to the array and the template will |
61 | | -not update as the underlying array changes. |
62 | | - |
63 | | -Additionally, if you try to set the model of an |
64 | | -`Ember.ArrayController` to a plain native array, it will raise an |
65 | | -exception since it no longer implements the `Ember.Array` interface. |
66 | | - |
67 | | -You can manually coerce a native array into an array that implements the |
68 | | -required interfaces using the convenience method `Ember.A`: |
69 | | - |
70 | | -```javascript |
71 | | -var islands = ['Oahu', 'Kauai']; |
72 | | -islands.contains('Oahu'); |
73 | | -//=> TypeError: Object Oahu,Kauai has no method 'contains' |
74 | | - |
75 | | -// Convert `islands` to an array that implements the |
76 | | -// Ember enumerable and array interfaces |
77 | | -Ember.A(islands); |
78 | | - |
79 | | -islands.contains('Oahu'); |
80 | | -//=> true |
81 | | -``` |
82 | | - |
83 | | -#### Strings |
84 | | - |
85 | | -Strings will no longer have the convenience methods described in the |
86 | | -[Ember.String API reference.](http://emberjs.com/api/classes/Ember.String.html). Instead, |
87 | | -you can use the similarly-named methods of the `Ember.String` object and |
88 | | -pass the string to use as the first parameter: |
89 | | - |
90 | | -```javascript |
91 | | -"my_cool_class".camelize(); |
92 | | -//=> TypeError: Object my_cool_class has no method 'camelize' |
93 | | - |
94 | | -Ember.String.camelize("my_cool_class"); |
95 | | -//=> "myCoolClass" |
96 | | -``` |
97 | | - |
98 | | -#### Functions |
99 | | - |
100 | | -To annotate computed properties, use the `Ember.computed()` method to |
101 | | -wrap the function: |
102 | | - |
103 | | -```javascript |
104 | | -// This won't work: |
105 | | -fullName: function() { |
106 | | - return this.get('firstName') + ' ' + this.get('lastName'); |
107 | | -}.property('firstName', 'lastName') |
108 | | - |
109 | | - |
110 | | -// Instead, do this: |
111 | | -fullName: Ember.computed('firstName', 'lastName', function() { |
112 | | - return this.get('firstName') + ' ' + this.get('lastName'); |
113 | | -}) |
114 | | -``` |
115 | | - |
116 | | -Observers are annotated using `Ember.observer()`: |
117 | | - |
118 | | -```javascript |
119 | | -// This won't work: |
120 | | -fullNameDidChange: function() { |
121 | | - console.log("Full name changed"); |
122 | | -}.observes('fullName') |
123 | | - |
124 | | - |
125 | | -// Instead, do this: |
126 | | -fullNameDidChange: Ember.observer('fullName', function() { |
127 | | - console.log("Full name changed"); |
128 | | -}) |
129 | | -``` |
130 | | - |
| 1 | +--- |
| 2 | +redirect: configuring-ember/index |
| 3 | +--- |
0 commit comments