[RSS]

Support for Facelets in NetBeans IDE

There are lots of requests that asking when and how the Facelets support be available on NetBeans 6.1. Yes, there is plan to officially release the support NBMs by the update center for NetBeans 6.1. We are currently working on that to resolve several compatible issues and migrate the internal APIs usage to NetBeans 6.1. When it is ready for the final release, we will announce it and make it available and show them under the Available Plugins list of NetBeans 6.1.

Build from Sources

According to the Open Sources concept, any users or developers can always pre-build their latest binaries and try/test before the official releases. This is also true for the Facelets plugin and believe me, it's very simple and can be done in just minutes! We have already done many tasks for the NetBeans 6.1 migration to ease the build requirement.

  1. Install your NetBeans 6.1 if you have not yet done so. You can get the installer from the NetBeans 6.1 download page.
  2. Get the sources: you can use the NetBeans GUI or simply your system command line to get the Facelets Support sources.
    • By NetBeans GUI: Invoke the CVS Checkout dialog by menu Versioning -> CVS -> Checkout..., fill the CVS Root (:pserver:your_userid@cvs.dev.java.net:/cvs) and Password, and click on Next.
      GetSource1.gif
      In the next dialog, use 'nbfaceletssupport' as the Module name and enter your planned working directory as the Local Folder, and click on Finish.
      GetSource2.gif
      After the IDE finished the checkout, it asks whether to open the projects or not, click on Open Project... (see next step)
    • By Command Prompt: Alternately you can checkout the CVS sources by just few command lines if you prefer.
      cvs -d :pserver:your_userid@cvs.dev.java.net:/cvs login cvs -d :pserver:your_userid@cvs.dev.java.net:/cvs checkout nbfaceletssupport
  3. Open the Facelets projects: Under NetBeans IDE, use menu File -> Open Projects... to invoke the Open Project dialog, select the Facelets projects and then click on Open Project.
    OpenProject.gif
  4. Build the NBMs: Under the Projects panel, right click on the Facelets Suite node and select the Create NBMs context menu to build all needed plugin NBMs.
    BuildNBM.gif
    Now you have done the build and all 4 NBMs can be found under the following directory that you may want to copy to somewhere for your later use:
    nbfaceletssuite/build/updates/org-netbeans-modules-web-frameworks-facelets.nbm nbfaceletssuite/build/updates/org-netbeans-libs-facelets.nbm nbfaceletssuite/build/updates/org-netbeans-modules-web-frameworks-facelets010114.nbm nbfaceletssuite/build/updates/org-netbeans-modules-web-jsf-simplesnippets.nbm

If you do want to skip the 'build from sources' steps, you may just download these NBMs (nbfaceletssupport-6.1.zip) that I have done.

Install the Facelets Support NBMs

The next step is to install the Facelets NBMs that we have just created into the IDE. You can invoke the Plugins dialog by menu Tools -> Plugins, select the Downloaded tab and click on Add Plugins... to open these 4 NBMs.

InstallNBM1.gif

Then click on Install, follow few Next/Continue/Finish clicking and accept the license agreements, finally your IDE is ready for the Facelets Support, on the latest released NetBeans 6.1!

Create Facelets Support Web Project

After installed the Facelets Support, you will find a new entry 'Facelets' in the Frameworks panel when you create a new web project. Select and check this entry before clicking on Finish. Multiple frameworks selection should work but is not a supported feature as there is no much testing has been done here.

CreateProject.gif

As you can see, options for 'JavaServer Faces Configuration' are all non-editable because the project creating currently only supports the default settings. However, it is still possible to modify them after the project has been created.

  • Debug: control the facelets.DEVELOPMENT parameter in the web.xml file. <context-param> <param-name>facelets.DEVELOPMENT</param-name> <param-value>false</param-value> </context-param>
Note: The parameter, facelets.DEVELOPMENT, is not required, but allows you to use the error-handling facility of Facelets. The browser will show more interesting error handling message, stack trace, component tree, and scoped variables if you enabled it.
  • Skip Comments: control the facelets.SKIP_COMMENTS parameter in the web.xml file. <context-param> <param-name>facelets.SKIP_COMMENTS</param-name&> <param-value>true</param-value> </context-param>
Note: Once you are using Facelets you are perhaps interested in putting some comments to your XHTML template. But not every component likes this, because the comments are interpreted as regular components and not every component allows every other component to be its child. To handle those comments without any side effect, add facelets.SKIP_COMMENTS to your project's web.xml file with true value.
  • Create Example Facelets Files: create a simple welcome page.
  • Libraries: the bundled Facelets libraries 1.1.14 are default selected. You may create your own version of library or just do not append any in case you plan to have your own copy of Facelets support libraries installed in your target servers. The concept is the same as seen in the 'JavaServer Faces' framework.<br><br>
