[jboss-user] [JBoss Tools] - JBoss Tools 3.2.0.GA JSF2 Composite Components Features

Denis Golovin do-not-reply at jboss.com
Wed Mar 16 18:04:48 EDT 2011 

Denis Golovin [http://community.jboss.org/people/dgolovin] modified the document:

"JBoss Tools 3.2.0.GA JSF2 Composite Components Features"

To view the document, visit: http://community.jboss.org/docs/DOC-16511

--------------------------------------------------------------
JBoss Tools introduced JSF 2 Composite Component support in version 3.2.0.M1, it matured through several development versions and got a lot of useful features like:
1. Content assist for component developers
2. Content assist for component users
3. Validation and quick fixes
4. Refactoring
5. Rendering in Visual Editor
6. Source Navigation* in text editor by Ctrl+Right Mouse Button Click on hyperlink
* in visual part by Double Mouse Click

h2. Prerequisites
To check this out lets start from New JSF Project wizard and follow simple steps. Select +"Find JBoss Tools Web -> JSF -> JSF Project"+ in New Dialog (see screenshot below)

 http://community.jboss.org/servlet/JiveServlet/showImage/11402/screenshot1.png  http://community.jboss.org/servlet/JiveServlet/downloadImage/11402/399-350/screenshot1.png 

Then fill "Create JSF Project" step with name and select "JSF 2.0" in "JSF Environment"

 http://community.jboss.org/servlet/JiveServlet/showImage/11403/screenshot2.png  http://community.jboss.org/servlet/JiveServlet/downloadImage/11403/400-326/screenshot2.png 

On last step select Runtime Servlet Container and server to deploy your application to. Runtime is required, if you don't have one just create new.

 http://community.jboss.org/servlet/JiveServlet/showImage/11404/screenshot3.png  http://community.jboss.org/servlet/JiveServlet/downloadImage/11404/400-327/screenshot3.png 

After Finish button's pressed new project appears in navigator. Its structure is shown below and it is reincarnation of JSF 1.2 KickStart project which is implemented using JSF 2 Composite Components.

 http://community.jboss.org/servlet/JiveServlet/showImage/11405/screenshot4.png  http://community.jboss.org/servlet/JiveServlet/downloadImage/11405/398-541/screenshot4.png 

At runtime it should look in your browser like this

 http://community.jboss.org/servlet/JiveServlet/showImage/11407/screenshot7.png  http://community.jboss.org/servlet/JiveServlet/downloadImage/11407/420-210/screenshot7.png 

Lets see what features JBoss Tools provides for JSF 2 Composite Components.


h2. Rendering in Visual Editor

Visual Editor discovers composite components and it is able to render them. inputname.xhtml opened in xhtml editor looks almost the same (see picture below) as at runtime (see picture above)

 http://community.jboss.org/servlet/JiveServlet/showImage/11419/screenshot5.png  http://community.jboss.org/servlet/JiveServlet/downloadImage/11419/600-650/screenshot5.png 

greeting.xhtm does not use composite component to render greeting and this article is going to show how to do this using JBoss Tools features for composite components. We're going to replace greeting text rendering form greeting.xhtml with new demo:greeting component, which takes +demo.User+ instance as attribute and render greeting the same way greeting.xhtml does.

h2. Composite Component Wizard
First, new composite component should be created using JBoss Tools XHTML New Wizard. Picture below show how to call XHTML New Wizard from Web Development Perspective.

 http://community.jboss.org/servlet/JiveServlet/showImage/11408/screenshot8.png  http://community.jboss.org/servlet/JiveServlet/downloadImage/11408/600-436/screenshot8.png 

Then in first step input component name as as shown below.

 http://community.jboss.org/servlet/JiveServlet/showImage/11409/screenshot9.png  http://community.jboss.org/servlet/JiveServlet/downloadImage/11409/400-413/screenshot9.png 

Select Use XHTL Template checkbox and JSF Composite Component from template list.

 http://community.jboss.org/servlet/JiveServlet/showImage/11410/screenshot10.png  http://community.jboss.org/servlet/JiveServlet/downloadImage/11410/400-410/screenshot10.png 
h2. Content Assist
After finishing in opened editor composite:interface and composite:implementation elements should be filed with template attributes and template content. Short description can be provided for composite:interface through shortDescription attribute, but is not used now by JBoss Tools.

 http://community.jboss.org/servlet/JiveServlet/showImage/11411/screenshot11.png  http://community.jboss.org/servlet/JiveServlet/downloadImage/11411/599-314/screenshot11.png 

We are creating component to show greeting message for user, so we need to add attribute "user" to pass it to component. Content assist provides proposal list for all composite:interface children nodes. It also shows documentation in documentation hover for selected proposal.

 http://community.jboss.org/servlet/JiveServlet/showImage/11412/screenshot12.png  http://community.jboss.org/servlet/JiveServlet/downloadImage/11412/600-340/screenshot12.png 

Inserted attribute has cursor located inside quotation marks and that lets to type attribute name as "user" right after proposal is inserted.

 http://community.jboss.org/servlet/JiveServlet/showImage/11413/screenshot13.png  http://community.jboss.org/servlet/JiveServlet/downloadImage/11413/screenshot13.png 

Text editor provides content assist with help for attributes inside tags from composite component namespace.

 http://community.jboss.org/servlet/JiveServlet/showImage/11421/screenshot6.png  http://community.jboss.org/servlet/JiveServlet/downloadImage/11421/screenshot6.png 

Using this content assist it is easy to mark new greeting component attribute "user" as required and provide short description for it. For most attributes there are predefined values available through content assist like it is shown below for "required" attribute.

 http://community.jboss.org/servlet/JiveServlet/showImage/11422/screenshot7.png  http://community.jboss.org/servlet/JiveServlet/downloadImage/11422/screenshot7.png 

After we're done with component's attribute definition it should look like this

 http://community.jboss.org/servlet/JiveServlet/showImage/11414/screenshot14.png  http://community.jboss.org/servlet/JiveServlet/downloadImage/11414/597-82/screenshot14.png 

Implementation for greeting component is going to be simple, it looks almost the same as body definition in greeting.xhtml page. The diffrence is in using cc.attr to reference user attribute.

#{megs.greeting} #{cc.attrs.user.name}!


Finished component in resources/demo/greeting.xhtml should look like it is shown below

 http://community.jboss.org/servlet/JiveServlet/showImage/11423/screenshot8.png  http://community.jboss.org/servlet/JiveServlet/downloadImage/11423/screenshot8.png 

Full text for greeting component is here:

<!DOCTYPE html PUBLIC -//W3C//DTD XHTML 1.0 Transitional//EN
http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd>
<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:h="http://java.sun.com/jsf/html"
      xmlns:composite="http://java.sun.com/jsf/composite"
      xmlns:f="http://java.sun.com/jsf/core"
      xmlns:ui="http://java.sun.com/jsf/facelets">
<head>
<title>Not present in rendered output</title>
</head>
<body>
<composite:interface>
    <composite:attribute name="user" required=""/>
</composite:interface>
<composite:implementation>
    #{megs.greeting} #{cc.attrs.user.name}!
</composite:implementation>
</body>
</html>


To use new greeting component in greeting.xhtml page root html element should be extended with demo composite component namespace. Add namespace *xmlns:ez=" http://java.sun.com/jsf/composite/demo http://java.sun.com/jsf/composite/demo"* after xmlns:f namespce and save the file or new component is not going to be visible for content assist. After removing content of <ui:define name="body"> request content assist by Ctrl+Space and content assist proposal list with components from resources/demo directory appears.

 http://community.jboss.org/servlet/JiveServlet/showImage/11415/screenshot15.png  http://community.jboss.org/servlet/JiveServlet/downloadImage/11415/screenshot15.png 

Select ez:greeting completion proposal and it inserts composite component tag with all required attributes, for greeting component we've defined above it is going to be only user attribute


 http://community.jboss.org/servlet/JiveServlet/showImage/11416/screenshot16.png  http://community.jboss.org/servlet/JiveServlet/downloadImage/11416/screenshot16.png 


If optional attribute should be set use content assist for composite component attributes. For example for greeting component. which has only one attribute, content assist would look like 
 http://community.jboss.org/servlet/JiveServlet/showImage/11417/screenshot17.png  http://community.jboss.org/servlet/JiveServlet/downloadImage/11417/600-293/screenshot17.png 

and it contains attributes with documentation hover filled with shortDescription text.

h2. Validation
JSF 2 Composite Components validator checks correctness of namespace declaration for component and each component from declared namespace. If *demo* component from examples above is renamed to *demos* like it is done on screenshot below
 http://community.jboss.org/servlet/JiveServlet/showImage/102-16511-1-11398/screenshot-validation-1.png  http://community.jboss.org/servlet/JiveServlet/downloadImage/102-16511-1-11398/450-224/screenshot-validation-1.png 

then two warning markers are created for new file after it is saved.

 http://community.jboss.org/servlet/JiveServlet/showImage/102-16511-1-11399/screenshot-validation-2.png  http://community.jboss.org/servlet/JiveServlet/downloadImage/102-16511-1-11399/450-67/screenshot-validation-2.png 

Marker for namespace declaration provides Quick Fix to create a missing folder. If it is selected, demos folder is created in JSF 2 resources folder.

 http://community.jboss.org/servlet/JiveServlet/showImage/102-16511-1-11400/screenshot-validation-3.png  http://community.jboss.org/servlet/JiveServlet/downloadImage/102-16511-1-11400/450-300/screenshot-validation-3.png 

Marker for component from missing namespace also provides Quick Fix, which suggests to create component XHTML file.

 http://community.jboss.org/servlet/JiveServlet/showImage/102-16511-1-11401/screenshot-validation-4.png  http://community.jboss.org/servlet/JiveServlet/downloadImage/102-16511-1-11401/450-372/screenshot-validation-4.png 

If Quick Fix for missing component is selected it reconstructs JSF 2 Composite Component based on tag name and attributes. It leaves implementation part of the component empty

 http://community.jboss.org/servlet/JiveServlet/showImage/11418/screenshot4.png  http://community.jboss.org/servlet/JiveServlet/downloadImage/11418/screenshot4.png 

h2. Refactoring

Refactoring supported for renaming folders referenced in composite component URI and for renaming component XHTML files.
Lets imagine WebContent/resources/demo folder from our project is going to be renamed through Rename action in Package Explorer view. After new folder name is entered, Preview button is going to be activated and it shows that renaming of *demo* folder affects composite component URI in inputname.xhtml page.

 http://community.jboss.org/servlet/JiveServlet/showImage/11434/screenshot23.png  http://community.jboss.org/servlet/JiveServlet/downloadImage/11434/screenshot23.png 

For renaming actual component's xhtml files it suggests to update component names in affected files. On screenshot below it shows what happens when input.xhtml component is renamed in demo folder

 http://community.jboss.org/servlet/JiveServlet/showImage/11435/screenshot22.png  http://community.jboss.org/servlet/JiveServlet/downloadImage/11435/screenshot22.png
--------------------------------------------------------------

Comment by going to Community
[http://community.jboss.org/docs/DOC-16511]

Create a new document in JBoss Tools at Community
[http://community.jboss.org/choose-container!input.jspa?contentType=102&containerType=14&container=2128]
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/jboss-user/attachments/20110316/f59561d1/attachment-0001.html

More information about the jboss-user mailing list