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