11# WuiDom
2-
3- ## Motivation for WUI
4-
5- Wizcorp UI (hereafter referred to as 'WUI') is a series of UI elements that were created to minimize
6- programmer interaction with the DOM and eliminate the need for programmers to create HTML.
7- Here at Wizcorp, we make single-page applications that often have many thousands of lines of
8- generated HTML. Therefore, even a single DOM query can be very slow, resulting in an unacceptably
9- slow user experience. WUI allows the programmer to create HTML elements while minimizing
10- interaction with the DOM, and maintain fine-level control over exactly when, where and in what
11- manner data is displayed and how events are handled.
12-
13- WUI also allows for simple interaction with Tomes, another Wizcorp API, to allow DOM elements to be
14- updated whenever the underlying data associated with them changes. This is useful for such things as
15- validation, real-time data display and for asynchronous processing. By fully leveraging the
16- non-blocking nature of Node.js, WUI will perform nearly real-time updating of data and allow the
17- programmer to avoid DOM calls, have more compact code and allow for more reusable user interface
18- components.
2+ [ ![ Circle CI] ( https://circleci.com/gh/WizUI/WuiDom/tree/master.svg?style=svg )] ( https://circleci.com/gh/WizUI/WuiDom/tree/master )
193
204## What WuiDom is
215
22- WuiDom is the base object of the WUI system. It represents the smallest unit of programmatic logic,
6+ WuiDom is the base object of the [ WizUI ] system. It represents the smallest unit of programmatic logic,
237an object corresponding to an underlying HTML element and that associated data (including, but not
248limited to, a Tome), events and other properties. WuiDom allows the programmer to keep a reference
259to generated elements (if desired) or to create throw-away elements. A simple function can create a
2610generic UI template or create a custom view. Because WuiDom inherits from EventEmitter,
27- programmer-defined events can be conditionally emitted and handled by WUI or other modules.
28-
29- ## WUI Components
30-
31- One of the major goals of WUI, aside from reducing interaction with the DOM, is to enable developers
32- to create re-usable user interface components, common behaviours and reusable views. When creating
33- WUI components, please try to keep that goal in mind. The ideal WUI component can be used on many
34- views and ideally that means to not making too many assumptions about the underlying data or the the
35- business logic of the game.
36-
37- Below is a partial list of the existing WUI components, and what their primary functions are:
38-
39- ### WuiButton
40-
41- You can read the WuiButton documentation [ here] ( https://github.com/Wizcorp/wui-button ) .
42-
43- ### WuiView
44-
45- You can read about the WuiView documentation [ here] ( https://github.com/Wizcorp/wui-view ) .
46-
47- ### WuiImage
48-
49- You can read more about the WuiImage documentation [ here] ( https://github.com/Wizcorp/wui-image ) .
11+ programmer-defined events can be conditionally emitted and handled by [ WizUI] or other modules.
5012
5113### Creating a new WuiDom element
5214
@@ -98,7 +60,7 @@ The result is a new child element is immediately inserted as the last child of p
9860Please note that this method is the preferred way to create new WuiDom elements.
9961
10062The createChild method takes an HTML tag name (such as 'input', 'label', 'div' or so forth)
101- and a list of associated options. WUI created an underlying rootElement (discussed at length below)
63+ and a list of associated options. [ WizUI ] created an underlying rootElement (discussed at length below)
10264and appends the element as the last child element of the parent (caller) element.
10365
10466An options element can contain numerous keys that are used by WuiDom to create the HTML element.
@@ -116,9 +78,9 @@ In the above example, the code assumes parentElement already exists and is also
11678(see above for creating the first WuiDom object in your code!). Here we create an input tag
11779(could just as easily be a 'div' or 'button'.)
11880
119- WUI reads the options object next, and creating a child text-node based on the user-supplied 'text'
81+ [ WizUI ] reads the options object next, and creating a child text-node based on the user-supplied 'text'
12082option, in this case using 'Example' for the text. It then applies the style and class name.
121- Finally, WUI will add each attribute specified by the keys in the 'attr' object. The resulting
83+ Finally, [ WizUI ] will add each attribute specified by the keys in the 'attr' object. The resulting
12284HTML markup can be seen below:
12385
12486``` html
@@ -414,11 +376,11 @@ onchange, onclick and others.
414376
415377##### allowDomEvents
416378
417- The allowDomEvents function can be called from any WuiDom element, in order to tell WUI that
379+ The allowDomEvents function can be called from any WuiDom element, in order to tell [WizUI] that
418380the element will listen for DOM events. The correct syntax for DOM events is 'dom.event'.
419381Therefore the change event would be emitted as 'dom.change'.
420382
421- Note that by default, DOM events are **not** propagated through WUI . **This method must be
383+ Note that by default, DOM events are **not** propagated through [WizUI] . **This method must be
422384called in order to enable DOM events on a WuiDom object.**
423385
424386##### Example
@@ -440,20 +402,20 @@ playerXPElement.on('dom.change', function() {
440402` ` `
441403
442404In this example, we create a WuiDom element called playerXPElement.
443- The function call to allowDomEvents tells WUI that the element that wants to consume DOM events.
405+ The function call to allowDomEvents tells [WizUI] that the element that wants to consume DOM events.
444406In the final line, we tell the element to run the function every time the dom.change event is fired.
445407
446408When the method runs, it will check to see if the player has gained a level, and then
447409possibly display an animation. If the player levels up, an event called levelUp is emitted.
448- This is just one example of how events might be used with WUI . Please see [here][0] for a list of
410+ This is just one example of how events might be used with [WizUI] . Please see [here][0] for a list of
449411DOM events.
450412
451413[0]: https://developer.mozilla.org/en-US/docs/DOM_Client_Object_Cross-Reference/DOM_Events
452414
453415### Operations on a WuiDom element
454416
455417WuiDom supports a number of functions that can be used to interact with the underlying element,
456- even after the element has already been added to the DOM. One primary purpose of WUI , is to allow
418+ even after the element has already been added to the DOM. One primary purpose of [WizUI] , is to allow
457419these operations to be performed without having to pay the cost of an inefficient DOM lookup every
458420time we wish to run a command.
459421
@@ -671,3 +633,5 @@ Calling the method:
671633` ` `
672634childElement .replaceClassNames ([' unread' ' read' ' stroke'
673635` ` `
636+
637+ [WizUI]: http://wizui.github.com "WizUI"
0 commit comments