FaceletsSupportSpec

Support for Facelets in NetBeans IDE

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

Install your NetBeans 6.1 if you have not yet done so. You can get the

 installer from the NetBeans 6.1
 download page.

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

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.

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.

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.

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

</tt> layout style and refers to a newly create <tt>cssLayout.css</tt> file under the <tt>css</tt> folder if it is not there. Otherwise, it will just refer to the exist <tt> cssLayout.css</tt> file without change the contents. If you select the Table style, the new <tt>xhtml</tt> template file will use the HTML <tt></tt> 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"> </tt> the template source <tt> <ui:include src = "/content/top.xhtml"> </tt> the source file Other hyperlinks in Facelets files Example File opened <tt> from #{NumberBean.min} to #{NumberBean.max} </tt> the faces configuration file on position where the managed bean been defined <tt> from #{NumberBean.min} to #{NumberBean.max} </tt> 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, <tt>ManagedBeans.java</tt> and <tt>ManagedBeans2.java</tt>. Right click on the <tt>ManagedBeans.java</tt> node and select Refactor -> Rename... and then click on Preview under the dialog. You will see the preview of refactoring <tt>ManagedBeans.java</tt>. The second example shows renaming the package name from <tt>foo</tt> to <tt>bar</tt>. Example Refactoring UI Managed Beans Folder / Package Move support associate with the refactoring is also provided. The following example shows the preview of moving <tt>ManagedBeans.java</tt> from package <tt>foo</tt> to package <tt>bar</tt>. 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, <tt>ManagedBeans.java</tt> 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 Media:nbfaceletssupport_FaceletsSupportSpec.zip