43 | | // ### Get a selector's first subview |
44 | | // |
45 | | // Fetches the first subview that matches a given `selector`. |
46 | | // |
47 | | // If no `selector` is provided, it will grab the first subview |
48 | | // attached to the view's root. |
49 | | // |
50 | | // Useful when a selector only has one subview at a time. |
| 52 | /** |
| 53 | * Fetches the first subview that matches a given `selector`. |
| 54 | * |
| 55 | * If no `selector` is provided, it will grab the first subview |
| 56 | * attached to the view's root. |
| 57 | * |
| 58 | * Useful when a selector only has one subview at a time. |
| 59 | * |
| 60 | * @param {string} selector A jQuery selector. |
| 61 | * |
| 62 | * @return {Backbone.View} The view. |
| 63 | */ |
56 | | // ### Register subview(s) |
57 | | // |
58 | | // Registers any number of `views` to a `selector`. |
59 | | // |
60 | | // When no `selector` is provided, the root selector (the empty string) |
61 | | // is used. `views` accepts a `Backbone.View` instance or an array of |
62 | | // `Backbone.View` instances. |
63 | | // |
64 | | // --- |
65 | | // |
66 | | // Accepts an `options` object, which has a significant effect on the |
67 | | // resulting behavior. |
68 | | // |
69 | | // `options.silent` – *boolean, `false`* |
70 | | // > If `options.silent` is true, no DOM modifications will be made. |
71 | | // |
72 | | // `options.add` – *boolean, `false`* |
73 | | // > Use `Views.add()` as a shortcut for setting `options.add` to true. |
74 | | // |
75 | | // > By default, the provided `views` will replace |
76 | | // any existing views associated with the selector. If `options.add` |
77 | | // is true, the provided `views` will be added to the existing views. |
78 | | // |
79 | | // `options.at` – *integer, `undefined`* |
80 | | // > When adding, to insert `views` at a specific index, use |
81 | | // `options.at`. By default, `views` are added to the end of the array. |
| 69 | /** |
| 70 | * Register subview(s) |
| 71 | * |
| 72 | * Registers any number of `views` to a `selector`. |
| 73 | * |
| 74 | * When no `selector` is provided, the root selector (the empty string) |
| 75 | * is used. `views` accepts a `Backbone.View` instance or an array of |
| 76 | * `Backbone.View` instances. |
| 77 | * |
| 78 | * --- |
| 79 | * |
| 80 | * Accepts an `options` object, which has a significant effect on the |
| 81 | * resulting behavior. |
| 82 | * |
| 83 | * `options.silent` – *boolean, `false`* |
| 84 | * > If `options.silent` is true, no DOM modifications will be made. |
| 85 | * |
| 86 | * `options.add` – *boolean, `false`* |
| 87 | * > Use `Views.add()` as a shortcut for setting `options.add` to true. |
| 88 | * |
| 89 | * > By default, the provided `views` will replace |
| 90 | * any existing views associated with the selector. If `options.add` |
| 91 | * is true, the provided `views` will be added to the existing views. |
| 92 | * |
| 93 | * `options.at` – *integer, `undefined`* |
| 94 | * > When adding, to insert `views` at a specific index, use |
| 95 | * `options.at`. By default, `views` are added to the end of the array. |
| 96 | * |
| 97 | * @param {string} selector A jQuery selector. |
| 98 | * @param {array|object} views The subviews for the main view. |
| 99 | * @param {} options Options for call. If `options.silent` is true, no DOM |
| 100 | * modifications will be made. Use `Views.add()` as a |
| 101 | * shortcut for setting `options.add` to true. If `options.add` |
| 102 | * is true, the provided `views` will be added to the existing |
| 103 | * views. When adding, to insert `views` at a specific index, |
| 104 | * use `options.at`. |
| 105 | * |
| 106 | * @return wp.Backbone.Subviews |
| 107 | */ |
137 | | // ### Add subview(s) to existing subviews |
138 | | // |
139 | | // An alias to `Views.set()`, which defaults `options.add` to true. |
140 | | // |
141 | | // Adds any number of `views` to a `selector`. |
142 | | // |
143 | | // When no `selector` is provided, the root selector (the empty string) |
144 | | // is used. `views` accepts a `Backbone.View` instance or an array of |
145 | | // `Backbone.View` instances. |
146 | | // |
147 | | // Use `Views.set()` when setting `options.add` to `false`. |
148 | | // |
149 | | // Accepts an `options` object. By default, provided `views` will be |
150 | | // inserted at the end of the array of existing views. To insert |
151 | | // `views` at a specific index, use `options.at`. If `options.silent` |
152 | | // is true, no DOM modifications will be made. |
153 | | // |
154 | | // For more information on the `options` object, see `Views.set()`. |
| 163 | /** |
| 164 | * Add subview(s) to existing subviews |
| 165 | * |
| 166 | * An alias to `Views.set()`, which defaults `options.add` to true. |
| 167 | * |
| 168 | * Adds any number of `views` to a `selector`. |
| 169 | * |
| 170 | * When no `selector` is provided, the root selector (the empty string) |
| 171 | * is used. `views` accepts a `Backbone.View` instance or an array of |
| 172 | * `Backbone.View` instances. |
| 173 | * |
| 174 | * Use `Views.set()` when setting `options.add` to `false`. |
| 175 | * |
| 176 | * Accepts an `options` object. By default, provided `views` will be |
| 177 | * inserted at the end of the array of existing views. To insert |
| 178 | * `views` at a specific index, use `options.at`. If `options.silent` |
| 179 | * is true, no DOM modifications will be made. |
| 180 | * |
| 181 | * For more information on the `options` object, see `Views.set()`. |
| 182 | * |
| 183 | * @param {string} selector A jQuery selector. |
| 184 | * @param {array|object} views The subviews for the main view. |
| 185 | * @param {} options Options for call. To insert `views` at a specific index, |
| 186 | * use `options.at`. If `options.silent` is true, no DOM |
| 187 | * modifications will be made. |
| 188 | * |
| 189 | * @return wp.Backbone.Subviews |
| 190 | */ |
164 | | |
165 | | // ### Stop tracking subviews |
166 | | // |
167 | | // Stops tracking `views` registered to a `selector`. If no `views` are |
168 | | // set, then all of the `selector`'s subviews will be unregistered and |
169 | | // removed. |
170 | | // |
171 | | // Accepts an `options` object. If `options.silent` is set, `remove` |
172 | | // will *not* be triggered on the unregistered views. |
| 200 | /** |
| 201 | * Stop tracking subviews |
| 202 | * |
| 203 | * Stops tracking `views` registered to a `selector`. If no `views` are |
| 204 | * set, then all of the `selector`'s subviews will be unregistered and |
| 205 | * removed. |
| 206 | * |
| 207 | * Accepts an `options` object. If `options.silent` is set, `remove` |
| 208 | * will *not* be triggered on the unregistered views. |
| 209 | * |
| 210 | * @param {string} selector A jQuery selector. |
| 211 | * @param {array|object} views The subviews for the main view. |
| 212 | * @param {} options Options for call. If `options.silent` is set, |
| 213 | * `remove` will *not* be triggered on the unregistered |
| 214 | * views. |
| 215 | * |
| 216 | * @return wp.Backbone.Subviews |
| 217 | */ |
222 | | // ### Remove all subviews |
223 | | // |
224 | | // Triggers the `remove()` method on all subviews. Detaches the master |
225 | | // view from its parent. Resets the internals of the views manager. |
226 | | // |
227 | | // Accepts an `options` object. If `options.silent` is set, `unset` |
228 | | // will *not* be triggered on the master view's parent. |
| 274 | /** |
| 275 | * Remove all subviews |
| 276 | * |
| 277 | * Triggers the `remove()` method on all subviews. Detaches the master |
| 278 | * view from its parent. Resets the internals of the views manager. |
| 279 | * |
| 280 | * Accepts an `options` object. If `options.silent` is set, `unset` |
| 281 | * will *not* be triggered on the master view's parent. |
| 282 | * |
| 283 | * @param {} options Options for call. If `options.silent` is set, `unset` will *not* be |
| 284 | * triggered on the master view's parent. |
| 285 | * |
| 286 | * @return {} |
| 287 | */ |
251 | | |
252 | | // ### Insert subviews into a selector |
253 | | // |
254 | | // By default, appends the subview `els` to the end of the `$target` |
255 | | // selector. If `options.at` is set, inserts the subview `els` at the |
256 | | // provided index. |
257 | | // |
258 | | // Can be overridden in subclasses. |
| 316 | /** |
| 317 | * Insert subviews into a selector |
| 318 | * |
| 319 | * By default, appends the subview `els` to the end of the `$target` |
| 320 | * selector. If `options.at` is set, inserts the subview `els` at the |
| 321 | * provided index. |
| 322 | * |
| 323 | * Can be overridden in subclasses. |
| 324 | * |
| 325 | * @param {} target |
| 326 | * @param {} els |
| 327 | * @param {} options Options for call. If `options.at` is set, inserts the subview `els` at the provided index. |
| 328 | * |
| 329 | * @return wp.Backbone.Subviews |
| 330 | */ |
286 | | |
287 | | // #### Internal. Attaches a series of views to a selector. |
288 | | // |
289 | | // Checks to see if a matching selector exists, renders the views, |
290 | | // performs the proper DOM operation, and then checks if the view is |
291 | | // attached to the document. |
| 358 | /** |
| 359 | * Internal. Attaches a series of views to a selector. |
| 360 | * |
| 361 | * Checks to see if a matching selector exists, renders the views, |
| 362 | * performs the proper DOM operation, and then checks if the view is |
| 363 | * attached to the document. |
| 364 | * |
| 365 | * @param {string} selector A jQuery selector. |
| 366 | * @param {array|object} views The subviews for the main view. |
| 367 | * @param {} options Options for call. If `options.add` is true, the provided |
| 368 | * `views` will be added to the existing views. |
| 369 | * |
| 370 | * @return wp.Backbone.Subviews |
| 371 | */ |