]> git.r.bdr.sh - rbdr/r.bdr.sh/blame - jekyll/js/vendor/neon/stdlib/widget.js
Adds new assets for dynamic headers
[rbdr/r.bdr.sh] / jekyll / js / vendor / neon / stdlib / widget.js
CommitLineData
0982546d
BB
1/**
2Base Class from which almost all widgets are based overall the project
3
4The main idea behind constructing a new widget toolkit instead of using one of the many high quality widget
5toolkits avaliable is that we considered that currently, no widget system provides all the features that where
6required for this project.
7
8Features of the widget system
9* A custom and easy to handle event binding, dispatching and manipulation, with some sort of bubbling support
10* A module system which we can use to include specific behaviour to any widget and reuse the code where needed
11* A tree structure support for the widgets that the event system could bubble, and that also serves as
12* A navigation system.
13* The widgets must be able to be grouped to form more complex widgets
14* Remove the complexity of DOM manipulation and handling
15* A way to wrap widgets at our convenience to reuse widgets avaliable and make them comly to our needs
16without the need to hack those widgets, that would force us to maintain the new versions of those widgets
17and that is a very complex task when widgets become so complex.
18* A widget system that would allow us to start wrapping some widgets for a fast start and later code our own widgets
19at will.
20* expose a consistent API that allow us to choose the use of widgets by API calls and user interaction at will and with the same
21clearance and capacity
22* an easy way to allow subclasing widgets
23* an easy way to provide new html, class, and css for a specific instance of a widget that would remove us the need
24to create complex inheritance structures that are hard to maintain.
25
26Usage Example.
27
28The most basic usage of a widget is to simply create an instance and render it at a target element
29in this case body
30var myWidgetInstance = new Breezi.Widget();
31myWidgetInstance.render(document.body);
32
33like this widget does renders does not display anything so lets give it something to display first
34var myWidgetInstance = new Breezi.Widget();
35myWidgetInstance.element.html('Im a simple widget');
36myWidgetInstance.render(document.body);
37
38this reveals that internally every widget has an element property that is initialized by default to a jQuery Instance
39this allow easy DOM manipulation, animation and operations handled by a high quality third party library.
40@class Widget
41@namespace Breezi
42@inlcudes CustomEventSupport
43@includes NodeSupport
44@dependency Neon
45@dependency CustomEventSupport
46@dependency NodeSupport
47**/
48Class('Widget').includes(CustomEventSupport, NodeSupport)({
49
50 /**
51 The default html for the widget, at the most simple case this is just a div.
52 @name HTML
53 @attribute_type CONSTANT
54 @type String
55 */
56 HTML : '<div></div>',
57
58 /**
59 the widget container default class for all widgets is widget
60 @name ELEMENT_CLASS
61 @constant
62 @type String
63 **/
64 ELEMENT_CLASS : 'widget',
65
66 /**
67 @property prototype
68 @type Object
69 **/
70 prototype : {
71 /**
72 Holds the active status of the widget
73 By default all widgets are deactivated waiting
74 for an action to activate it.
75 @property active <public> [Boolean] (false)
76 **/
77 active : false,
78
79 /**
80 Holds the disabled status of the widget
81 By default all widgets are enabled and only by
82 API could be disabled.
83 @property disabled <public> [Boolean] (false)
84 **/
85 disabled : false,
86
87 __destroyed : false,
88
89 init : function init(config) {
90 var property;
91
92 Object.keys(config || {}).forEach(function (propertyName) {
93 this[propertyName] = config[propertyName];
94 }, this);
95
96 if (this.element == null) {
97 this.element = $(this.constructor.HTML.replace(/\s\s+/g, ''));
98 this.element.addClass(this.constructor.ELEMENT_CLASS);
99 }
100
101 if (this.hasOwnProperty('className') === true) {
102 this.element.addClass(this.className);
103 }
104 },
105
106 /**
107 implementation of the activate method, when you need an override, do it
108 over this method instead of doing it on activate
109 @property _activate <private> [Function]
110 @return undefined [undefined]
111 **/
112 _activate : function _activate() {
113 this.active = true;
114 this.element.addClass('active');
115 },
116
117 /**
118 Public activation method for widget, you can listen to this event
119 to take some other actions, but the most important part of this
120 method is that it runs its default action, (its activation)
121 this method uses _activate as its implementation to maintain
122 the events order intact.
123 @property activate <public> [Function]
124 @method
125 @dispatch beforeActivate
126 @dispatch activate
127 @return this [Widget]
128 **/
129 activate : function activate() {
130 if (this.__destroyed === true) {
131 console.warn('calling on destroyed object');
132 }
133 this.dispatch('beforeActivate');
134 this._activate();
135 this.dispatch('activate');
136 return this;
137 },
138
139 /**
140 deactivation implementation
141 this is the oposite of activation method and as such it must be
142 treated as important as that.
143 @property _deactivate <private> [Function]
144 @method
145 @return undefined [undefined]
146 **/
147 _deactivate : function _deactivate() {
148 this.active = false;
149 this.element.removeClass('active');
150 },
151
152 /**
153 Public deactivation method for widget, you can listen to this event
154 to take some other actions, but the most important part of this
155 method is that it runs its default action, (its activation)
156 this method uses _deactivate as its implementation to maintain
157 the events order intact.
158 @property activate <public> [Function]
159 @method
160 @dispatch beforeDeactivatee
161 @dispatch deactivate
162 @return this [Widget]
163 **/
164 deactivate : function deactivate() {
165 if (this.__destroyed === true) {
166 console.warn('calling on destroyed object');
167 }
168 this.dispatch('beforeDeactivate');
169 this._deactivate();
170 this.dispatch('deactivate');
171 return this;
172 },
173
174 /**
175 Enable implementation method
176 if you need to provide a different procedure for enable
177 you must override this method and call "super"
178 @property _enable <private> [Function]
179 @method
180 @return undefined [undefined]
181 **/
182 _enable : function _enable() {
183 this.disabled = false;
184 this.element.removeClass('disable');
185 },
186
187 /**
188 Public enable method, this method should not be
189 overriden.
190 @property enable <public> [Function]
191 @method
192 @return this [Widget]
193 **/
194 enable : function enable() {
195 if (this.__destroyed === true) {
196 console.warn('calling on destroyed object');
197 }
198 this.dispatch('beforeEnable');
199 this._enable();
200 this.dispatch('enable');
201
202 return this;
203 },
204
205 /**
206 Disable implementation
207 @property _disable <private> [Function]
208 @return undefined [undefined]
209 **/
210 _disable : function _disable() {
211 this.disabled = true;
212 this.element.addClass('disable');
213 },
214
215 /**
216 Disables the widget, the idea behind disabling a widget
217 comes from DOM form elements. so following this idea
218 all widgets can be disabled and queried for its disabled
219 state via the disabled property.
220 Same as DOM form elements there is feedback and that is why
221 the default implementation sets the "disable" class
222 on the element so proper visual feedback can be provided
223 to the user.
224 @property disable <public> [Function]
225 @method
226 @return this [Widget]
227 **/
228 disable : function disable() {
229 if (this.__destroyed === true) {
230 console.warn('calling on destroyed object');
231 }
232 this.dispatch('beforeDisable');
233 this._disable();
234 this.dispatch('disable');
235
236 return this;
237 },
238
239 /**
240 Destroy implementation. Its main responsabilities are cleaning
241 all references to other objects so garbage collector can collect
242 the memory used by this and the other objects
243 @property _destroy <private> [Function]
244 @method
245 @return undefined [undefined]
246 **/
247 _destroy : function _destroy() {
248 var childrenLength;
249
250 if (this.element) {
251 this.element.remove();
252 }
253
254 if (this.children !== null){
255 childrenLength = this.children.length;
256 while(childrenLength > 0){
257 this.children[0].destroy();
258 if (this.children.length === childrenLength) {
259 this.children.shift();
260 }
261 childrenLength--;
262 }
263 }
264
265 if (this.parent) {
266 this.parent.removeChild(this);
267 }
268
269 this.children = null;
270 this.element = null;
271 },
272
273 /**
274 Destroy public method, this one should not be replaced
275 @property destroy <public> [Function]
276 @method
277 @return null [null]
278 **/
279 destroy : function destroy() {
280 if (this.__destroyed === true) {
281 console.warn('calling on destroyed object');
282 }
283
284 this.dispatch('beforeDestroy');
285 this._destroy();
286 this.dispatch('destroy');
287
288 this.eventListeners = null;
289 this.__destroyed = true;
290
291 return null;
292 },
293
294 /**
295 The render method is the mechanism by which you pass a widget from
296 living only on memory to get into the DOM and with this into the
297 application flow. The recomendation is that render is the last method
298 of the setup of a widget, including appending its children. this is
299 because once a widget gets renderer, further operations cause browser
300 reflows, and DOM operations are slower than memory operations.
301 This method shoudl not be replaced by its children.
302 @property render <public> [Function]
303 @method
304 @argument element <required> [JQuery] (undefined) This is the element
305 into which the widget will be appended.
306 @argument beforeElement <optional> [jQuery] (undefined) this is the element
307 that will be used as a reference to insert the widgets element. this argument
308 must be a child of the "element" argument.
309 @return this [Widget]
310 **/
311 render : function render(element, beforeElement) {
312 if (this.__destroyed === true) {
313 console.warn('calling on destroyed object');
314 }
315 this.dispatch('beforeRender', {
316 element : element,
317 beforeElement : beforeElement
318 });
319 if (beforeElement) {
320 this.element.insertBefore(beforeElement);
321 } else {
322 this.element.appendTo(element);
323 }
324 this.dispatch('render');
325 return this;
326 }
327 }
328});