Bug 248418

I am going to describe the plan for inception review at
http://wiki.netbeans.org/HtmlUIForTemplates

Created attachment 150293 [details]
wizardchome.html showing how a wizard skeleton around a wizard content could look like in a browser

Guys, can we start an inception review for this enhancement? Please see the associated wiki page and leave your comments here.

Can we meet on Dec 2, 2pm? I'd like the reviewers to be Jaroslav Havlín, Tomáš Zezula, Svatopluk Dědic and Toni Epple. Prague will meet in Giza. I'll provide the call in info before the meeting.

Any comments?

I would prefer some solution that does not depend on global element ids (if possible).
Reusing the wizard would be easier then, as there would be no risk of id conflict.

Ideas
 - Possibility to set step id and step display name in the template
 - Avoid need to list steps in both model and template
 - Separate models for data and for controls (current step, validations)
 - Would some support for progress bar make sense?
 - Is some support for internationalization needed?

We can also consider template format similar to some JQuery plugins.
Example:

<div class="someEmbeddableSelector">
    <h1 data-step="init">Initial Page</h1>
        <section>
        <p>
        JavaScript will ask you few questions about your mood.
        </p>
    </section>

    <h1 data-step="info">Query Page</h1>
    <section>
        <p>
        Is everything OK?
        </p>
        <input type="checkbox" data-bind="checked: ok"/>
        <p>How do you feel?
        </p>
        <input type='text' data-bind="value: msg"/>
    </section>

    <h1 data-step="summary">Summary Page</h1>
    <section>
        <p>
        You are feeling <span data-bind="text: msg"></span>!
        </p>
    </section>
</div>

Notes from inception review:

TCR: Avoid knockout templates, use data-step approach.
TCR: Filter control data
TCR: Support for progress bar
TCR: Do not depend on JavaFX

TCA: Prepare TCK (Technology Compatibility Kit)

> TCR: Do not depend on JavaFX

Addressed in
https://hg.netbeans.org/ergonomics/rev/6576fe363d45
now there is api.templates and templatesui module connected via org.netbeans.api.templates.wizard token.

> TCA: Prepare TCK (Technology Compatibility Kit)

This is the way to write new TCK tests:
http://hg.netbeans.org/ergonomics/rev/c2fce646315b
A test is composed from an HTML page, initialization code and set of JavaScript operations to perform. These operations may acces "tck" object with various methods defined by the wizard framework implementation - e.g. other implementations would define the "tck" object differently to expose their own internals.

> TCR: Avoid knockout templates, use data-step approach.

While having a way to define the list of steps in HTML is convenient, the data-step approach is too "jQuery-like" - e.g. one would need to mangle around the DOM a bit too much. Here is more knockoutish approach - use of custom 'step' binding: http://hg.netbeans.org/ergonomics/rev/c5ec0030bd76 - hopefully it will be found acceptable too.

> TCR: Filter control data

Done: http://hg.netbeans.org/ergonomics/rev/31f42048137a

(In reply to Jaroslav Tulach from comment #10)
> Here is more knockoutish approach - use of
> custom 'step' binding: http://hg.netbeans.org/ergonomics/rev/c5ec0030bd76 -
> hopefully it will be found acceptable too.
It seems fine to me. Thank you.

Everything is done, including wizard to generate the wizard:
http://hg.netbeans.org/ergonomics/rev/c46aa831443d

The only missing piece is "TCR: Support for progress bar". There is no progress support in our Wizard API - only ProgressInstantiatingIterator - but so far the instantiation is handled by the system itself (using a freemarker templating engine). The only place for progress would be on "Next" button. For that there is AsynchronousValidatingPanel, but that one does not show progress. Anyway I will try to think about ways to bridge AsynchronousValidatingPanel into JavaScript by the final review.

Btw. can we have the review on Thursday, Dec 18? Say 11am CET? Tomáš is leaving for vacation, but he promised to review the change in advance. Can others Sváťa, Toni and Jarda join on Thursday?

The validation is implemented and tested in the TCK as of
http://hg.netbeans.org/ergonomics/rev/3c0135fb4681

I will work on better documentation now.

Finally the builder succeeded and we have Javadoc:
http://deadlock.netbeans.org/job/prototypes-WizardFor247926/javadoc/

Final review happened on Dec 18, 2014 with Jaroslav Havlín, Toni Epple, Martin Entlicher and Ondřej Vrabec being the reviewers. The change was approved for integration. See the notes at http://wiki.netbeans.org/wiki/index.php?title=HtmlUIForTemplates&diff=67358&oldid=67344

I'd like to especially thank Ondřej for bringing up his requirejs experience and spelling his global namespace initialization requirements. Thanks.

Documentation improved as of
http://hg.netbeans.org/ergonomics/rev/db40c3773567

Integrated into 'main-silver', will be available in build *201412230001* on http://bits.netbeans.org/dev/nightly/ (upload may still be in progress)

Changeset: http://hg.netbeans.org/main-silver/rev/45cde3eda538
User: Jaroslav Tulach <jtulach@netbeans.org>
Log: Review of #248418 went OK, the tests seem to be passing. Integrating. Still pending documentation fixes.