Note: You may want to create a new Facelets library for different version or the latest distribution got from the Facelets project page. Check the Create New Library under the Libraries tab, use the Browse file chooser to locate the folder where you unzipped the Facelets distribution and enter a meaningful Version number for later reference. The IDE validates the folder if it contains jsf-facelets.jar and a lib directory. The newly created library will later be shown in the Library Manager as well.

To see what you have for the new Facelets project, expand the folder nodes under the Project panel.

  • default.css: a default Cascading Style Sheets (CSS).
  • forward.jsp: a default welcome JSP page that has been defined in web.xml file. The contents have jsp:forward to the Facelets page template-client.xhtml.
  • template-client.xhtml: the real welcome Facelets page.
  • template.xhtml: the ui:composition template used by the welcome Facelets page template-client.xhtml.
  • faces-config.xml: the JavaServer Faces configuration file. The definition of a Facelets view handler is included.
  • Facelets 1.1.14 jar files: the bundled Facelets libraries needed for the Facalets projects. If you are using a server that does not directly support the JSF RI, then the bundled JSF RI libraries will also be included.

ProjectsView.gif

The IDE recognizes a file as a Facelets file if:

  • it has xhtml extension
  • its root tag includes http://java.sun.com/jsf/facelets in the list of namespaces

You may want to try the one-click deploy toolbar button (the green arrow) now to see the simple welcome Facelets been deployed on your browser.

Add more Facelets Pages and Contents

Now we are going to add more interesting contents to our Facelets project. When you focus on the Facelets .xhtml editor, you will notice that there are extra palettes available for your Facelets pages.

Palette.gif

Let's add more JSF components into our boring welcome page by drag-n-drop the palette to the .xhtml editor. I have done here by just drag-n-drop an outputText and a commandButton to the editor and change their values to something meaningful.

    <ui:define name="body">
       Hello, this text comming from template client.
       <p>
          <h:outputText value="Go to Next Page:"/>
          <h:commandButton id="GO" value="GO"/>
       </p>
    </ui:define>

Click on the Run button and you will see the following contents appear in your browser:

Deployment1.gif

To add more Facelets files to your project, right click on the Web Pages node and select New -> Other... to invoke the New File dialog. Select the JavaServer Faces category and you will see there are 3 templates for the Facelets support:

NewFile.gif

  • Facelets Simple File: Create a simple Facelets file, an xhtml file which has <html> tag as a root tag and also defines ui namespace.
  • Facelets Template: Create a new Facelets template with the option to choose from eight layouts either be done through css file or table tag.
    When you select the CSS style, the IDE will generate an xhtml template file which uses the CSS <div> layout style and refers to a newly create cssLayout.css file under the css folder if it is not there. Otherwise, it will just refer to the exist cssLayout.css file without change the contents. If you select the Table style, the new xhtml template file will use the HTML <table> style and refer to a newly create tableLayout.css file instead. Both the cssLayout.css and tableLayout.css files contain the layout definitions.
    NewTemplate.gif
  • Facelets Template Client: Create a new Facelets template client by the Template selected, mandatory. The IDE will parse the selected Template and generate <ui:define name="xxx"> tag in the client file for every <ui:insert name="xxx"> tag found. You can also choose either using the <html> tag or the <ui:composition> tag as the root tag in the generated template client.
    NewTemplateClient.gif

Use Code Completion

The IDE provides tag code completion for all Facelets tag libraries that are included in the web project. The IDE scans the tag libraries definition file in the same way as Facelets does. These XML files can be referenced in the following two ways:

  • In a ";" delimitted list within your web.xml under the init-param "facelets.LIBRARIES".
  • In JAR's META-INF folder with a file extension of ".taglib.xml".

By default code completion offers the tags with default prefixes. Developers can add extra namespace definition or modify the default prefix. The code completion will adjust to include the new prefixes in the list.

CodeCompletion1.gif

The default prefixes are:

xmlns="http://www.w3.org/1999/xhtml" JSTL Core
xmlns:ui="http://java.sun.com/jsf/facelets" JSF - Facelets

More available prefixes are also available when drag-n-drop components from the Palette:

xmlns:f="http://java.sun.com/jsf/core" JSF - core components
xmlns:h="http://java.sun.com/jsf/html" JSF - html components

The namespace will automatically be imported into the root tag when you drag-n-drop a Facelets component or by using the code completion to add one.

Add Facelets component by Code Completion: Namespace automatically been added into the root tag:
CodeCompletion2.gif CodeCompletion3.gif

Extra html tags support for the attribute jsfc (JavaServer Faces Component) are available (see Facelets developer documentation) from the code completion.

Code Completion shows the attribute jsfc: Code Completion for the attribute jsfc: Namespace automatically been added into the root tag:
CodeCompletion4.gif CodeCompletion5.gif CodeCompletion6.gif

