JSF Central - Building JSF 2.0 Composite Components Based on JavaFX with NetBeans
JSF Central

 
 Home 
 
 Products 
 
 Articles & Books 
 
 Resources 
Building JSF 2.0 composite components based on JavaFX with NetBeans
 
Building JSF 2.0 Composite Components Based on JavaFX with NetBeans
by Hamilton Matos
07 Oct 2011 03:30 EDT

Most people think of JSF as a technology for building standard HTML applications. However, the JSF 2.0 composite model is quite flexible and can work with other technologies as well. In this article, Hamilton Matos will show how to create a JSF component that is based on JavaFX.


Some of the changes present in version 2.0 of JavaServer Faces (JSF) are related to the process of creating custom components. In the previous versions, it was necessary to follow a series of steps in order to create even simple components. So, if you wanted to create a component that was, for example, responsible for showing a formatted sequence of input fields you had to:

  • create a Tag Library Descriptor (TLD) file;
  • create a tag handler class;
  • create a class to hold the logic of the component;
  • create a class responsible for rendering the component;
  • enter some data in the faces-config.xml configuration file.

In order to enhance the process of creating components, the JSF expert group came up with a strategy called composite components. The main idea of the model is to rely on conventions in order to ease the process of creating components. For simple scenarios, it is possible to build the component in a single file with no further configuration.

With this new strategy it is easier to create and maintain components. Also, due to the flexibility of composite components, it is possible to integrate different technologies within the components in order to achieve a given behavior. For example, dynamically generated charts that allow user interaction require some third party libraries or technologies such as Javascript, JFreeChart, Flex, JavaFX, and so on. JSF 2.0 allows you to integrate these technologies into components. With this approach it is possible for developers to work normally with components that will work behind the scenes to provide them with complex functionality.

JSF 2.0 composite components

Let’s take a look at the process of creating composite components in JSF 2.0. I will show how to create a simple component that renders two input text fields. In the example, the parameters that the component will accept are the labels for each field. If you want to follow along, you can download the sample applications.

Strategy for creating composite components

One of the strategies that you can use to build composite components is to create the functionality in the standard way. That is, build the HTML page normally, including the mechanisms you may need, such as Javascript, CSS, etc. Once you get the functionality working as desired, you can wrap it as a composite component. The component can then be packaged and distributed for usage.

In order to build the example we will use NetBeans 6.9 and GlassFish v3.0. NetBeans offers a wide range of fetaures for working with JSF 2.0. There’s even an option for refactoring existing code into a composite component.

One of the purposes of the example component could be to check that both fields are equal, such as when confirming email. Let’s start by creating a new web project and adding the JavaServer Faces framework, as shown in the steps in figure 1.

  Figure 1: Creation of a web project with JSF 2.0 support in NetBeans 6.9..
Figure 1: Creation of a web project with JSF 2.0 support in NetBeans 6.9..

In JSF 2.0, Facelets is the standard view declaration language for writing pages, so NetBeans 6.9 will create a page called index.xhtml automatically. The purpose of the example is to provide a component that renders two input fields with labels, so let’s create these elements in index.xhtml, as shown in figure 2.

  Figure 2: Standard creation of the functionality desired for the component.
Figure 2: Standard creation of the functionality desired for the component.

For this example, we wanted two input text fields with labels for each one. Now, these elements will be wrapped as a composite component. NetBeans 6.9 has refactoring support for doing that. It is accessed following the steps as shown in figure 3: select the elements we want to be present in the component. In this case, they are the labels and input fields. Then, with these elements selected, we right click and choose the menu option “refactor”, and the item “convert to composite component”.

  Figure 3: NetBeans 6.9 feature for refactoring to composite component.
Figure 3: NetBeans 6.9 feature for refactoring to composite component.

The next screen will provide some options for creating the component. The example will use the values as shown in figure 4.

  Figure 4: Values for the sample composite component.
Figure 4: Values for the sample composite component.

The index.xhtml now has a declaration of the component just created. Let’s come back to index.xhtml later on when we are finished with the component.

Once the component is created, it will be available under the folder specified in the “Folder” property as shown in Figure 4. If you check the sampleComponent.xhtml file, you will notice that it was generated with standard composite components sections such as <cc:interface> and <cc:implementation>. Notice that the elements that we wrapped previously are now present under the <cc:implementation> tag as in figure 5.

  Figure 5: Generated content of file sampleComponent.xhtml.
Figure 5: Generated content of file sampleComponent.xhtml.

The tag <cc:interface> is where we put the attributes that we want available for the components. In this case, they will be the labels for the input texts. Please reference JSF 2.0 documentation in order to check the other available options for these sections. We should insert the two attributes as shown in figure 6. Inside the implementation section, we will change the value property of each outputLabel so that they will be retrieved according to the values present in the interface.

  Figure 6: Interface and implementation areas modified.
