src/main/javadoc/overview.html
author Jaroslav Tulach <jtulach@netbeans.org>
Fri, 02 Oct 2015 08:57:14 +0200
changeset 1006 a0f79e32d526
parent 991 a5c83b735cca
child 1017 10427ce1c0ee
permissions -rw-r--r--
Ability to run the JavaFX presenter in headless mode is useful for testing
jaroslav@550
     1
<!--
jaroslav@550
     2
jaroslav@550
     3
    DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
jaroslav@550
     4
jaroslav@551
     5
    Copyright 2013-2014 Oracle and/or its affiliates. All rights reserved.
jaroslav@550
     6
jaroslav@550
     7
    Oracle and Java are registered trademarks of Oracle and/or its affiliates.
jaroslav@550
     8
    Other names may be trademarks of their respective owners.
jaroslav@550
     9
jaroslav@550
    10
    The contents of this file are subject to the terms of either the GNU
jaroslav@550
    11
    General Public License Version 2 only ("GPL") or the Common
jaroslav@550
    12
    Development and Distribution License("CDDL") (collectively, the
jaroslav@550
    13
    "License"). You may not use this file except in compliance with the
jaroslav@550
    14
    License. You can obtain a copy of the License at
jaroslav@550
    15
    http://www.netbeans.org/cddl-gplv2.html
jaroslav@550
    16
    or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
jaroslav@550
    17
    specific language governing permissions and limitations under the
jaroslav@550
    18
    License.  When distributing the software, include this License Header
jaroslav@550
    19
    Notice in each file and include the License file at
jaroslav@550
    20
    nbbuild/licenses/CDDL-GPL-2-CP.  Oracle designates this
jaroslav@550
    21
    particular file as subject to the "Classpath" exception as provided
jaroslav@550
    22
    by Oracle in the GPL Version 2 section of the License file that
jaroslav@550
    23
    accompanied this code. If applicable, add the following below the
jaroslav@550
    24
    License Header, with the fields enclosed by brackets [] replaced by
jaroslav@550
    25
    your own identifying information:
jaroslav@550
    26
    "Portions Copyrighted [year] [name of copyright owner]"
jaroslav@550
    27
jaroslav@550
    28
    Contributor(s):
jaroslav@550
    29
jaroslav@550
    30
    The Original Software is NetBeans. The Initial Developer of the Original
jaroslav@551
    31
    Software is Oracle. Portions Copyright 2013-2014 Oracle. All Rights Reserved.
jaroslav@550
    32
jaroslav@550
    33
    If you wish your version of this file to be governed by only the CDDL
jaroslav@550
    34
    or only the GPL Version 2, indicate your decision by adding
jaroslav@550
    35
    "[Contributor] elects to include this software in this distribution
jaroslav@550
    36
    under the [CDDL or GPL Version 2] license." If you do not indicate a
jaroslav@550
    37
    single choice of license, a recipient has the option to distribute
jaroslav@550
    38
    your version of this file under either the CDDL, the GPL Version 2 or
jaroslav@550
    39
    to extend the choice of license to its licensees as provided above.
jaroslav@550
    40
    However, if you add GPL Version 2 code and therefore, elected the GPL
jaroslav@550
    41
    Version 2 license, then the option applies only if the new code is
jaroslav@550
    42
    made subject to such option by the copyright holder.
jaroslav@550
    43
jaroslav@550
    44
-->
jaroslav@541
    45
<!DOCTYPE html>
jaroslav@541
    46
<html>
jaroslav@541
    47
    <head>
jaroslav@541
    48
        <title>HTML for Java APIs</title>
jaroslav@541
    49
        <meta charset="UTF-8">
jaroslav@541
    50
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
jtulach@982
    51
        <style type="text/css">
jtulach@982
    52
        table.field td {
jtulach@982
    53
            padding: 4px;
jtulach@982
    54
            width: 18px;
jtulach@982
    55
            height: 18px;
jtulach@982
    56
            font-size: 1.5em;
jtulach@982
    57
            border: 1px solid black;
jtulach@982
    58
        }
jtulach@982
    59
        table.field td.UNKNOWN {
jtulach@982
    60
            background-color: #D6E4E1;
jtulach@982
    61
            cursor: pointer;
jtulach@982
    62
        }
jtulach@982
    63
        table.field td.EXPLOSION {
jtulach@982
    64
            background-color: #A31E39;
jtulach@982
    65
        }
jtulach@982
    66
        table.field td.DISCOVERED {
jtulach@982
    67
            background-color: #9DB2B1;
jtulach@982
    68
        }
jtulach@982
    69
        </style>
jaroslav@541
    70
    </head>
jaroslav@541
    71
    <body>
jaroslav@541
    72
        <p>
jtulach@940
    73
         Use Java to write application logic; Use HTML5 to render the UI;
jaroslav@630
    74
         {@link net.java.html.json.Model Animate an HTML page from Java}
jtulach@668
    75
         (see <a target="_blank" href="http://dew.apidesign.org/dew/#7212206">Duke being rotated</a> by CSS);
