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. |
| 54 | /** |
| 55 | * Fetches the first subview that matches a given `selector`. |
| 56 | * |
| 57 | * If no `selector` is provided, it will grab the first subview attached to the |
| 58 | * view's root. |
| 59 | * |
| 60 | * Useful when a selector only has one subview at a time. |
| 61 | * |
| 62 | * @param {string} selector A jQuery selector. |
| 63 | * |
| 64 | * @return {Backbone.View} The view. |
| 65 | */ |
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. |
| 71 | /** |
| 72 | * Registers subview(s). |
| 73 | * |
| 74 | * Registers any number of `views` to a `selector`. |
| 75 | * |
| 76 | * When no `selector` is provided, the root selector (the empty string) |
| 77 | * is used. `views` accepts a `Backbone.View` instance or an array of |
| 78 | * `Backbone.View` instances. |
| 79 | * |
| 80 | * --- |
| 81 | * |
| 82 | * Accepts an `options` object, which has a significant effect on the |
| 83 | * resulting behavior. |
| 84 | * |
| 85 | * `options.silent` – *boolean, `false`* |
| 86 | * > If `options.silent` is true, no DOM modifications will be made. |
| 87 | * |
| 88 | * `options.add` – *boolean, `false`* |
| 89 | * > Use `Views.add()` as a shortcut for setting `options.add` to true. |
| 90 | * |
| 91 | * > By default, the provided `views` will replace |
| 92 | * any existing views associated with the selector. If `options.add` |
| 93 | * is true, the provided `views` will be added to the existing views. |
| 94 | * |
| 95 | * `options.at` – *integer, `undefined`* |
| 96 | * > When adding, to insert `views` at a specific index, use |
| 97 | * `options.at`. By default, `views` are added to the end of the array. |
| 98 | * |
| 99 | * @param {string} selector A jQuery selector. |
| 100 | * @param {array|Object} views The subviews for the main view. |
| 101 | * @param {Object} options Options for call. If `options.silent` is true, no DOM |
| 102 | * modifications will be made. Use `Views.add()` as a |
| 103 | * shortcut for setting `options.add` to true. If `options.add` |
| 104 | * is true, the provided `views` will be added to the existing |
| 105 | * views. When adding, to insert `views` at a specific index, |
| 106 | * use `options.at`. |
| 107 | * |
| 108 | * @return wp.Backbone.Subviews |
| 109 | */ |
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()`. |
| 165 | /** |
| 166 | * Add subview(s) to existing subviews. |
| 167 | * |
| 168 | * An alias to `Views.set()`, which defaults `options.add` to true. |
| 169 | * |
| 170 | * Adds any number of `views` to a `selector`. |
| 171 | * |
| 172 | * When no `selector` is provided, the root selector (the empty string) |
| 173 | * is used. `views` accepts a `Backbone.View` instance or an array of |
| 174 | * `Backbone.View` instances. |
| 175 | * |
| 176 | * Uses `Views.set()` when setting `options.add` to `false`. |
| 177 | * |
| 178 | * Accepts an `options` object. By default, provided `views` will be |
| 179 | * inserted at the end of the array of existing views. To insert |
| 180 | * `views` at a specific index, use `options.at`. If `options.silent` |
| 181 | * is true, no DOM modifications will be made. |
| 182 | * |
| 183 | * For more information on the `options` object, see `Views.set()`. |
| 184 | * |
| 185 | * @param {string} selector A jQuery selector. |
| 186 | * @param {array|object} views The subviews for the main view. |
| 187 | * @param {Object} options Options for call. To insert `views` at a specific index, |
| 188 | * use `options.at`. If `options.silent` is true, no DOM |
| 189 | * modifications will be made. |
| 190 | * |
| 191 | * @return wp.Backbone.Subviews |
| 192 | */ |
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. |
| 203 | /** |
| 204 | * Removes an added subview. |
| 205 | * |
| 206 | * Stops tracking `views` registered to a `selector`. If no `views` are |
| 207 | * set, then all of the `selector`'s subviews will be unregistered and |
| 208 | * removed. |
| 209 | * |
| 210 | * Accepts an `options` object. If `options.silent` is set, `remove` |
| 211 | * will *not* be triggered on the unregistered views. |
| 212 | * |
| 213 | * @param {string} selector A jQuery selector. |
| 214 | * @param {array|object} views The subviews for the main view. |
| 215 | * @param {} options Options for call. If `options.silent` is set, |
| 216 | * `remove` will *not* be triggered on the unregistered |
| 217 | * views. |
| 218 | * |
| 219 | * @return {wp.Backbone.Subviews} The current Subviews instance. |
| 220 | */ |
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. |
| 276 | /** |
| 277 | * Removes all subviews |
| 278 | * |
| 279 | * Triggers the `remove()` method on all subviews. Detaches the master |
| 280 | * view from its parent. Resets the internals of the views manager. |
| 281 | * |
| 282 | * Accepts an `options` object. If `options.silent` is set, `unset` |
| 283 | * will *not* be triggered on the master view's parent. |
| 284 | * |
| 285 | * @param {Object} options Options for call. |
| 286 | * @param {boolean} options.silent If true, `unset` wil *not* be triggered on |
| 287 | * the master views' parent. |
| 288 | * |
| 289 | * @return {wp.Backbone.Subviews} The current Subviews instance. |
| 290 | */ |
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. |
| 321 | /** |
| 322 | * Insert subviews into a selector |
| 323 | * |
| 324 | * By default, appends the subview `els` to the end of the `$target` |
| 325 | * selector. If `options.at` is set, inserts the subview `els` at the |
| 326 | * provided index. |
| 327 | * |
| 328 | * Can be overridden in subclasses. |
| 329 | * |
| 330 | * @param {string} $target Selector where to put the elements. |
| 331 | * @param {*} els HTML or elements to put at the end of the $target. |
| 332 | * @param {?Object} options Options for call. |
| 333 | * @param {?number} options.at At which index to put the elements. |
| 334 | * |
| 335 | * @return {wp.Backbone.Subviews} The current Subviews instance. |
| 336 | */ |
271 | | // ### Trigger the ready event |
272 | | // |
273 | | // **Only use this method if you know what you're doing.** |
274 | | // For performance reasons, this method does not check if the view is |
275 | | // actually attached to the DOM. It's taking your word for it. |
276 | | // |
277 | | // Fires the ready event on the current view and all attached subviews. |
| 349 | /** |
| 350 | * Triggers the ready event. |
| 351 | * |
| 352 | * Only use this method if you know what you're doing. For performance reasons, |
| 353 | * this method does not check if the view is actually attached to the DOM. It's |
| 354 | * taking your word for it. |
| 355 | * |
| 356 | * Fires the ready event on the current view and all attached subviews. |
| 357 | */ |
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. |
| 366 | /** |
| 367 | * Attaches a series of views to a selector. Internal. |
| 368 | * |
| 369 | * Checks to see if a matching selector exists, renders the views, |
| 370 | * performs the proper DOM operation, and then checks if the view is |
| 371 | * attached to the document. |
| 372 | * |
| 373 | * @private |
| 374 | * |
| 375 | * @param {string} selector A jQuery selector. |
| 376 | * @param {array|object} views The subviews for the main view. |
| 377 | * @param {Object} options Options for call. |
| 378 | * @param {boolean} options.add If true the provided views will be added. |
| 379 | * |
| 380 | * @return {wp.Backbone.Subviews} The current Subviews instance. |
| 381 | */ |