---

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.
     
     In the next dialog, use 'nbfaceletssupport' as the Module name and enter your planned working directory as the Local Folder, and click on Finish.
     
     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.
   
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.
   
   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.

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.

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.

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.

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:

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:

• 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.
  
  
• 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.
  
  

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.

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:

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:

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.

Use Hyperlink

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
Folder / Package

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

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

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

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.

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.

Attachments