jaroslav@543
    76
         Use {@link net.java.html.json.OnReceive REST} or
jaroslav@543
    77
         <a href="net/java/html/json/doc-files/websockets.html">WebSockets</a>;
jaroslav@543
    78
         interact with <a href="net/java/html/js/package-summary.html">JavaScript</a>;
jaroslav@543
    79
         Get the best of both worlds!
jtulach@940
    80
jtulach@940
    81
         The goal of these APIs is to use full featured Java runtime
jtulach@940
    82
         (like real <a href="http://wiki.apidesign.org/wiki/HotSpot">HotSpot VM</a>),
jtulach@940
    83
         but still rely on a very lightweight rendering technology
jtulach@940
    84
         (so it can potentially fit
jaroslav@541
    85
         <a href="http://bck2brwsr.apidesign.org">Bck2Brwsr</a> and definitely
jtulach@940
    86
         to various types of phones). What can be more lightweight
jtulach@940
    87
         (from a browser perspective) than
jaroslav@541
    88
         <a href="http://wiki.apidesign.org/wiki/HTML">HTML</a>!?
jtulach@940
    89
         By default we use {@link net.java.html.boot.fx JavaFX's WebView}
jtulach@940
    90
         component to display the <a href="http://wiki.apidesign.org/wiki/HTML">HTML</a>.
jtulach@940
    91
         We eliminate the need to manipulate the DOM directly,
jtulach@940
    92
         there is a special {@link net.java.html.json Java to Knockout.js binding}.
jtulach@940
    93
         As a result the <a href="http://knockoutjs.com">HTML uses Knockout.js syntax</a>,
jaroslav@541
    94
         yet the application code can be written in Java.
jaroslav@541
    95
        </p>
jtulach@940
    96
jtulach@1006
    97
        <h3>Improvements in version 1.3</h3>
jtulach@1006
    98
jtulach@1006
    99
        The <em>JavaFX</em> presenter can be executed in headless mode -
jtulach@1006
   100
        just specify <code>-Dfxpresenter.headless=true</code> when launching
jtulach@1006
   101
        its virtual machine and no window will be shown. This is particularly
jtulach@1006
   102
        useful for testing. Configure your <em>surefire</em> or <em>failsafe</em>
jtulach@1006
   103
        plugins like: <pre>
jtulach@1006
   104
&lt;plugin&gt;
jtulach@1006
   105
  &lt;groupId&gt;org.apache.maven.plugins&lt;/groupId&gt;
jtulach@1006
   106
  &lt;artifactId&gt;maven-surefire-plugin&lt;/artifactId&gt;
jtulach@1006
   107
  &lt;version&gt;2.13&lt;/version&gt;
jtulach@1006
   108
  &lt;configuration&gt;
jtulach@1006
   109
      &lt;systemPropertyVariables&gt;
jtulach@1006
   110
          &lt;fxpresenter.headless&gt;true&lt;/fxpresenter.headless&gt;
jtulach@1006
   111
      &lt;/systemPropertyVariables&gt;
jtulach@1006
   112
  &lt;/configuration&gt;
jtulach@1006
   113
&lt;/plugin&gt;
jtulach@1006
   114
</pre>
jtulach@1006
   115
jtulach@991
   116
        <h3>What's Been Improved in Version 1.2.3?</h3>
jtulach@940
   117
jtulach@940
   118
        One can control {@link net.java.html.json.OnReceive#headers() HTTP request headers}
jtulach@940
   119
        when connecting to server using the {@link net.java.html.json.OnReceive}
jtulach@951
   120
        annotation. It is possible to have
jtulach@951
   121
        {@link net.java.html.json.ComputedProperty#write() writable computed properties}.
maxnitribitt@964
   122
        There is an easy way to enable <a target="_blank" href="http://getfirebug.com/">Firebug</a> in
maxnitribitt@964
   123
        the JavaFX based Web View -
maxnitribitt@964
   124
        just run with <code>-Dfirebug.lite=true</code> as
maxnitribitt@964
   125
        <a target="_blank" href="https://www.youtube.com/watch?v=2rxwY-QJiLo">this video</a>
maxnitribitt@964
   126
        demonstrates.
jtulach@943
   127
        Bugfix of issues <a target="_blank" href='https://netbeans.org/bugzilla/show_bug.cgi?id=250503'>250503</a>,
jtulach@943
   128
        <a target="_blank" href='https://netbeans.org/bugzilla/show_bug.cgi?id=252987'>252987</a>.
jtulach@940
   129
jtulach@886
   130
        <h3>What's New in Version 1.1?</h3>
jtulach@940
   131
jtulach@886
   132
        <p>
jtulach@886
   133
            The content of a {@link net.java.html.BrwsrCtx context}
jtulach@886
   134
            can be selected by registering implementations under specific
jtulach@940
   135
            {@link org.netbeans.html.context.spi.Contexts.Id technology identifiers}
jtulach@940
   136
            and requesting them during
jtulach@940
   137
            {@link org.netbeans.html.context.spi.Contexts#newBuilder(java.lang.Object...) construction}
jtulach@886
   138
            of the context. <code>org.netbeans.html:ko4j</code> module's implementation
jtulach@886
   139
            offers <b>ko4j</b>, <b>xhr</b> and <b>websocket</b> identifiers
jtulach@940
   140
            for its registered services
jtulach@886
   141
            (e.g. {@link org.netbeans.html.json.spi.Technology},
jtulach@886
   142
            {@link org.netbeans.html.json.spi.Transfer} and
jtulach@886
   143
            {@link org.netbeans.html.json.spi.WSTransfer}).
jtulach@886
   144
            <code>org.netbeans.html:ko-ws-tyrus</code>
jtulach@940
   145
            module registers its
jtulach@940
   146
            {@link org.netbeans.html.json.spi.Transfer Java based JSON} and
jtulach@886
   147
            {@link org.netbeans.html.json.spi.WSTransfer WebSocket} implementations
jtulach@886
   148
            under the name <b>tyrus</b>.
jtulach@920
   149
        </p>
jtulach@920
   150
        <p>
jtulach@920
   151
            A particular DOM subtree
jtulach@920
   152
            that a <a target="_blank" href="http://knockoutjs.com">knockout.js</a> model gets
jtulach@940
   153
            applied to can be selected by using
jtulach@921
   154
            {@link net.java.html.json.Models#applyBindings(java.lang.Object,java.lang.String)
jtulach@920
   155
            Models.applyBindings(m, id)} with an id of an HTML element.
jtulach@940
   156
            There is new {@link net.java.html.json.Model#targetId()} attribute
jtulach@940
   157
            which controls behavior of the generated <code>applyBindings</code> method.
jtulach@920
   158
            If <em>specified and non-empty</em>, then the generated method
jtulach@920
   159
            will call {@link net.java.html.json.Models#applyBindings(java.lang.Object,java.lang.String)}
jtulach@920
   160
            with <code>this</code> and the provided {@link net.java.html.json.Model#targetId() target id}.
jtulach@920
   161
            If <em>specified, but left empty</em>, then the generated method
jtulach@920
   162
            calls {@link net.java.html.json.Models#applyBindings(java.lang.Object)}.
jtulach@920
   163
            <em>If unspecified</em>, the method will <b>not</b> be generated at all
jtulach@920
   164
            (a change with respect to older versions). However one can
jtulach@920
   165
            still use {@link net.java.html.json.Models#applyBindings(java.lang.Object)}
jtulach@920
   166
            or {@link net.java.html.json.Models#applyBindings(java.lang.Object,java.lang.String)}
jtulach@920
   167
            to perform the association of any model with the page element.
jtulach@982
   168
        </p>
jtulach@920
   169
        <p>
jtulach@870
   170
            Memory model when using Knockout bindings has been improved
jtulach@870
   171
            (required additions of two new methods:
jtulach@870
   172
            {@link org.netbeans.html.json.spi.PropertyBinding#weak()} and
jtulach@870
   173
            {@link org.netbeans.html.json.spi.FunctionBinding#weak()}) and
jtulach@870
   174
            now the Java {@link net.java.html.json.Model models} can garbage collect,
jtulach@940
   175
            when no longer used. Library writers that use
jtulach@940
   176
            {@link net.java.html.js.JavaScriptBody} annotation can also
jtulach@903
   177
            control garbage collection behavior of method arguments by
jtulach@903
   178
            setting {@link net.java.html.js.JavaScriptBody#keepAlive() keepAlive=false}
jtulach@903
   179
            attribute.
jtulach@886
   180
        </p>
jtulach@940
   181
jtulach@832
   182
        <h3>What's New in Version 1.0?</h3>
jtulach@940
   183
jtulach@832
   184
        <p>
jtulach@832
   185
            {@link net.java.html.json.Property#array() Array properties} are now
jtulach@832
   186
            mutable from the <a href="http://knockoutjs.com">knockout.js</a>
jtulach@838
   187
            point of view (required {@link org.netbeans.html.json.spi.Proto.Type#replaceValue one SPI change}).
jtulach@834
   188
            The page lookup mechanism can use {@link net.java.html.boot.BrowserBuilder#locale(java.util.Locale) locale}
jtulach@834
   189
            to load localized a page with appropriate suffix.
jtulach@841
   190
            All SPI were moved under the NetBeans namespace - e.g.
jtulach@841
   191
            {@link org.netbeans.html.boot.spi},
jtulach@841
   192
            {@link org.netbeans.html.context.spi},
jtulach@841
   193
            {@link org.netbeans.html.json.spi},
jtulach@841
   194
            {@link org.netbeans.html.sound.spi}, and also
jtulach@852
   195
            {@link org.netbeans.html.json.tck}. Methods annotated
jtulach@852
   196
            with {@link net.java.html.js.JavaScriptBody} annotation and
jtulach@852
   197
            without fallback Java code now throw {@link java.lang.IllegalStateException}
jtulach@852
   198
            with a message suggesting to switch to proper
jtulach@852
   199
            {@link net.java.html.BrwsrCtx#execute browser context} to
jtulach@852
   200
            prevent endless debugging when one forgets to do so.
jtulach@832
   201
        </p>
jtulach@940
   202
jtulach@887
   203
        <p>
jtulach@940
   204
        What's new in older versions? Click the
jtulach@940
   205
        <a href="#" onclick="return showHistoric(true)">link</a>
jtulach@940
   206
        to view even more
jtulach@887
   207
        <a href="#" onclick="return showHistoric(true)">historic changes</a> below:
jtulach@887
   208
        </p>
jtulach@940
   209
jtulach@887
   210
        <a name="historic.changes"></a>
jtulach@887
   211
        <div id="historic.changes">
jtulach@887
   212
            <script>
jtulach@887
   213
            function showHistoric(show) {
jtulach@887
   214
                var e = document.getElementById("historic.changes");
jtulach@887
   215
                if (show) {
jtulach@887
   216
                    e.style.display="block";
jtulach@887
   217
                } else {
jtulach@887
   218
                    e.style.display="none";
jtulach@887
   219
                }
jtulach@887
   220
                return false;
jtulach@887
   221
            }
jtulach@887
   222
            showHistoric(false);
jtulach@887
   223
            </script>
jtulach@940
   224
jtulach@771
   225
        <h3>What's New in Version 0.9?</h3>
jtulach@940
   226
jtulach@771
   227
        <p>
jtulach@771
   228
            System can run in {@link net.java.html.boot.BrowserBuilder#classloader(java.lang.ClassLoader) Felix OSGi container} (originally only Equinox).
jtulach@788
   229
            {@link net.java.html.json.ComputedProperty Derived properties}
jtulach@788
   230
            now deeply check changes in other {@link net.java.html.json.Model model
jtulach@788
   231
            classes} they depend on and recompute their values accordingly.
jtulach@810
   232
            <a target="_blank" href="http://knockoutjs.com">Knockout.js</a> library has been updated
jtulach@810
   233
            to version 3.2.0.
jtulach@771
   234
        </p>
jtulach@940
   235
jtulach@771
   236
        <h3>What's New in 0.8.x Versions?</h3>
jtulach@940
   237
jaroslav@720
   238
        <p>
jaroslav@720
   239
            Setters or array properties on classes generated by {@link net.java.html.json.Model}
jtulach@838
   240
            annotation can be accessed from any thread. {@link org.netbeans.html.sound.spi.AudioEnvironment}
jtulach@747
   241
            can be registered into {@link net.java.html.BrwsrCtx}. There is
jtulach@747
   242
            a {@link net.java.html.json.Models#parse(net.java.html.BrwsrCtx, java.lang.Class, java.io.InputStream, java.util.Collection)  method}
jtulach@940
   243
            to parse a JSON array and convert it into
jtulach@747
   244
            {@link net.java.html.json.Model model classes}.
jtulach@940
   245
            Improved behavior of <code>enum</code> values in
jtulach@758
   246
            {@link net.java.html.json.Model knockout bindings}.
jaroslav@720
   247
        </p>
jtulach@940
   248
jtulach@702
   249
        <p>
jtulach@940
   250
            Few bugfixes for better portability.
jtulach@702
   251
            New API for {@link net.java.html.boot.script.Scripts headless execution}
jtulach@703
   252
            on top of <em>Nashorn</em> - does not run <em>knockout for Java</em>
jtulach@940
   253
            fully yet
jtulach@702
   254
            (reported as <a href="https://bugs.openjdk.java.net/browse/JDK-8046013">JDK-8046013</a>),
jtulach@940
   255
            however even in current state it is quite
jtulach@703
   256
            {@link net.java.html.boot.script.Scripts useful for testing}
jtulach@940
   257
            of
jtulach@703
   258
            {@link net.java.html.js Java/JavaScript interactions}.
jtulach@702
   259
        </p>
jtulach@940
   260
jtulach@654
   261
        <p>
jtulach@656
   262
            {@link net.java.html.boot.fx.FXBrowsers} has been extended
jtulach@656
   263
            with new helper methods to make it easier to use HTML+Java
jtulach@656
   264
            API in existing JavaFX applications.
jtulach@656
   265
            The annotation processor is made
jtulach@654
   266
            more robust with respect to errors in callback syntax of
jtulach@654
   267
            {@link net.java.html.js.JavaScriptBody} body parameter.
jtulach@654
   268
            Javadoc of {@link net.java.html.BrwsrCtx#execute} method
jtulach@654
   269
            has been improved based on a failure of its usability study.
jtulach@654
   270
            There can be additional parameters to methods annotated by
jtulach@654
   271
            {@link net.java.html.json.OnReceive} that allows one to
jtulach@654
   272
            pass state when a JSON call is made and use it when it finishes.
jtulach@654
   273
            The mechanism of discovery of sibling HTML page has been
jtulach@654
   274
            extended to work on systems that don't support
jtulach@654
   275
            {@link java.lang.Class#getProtectionDomain}.
jtulach@654
   276
        </p>
jtulach@940
   277
jaroslav@617
   278
        <p>
jtulach@650
   279
            The first argument of method annotated by
jtulach@650
   280
            {@link net.java.html.json.OnReceive} annotation has to
jtulach@650
   281
            be the associated {@link net.java.html.json.Model model class}.
jtulach@650
   282
        </p>
jtulach@940
   283
jtulach@650
   284
        <p>
jtulach@647
   285
            {@link net.java.html.json.OnReceive} annotation now accepts
jtulach@647
   286
            {@link java.util.List} of data values as second argument
jtulach@647
   287
            (previously required an array).
jtulach@647
   288
        </p>
jtulach@940
   289
jtulach@940
   290
jtulach@887
   291
        <h3>What's New in 0.7.x Versions?</h3>
jtulach@940
   292
jtulach@647
   293
        <p>
jaroslav@617
   294
            {@link net.java.html.js.JavaScriptBody} annotation has new attribute
jaroslav@617
   295
            {@link net.java.html.js.JavaScriptBody#wait4js()} which allows
jaroslav@617
   296
            asynchronous execution. Libraries using
jaroslav@617
   297
            {@link net.java.html.js.JavaScriptBody} are urged to use this
jaroslav@617
   298
            new attribute as much as possible, as it can speed up execution
jaroslav@617
   299
            in certain environments.
jaroslav@617
   300
        </p>
jtulach@940
   301
jaroslav@617
   302
        <p>
jaroslav@617
   303
            Use {@link net.java.html.BrwsrCtx#execute(java.lang.Runnable)} in
jaroslav@617
   304
            multi-threaded environment to execute your code on the browser thread.
jtulach@940
   305
            See example
jaroslav@617
   306
            {@link net.java.html.BrwsrCtx#execute(java.lang.Runnable) using Java timer}.
jaroslav@617
   307
        </p>
jtulach@887
   308
        </div>
jtulach@940
   309
jaroslav@541
   310
        <h3>Interesting Entry Points</h3>
jtulach@940
   311
jaroslav@541
   312
        <p>Learn how to {@link net.java.html.json.Model animate an HTML page from Java}
jaroslav@541
   313
            without referencing single HTML element from the Java code.
jaroslav@541
   314
        </p>
jaroslav@541
   315
        <p>Use {@link net.java.html.json.OnReceive JSON} to communicate
jaroslav@541
   316
            with REST based server API.
jaroslav@541
   317
        </p>
jaroslav@541
   318
        <p>Use <a href="net/java/html/json/doc-files/websockets.html">WebSockets</a>
jaroslav@541
   319
            and JSON.
jaroslav@541
   320
        </p>
jaroslav@541
   321
        <p>Call JavaScript methods from Java and vice versa, via
jaroslav@541
   322
            <a href="net/java/html/js/package-summary.html">JavaScriptBody</a>.
jaroslav@541
   323
        </p>
jaroslav@541
   324
jaroslav@541
   325
        <h3>Getting Started</h3>
jaroslav@541
   326
jtulach@940
   327
        There are <a href="http://wiki.apidesign.org/wiki/DukeScriptInNetBeans">many ways</a>
jtulach@940
   328
        to start developing
jtulach@940
   329
        <a href="http://html.java.net">Html for Java</a> application.
jaroslav@541
   330
        However to be sure one chooses the most recent setup, it is recommended
jtulach@940
   331
        to switch to good old command line and use a
jaroslav@541
   332
        <a href="http://wiki.apidesign.org/wiki/Knockout4Java">Maven archetype</a>
jtulach@940
   333
        associated with every version of this project. Make sure at least
jaroslav@610
   334
        <em>JDK7</em> is your installed Java and type:
jtulach@940
   335
        <pre>
jaroslav@541
   336
$ mvn archetype:generate \
jaroslav@541
   337
 -DarchetypeGroupId=org.apidesign.html \
jaroslav@541
   338
 -DarchetypeArtifactId=knockout4j-archetype \
jtulach@759
   339
 -DarchetypeVersion=0.8 <em># or newer version, if available</em>
jaroslav@541
   340
        </pre>
jtulach@940
   341
        Answer few questions (for example choose myfirstbrwsrpage as artifactId)
jaroslav@611
   342
        and then you can:
jaroslav@541
   343
        <pre>
jaroslav@541
   344
$ cd myfirstbrwsrpage
jaroslav@541
   345
$ mvn process-classes exec:java
jaroslav@541
   346
        </pre>
jtulach@940
   347
        In a few seconds (or minutes if
jaroslav@541
   348
        <a href="http://wiki.apidesign.org/wiki/Maven">Maven</a>
jtulach@940
   349
        decides to download the whole Internet of dependencies) you should
jtulach@940
   350
        see a sample Hello World application rendered in a
jaroslav@611
   351
        <a href="http://wiki.apidesign.org/wiki/JavaFX">JavaFX</a>
jaroslav@611
   352
        web view component (that of course requires your JDK to come
jtulach@940
   353
        with <a href="http://wiki.apidesign.org/wiki/JavaFX">JavaFX</a>;
jtulach@940
   354
        <a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">JDK7
jtulach@940
   355
            and JDK8 from Oracle</a> contain everything that is needed).
jtulach@940
   356
        The generated application is built around one
jaroslav@611
   357
        Java source (uses the {@link net.java.html.json.Model} annotation to
jaroslav@611
   358
        auto-generate another <code>Data.java</code> class during compilation)
jaroslav@611
   359
        and one HTML file (uses the <a href="http://knockoutjs.com">Knockout</a>
jtulach@940
   360
        syntax to <code>data-bind</code> the HTML elements to the
jaroslav@611
   361
        generated <code>Data</code> model):
jaroslav@541
   362
        <pre>
jaroslav@541
   363
$ ls src/main/java/**/DataModel.java
jaroslav@541
   364
$ ls src/main/webapp/pages/index.html
jaroslav@541
   365
        </pre>
jtulach@940
   366
        That is all you need to get started. Play with the sources,
jaroslav@611
   367
        modify them and enjoy
jaroslav@541
   368
        <a href="http://html.java.net">Html for Java</a>!
jtulach@940
   369
jaroslav@614
   370
        <h2>IDE Support</h2>
jtulach@940
   371
jaroslav@614
   372
        <p>
jaroslav@614
   373
            This API is part of <a target="_blank"
jaroslav@614
   374
            href="http://netbeans.org">NetBeans.org</a> project and as such
jaroslav@614
   375
            it works naturally with the <a target="_blank"
jaroslav@614
   376
            href="https://netbeans.org/features/index.html">NetBeans IDE</a>.
jaroslav@614
   377
            On the other hand, the API is using nothing NetBeans specific,
jaroslav@614
   378
            it builds on standard Java6 APIs and as such it shall work fine
jaroslav@614
   379
            in any IDE.
jaroslav@614
   380
        </p>
jtulach@940
   381
jaroslav@614
   382
        <p>
jtulach@940
   383
            A lot of work is done by
jaroslav@614
   384
            <a href="http://wiki.apidesign.org/wiki/AnnotationProcessor">
jaroslav@614
   385
            annotation processors</a>
jaroslav@614
   386
            that generate various boiler plate code during compilation. This
jaroslav@614
   387
            is a standard part of Java since JDK6, but for example Eclipse
jaroslav@614
   388
            is known not to deal with processors well and developers using
jaroslav@614
   389
            it need to be careful. IntelliJ users hasn't reported any issues
jtulach@940
   390
            and of course, NetBeans IDE support for
jaroslav@614
   391
            <a href="http://wiki.apidesign.org/wiki/AnnotationProcessor">processors</a>
jaroslav@614
   392
            is outstanding.
jaroslav@614
   393
        </p>
jtulach@940
   394
jaroslav@614
   395
        <p>
jaroslav@614
   396
            When using {@link net.java.html.js.JavaScriptBody} annotation, it is
jaroslav@614
   397
            useful to do a bit of post processing of classes. There is a
jtulach@940
   398
            <a href="http://wiki.apidesign.org/wiki/Maven">Maven</a>
jaroslav@614
   399
            plugin for that.
jtulach@940
   400
            NetBeans IDE will invoke it when doing a build. Other IDEs may
jtulach@940
   401
            need some hint to do so.
jaroslav@614
   402
            Anyway: If one does not see all (generated) sources or is getting
jtulach@940
   403
            {@link java.lang.LinkageError}s when executing the application,
jaroslav@614
   404
            switch to command line and do clean build
jaroslav@614
   405
            from there:
jaroslav@614
   406
        </p>
jaroslav@614
   407
        <pre>$ mvn clean install</pre>
jaroslav@614
   408
        <p>
jaroslav@614
   409
            If that succeeds, your IDE of choice will hopefully
jtulach@940
   410
            pick the generated sources up and present the result of the build
jtulach@940
   411
            properly. If not,
jtulach@940
   412
            <a href="https://netbeans.org/downloads/">download NetBeans</a>,
jtulach@940
   413
            you will be pleasantly
jtulach@940
   414
            surprised - for example with our excellent
jtulach@940
   415
            <a href="net/java/html/js/package-summary.html#debugging">Java/JavaScript
jaroslav@614
   416
            debugging</a> support.
jaroslav@614
   417
        </p>
jtulach@940
   418
jaroslav@615
   419
        <a name="deploy">
jaroslav@615
   420
        <h2>Deploy Your Application</h2>
jaroslav@615
   421
        </a>
jtulach@940
   422
jaroslav@615
   423
        <p>
jaroslav@615
   424
        It is not goal of this documentation to list all possible ways
jtulach@940
   425
        to package and deploy applications which use this API. However it is
jaroslav@615
   426
        important for new comers to see the benefits of using the
jaroslav@615
   427
        <a href="http://html.java.net">HTML for Java</a> API and as such
jtulach@940
   428
        let's list at least few bundling options, known to work at the time of writing
jaroslav@615
   429
        this documentation.
jaroslav@615
   430
        </p>
jtulach@940
   431
jaroslav@615
   432
        <p>
jaroslav@615
   433
        First of all, this is a <em>client technology</em>. You write client applications
jaroslav@615
   434
        with it which may, but need not connect to a server. You don't need
jtulach@940
   435
        Tomcat or WebLogic to deploy
jaroslav@615
   436
        <a href="http://html.java.net">HTML for Java</a> applications.
jaroslav@615
   437
        </p>
jtulach@940
   438
jaroslav@615
   439
        <p>
jaroslav@615
   440
            <img src='resources/javafx_logo.jpg' width="64"
jaroslav@615
   441
                 height="64" align="left"/>
jaroslav@615
   442
            The sample project generated by
jaroslav@615
   443
            <code>org.apidesign.html knockout4j-archetype</code> is configured
jaroslav@615
   444
            to use <a href="http://wiki.apidesign.org/wiki/JavaFX">JavaFX</a>
jtulach@940
   445
            as the rendering technology. This setup is primarily suitable for
jaroslav@615
   446
            development - it needs no special packaging, starts quickly and
jtulach@940
   447
            allows you to use classical HotSpot VM debuggers. A final
jaroslav@615
   448
            artifact from the build is also a ZIP file which you can use
jaroslav@615
   449
            and distribute to your users. Good for desktop applications.
jaroslav@615
   450
        </p>
jtulach@940
   451
jaroslav@615
   452
        <p>
jaroslav@615
   453
            <img src='resources/netbeans_logo.jpg' width="64"
jaroslav@615
   454
                 height="64" align="right"/>
jaroslav@615
   455
            <img src='resources/eclipse_logo.png' width="64"
jaroslav@615
   456
                 height="64" align="right"/>
jaroslav@615
   457
            All the <a href="http://html.java.net">HTML for Java</a> libraries
jtulach@638
   458
            are packaged as <a href="http://wiki.apidesign.org/wiki/OSGi">OSGi</a>
jaroslav@615
   459
            bundles and as such they can easily be run in NetBeans as well as
jtulach@940
   460
            in Eclipse. As a result one can use
jaroslav@615
   461
            <a href="http://wiki.apidesign.org/wiki/OSGi">OSGi</a>
jtulach@940
   462
            and have a common module system for both platforms. In addition to that
jtulach@638
   463
            one can render using
jaroslav@615
   464
            HTML and have a common UI in both platforms. In such case
jaroslav@615
   465
            your application would be packaged as a set of
jaroslav@615
   466
            <a href="http://wiki.apidesign.org/wiki/OSGi">OSGi</a> bundles.
jtulach@940
   467
            Read
jaroslav@615
   468
            <a href="http://wiki.apidesign.org/wiki/HTML">more</a>...
jaroslav@615
   469
        </p>
jtulach@940
   470
jaroslav@615
   471
        <p>
jaroslav@615
   472
            <img src='resources/chrome_logo.png' width="64"
jaroslav@615
   473
                 height="64" align="left"/>
jaroslav@615
   474
            <img src='resources/safari_logo.png' width="64"
jaroslav@615
   475
                 height="64" align="left"/>
jaroslav@615
   476
            <img src='resources/ie_logo.png' width="64"
jaroslav@615
   477
                 height="64" align="left"/>
jaroslav@615
   478
            <img src='resources/firefox_logo.png' width="64"
jaroslav@615
   479
                 height="64" align="left"/>
jtulach@940
   480
jaroslav@615
   481
            There is more and more attempts to execute Java bytecode
jtulach@638
   482
            in a browser, without any special Java plugin installed.
jaroslav@615
   483
            The <a href="http://html.java.net">HTML for Java</a> is
jaroslav@615
   484
            carefully designed to produce lightweight, well performing
jaroslav@615
   485
            applications even on such restricted environments. It uses
jaroslav@615
   486
            no reflection calls and that allows to statically pre-compile
jaroslav@615
   487
            the applications into JavaScript. One of such environments
jtulach@940
   488
            is called <a href="http://wiki.apidesign.org/wiki/Bck2Brwsr">Bck2Brwsr</a>,
jtulach@638
   489
            another <a href="http://wiki.apidesign.org/wiki/TeaVM">TeaVM</a>. Both support the
jtulach@940
   490
            {@link net.java.html.js.JavaScriptBody} annotation. Read
jaroslav@615
   491
            <a href="http://wiki.apidesign.org/wiki/Bck2BrwsrViaCLI">more</a> or play
jtulach@940
   492
            a minesweeper game packaged for your browser
jaroslav@616
   493
            (of course <a target="_blank"
jaroslav@616
   494
                href="http://source.apidesign.org/hg/html~demo/file/ea79b73d590a/minesweeper/src/main/java/org/apidesign/demo/minesweeper/MinesModel.java">
jaroslav@616
   495
                written</a> in Java):
jaroslav@615
   496
        </p>
jtulach@940
   497
jaroslav@616
   498
        <script type="text/html" id="field">
jaroslav@616
   499
            <table class="field">
jaroslav@616
   500
                <tbody>
jaroslav@616
   501
                    <!-- ko foreach: rows -->
jaroslav@616
   502
                    <tr>
jaroslav@616
   503
                        <!-- ko foreach: columns -->
jaroslav@616
   504
                        <td data-bind="css: style, click: $parents[1].click" >
jaroslav@616
   505
                            <div data-bind='html: html'></div>
jaroslav@616
   506
                        </td>
jaroslav@616
   507
                        <!-- /ko -->
jaroslav@616
   508
                    </tr>
jaroslav@616
   509
                    <!-- /ko -->
jaroslav@616
   510
                </tbody>
jaroslav@616
   511
            </table>
jaroslav@616
   512
        </script>
jaroslav@616
   513
jaroslav@616
   514
        <div data-bind="template: { name : 'field', if: fieldShowing }"></div>
jaroslav@616
   515
jaroslav@616
   516
        <!-- boot bck2brwsr -->
jaroslav@616
   517
        <script type="text/javascript" src="resources/teavm.js"></script>
jaroslav@616
   518
        <script>
jaroslav@616
   519
            var vm = new VM();
jaroslav@616
   520
            vm.loadClass('org.apidesign.demo.minesweeper.MainBrwsr');
jaroslav@616
   521
        </script>
jaroslav@616
   522
jaroslav@615
   523
        <p>
jtulach@654
   524
            <img src='resources/ios_logo.jpg' width="64"
jtulach@654
   525
                 height="64" align="right"/>
jaroslav@615
   526
            <img src='resources/android_logo.jpg' width="64"
jaroslav@615
   527
                 height="64" align="right"/>
jtulach@940
   528
jtulach@940
   529
            Now when we have seen that the
jtulach@940
   530
            <a href="http://html.java.net">HTML for Java</a> applications
jaroslav@615
   531
            can run on any modern browser, we can ask whether they can also
jtulach@940
   532
            fit into a phone!? Yes, they can and especially to phones
jaroslav@615
   533
            that can execute Java code already! Just by changing your
jaroslav@615
   534
            packaging you can create an APK file and deploy it to your
jtulach@940
   535
            Android phone.
jtulach@624
   536
            Read <a target="_blank" href="http://wiki.apidesign.org/wiki/DlvkBrwsr">more</a>...
jtulach@654
   537
            In case you'd like your application to reach out to second biggest
jtulach@940
   538
            group of smartphone users, don't despair: It
jtulach@654
   539
            seems the set of devices that can execute
jtulach@940
   540
            <a href="http://html.java.net">HTML for Java</a> applications
jtulach@940
   541
            has been extended to <em>iPads</em> and <em>iPhones</em>. Get the
jtulach@654
   542
            <a target="_blank" href="http://wiki.apidesign.org/wiki/IBrwsr">details here</a>
jtulach@654
   543
            and deploy everywhere!
jaroslav@615
   544
        </p>
jaroslav@615
   545
        <p>
jtulach@940
   546
            Convinced it makes sense to use
jaroslav@615
   547
            <a href="http://html.java.net">HTML for Java</a>
jtulach@940
   548
            APIs for writing applications that are
jaroslav@615
   549
            <em>written once, displayed anywhere</em>? Or do you have an
jaroslav@615
   550
            environment which is not supported? In such case you can bring
jaroslav@615
   551
            <a href="http://html.java.net">HTML for Java</a>
jaroslav@615
   552
            to your environment yourself. Just implement your own
jtulach@838
   553
            {@link org.netbeans.html.boot.spi.Fn.Presenter}!
jaroslav@615
   554
        </p>
jtulach@940
   555
jaroslav@607
   556
        <h2>Other Resources</h2>
jtulach@940
   557
jaroslav@607
   558
        <img src="net/java/html/json/doc-files/DukeHTML.png" width="256" height="184" alt="Duke and HTML5. Together at last!" align="right"/>
jtulach@940
   559
jaroslav@607
   560
        The javadoc for latest and previous versions is also available
jaroslav@607
   561
        online:
jaroslav@607
   562
        <ul>
jaroslav@607
   563
            <li>Current <a target="_blank" href="http://bits.netbeans.org/html+java/dev/">development</a> version
jtulach@940
   564
            <li>Version <a target="_blank" href="http://bits.netbeans.org/html+java/1.1">1.1</a>
jtulach@891
   565
            <li>Version <a target="_blank" href="http://bits.netbeans.org/html+java/1.0">1.0</a>
jtulach@940
   566
            <li>Version <a target="_blank" href="http://bits.netbeans.org/html+java/0.9">0.9</a>
jtulach@891
   567
                and historic ones (<a target="_blank" href="http://bits.netbeans.org/html+java/0.8.3">0.8.3</a>,
jtulach@940
   568
                <a target="_blank" href="http://bits.netbeans.org/html+java/0.8.2">0.8.2</a>,
jtulach@891
   569
                <a target="_blank" href="http://bits.netbeans.org/html+java/0.8.1">0.8.1</a>,
jtulach@891
   570
                <a target="_blank" href="http://bits.netbeans.org/html+java/0.8">0.8</a>, and
jtulach@891
   571
                <a target="_blank" href="http://bits.netbeans.org/html+java/0.7.5">0.7.5</a>)
jtulach@891
   572
            </li>
jaroslav@607
   573
        </ul>
jaroslav@541
   574
    </body>
jaroslav@541
   575
</html>