By default, the Facelets tag code completion provides tag attributes for the following standard Facelets libraries:

  • http://java.sun.com/jsf/facelets
  • http://java.sun.com/jsf/html
  • http://java.sun.com/jsf/core
  • http://java.sun.com/jstl/core
  • http://java.sun.com/jsp/jstl/functions

The IDE also scans the project classpath for all tld files. The code completion will provide extra attribute support if the tld file defines the Facelets Tag library. Their associate dynamic help will also be provided.

CodeCompletion7.gif

By using the Hyperlink, developers can fast navigate from one source to another reference. You can visualize the link by holding down the CTRL key and mouse over a hyperlink active area. After you see the text changed into a link, click on it by the left mouse button. An appropriate source should be open. The tables below briefly displays this feature in the Facelets support.

  • Hyperlinks in Facelets tags
Example File opened
<ui:composition template = "/template.xhtml"> the template source
<ui:include src = "/content/top.xhtml"> the source file
  • Other hyperlinks in Facelets files
Example File opened
<h3>from #{NumberBean.min} to #{NumberBean.max}</h3> the faces configuration file on position where the managed bean been defined
<h3>from #{NumberBean.min} to #{NumberBean.max}</h3> the appropriate java file on position where the getter for the property been defined

Refactoring Support

The refactoring support processes all files in the list of JSF configuration files. Bean and Java class/method usages are found in bean and alias elements and their subelements, as well as elements in the util namespace. In the following examples, it creates 2 managed beans, ManagedBeans.java and ManagedBeans2.java. Right click on the ManagedBeans.java node and select Refactor -> Rename... and then click on Preview under the dialog. You will see the preview of refactoring ManagedBeans.java. The second example shows renaming the package name from foo to bar.

Example Refactoring UI
Managed Beans Refactoring1.gif
Folder / Package Refactoring2.gif

Move support associate with the refactoring is also provided. The following example shows the preview of moving ManagedBeans.java from package foo to package bar.

Example Move UI
Managed Beans Move.gif

Save Delete support associate with the refactoring is also provided which will search the usage with preview.
SafeDelete.gif

Find usages

The Facelets support will plug into the Java find usages to show JSF beans definitions which refer to Java elements (classes, methods, fields, properties). The Find Usages action will be available for bean definitions as well, to show beans used by other beans. The following example shows how the managed bean file, ManagedBeans.java has been referred by the JSF configuration files and other bean files.

Example Usages UI
Managed Beans Usages.gif

Create Sample Projects

There are two sample projects included in these modules. The first one is Facelets Template Examples that shows the example of layouts usage. The second one is the well known Number Guess Example by using the Facelets. You may simply create the project and deploy to see the Facelets in your browser.

SampleProject.gif

Uninstall the Facelets Support

In case you need to uninstall the Facelets Support for any reason, use the menu Tools -> Plugins to get the dialog, select the Installed tab and choose 'Facelets Support', 'Simple JSF/Facelets Snippets', and 'Facelets Library 1.1.14', then click on Uninstall to uninstall the support.

UninstallNBM.gif

Attachments

BuildNBM.gif Info on BuildNBM.gif 12191 bytes
CodeCompletion1.gif Info on CodeCompletion1.gif 31414 bytes
CodeCompletion2.gif Info on CodeCompletion2.gif 6148 bytes
CodeCompletion3.gif Info on CodeCompletion3.gif 4922 bytes
CodeCompletion4.gif Info on CodeCompletion4.gif 5880 bytes
CodeCompletion5.gif Info on CodeCompletion5.gif 6783 bytes
CodeCompletion6.gif Info on CodeCompletion6.gif 5117 bytes
CodeCompletion7.gif Info on CodeCompletion7.gif 18485 bytes
CreateProject.gif Info on CreateProject.gif 23249 bytes
Deployment1.gif Info on Deployment1.gif 2497 bytes
GetSource1.gif Info on GetSource1.gif 15138 bytes
GetSource2.gif Info on GetSource2.gif 16384 bytes
InstallNBM1.gif Info on InstallNBM1.gif 25405 bytes
Move.gif Info on Move.gif 28664 bytes
NewFile.gif Info on NewFile.gif 22812 bytes
NewTemplate.gif Info on NewTemplate.gif 20202 bytes
NewTemplateClient.gif Info on NewTemplateClient.gif 18713 bytes
OpenProject.gif Info on OpenProject.gif 19092 bytes
Palette.gif Info on Palette.gif 47917 bytes
ProjectsView.gif Info on ProjectsView.gif 12845 bytes
Refactoring1.gif Info on Refactoring1.gif 32624 bytes
Refactoring2.gif Info on Refactoring2.gif 35741 bytes
SafeDelete.gif Info on SafeDelete.gif 10697 bytes
SampleProject.gif Info on SampleProject.gif 24156 bytes
UninstallNBM.gif Info on UninstallNBM.gif 33477 bytes
Usages.gif Info on Usages.gif 12085 bytes
nbfaceletssupport.zip Info on nbfaceletssupport.zip 3127120 bytes