| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> | |
| <html xmlns="http://www.w3.org/1999/xhtml"> | |
| <head> | |
| <!-- -*- xhtml -*- --> | |
| <title>NetBeans Platform 6.0 Quick Start Tutorial for NetBeans Platform 6.0</title> | |
| <link rel="stylesheet" type="text/css" href="https://netbeans.org/netbeans.css"> | |
| <meta name="AUDIENCE" content="NBUSER"> | |
| <meta name="TYPE" content="ARTICLE"> | |
| <meta name="EXPIRES" content="N"> | |
| <meta name="developer" content="jtulach@netbeans.org"> | |
| <meta name="indexed" content="y"> | |
| <meta name="description" | |
| content="A short guide to using the Nodes API."> | |
| <!-- Copyright (c) 2005 Sun Microsystems, Inc. All rights reserved. --> | |
| <!-- Use is subject to license terms.--> | |
| </head> | |
| <body> | |
| <h1>NetBeans Platform 6.0 Quick Start Tutorial</h1> | |
| <p>This tutorial demonstrates how to build an HTML Editor, without any Java coding whatsoever. At | |
| the end of this tutorial, you will have an HTML Editor that looks like this: | |
| <p align="left"><img src="../../images/tutorials/htmleditor/html_editor_60.png" border="1" alt="splash screen panel"> | |
| <p>Although this is a very simple demo application, it is not a toy! It is a <i>real</i> | |
| program that supports easy editing of HTML pages, with features such as code completion, | |
| validation, and predefined HTML snippets. | |
| <p><strong class="notes">Note: </strong>This is not the latest version of this | |
| document. It applies to NetBeans IDE 6.0 only. | |
| <a href="../nbm-htmleditor.html">Click here</a> to | |
| see the most up to date version. | |
| <p>The HTML Editor that you create in this tutorial is a rich-client application built "on top of the NetBeans Platform". What this | |
| means is that the core of the IDE, which is what the NetBeans Platform <i><u>is</u></i>, will be the base | |
| of your application. On top of the NetBeans Platform, you add the modules that you need | |
| and exclude the ones that the IDE needs but that your application doesn't. | |
| Here you see some of the IDE's modules, added to the NetBeans Platform, which is its base: | |
| <p align="left"><img src="../../images/tutorials/htmleditor/diagram.png" alt="HTML Editor"> | |
| <p>Creating this HTML Editor means generating an application skeleton, excluding the modules | |
| and user interface items that you do not need, and then setting the Favorites window | |
| as the window that will open by default when the IDE starts. All of these activities | |
| are supported by user interface elements in the IDE. </p> | |
| <p>You will see for yourself how simple | |
| and easy it is to build, or to be more precise, to <em>assemble</em> a | |
| full-featured application on top of the NetBeans Platform. At the end, you are shown how | |
| to make the final product easily downloadable and launchable using WebStart. | |
| </p> | |
| <p><b>Note:</b> Even though it is a separate product, there is no need to download the NetBeans Platform separately | |
| for purposes of this tutorial. You will develop the rich-client application in the IDE and then exclude the modules | |
| that are specific to the IDE but that are superfluous to you application. | |
| <h3>Contents</h3> | |
| <table border="0" cellpadding="0" cellspacing="0" width="100%"> | |
| <tbody><tr> | |
| <td align="left" valign="top"> | |
| <ul> | |
| <li><a href="#gettingstarted">Getting Started</a></li> | |
| <li><a href="#generating">Generating the Skeleton Application</a></li> | |
| <li><a href="#tweakingthemenuitems">Tweaking the User Interface</a> | |
| <li><a href="#tweakingthewindowlayout">Tweaking the Window Layout</a></li> | |
| <li><a href="#tweakingthefavorites">Tweaking the Favorites Window</a></li> | |
| <li><a href="#runningtheapplication">Running the Application</a></li> | |
| <li><a href="#updatingtheapplication">Including Update Functionality</a></li> | |
| <li><a href="#distributingtheapplication">Distributing the Application</a></li> | |
| <li><a href="#distributingshared">Distributing the HTML Editor via the Shared NetBeans JNLP Repository</a></li> | |
| </ul> | |
| </td> | |
| <td width="20"> </td> | |
| <td align="right" valign="top"> | |
| <img src="../../images/tutorials/netbeans-stamp.gif" | |
| alt="Content on this page applies to NetBeans IDE 6.0" title="Content on this page applies to the NetBeans | |
| IDE 6.0" border="0" height="45" width="206"> | |
| </td> | |
| </tr> | |
| </tbody></table> | |
| <p>For more information on working with modules, see the <a href="https://platform.netbeans.org/index.html"> | |
| NetBeans Development Project home</a> on the NetBeans website. If you have questions, visit the | |
| <a href="http://wiki.netbeans.org/wiki/view/NetBeansDeveloperFAQ">NetBeans Developer FAQ</a> or use the feedback link | |
| at the top of this page.</p> | |
| <br /> | |
| <!-- ===================================================================================== --> | |
| <h2 class="tutorial"><a name="gettingstarted"></a>Getting Started</h2> | |
| <p>Before you begin, you need to install the following software on your | |
| computer:</p> | |
| <ul> | |
| <li>The J2SE(TM) Development Kit (JDK), version 5.0 or compatible | |
| (<a href="http://java.sun.com/javase/downloads/index.jsp">download the | |
| most recent JDK</a>).</li> | |
| <li>NetBeans IDE 6.0 (<a href="http://download.netbeans.org/netbeans/6.0/final/">download</a>). | |
| </ul> | |
| <br /> | |
| <!-- ===================================================================================== --> | |
| <h2 class="tutorial"><a name="generating"></a>Generating the Skeleton Application</h2> | |
| <p>When creating an application on the NetBeans Platform, | |
| the very first step is to create a module suite project. | |
| The default module suite project includes <i>all</i> the modules | |
| included in the NetBeans Platform as well as <i>all</i> the | |
| modules included in NetBeans IDE. Since we do not need all | |
| these modules, we will exclude those that we do not need. | |
| <ol><li>Using the New Project wizard (Ctrl-Shift-N), create a Module Suite Project from the template | |
| in | |
| the NetBeans modules category, as shown below:</p> | |
| <p align="left"><img border="1" src="../../images/tutorials/htmleditor/module-suite-60.png" border="1" alt="splash screen panel"> | |
| <p>Click Next and name the module suite "NetBeans HTML Editor". | |
| Click Finish.</p> | |
| <li>Right-click the project node, choose Properties, | |
| and then make a few changes in the module suite's Project Properties | |
| dialog box: | |
| <ul><li>In the Build panel, click | |
| "Create Standalone Application", to specify that this | |
| is going to be a rich-client application | |
| on top of the NetBeans Platform. </p> | |
| <p>Make sure | |
| that you like the branding name for the executable | |
| and the application title for the titlebar, | |
| as shown below:</p> | |
| <p align="left"><img border="1" src="../../images/tutorials/htmleditor/application_panel-60.png" border="1" alt="application panel"> | |
| <li>In the Splash Screen panel, provide the application's splash screen, as shown below: | |
| </p> | |
| <p align="left"><img border="1" src="../../images/tutorials/htmleditor/splash_screen_panel-60.png" border="1" alt="splash screen panel"> | |
| <p>If you do not have a splash screen, use <a href="../../images/tutorials/htmleditor/splash.gif">this one</a>. | |
| </ul> | |
| <li>In the Libraries panel of the Project Properties | |
| dialog box, you see a list of "clusters". A cluster is | |
| a collection of related modules. The only clusters that need to be | |
| selected are <tt>ide8</tt> and <tt>platform7</tt>. Deselect | |
| all the other clusters. | |
| <li>In the <tt>platform7</tt> cluster, you only | |
| need the following modules:</p> | |
| <p>Actions APIs | |
| <br>Bootstrap | |
| <br>Core | |
| <br>Core - Execution | |
| <br>Core - UI | |
| <br>Core - Windows | |
| <br>Datasystems API | |
| <br>Dialogs API | |
| <br>Execution API | |
| <br>Explorer and Property Sheet API | |
| <br>Favorites | |
| <br>File System API | |
| <br>General Queries API | |
| <br>I/O APIs | |
| <br>JavaHelp Integration | |
| <br>Keymap Options | |
| <br>Look & Feel Customization Library | |
| <br>MIME Lookup API | |
| <br>MIME Lookup On SystemFS | |
| <br>Master Filesystem | |
| <br>Module System API | |
| <br>Nodes API | |
| <br>Options Dialog and SPI | |
| <br>Output Window | |
| <br>Progress API | |
| <br>Progress UI | |
| <br>Settings API | |
| <br>Settings Options API | |
| <br>Startup | |
| <br>Swing Layout Extensions integration | |
| <br>Tab Control | |
| <br>Text API | |
| <br>UI Utilities API | |
| <br>Utilities API | |
| <br>Window System API | |
| <li>In <tt>ide8</tt> cluster, only the following modules are needed:</p> | |
| <p>Common Palette | |
| <br>Diff | |
| <br>Editor | |
| <br>Editor Brace Matching | |
| <br>Editor Code Completion | |
| <br>Editor Code Folding | |
| <br>Editor Guarded Sections | |
| <br>Editor Indentation | |
| <br>Editor Library | |
| <br>Editor Library2 | |
| <br>Editor Settings | |
| <br>Editor Settings Storage | |
| <br>Editor Utilities | |
| <br>Error Stripe API | |
| <br>Error Stripe Core | |
| <br>General Options Dialog Panels | |
| <br>Generic Languages Framework | |
| <br>HTML | |
| <br>HTML Editor | |
| <br>HTML Editor Library | |
| <br>HTML Lexer | |
| <br>IDE Defaults | |
| <br>Image | |
| <br>Lexer | |
| <br>Lexer to NetBeans Bridge | |
| <br>Navigator API | |
| <br>Plain Editor | |
| <br>Plain Editor Library | |
| <br>Project API | |
| <br>Search API | |
| <br>Tags Based Editors Library | |
| </p> </ol> | |
| <!-- ===================================================================================== --> | |
| <h2 class="tutorial"><a name="tweakingthemenuitems"></a>Tweaking the User Interface</h2> | |
| <p>You can keep or reject as much of the IDE's user interface as you want. Your HTML Editor probably | |
| does not need any or all of the items under the Tools menu. Similarly, maybe there are toolbars | |
| or toolbar buttons that you can do without. In this section, you prune the IDE's user interface | |
| until you are left with a subset that is useful to your rich-client application. | |
| <ol><li>Expand the module suite, right-click the Modules node | |
| and choose Add New, as shown below:</p> | |
| <p><img border="1" src="../../images/tutorials/htmleditor/add-module-60.png" alt="this layer in context"> | |
| <p>The New Project wizard (Ctrl-Shift-N) appears. | |
| Name the project <tt>BrandingModule</tt>, click Next, and then | |
| click Finish. | |
| <li>In the branding module's | |
| Important Files node, expand the XML Layer node. | |
| Two subnodes are exposed:</p> | |
| <p><img border="1" src="../../images/tutorials/htmleditor/expanded-xml-layer-60.png" alt="expanded xml layer"> | |
| <li>In the <tt><this layer in context></tt> node, | |
| the IDE shows you a merged view of all folders and files that all modules register in their | |
| layers. To exclude items, you can right-click them and choose 'Delete', as shown below:</p> | |
| <p><img border="1" src="../../images/tutorials/htmleditor/this-layer-in-context-60.png" alt="this layer in context"> | |
| <p>The IDE then adds | |
| tags to the module's <tt>layer.xml</tt> file which, when the module is installed, | |
| hides the items that you have deleted. For example, by right-clicking within <tt>Menu Bar/Edit</tt>, you can remove | |
| menu items from the Edit menu that are not necessary for the HTML Editor. | |
| By doing this, you generate snippets such as the following in the <tt>layer.xml</tt> file: | |
| <pre class="examplecode"><folder name="Menu"> | |
| <folder name="Edit"> | |
| <file name="org-netbeans-modules-editor-MainMenuAction$StartMacroRecordingAction.instance_hidden"/> | |
| <file name="org-netbeans-modules-editor-MainMenuAction$StopMacroRecordingAction.instance_hidden"/> | |
| </folder> | |
| </folder></pre> | |
| <p> | |
| The result of the above snippet is that the <tt>Start Macro Recording</tt> and <tt>Stop Macro Recording</tt> | |
| actions provided by another module are removed from the menu by your branding module. | |
| <li>Use the approach described in the previous step to hide as many toolbars, toolbar buttons, | |
| menus, and menu items as you want. | |
| </ol> | |
| <!-- ===================================================================================== --> | |
| <h2 class="tutorial"><a name="tweakingthewindowlayout"></a>Tweaking the Window Layout</h2> | |
| <p> | |
| By using the <tt><this layer in context></tt> node, you can not only delete existing | |
| items, but you can also change their content. For example, the | |
| HTML Editor works on HTML files, so in contrast to the regular IDE, which works with Java source files and projects as well, | |
| it makes sense to show the <tt>Favorites</tt> window in the initial layout. | |
| </p> | |
| <p> | |
| The definition of the window layout is also described as files in layers, | |
| all stored under the <tt>Windows2</tt> folder. The files in the <tt>Windows2</tt> folder are | |
| pseudo-human readable XML files defined by the | |
| <a href="http://bits.netbeans.org/dev/javadoc/org-openide-windows/org/openide/windows/doc-files/api.html"> | |
| Window System APIs</a>. They are quite complex but the good news is | |
| that, for purposes of our HTML Editor, it is not necessary | |
| to understand them fully, as shown below. | |
| </p> | |
| <ol><li>In your branding module's <tt><this layer in context></tt> node, | |
| right-click the <tt>Windows2</tt> node and choose Find, | |
| as shown below:</p> | |
| <p><img border="1" src="../../images/tutorials/htmleditor/find-favorites-60.png" alt="find favorites"> | |
| <li>Search | |
| for an object named <tt>Favorites</tt>, ignoring the case. You will find two files: | |
| </p> | |
| <p><img border="1" src="../../images/tutorials/htmleditor/find-favorites2-60.png" alt="find favorites"> | |
| <p> | |
| The first file defines what the component is going to look like and | |
| how it gets created. As this does not need to be changed, there is no need to | |
| modify the file. The second is more interesting for your purposes, | |
| it contains the following: | |
| </p> | |
| <pre class="examplecode"> | |
| <tc-ref version="2.0"> | |
| <module name="org.netbeans.modules.favorites/1" spec="1.1" /> | |
| <tc-id id="favorites" /> | |
| <state opened="false" /> | |
| </tc-ref></pre> | |
| <p> | |
| <li>Even though most of the XML is cryptic, there is one line which | |
| seems promising—without needing to read | |
| any kind of documentation, it seems likely that | |
| changing the <tt>false</tt> to <tt>true</tt> is going to make the component | |
| opened by default. Do so now. | |
| <li> | |
| In a similar way you can change the Component Palete so that it opens by default, | |
| and the Navigator so that it is closed. Perform both these steps. | |
| </ol> | |
| <p>You should now see that your branding module contains three new files, | |
| one for each of the files that you changed. In effect, these files | |
| override the ones that you found in the previous steps, so that you | |
| have now provided the required information for overriding the window | |
| layout:</p> | |
| <p><img border="1" src="../../images/tutorials/htmleditor/wstcrefs-overridden-60.png" alt="find favorites"> | |
| <!-- ===================================================================================== --> | |
| <h2 class="tutorial"><a name="tweakingthefavorites"></a>Tweaking the Favorites Window</h2> | |
| <p> | |
| In the subfolders of a module suite's <tt>branding</tt> folder, which | |
| is visible in the Files window, you | |
| can override strings defined in the NetBeans sources. In | |
| this section, you will override strings that define | |
| labels used in the Favorites window. For example, we | |
| will change the "Favorites" label to "HTML Files", | |
| because we will use that window specifically for | |
| HTML files. | |
| </p> | |
| <ol><li>Open the Files window and | |
| expand the module suite's <tt>branding</tt> folder. | |
| <li>Create a new folder structure within <tt>branding/modules</tt>. | |
| The new folder should be named <tt>org-netbeans-modules-favorites.jar</tt>. | |
| Within that folder, create a folder hierarchy | |
| of <tt>org/netbeans/modules/favorites</tt>. Within the final folder, | |
| i.e. <tt>favorites</tt>, create a new <tt>Bundle.properties</tt> file. | |
| This folder structure and properties file matches the | |
| folder structure in the NetBeans sources that relate to | |
| the Favorites window. | |
| <li>Add the strings shown in the screenshot below, | |
| to override the same strings defined in the matching | |
| properties file in the Favorites window sources:</p> | |
| <p><img border="1" src="../../images/tutorials/htmleditor/favorites-branding-60.png" alt="find favorites"> | |
| <p>For ease of copying and pasting, these are the strings defined above: | |
| <pre>Favorites=HTML Files | |
| ACT_AddOnFavoritesNode=&Find HTML Files... | |
| ACT_Remove=&Remove from HTML Files List | |
| ACT_View=HTML Files | |
| ACT_Select=HTML Files | |
| ACT_Select_Main_Menu=Select in HTML Files List | |
| # JFileChooser | |
| CTL_DialogTitle=Add to HTML Files List | |
| CTL_ApproveButtonText=Add | |
| ERR_FileDoesNotExist={0} does not exist. | |
| ERR_FileDoesNotExistDlgTitle=Add to HTML Files List | |
| MSG_NodeNotFound=The document node could not be found in the HTML Files List.</pre> | |
| </ol> | |
| <!-- ===================================================================================== --> | |
| <h2 class="tutorial"><a name="runningtheapplication"></a>Running the Application</h2> | |
| <p> | |
| Running your application is as simple | |
| as right-clicking the project node | |
| and choosing a menu item. | |
| </p> | |
| <ol> | |
| <li>Right-click the application's project node and | |
| choose Clean and Build All. | |
| <li>Right-click the application's project node and | |
| choose Run:</p> | |
| <p><img border="1" src="../../images/tutorials/htmleditor/run-app-60.png" alt="running the application"> | |
| <li>After the application is deployed, you can right-click | |
| inside the Favorites window and choose a folder containing | |
| HTML files, and then open an HTML file, as shown below:</p> | |
| <p align="left"><img src="../../images/tutorials/htmleditor/html_editor_60.png" border="1" alt="splash screen panel"> | |
| </ol> | |
| <!-- ===================================================================================== --> | |
| <h2 class="tutorial"><a name="updatingtheapplication"></a>Including Update Functionality</h2> | |
| <p> | |
| To make your application extendable, you need to let your | |
| users install modules to enhance the application's | |
| functionality. To do so, you simply need to enable a few | |
| extra modules, which will bundle the Plugin Manager with | |
| your HTML Editor. | |
| </p> | |
| <ol><li>Right-click the module suite project and | |
| choose Properties. In the Project Properties dialog box, | |
| use the Libraries panel and select the checkboxes that | |
| are highlighted below:</p> | |
| <p><img border="1" src="../../images/tutorials/htmleditor/auto-update-60.png" alt="running the application"> | |
| <li>Right-click the application's project node and | |
| choose Clean and Build All. | |
| <li>Run the application again and notice that | |
| you now have a new menu item, named "Plugins", | |
| under the Tools menu:</p> | |
| <p align="left"><img src="../../images/tutorials/htmleditor/auto-update2-60.png" border="1" alt="splash screen panel"> | |
| <li>Choose the new Plugins menu item and install | |
| some plugins that are useful to your HTML Editor. | |
| Browse the <a href="http://plugins.netbeans.org/PluginPortal/">Plugin Portal</a> | |
| to find some suitable ones. | |
| </ol> | |
| <!-- ===================================================================================== --> | |
| <h2 class="tutorial"><a name="distributingtheapplication"></a>Distributing the Application</h2> | |
| <p> | |
| The IDE can create a JNLP application, for web | |
| starting your application, as well as a ZIP file, | |
| which includes the application's launcher. In this | |
| section, we examine the latter approach. | |
| </p> | |
| <ol><li>Right-click the application's project node and | |
| choose Build ZIP Distribution, as shown below:</p> | |
| <p><img border="1" src="../../images/tutorials/htmleditor/zip-app-60.png" alt="running the application"> | |
| <p>A ZIP file is created in the module suite's <tt>dist</tt> | |
| folder, which you can see in the Files window. | |
| <li>After unzipping the application, you should see the | |
| following:</p> | |
| <p><img border="1" src="../../images/tutorials/htmleditor/unzipped-app-60.png" alt="running the application"> | |
| <p><b>Note:</b> The application's launcher is created in | |
| the <tt>bin</tt> folder, as shown above. | |
| </ol> | |
| <br /> | |
| <!-- ======================================================================================== --> | |
| <h2><a name="distributingshare"></a>Distributing the HTML Editor via the Shared NetBeans JNLP Repository</h2> | |
| <p> | |
| Finally, let's finetune the <tt>master.jnlp</tt> file that is | |
| generated the first time you start the application. Even though it does the job, it | |
| is not yet ready for distribution. At the very least, you need to change the | |
| information section to provide better descriptions and icons. | |
| <p> | |
| Another change to the standard JNLP infrastructure is the use of a | |
| shared JNLP repository on www.netbeans.org. By default, the JNLP application | |
| generated for a suite always contains all its modules as well as all the modules it depends on. | |
| This may be useful for intranet usage, but it is a bit less practical for | |
| wide internet use. When on the internet, it is much better if all the | |
| applications built on the NetBeans Platform refer to one repository of | |
| NetBeans modules, which means that such modules are shared and | |
| do not need to be downloaded | |
| more than once. | |
| </p> | |
| <p> | |
| There is such a repository for NetBeans 6.0. It does not contain all | |
| the modules that NetBeans IDE has, but | |
| it contains enough to make non-IDE applications like our HTML Editor | |
| possible. (<a href="https://netbeans.org/bugzilla/show_bug.cgi?id=112726">See issue 112726.</a>) | |
| To use the repository you only need to modify <tt>platform.properties</tt> | |
| by adding the correct URL: | |
| </p> | |
| <pre class="examplecode"> | |
| # share the libraries from common repository on netbeans.org | |
| # this URL is for release60 JNLP files: | |
| jnlp.platform.codebase=https://netbeans.org/download/6_0/jnlp/ | |
| </pre> | |
| <p> | |
| As soon as the application is started as a JNLP application, all its shared modules | |
| are going to be loaded from netbeans.org and shared with other | |
| applications doing the same.</p> | |
| <br /> | |
| <!-- ======================================================================================== --> | |
| <br> | |
| <div class="feedback-box"><a href="https://netbeans.org/about/contact_form.html?to=3&subject=Feedback:%20NetBeans%20Platform%206.0%20Quick%20Start%20Tutorial">Send Us Your Feedback</a></div> | |
| <br style="clear:both;" /> | |
| <!-- ======================================================================================== --> | |
| <h2><a name="nextsteps"></a>Next Steps</h2> | |
| <p>Now that you have learnt a lot of nice tricks and have a working application built on the NetBeans Platform, you | |
| can look at the XML Layer node's subnodes some more. Without much work, you can continue finetuning your application, | |
| pruning and tweaking it until you have a solid, streamlined application that does exactly what you want it to do. Next, | |
| find out how easy it is to add your own modules to your application. The | |
| <a href="https://platform.netbeans.org/tutorials/index.html">NetBeans Platform Learning Trail</a> show you a wide variety | |
| of use cases for extending the HTML Editor. For example, maybe you want to add your own menu items in the menu bar. | |
| Or maybe you want to provide additional HTML snippets in the component palette. Both these scenarios, and many more, | |
| are outlined in the tutorials in the Module Developer's Resources. | |
| <p>Also take a look at the | |
| <a href="https://platform.netbeans.org/tutorials/60/nbm-paintapp.html">NetBeans Platform 6.0 Paint Application Tutorial</a>, which shows | |
| you how to create your own Paint Application. Finally, a slightly more complex application is | |
| provided in the <a href="https://platform.netbeans.org/tutorials/60/nbm-feedreader.html">NetBeans Platform 6.0 Feed Reader Tutorial</a>. | |
| </p> | |
| <hr> | |
| <!-- ======================================================================================== --> | |
| </body> | |
| </html> |