Example Form for review

[Mingfai]

hi,

There are a couple of issues about the examples we got:

1. each example has a piece of JavaScript and a code block for display separately, it against the DRY principle
   
   
2. given we do a lot of DOM transformation, i personally found a need to see how actually the fields transform the HTML DOM. I used to rely on firebug to check example by example. But it's not easy as the DOM is manipulated dynamically in runtime.
   
   For progressive enhancement, I expect we have to break the rendering process to two steps clearly. The first step to get a set of required HTML DOM ready. The 2nd step to apply additional JavaScript rendering logics. Ideally, the examples should show the original DOM or the rendered result of step 1, and also the ultimate rendered result, and hopefully the dynamically changed result. (e.g. when u change some values and triggered validation error message, the DOM is changed after the first rendering) For sure we don't need to display everything at the beginning, they could be hidden and display only after user click on a button/link.
   
   
3. when there are lots of example on a page, we want to mange them better. e.g. generate a TOC, show in a tabview instead of list them on a page.
   http://javascript.neyric.com/inputex/examples/string_field.html
   
   
4. Currently, the common style is to list the HTML element on the top, and all JavaScript at the bottom. It's not easy to track the usage.
   
   
5. For the example to be most useful to the users, I would be good if they could change the example easily and get the rendered result. Similar to the examples on w3schools.
   

I'm working on putting any example in a standard format, and a "util" to render the examples. Please find the initial work at:
http://mingfai.ma.googlepages.com/example_template.html

in short:

• we put the JavaScript in one piece only. It's as a JavaScript string for now. And will be 'copied' to the <pre> tag for highlight. I'm actually thinking about reversing the position, i.e. the master JavaScript be put at the <pre> tag, or use a textarea and YUI Editor for editing. Anyway, at some point, the example script has to be in the form of JavaScript string, and will be evaluated.
  
  
• for every example, you'll see 5 elements now. 1 set of textual info,  1 demo box, and 3 syntax highlight box. The first syntax highlight box is for the demo JavaScript, the 2nd is for showing the HTML DOM before the progressive enhancement (it won't work now as our field doesn't support progressive enhancement, and it looks for a 'renderDOM' method to decide if it support progress enhancement), the last box is the ultimate rendered result, that is simply the innerHTML of the demo area.
  
  

The util is for the following issue:  http://code.google.com/p/inputex/issues/detail?id=99 . In the future it will probably be named as ExampleForm (or InputExExampleForm) as the whole stuff is a form in our concept. I gave it a nick name of 'inputEg' right now! :-)

Let me know if you have any comment on this topic. Thank you.


Regards,
mingfai