UIZE JavaScript Framework

TO DO - Documentation

This document lists to do tasks relating to the documentation and Web site for the UIZE JavaScript Framework.

1. Doc Lint

Implement a doc lint / audit tool to assess quality of documentation according to the following criteria...

sections that are missing documentation (such as with a "document..." or "." placeholder
sections that are commented out (such as with "###" style comments)
ambiguous links (multiple sections with the same title)
dead links (to sections that don't exist or are commented out)
sections that have multi-sentence (or very long single sentence) first paragraphs
for modules, methods or properties that are introduced or overridden by the module and that have no documentation

2. Site Nav Left Pane

Remaining to do...

figure out how to get item text to wrap (there's currently a nobr tag around items)

3. Scroll to Top

Implement animated scroll-to-top feature (arrow can be near bottom left in main content region.

4. Add Search to Header

Add a general search input box on the right side (as is typical in sites).

5. Support External Code

Implement support for code that is external to the UIZE site.

When this feature is enabled / configured by a user of UIZE, it should provide the following benefits to the developer...

5.1. Module Reference Integration

5.1.1. - generated pages

reference page
TO DO document (if .todo file is present)
source code page

5.1.2. - links

source code page
unit tests
visual tests for V2 widgets
inline preview of visual sampler for V2 widgets

5.2. Presence in Tools

.

Dependency Analyzer
SOTU
UIZE Unit Tests
Widget Visual Tests
Widget Visual Samplers
DELVE

5.3. A UIZE Site Configuration

This can be viewed as a configuration for the UIZE Web site project, and not a general configuration for UIZE.

5.4. Implementation Considerations

.

it's worth thinking about whether there should be a one-namespace-per-project limitation, or whether the mapping should be deliberately handled in a different way to support multiple namespaces per project

5.4.1. Loading Modules in build.js

The build.js bootstrapping script must support loading modules from multiple paths, depending on the relative paths configured for the various external code namespaces.

5.4.2. Folder Organized Namespaces

Currently, the folder organized namespaces for a project are specified in the uize-config.json file for a project.

This implies that the build.js script would need to read the config files for all external code projects - currently the code assumes that there is a single config file. One possibility would be to move the folder organized namespaces configuration into a new file under the code folder and formalize support in uize-config.json for multiple code folders rather than just one.

Naturally, if you're pulling in code from multiple sources that may belong to other UIZE projects, you don't want to duplicate the folder organized namespaces config - you want to be able to retrieve that config from the external source folders.

5.4.3. File Builders

.

5.4.4. Module Lists

.

5.4.5. Build Configuration of External Code

.

modulesFolder
folderOrgNamespaces
headComments
scrunchedHeadComments
staticFilePathMatcher
modulesToStub

5.5. Implementation Approaches

5.5.1. Implement as a File Service Configuration

One possibility for implementing inclusion of external code might be providing a configuration capability in the file system service to allow the contents of various folders to be merged in.

With this approach, a configuration would be provided for the modules folder that would define multiple virtual sources. With this configuration in place, various methods would behave differently when dealing with paths under this folder's path. Specifically, listing folder contents would have to list the contents for the multiple folders and merge the results. Similarly, reading a file would have to try all the folders until the specified file is found in one of the folders.

5.5.2. Implement Using Symbolic Links

On operating systems that support symblic links, a temptingly simple approach would be to just implement the inclusion of external code using symbolic links.

5.5.2.1. Modules Folder to Contain Subfolders

In order to use symbolic links to implement this feature, it would be necessary to allow the modules folder to contain subfolders that would contain the code linked in from multiple sources.

The current assumption in the code is that all the code starts from the root of the modules folder, and the only provision for subfolders is with folder organized namespaces. In order to rely on folder organized namespaces, with symbolic links inside the modules folder to the various namespace folders of external project code, all namespaces would need to be purely namespaces and not code implementations inside JavaScript files. This is not currently true of the Uize namespace, because this namespace is defined by Uize.js.

It might be ok to have this be a limitation for now that would only apply for non-UIZE site projects if they wanted to use symbolic links to pull in the UIZE modules. But it wouldn't be a blocker for using this technique with the UIZE site and symblic linking in code from external projects.

5.5.2.2. No Windows Support

A downside of this approach is that it won't work on operating systems that don't support symblic links.

Basically, this would eliminate support for this feature on Windows.

5.6. Usage Considerations

.

5.6.1. UIZE Version Compatibility

.

5.6.2. File Builder Compatibility

.

6. Basic Wireframe Documentation for *ALL* Modules

Add at least a single line summary for every feature of every module.

This applies to...

instance methods
instance properties
static methods
static properties
state properties
DOM nodes (widgets)
instance events
static events
etc.

7. Improved Location of Source Code

For examples, modules, put source code into a peer folder, rather than child folder.

So...

examples/
examples-source-code/
reference
reference-source-code/
must add 301 redirect rules in .htaccess
must update .jst files that generate reference pages and source code pages, to link to correct places
must update examples to link to source code files correctly
must update search page to allow separate searching in source code folders
benefit: users can search only within source code, or only documents

8. Move Away From VARIATION N

For methods that support multiple variations, move away from the "VARIATION N" approach to listing those variations.

Instead, move to the newer "DIFFERENT USAGES" section, with descriptive use case oriented titles for the different usages and links to more detailed descriptions with examples.

9. JIT File Builder Web Server

Document the Web server functionality (under dev section initially) that is used by the UIZE Web site and that employs the same code as the build process.

10. Issues With Auto-generated Documentation

10.1. Function Type Static Properties Regarded as Static Methods

Static properties whose values are functions are regarded as static methods.

Perhaps in such cases such features should just get documented and referred to as static methods. In the future, however, it should be possible to register a feature as a static property, but where the type of the property can be function, through a formal feature declaration mechanism.

10.2. Extension Modules Mess Things Up

Documenting extension modules can mess things up.

Loading extension modules in the documentation build script in order to document them can have the side effect of modifying a class, and other modules that are subclasses of the modified class that are then documented later appear to have features that they really do not have, because they've inherited the features that were extended on their base class by loading and documenting the extension module.

10.3. State Properties With Object Initial Values Treated as Overridden

State properties whose initial values are objects or arrays are incorrectly indicated as having been overridden in a module that inherits the feature.

This is simply because the initial value in the subclass is a clone of the initial value in the base class and not a shared reference. The initial value is a clone because the whole property definition is a clone. Not sure what the solution is.

11. Finish "Creating a New UIZE Example Page" Guide

.

12. iPad issues

12.1. - outstanding

12.1.1. - all pages

share it panel is useless on iPad, because neither mouseover nor fixed positioning are supported

12.1.1.1. - performance

on doc pages, building of contents tree's DOM in JavaScript slows down page load, and also leaves page in unattractive state for too long. Suggest moving to building contents tree HTML as part of build script, and modify tree widget to be able to wire up prebuilt HTML (perhaps it already can do this)
rendering share it panel slows down page rendering, and it adds no value on iPad. Perhaps an alternate UI that defers the cost until the user wants to share a page would be a better approach.

12.1.2. - example pages

have to tap tour navigation buttons twice in order to navigate (first tap shows tooltip), which is annoying
navigating back leaves some pages in a state where dynamically rendered HTML is not re-rendered. You can see this in the pages that have lists of presets - they are rendered on arriving on the pages, but using the back button to go back to them leaves them in a broken state.

12.1.3. - misc

for example and module source code pages, width of pages causes titlebar to be tiny, since default is to scale page so there is no horizontal scrolling

13. Bugs

13.1. file:///C:/~uize/UIZE-JavaScript-Framework/examples/date-picker.html

initial values in text input all display as null

13.2. file:///C:/~uize/UIZE-JavaScript-Framework/examples/dialog-resizable.html

when resizing by dragging either the left or top edges, dialog repositions incorrectly after drag

13.3. file:///C:/~uize/UIZE-JavaScript-Framework/examples/slideshow-of-data.html

data bars don't have any space around them (has to do with IE8's handling of cellspacing attribute of table)
weird bug with slideshow with wipes, where if you navigate forward and then back (or vice versa), it starts coming up with bogus wipe effect settings. Is this a side effect of the code that picks a new random wipe each slide? Or is this a side effect of recent loop optimizations? Seems like it may have to do with the images for the various panes being cached. Maybe something about the load handler behavior. Doesn't seem reproducable at all when going straight through - regardless of direction. Flipping back and forth between two images, however, causes corruption of the effects.
FF: issue with ThumbZoom and horizontal scrolly in scrolly example - zooms out from pancaked sliver (could this be a result of changes in getCoordinates?)
IE7: Hover Fader Stretching Menu - weird flickering with some presets, screwy sticky shifting of entire menu with other presets

14. Doc Improvements

integrate module meta data into reference doc

14.1. - link references to static methods and properties (e.g. =Uize.clone=) to appropriate sections of reference documents

will need to settle on naming scheme for anchors for doc sections
will need ability to register custom linker function, so that the doc build script can provide this meta level intelligence about the documentation
tooltip behavior for linking to other documents in documentation

15. Build Process Improvements

script to insert UIZE version number into all script tags that source in the Uize.js file
write script to test for HTML pages with meta descriptions that are too long (more than 150 characters)

16. gzipping Text Files

Look into gzip'ing entire site (or enabling Apache's mod_gzip).

Add the following to the ".htaccess" file...

AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css application/javascript

BACKGROUND

http://httpd.apache.org/docs/2.0/mod/mod_deflate.html

17. Add Interview Questions

the matrix

17.1. - find smallest number

find the smallest number in an array of numbers, without using methods of the Math object (like Math.max or Math.min)
now, find the smallest number using a method of the Math object
does the candidate still use iteration? do they know about the Infinity value?
now, find the smallest number in a single statement
does the candidate know that Math.min can take an arbitrary number of parameters?
does the candidate understand how to use the call and apply methods of Function objects?

17.2. Brain Teaser / Interview Question

alert (blah);            // displays "Hello"
alert (blah + 'Brian');  // displays "Hello, Brian"

define blah

var blah = {};
blah.toString = function () {return 'Hello'};
blah.valueOf = function () {return 'Hello, '};

or...

var blah = new String ('Hello');
blah.valueOf = function () {return 'Hello, '};

or...

var blah = new String ('Hello');
blah.valueOf = function () {return this.toString () + ', '};

17.3. Interview question / brainteaser

optimize the following statement...

someCondition ? variableA - variableB : variableA
variableA - (someCondition ? variableB : 0)
variableA - someCondition * variableB        // works if someCondition is guaranteed to produce a boolean
variableA - !!someCondition * variableB      // works even if someCondition is not a boolean value

18. Optimization Tricks

18.1. Page Performance Optimization

put JavaScript only as early in page as is needed (at end of page, if possible)

18.2. Loop Optimization Approaches

Finish loop optimization approaches performance test.

write up explanation
list in directory
add entry in javascript optimization appendix

18.3. Conditional Expression Optimization

if (blah) doSomething ();   ==>  blah && doSomething ();
if (!blah) doSomething ();  ==>  blah || doSomething ();

18.4. Sacred Empty Object

.

18.5. Sacred Empty Array

.

19. Code Size Optimization

UIZE-specific: Leave State Property Initial Values undefined, where possible. don't define an initial value for a state property when it offers no benefit (especially if your code tests the property in its execution to protect against null or undefined values)
use slice instead of substring (or substr when just one parameter) method, wherever possible
omit parentheses after constructor when constructor doesn't take any parameters

19.1. - lazy assignment combined with conditional execution

if (!_param) _param = _lastValue;
if (_param) {
  // do stuff
}
_lastValue = _param;
if (_param || (_param = _lastValue)) {
  // do stuff
}
_lastValue = _param;

20. General Tips

20.1. How to test if a multi-line string contains any lines exceeding a specific length

function hasLineExceedingMaxLength (sourceStr,maxLength) {
  return new RegExp ('^.{' + (maxLength + 1) + ',}$','m').test (sourceStr);
}

20.2. How to create a copy of an array...

myArray.concat ();

20.3. How to split out the characters from a string into an array of characters...

myString.split ('');

20.4. How to double space the characters in a string...

myString.split ('').join (' ');

20.5. Testing if instance is of a certain class or object type

if (someInstance.constructor == SomeClass) {
  // ...
}

20.6. Testing if two instances are of the same class or object type

if (someInstance1.constructor == someInstance2.constructor) {
  // ...
}

20.7. Creating a fresh instance with same state

someInstance2 = someInstance1.Class (someInstance1.get ());
explain about layer library modules (as used by the UIZE Web site)

21. URLs to link to somewhere in docs

http://dean.edwards.name/weblog/2007/03/rules/

22. For Framework Developers

22.1. Documentation Style Guide

first paragraph at root of document, or first paragraph of first section of document should be no more than 150 characters (excluding SimpleDoc formatting characters). This is because this paragraph is used as the value for the meta description tag. In this paragraph, make careful use of words, with the mind to maximizing the value of the description. This is the first opporunity that the reader will have to glean what the document is discussing. Sum it all up, ideally, in a single sentence, touching on key themes that will capture the reader's attention and interest. This paragraph has to make a case for reading the document.

22.1.1. General

22.1.1.1. First Paragraph Should Summarize

Each section should start with a clear and concise, salient, in-a-nutshell declaration of what the section is about. This first paragraph should be able to stand alone, without requiring the subsequent paragraphs for it to make sense. The first paragraph

22.1.2. Module References

22.1.2.1. Defining Syntax

SYNTAX

resultTYPE = object.methodName (...);

SYNTAX

object.methodName (...);
talk about type indicating assignment variable only being to indicate type, optional because one can always discard the result of a method call, function call, or expression
Deprecating Features
Renaming UIZE Modules

22.2. - Creating a New Guide

Add an Entry to the Site Map

22.2.1. Announce the New Guide

refer to Announcing a New Development
Announcing a New Development
Registering New Developers
Registering New Contributing Organizations
Releasing a Build

23. New Guides

23.1. Services

Create an guide to explain the approach UIZE takes to services.

23.2. Conditions

Document the conditions system that is implemented in the Uize.Class base class.

23.3. Needs and Providers

Document the needs management system that is implemented in the Uize.Util.Needs class.

23.4. Ajax

specifying params
GET vs. POST
caching results
batching requests

23.5. JavaScript Mobile Development

23.5.1. - UIZE works in smart phones and other mobile devices with Web browsers that support JavaScript and other Web standards

typically, these are devices that support HTML5 and CSS3

23.5.2. - emphasize that UIZE file size is compact, and that features better suited to devices with more real estate, processing power, or memory need not be loaded in

provide examples: Uize.Fx, Uize.Fade.*, etc.
point to example widgets that run on Palm Pre and Apple iPhone

23.6. JavaScript Colors

animating colors
working with colors
color selector

23.7. Unobtrusive JavaScript

GLUE paradigm

23.7.1. - progressive enhancement

Uize.Widget.HoverFader
Uize.Widget.TableSort
code beside concept

23.8. Drag-and-drop

Uize.Widget.Drag (for drag handles)

23.9. Interfaces

The Value Interface
The ValueAndValues Interface
The ValueAndRange Interface
The ValueSelectorDialog Interface

23.10. Extending UIZE

23.10.1. - subclassing existing widget classes, or other classes

creating your own widgets
extension modules to extend classes or packages

23.10.2. - extending color support

defining new named colors
defining new color spaces (including encodings)

23.10.3. - extending Fx

adding new effects
supporting style properties

23.10.4. - adding support for communication protocols

creating Uize.Comm subclasses
implementing virtual DOM events

24. Search on Selected Text

for any content document, pop open search pop-up when selecting text (as long as text is not more than a certain max length, and does not contain linebreaks -- must make sure that this feature wouldn't be annoying, so perhaps only for documentation pages? Don't want to confuse this search feature with normal interaction with form fields).

25. Guide: JavaScript Localization

default localized strings (could be English)

26. Guide: JavaScript Libraries

26.1. - feedback from Ben

I read over the JavaScript Library Documentation and here are my suggestions:

I like the metaphor in the 1. Introduction section. When talking about the performance benefit of the libraries maybe using an actual real example (maybe the UizeSite.Page.Doc.library.js file?) of what the savings look like of one request versus many requests.
In the 2. Where They Live section, I think it'd be helpful to actually list where the default JavaScript modules folder is (both the source and built versions) just so someone reading can know exactly what you're referring to.
In the 3.1.2.3. Don't Require List Modules I understand what you're getting at in the paragraph about not requiring the modules so the onus is on the modules that actually need those modules to require them properly. I think what's confusing is that if you don't know how the framework works in "source-mode" (i.e. all the modules are loaded dynamically) then the paragraph seems pretty confusing. I think either it needs some examples of what you're trying to explain or at least a reference to the guide section that talks about the source-mode module loading
In 3.2 The Built Version I think you may want to play up the performance benefits mention in 1. Introduction about saving http requests because that's when the benefits come in (in the built version). Maybe here is where you can do an analysis using the UizeSite page widget library file (if not in the intro)
In 4. How To use Them it seems to me that the example in 4.1 Sourcing the Source Version looks the same as the example in 4.2 Source in the Built Version. This also got me thinking. In Zazzle we have a function that listens to a config entry as to whether to use the source JS. How does Uize.com (or any other site for that matter) determine which version to use? Most likely people will just copy what they developed locally to their website. Maybe a suggestion on how to implement that in the Build Scripts guide (I did a cursory search and didn't find anything) would help
It seems that the paragraph in 4.3 Requiring a JavaScript Library sort of explains what I was just talking about, although I still don't see how the module loading mechanism knows to use the built version of the modules. Is that because the script tag sourcing of the Uize.js module would be changed to point to the built version (and thus the module loading mechanism knows where to find the rest)?
I think an example of what you mean in 7.1. Pages Should Always Work Without Libraries would be nice

Looking at all my suggestions, I think I understand now where my confusions lie. In some regards I'm a visual learner so I like to see things rather than just read or hear them. So for the more tricky explanation, an example of what you're talking about would clear things up for me. Towards the end of the guide it seems that you talked about some of the things I was mentioning earlier on the guide, so maybe some well-placed links to further in the document might help as well.

But overall after reading the guide, I think you really need to beat the developer over the head as to why library files are useful. There's all this explanation of how they were and some dancing you have to do, but only a little bit on why you would actually use them.

26.2. - feedback from Tim

26.2.1. General:

The word “page” is used primarily to describe the environment in which Uize operates, but using the word “application” would suggest that Uize is able to work in more diverse environments than just a web browser. Of course, using “application” would confuse people who aren't used to thinking about javascript as anything more than a web-scripting tool.

More emphasis on how libraries are an optimization, and that the application should be able to chug along if the libraries were stripped from it. I'd personally use some analogy about how the modules are like Captain Kirk and Spock, while the libraries are Red-shirt Ensign #3. If the Ensign is killed, the mission should still succeed.

26.2.2. Where They Live:

Doesn't using the extension .library.js remove an entire range of possible names for js files? Could .jsl be appropriate?

26.2.3. 3.1

Point out that, in source, absolutely nothing happens if the Library Contents comment is all that is in the library file. People might wonder if there's a special mechanism within Uize to parse the comment and load the js classes using the module loader.

26.2.4. 3.1.2.3

The paragraph about not requiring modules that are listed in a library module is unclear. This would be my re-write:

“The source version of the library module, if consisting solely of the Library Contents comment, will not load any modules, thus forcing the other modules in the application to load their required lists (which may include modules listed in the library). This mechanism allows any errors in the modules' required lists to be revealed while running in source. By requiring the modules in the library file that are listed in the Library Contents comment, this mechanism will be hidden.”

26.2.5. Real World Examples

Add Zazzle?

26.2.6. 7.1

A gentle reminder of how multiple module declarations of the same module won't lead to multiple requests might be helpful

27. Guide: JavaScript Modules

27.1. Uize.module -> Parameters -> required

27.1.1. Order Unimportant

It's worth mentioning and explaining why order is not important in the required list

27.1.2. Requiring Extension Modules

Because they extend namespaces, how do you know from the code if you need them? Yes, it's a little trickier.

27.2. Multiple Consecutive Module Declarations

You can have multiple consecutive module declarations that share common required modules and things will work correctly, rather than some of the required modules being loaded multiple times (which would cause all sorts of problems with modules stomping over themselves when re-declaring themselves and thereby crippling code).

EXAMPLE

Uize.module ({
  name:'MyNamespace.Module1',
  required:'Uize.Widget',
  builder:function () {
    alert ('build the first module');
  }
});

Uize.module ({
  name:'MyNamespace.Module1',
  required:'Uize.Widget',
  builder:function () {
    alert ('build the second module');
  }
});

The first module being declared requires the Uize.Widget module. If this module is not already loaded, then the module loader mechanism will load it asynchronously. The second module declaration occurs immediately after the first (because this code is synchronous), and it also requires the Uize.Widget module. A second request to load this required module externally is not made, because the module loader mechanism knows that loading of the module is already in progress.

27.3. Named Inline Module Required By Subsequent Anonymous Inline Module

You can have an inline module declaration that requires other external modules, and subsequent inline module declarations that require that first module will correctly wait until it is built - rather than trying to load it externally

EXAMPLE

Uize.module ({
  name:'Uize.MyInlineModule',
  required:'Uize.Widget',
  builder:function () {
    alert ('build Uize.MyInlineModule');
  }
});

Uize.module {{
  required:'Uize.MyInlineModule',
  builder:function () {
    alert ('build the anonymous module that requires Uize.MyInlineModule');
  }
});

The Uize.MyInlineModule module may not be built yet when the second, anonymous module is declared because Uize.MyInlineModule requires the module Uize.Widget that may not yet be defined and may have to be loaded asynchronously. Now, when the anonymous module is declared, the module loader mechanism doesn't try to load Uize.MyInlineModule externally even though it is not yet defined, because it knows that this required module is in the process of being defined.

discuss Uize.moduleUrlResolver

27.4. Document Inner Classes

Document the pattern of creating inner classes.

27.4.1. Private Inner Classes

Push dependencies of inner class(es) into required list of host class or module.

EXAMPLE

Uize.module ({
  name:'MySite.MyClass',
  required:[
    'MySite.Widget',  // required as base class of inner class
    'Uize.Data'       // required for inner class
  ],
  builder:function () {
    /*** create the inner class ***/
      var _MyInnerClass = MySite.Widget.subclass ();
      // code here to further create the inner class

    /*** build the class ***/
      // code here to build the main class for the module
  }
});

27.4.2. Public Inner Classes

Don't do them, because they're too problematic.

27.4.3. Can't Have Inner Subclasses

Because the inner subclass would require the host module as its base class, and it would not be built before trying to declare the module for the inner subclass.

28. Miscellaneous

28.1. Novel map Method

Uize.map (30,'key > 1 ? this [key - 2] + this [key - 1] : key')

Can't do this with JavaScript 1.6's map method (or the map methods in any other framework), because the map function can't reference the newly created target array.

29. XHTML Validation Problems

When running the UIZE documentation pages through an XHTML validator to test for well-formedness, the following problems are revealed...

"JavaScript Templates" guide has issue with "<%" and ">" chars not being entities. This is a problem for SimpleDoc in general.
for all pages when run locally, need default style language

29.1. - for pages delivered by server, no char encoding specified in response headers (refer to zazzle.com response headers)

29.2. - script tags with inline code should really have...

<!--
// -->

30. Design Philosophy (some ramblings)

DOM node related methods implemented in Uize.Widget are a reflection of static methods from the Uize.Dom.Basics package that are the most useful and frequently used in the context of widget implementations. If you need to use more esoteric methods, you can access those from the Uize.Dom.Basics package and use the getNode instance method to get references to DOM nodes to supply to the methods of the Uize.Dom.Basics package.

UIZE takes the approach of exposing abstractions for things for which it is useful to provide abstractions. Beyond these useful abstractions, UIZE does not attempt to provide a comprehensive abstraction of all DOM APIs. There's nothing wrong with using safe and consistently implemented methods of the standard DOM APIs.

31. Site & Documentation (in order of priority)

31.1. - go through all documentation pages and see what tooltips show up for the contents tree links. Make sure all sections have a concise introductory first paragraph.

possibly write a build script to find documents with first paragraphs for sections that are long or contain multiple sentences (non-period, following by period, followed by space)

31.2. UIZE Comparison With Other Frameworks

In discussion of UIZE, WRT how UIZE compares to other frameworks.

31.2.1. Discuss convenience iterators...

Uize.callOn
Uize.doForAll
Uize.Comm.processArrayAsync

31.3. Thoughts on Good Design

A feature can be a side effect of an implementation by design.

In other words, an elegant design can have the intention of producing positive side effects. From a certain perspective, it might seem purely lucky or fortuitous that certain good things fall out of a particular implementation choice. But a good designer has their mind tuned to deliver positive knock-on effects from their design choices.

32. Overview

mention Uize/uize/UIZE namespace considerations for developers

33. For All Examples

33.1. Add Explanation Copy

C:/~uize/UIZE-JavaScript-Framework/examples/hierarchical-selector.html
C:/~uize/UIZE-JavaScript-Framework/examples/two-hierarchical-selectors.html
C:/~uize/UIZE-JavaScript-Framework/examples/button-toggle.html
for examples that should wait until all images are loaded (e.g. sequenced show), for now use Uize.Widget's "Document Loaded" event as a proxy for detecting that state

34. Performance Test Pages

34.1. Migrate Non-browser Performance Tests

For all environment agnostic (i.e. non-browser) performance tests, migrate the tests from being dedicated HTML pages to being true tests using the Uize.Test class, under the Uize.Test.Performance namespace...

C:/~uize/UIZE-JavaScript-Framework/site-source/tests/performance/declared-function-vs-function-object.html
C:/~uize/UIZE-JavaScript-Framework/site-source/tests/performance/extended-string-class.html
C:/~uize/UIZE-JavaScript-Framework/site-source/tests/performance/global-eval-approaches.html
C:/~uize/UIZE-JavaScript-Framework/site-source/tests/performance/is-string-one-of-possible-values.html
C:/~uize/UIZE-JavaScript-Framework/site-source/tests/performance/loop-optimization-approaches.html
C:/~uize/UIZE-JavaScript-Framework/site-source/tests/performance/regexp-compile.html
C:/~uize/UIZE-JavaScript-Framework/site-source/tests/performance/regexp-test-vs-search.html
C:/~uize/UIZE-JavaScript-Framework/site-source/tests/performance/repeat-string-approaches.html
C:/~uize/UIZE-JavaScript-Framework/site-source/tests/performance/reused-object-vs-garbage-collected.html
C:/~uize/UIZE-JavaScript-Framework/site-source/tests/performance/storing-length-for-iterator.html
C:/~uize/UIZE-JavaScript-Framework/site-source/tests/performance/storing-reference-to-subobject.html
C:/~uize/UIZE-JavaScript-Framework/site-source/tests/performance/string-concatenation-approaches.html
C:/~uize/UIZE-JavaScript-Framework/site-source/tests/performance/string-match-conditional-styles.html
C:/~uize/UIZE-JavaScript-Framework/site-source/tests/performance/string-starts-with-substring-styles.html
C:/~uize/UIZE-JavaScript-Framework/site-source/tests/performance/string-to-literal.html
C:/~uize/UIZE-JavaScript-Framework/site-source/tests/performance/string-trim-functions.html
C:/~uize/UIZE-JavaScript-Framework/site-source/tests/performance/testing-if-string-approaches.html
C:/~uize/UIZE-JavaScript-Framework/site-source/tests/performance/testing-object-for-type-marker.html

As true tests, they will show up in the unit tests page.

34.2. Improvements to HTML Page Performance Tests

For performance tests that can't be migrated to using the unit test system, make the following improvements...

add description copy

34.2.1. - improve test framework, so that...

34.2.1.1. - each individual test can specify its title, so that...

generating the report is easier
the user can know what test is currently being performed

34.2.1.2. - give better status updates, so that...

the user knows when a wait is happening
the user knows what test is currently being performed
the user can see the results as they come in
have a non-animating progress bar that indicates how far along the user is through the tests

35. New Examples to Create

35.1. Uize

35.1.1. - Changed.* event

an example that demonstrates the Changed.* event
a widget that updates a lot of state properties during user interaction
a log pane that fills with notifications of state properties changed during user interaction
possibly a listing (to the right of the widget) of all the widget's state properties, with the most recently changed properties highlighted in red and bolded

35.2. - Color Gradients

demonstrates use of Uize.Fx.fadeStyleAcrossNodes
demonstrates use of different curve functions for different color components
should have ability to select color for both ends of gradient

35.3. Uize.Color.xUtil

35.3.1. - Color Theme Transformation

an example that takes a set of colors and provides various controls for transforming the colors in the color theme
a live preview of the theme is updated in realtime as the theme is transformed
a variety of preset color themes as starting points

35.3.1.1. - ability to...

35.3.1.1.1. - change hue
reduce range
shift (with shift mode = "wrap", "constrain", "align")
35.3.1.1.2. - change saturation
reduce range
shift (with shift mode = "wrap", "constrain", "align")
35.3.1.1.3. - change lightness
reduce range
shift (with shift mode = "wrap", "constrain", "align")

35.4. Uize.Data.Csv

CSV-to-JSON / JSON-to-CSV converter

35.5. Uize.Fade.xFactory

an example that illustrates animating the opening of a popup browser window for displaying help topics

35.5.1. - an example that illustrates animating the positioning of the browser window

top left, top center, top right
center left, center center, center right
bottom left, bottom center, bottom right

35.6. Uize.Fx.fadeStyle

35.6.1. - an example that demonstrates fading of many different CSS style properties

35.6.1.1. - layout...

left side has playground area
35.6.1.1.1. - right side has vertically scrolling list of fade operations, below which is...
a text field where selected operation is editable
a button for performing the current edited operation

35.6.1.2. - stuff to demo

moving an object
fading an object's size
fading position and size
fading position and size and properties
I'm feeling lucky (where many properties are randomized)
a reset
fading an object's font-size

35.7. Uize.Widget.Collection

movie queue sorter (ala Netflix)

35.8. Uize.Widget.Dialog.Iframe

a demo that loads an example into a resizable iframe dialog

Uize.Widget.EggTimer

35.9. Uize.Widget.FormElement

a vanilla widget that has a bunch of Uize.Widget.FormElement instances as child widgets
a checkbox for changing the enabled state of the form widget
a checkbox for changing the busy state of the form widget
spans / divs alongside form elements for displaying current value
hook into Changed.value event for each element to update display of current value

35.9.1. - form elements

text input
checkbox
radio buttons
select (single)
select (multiple)
all form element nodes to have labels (for radio buttons, a label per radio)

35.10. Uize.Widget.Options

35.10.1. - dynamic options, with more elaborate HTML

image selector UI, where each selector has thumbnail, title, rating
values uses object form
displayName property (rather than name) is used in JST template for displaying title
example with animating arrow pointing to selected option, with elastic motion
possible trail of ghosted arrows, delayed behind main arrow

Uize.Widget.Stretchy

35.11. Uize.Widget.Scrolly

new demo to show how scrolly could be used simply to scroll a regular block of HTML (a div with scrollbar)
a scrolly combined with an options widget for pagination

Uize.Widget.Options.Accordion

35.12. Uize.Dom.Basics.injectHtml

migrate existing test from functionality test and add explanation
create interactive example that lets you add things in different places

35.13. Uize.Widget

Declarative Syntax for Properties
mouserest Virtual Event

Uize.Widget.Committer

35.14. Uize.Widget.Page

35.14.1. Widget Adoption by Page Widget

declarative syntax for page's child widgets

35.15. Uize.Widget.TableSort

example showing how multiple table are made sortable with a single spawning declaration

Uize.Tooltip

Uize.Widget.Options.Popup

Uize.Widget.Committer

35.16. Form Validation

Uize.Validator

Uize.Widget.FormElement

Uize.Comm.Ajax

35.17. Uize.Widget.Tree.List

example with different icon themes
example of tree generated from document

35.18. Transferring Form Field Values

an example with two columns of identical form fields, a bunch of different types of form fields in each column, with a different form field per row
for each row, arrows exist between the two columns to transfer the values from one side to the other
the example demonstrates how easy it is to tranfer a value from form field to another using the getNodeValue and setNodeValue methods, and also tests that there is parity between these two methods

36. SIMPLE-based Presentation Tool

lightweight, quick to create presentations

37. Things to Add to Documentation

trademark & copyright notices

37.1. - more endorsements

GIT/github

37.1.1. - Firefox

Tamper Data
DustMe Selectors
YSlow

37.1.2. - for IE

Fiddler
DevToolBar for IE
Windows Script Host

38. Comparison of UIZE Widgets Versus Other Frameworks

38.1. Example 1

Taken from http://ruoyusun.com/2013/08/24/a-glimpse-of-angularjs-scope-via-example.html...

38.1.1. The Angular Approach

HTML TEMPLATE

<div ng-controller="MenuCtrl" ng-app="App">
   <button ng-click="showMenu = true">Show Menu</button>
   <div ng-show="showMenu">
      <input type="text" focus-if="showMenu">
   </div>
</div>

JAVASCRIPT

app = angular.module('App', []);
app.controller('MenuCtrl', function () {});
app.directive('focusIf', [function () {
   return function focusIf(scope, element, attr) {
      scope.$watch(attr.focusIf, function (newVal) {
        if (newVal) {
           scope.$evalAsync(function() {
              element[0].focus();
           });
        }
      });
   }
}]);

38.1.2. The jQuery Approach

HTML TEMPLATE

<div>
   <button id="show-menu">Show Menu</button>
   <div id="menu">
      <input type="text" class="to-focus">
   </div>
</div>

JAVASCRIPT

$(function(){
   $('#show-menu').click(function() {
      $menu = $('#menu');
      $menu.show();
      $menu.find('input.to-focus').focus();
   });
});

Issues with this jQuery implementation...

not expressed as a plug-in, so not designed for re-use (therefore, shorter than it would be)
not designed for multi-instantiation, because of use of non-namespaced IDs
The Uize Approach (ideal version)

  HTML TEMPLATE
  ............................................
  <div>
     <button id="showMenu">Show Menu</button>
     <div id="menu">
        <input id="menuText" type="text">
     </div>
  </div>
  ............................................

  JAVASCRIPT
  ................................................................
  var MenuClass = Uize.Widget.V2.subclass ({
    stateProperties:{
      menuShown:{value:false}
    },
    htmlBindings:{
      menuShown:['menu:[shown]','menuText:[focused]']
    },
    eventWirings:{
      showMenu:{click:function () {this.set ('menuShown',true)}}
    }
  });
  ................................................................

The Uize Approach (current)

  HTML JST TEMPLATE
  ............................................................
  <div id="<%. idPrefix %>">
     <button id="<%. idPrefix %>-showMenu">Show Menu</button>
     <div id="<%. idPrefix %>-menu">
        <input id="<%. idPrefix %>-menuText" type="text">
     </div>
  </div>
  ............................................................

  JAVASCRIPT
  ................................................................
  var MenuClass = Uize.Widget.V2.subclass ({
    stateProperties:{
      menuShown:{value:false}
    },
    htmlBindings:{
      menuShown:['menu:[shown]','menuText:[focused]']
    },
    eventWirings:{
      showMenu:{click:function () {this.set ('menuShown',true)}}
    }
  });
  ................................................................

xample 2
Taken from [[http://www.adobe.com/devnet/html5/articles/angularjs-directives-and-the-computer-science-of-javascript.html]]

The Angular Approach

  HTML TEMPLATE
  .............................................................................................
  <div>
    <marquee ng-click="edit()" ng-hide="editMode" scrollamount="100%" ng-transclude></marquee>
    <input type="text" ng-show="editMode">
  </div>
  .............................................................................................

  JAVASCRIPT
  .........................................................................
  // add a namespace for custom directives
  angular.module('mydirectives', []);

  angular.module('mydirectives').directive('blink', function() {
    return {
     restrict: 'E',
     transclude: true,
     templateUrl: 'views/blink.html',
     link: function(scope, element, attrs) {

      // select the needed DOM elements from the template
      var marquee = element.find("marquee");
      var input = element.find("input");

      // attach a blur event to the input
      input.bind('blur', function() {
        scope.$apply(function() {
         // exit edit mode
         scope.editMode = false;
         // update the text of the marquee
         marquee.text(input.val());
        });
      });

      // edit mode boolean controls the visibility of the blink and input
      scope.editMode = false;
      // called when the marquee tag is clicked
      scope.edit = function() {
         scope.editMode = true;
         input.val(marquee.text());
      };
     }
    };
  });
  .........................................................................

The Uize Approach

  HTML TEMPLATE
  .......................................................
  <div>
    <marquee id="marquee" scrollamount="100%"></marquee>
    <input id="edit" type="text">
  </div>
  .......................................................

  JAVASCRIPT
  ....................................................
  var EditableBlinkWidget = Uize.Widget.V2.subclass ({
    stateProperties:{
      blinkText:{value:''},
      editMode:{value:false}
    },
    htmlBindings:{
      blinkText:['marguee','edit:value'],
      editMode:['marquee:[hide]','edit:[show]']
    },
    eventBindings:{
      marquee:{click:this.set ({editMode:true})},
      edit:{
        blur:function () {
          this.set ({
            blinkText,this.getNodeValue ('edit'),
            editMode:false
          });
        }
      }
    }
  });
  ....................................................

SON Format for HTML

OBJECT FORM

38.1.3. {

tag:tagNameSTR,

attr:attributesOBJ,

children:childNodesARRAY

tag:'div',

38.1.3.1. children:[

{tag:'marquee',attr:{id:'marquee',scrollamount:'100%'}},

{tag:'input',attr:{id:'edit',type:'text'}},

]

}

EXAMPLE

}

Array Forms
  ARRAY FORM - TAG, ATTRIBUTES, CHILDREN
  ............................................................................................
  [tagNameSTR,attributesOBJ,childNodesARRAY]  // tag, with attributes and children specified
  [tagNameSTR,attributesOBJ]                  // tag, with attributes specified
  [tagNameSTR,childNodesARRAY]                // tag, with children specified
  [tagNameSTR]                                // tag, with no attributes or children specified
  [attributesOBJ]                             // div tag, with attributes specified
  [childNodesARRAY]                           // div tag, with children specified
  ............................................................................................

EXAMPLE

38.1.4. ['div',[

['marquee',{id:'marquee',scrollamount:'100%'}],

['input',{id:'edit',type:'text'}]

]]

imple Format for HTML

38.1.5. div

marquee: id=marquee scrollamount=100%

input: id=edit type=text

38.1.5.1. marquee

@id: marquee

@scrollamount: 100%

38.1.5.2. input

@id: edit

@type: text


			
			
ownsides of HTML Templates Being Pure HTML

Control Flow
  How does one do repetition or conditionals?

Inline Functions
  How important are functions, and how would they be supported?

Subclassing Templates
  How does one extend a widget superclass' HTML?

Child Widgets
  How does one do child widgets?

  Some form of custom tags...

  ............................
  <div>
    <slider id="sliderRed"/>
    <slider id="sliderBlue"/>
  </div>
  ............................

  A standard =widget= tag with =type= attribute...

  ...........................................
  <div>
    <widget id="sliderRed" type="slider"/>
    <widget id="sliderGreen" type="slider"/>
    <widget id="sliderBlue" type="slider"/>
  </div>
  ...........................................

  Type attribute does not need to be specified if the child widget is created in the JavaScript.

  .............................
  <div>
    <widget id="sliderRed"/>
    <widget id="sliderGreen"/>
    <widget id="sliderBlue"/>
  </div>
  .............................

Arbitrary JavaScript
  How does one use any other JavaScript code in construction of templates?

  Perhaps for the pure HTML template approach, JST format JavaScript code is pre-processed in the same way as CSS, before the template HTML is parsed.

urning HTML and Bindings Into Template Function
- parse HTML into object representation
- translate bindings into structure modifiers
- re-serialize object representation of HTML, replacing all dynamic sections with expressions to form a single concatenation expression

arsing HTML
- states
  - in open tag
    - in tagName
    - in attribute
      - in attribute name
      - in attribute name/value delimiter
      - in attribute value
  - in close tag
  - in tag contents
  - in text
  - in comment

erializing to HTML
All dynamic sections are replaced with expressions to form a single concatenation expression.

For =widget= tags, serialize to expression that calls =childHtml= method, where values of attributes are provided as values for state properties.

Serializing Child Widgets
  what about child widgets where the values for some properties need to, themselves, be child widgets?

  .........................................
  <widget type="boxWithHeading">
    <heading>This is the heading</heading>
    <body>
      <widget type="foo"/>
    </body>
  </widget>
  .........................................