Figure 6: Interface and implementation areas modified.

Now it’s time to get back to index.xhtml and make the final changes. Include the tag library of our component (http://java.sun.com/jsf/composite/sampleComponent) and add the two label attributes values for testing. Figure 7 shows the final result of the component, as well as how the component is rendered in the browser.

  Figure 7: Final composite component.
Figure 7: Final composite component.

As mentioned before, this is just a simple component to show the main parts of the building process. In this same way, it is possible to add features to the sampleComponent.xhtml such as on the fly validation, messages, different behaviors, etc. Since you are able to manipulate the values passed to the parameters, you can modify the component as you need.

JavaFX

JavaFX provides developers with a platform for building rich internet applications. Some of the features include support for deployment at different devices, integration with graphical designing tools, and support by IDEs. It’s one of the newest Java-based technologies and its current version, 1.3 was released on April, 2010.

3D Pie Chart example

I’ll show how to create a simple 3D pie chart in JavaFX using NetBeans 6.9. Under menu File, choose the New Project option. Figure 8 shows the steps to create a blank project.

  Figure 8: Create a new JavaFX desktop business application.
Figure 8: Create a new JavaFX desktop business application.

This option will allow us to design the stage in the visual composer provided by NetBeans. On the right side of the IDE, there will be two main sections: Palette and Properties. The palette contains most of the elements that we will use for designing the scene such as panels, buttons, labels and others. The Properties tab displays the available properties for the element that we select in the stage.

Expand the Palette tab and scroll to the Charts section. Drag and drop a Pie Chart 3D to the main scene as shown in figure 9.

  Figure 9: 3D Pie Chart created in Visual Composer.
Figure 9: 3D Pie Chart created in Visual Composer.

Now we will bind the data to be displayed in the chart. Select the pie chart in the scene, expand the Properties tab on the right side pane and under the Basic section, click on the button for configuring the property Data as in figure 10.

  Figure 10: Values to display as 3D Pie Chart.
Figure 10: Values to display as 3D Pie Chart.

For the example, we will insert the values manually. This can be done by checking the radio button "Use specified value:" and inserting the values as Value,Label pairs.

Under the menu Run, click on Run Main Project. Figure 11 shows the final result for the 3D Pie Chart JavaFX application.

  Figure 11: JavaFX 3D Pie Chart.
Figure 11: JavaFX 3D Pie Chart.

Now that you know the basics of the processes for creating a JSF 2.0 composite component as well as a simple JavaFX application, let’s see how it’s possible to get them together in order to offer a functionality for rendering JavaFX charts through JSF.

JavaFX in JSF 2.0 composite components

We will use the same example of the 3D Pie Chart along with the strategy for composite components described previously in order to create the JavaFX-based JSF 2.0 composite component.

Adapting the 3D Pie Chart example

The component that we will create will accept two attributes: labels and values. So, the user of the component will be able to provide a list of labels along with the values for each label to be displayed in the chart. Please note that we could support additional features with the same process. The composite component could, for example, provide options for visual effects, rendering in 2D, etc. The composite component could then pick up the individual values and pass them to the JavaFX application.

In order to have the component and JavaFX working together, we have to define a way for the component to pass values to be processed by the JavaFX application. This can be done through the class javafx.lang.FX. This class has a static function called getArgument() that receives a String and returns an Object. Figure 12 shows how things will be put together.

  Figure 12: Passing values between composite components and JavaFX.
Figure 12: Passing values between composite components and JavaFX.

Let’s get back to the JavaFX application and change the way the values are retrieved. Click on the pie chart element in the stage. Under the Properties tab on the right side, under the Basic section, choose the button for the attribute Data. Now we will build a function that will be responsible for creating the chart according to the values that we pass through our composite component. Check the option “Use the value resolved from function” as shown in figure 13, and write the name of the function. When we click the Generate button, a blank function will be created with the correct signature.

  Figure 13: Attaching the values of the chart with a function.
Figure 13: Attaching the values of the chart with a function.

The function will be responsible for retrieving the external data and building the chart. Let’s modify that according to following code: function getPieChart3DValues(): javafx.scene.chart.PieChart.Data[] { var labels: String[] = stringToArray({ getExternalParameter("labels") }); var values: Number[] = { stringToNumberArray({ getExternalParameter("values") }) }; return for (s in labels) { PieChart3D.Data { label: labels[indexof s] value: values[indexof s] } }; }

JavaFX script will be discontinued in the next release of JavaFX, but the concept will be the same using pure Java or maybe other supported languages such as Groovy or Scala. The syntax of JavaFX Script is different from standard Java, but it’s not hard to understand what is going on. The two values that we will retrieve from our component are the labels and the values. The function getExternalParameter(String) will retrieve these two values from the component. Since we will be able to pass only Strings to the JavaFX application, we have the private functions stringToArray and stringToNumberArray that are responsible for converting the values for us. This is basically what needs to be done in the JavaFX application for communicating with our composite component.

The next step is changing the execution model of the JavaFX application. This will tell the IDE to generate the files we need to be wrapped in our component. Right click on the project and choose the option Properties. Under the Categories section, select Run. The Standard execution option will be selected. Change this to Run in Browser as shown in figure 14.

  Figure 14: Execution model to run in browser.
Figure 14: Execution model to run in browser.

As you clean and build the project with this option selected, the IDE will generate the standard files to have the application running on the browser. Select the menu Run, and the option Clean and Build Main Project. Go to the root folder of the project. NetBeans will generate a folder called dist. This folder will contain the files we need. We will get back to these files as we build the composite component.

Building the composite component

Let’s build a new web project with JSF framework enabled as described previously. Create a composite component with the attributes labels and values as shown in figure 15.

  Figure 15: Basic structure of the JavaFX pie chart 3D composite component.
Figure 15: Basic structure of the JavaFX pie chart 3D composite component.

What we need to do now is to populate the <cc:implementation> section with the code for calling the JavaFX application.

Let’s go back to the dist folder under the root of our JavaFX pie chart application and copy the automatically generated files: PieChartExample.html, PieChartExample.jar and PieChartExample_browser.jnlp to our resources/pieChart3D folder, as in figure 16.

  Figure 16: Files to be copied to the composite component project.
Figure 16: Files to be copied to the composite component project.

We need the JAR and JNLP files to have the application running correctly. We also want to check the content of the HTML file. We will copy its structure into our <cc:implementation> section.

Open the PieChartExample.html. This file will have two <script> tags. One contains a reference to dtfx.js for executing the JavaFX and the other has a reference to the JAR file. We will copy these two tags and their contents into the <cc:implementation> section of our pieChart3D.xhtml file, as shown in figure 17.

  Figure 17: JavaFX script tags inside composite component.
Figure 17: JavaFX script tags inside composite component.

We no longer need the PieChartExample.html, so you can delete it.

Figure 17 also shows some changes that are necessary to have the component working properly. For example, you can change the width and height with arbitrary values to fit the component area.

Another important change is the <f:view> tag around the <script> tags. This is necessary because some browsers like Chrome and Safari will create a CDATA section automatically when the component is rendered, and this will cause the JavaFX content to not be displayed.

We should now modify the PieChartExample_browser.jnlp file to reference our application address correctly as shown in figure 18.

  Figure 18: Modified jnlp file.
Figure 18: Modified jnlp file.

If you run the web application you will see that the JavaFX content will not be displayed. This is because we still have to pass the values of the attributes to the JavaFX section. Modify the pieChart3D.xhtml as in figure 19.

  Figure 19: Final pieChart3D.xhtml file.
Figure 19: Final pieChart3D.xhtml file.

The values of the attributes can be retrieved from the <cc:interface> section as #{cc.attrs.nameOfTheAttribute}. So, what we have to do is add the two attributes of our component to the JavaFX section. This way, when the JavaFX section is created, the values of our composite component attributes will be passed to the JavaFX dynamically.

Run the web application and the browser will display the composite component values in JavaFX.

  Figure 20: Composite component displaying data through JavaFX.
Figure 20: Composite component displaying data through JavaFX.

Figure 20 displays the final result of the composite component encapsulating the JavaFX application. Any additional functionality would follow the same basic principles described. You could, for example, add different parameters to the component, like background color and chart title, and have them reflected on the JavaFX generated chart. You can also add standard HTML to the component, such as a series of charts, or adding style to the panel where the JavaFX is inserted, etc.

Conclusion

The composite components model in version 2.0 of JSF provides great flexibility for building components. Just by following some steps and conventions, it is possible to build components very quickly. This article showed how it is also possible to take advantage of this model to build features that require different technologies, such as JavaFX. When this is necessary, composite components are also a great feature for maintenance, since third parties can be arranged in centralized ways.

Resources



RSS feed(all feeds)

The Editor's Desk
Podcasts
Inside Facelets
In the Trenches

Site version 1.83  Report web site problems

Copyright (C) 2003-2015 Virtua, Inc. All Rights Reserved. Java, JavaServer Faces, and all Java-based marks are trademarks or registered trademarks of Oracle Corporation. in the United States and other countries. Virtua, Inc. is independent of Oracle Corporation. All other trademarks are the sole property of their respective owners.