GettingStarted

Getting Started

Getting The Plugin

The module is being release as an installable NBM plugin module. The module is NetBeans implementation dependent, so please watch for the implementation version indicated in the file. If the IDE you're using is not the same, please go ahead and try [Installing Into Another NetBeans Version].

1. Download the nbpfcrudgen-x.x-y.y.yimpl.zip plugin file.
2. Unzip the file which contains an NBM file.
3. Launch NetBeans and go to Tools->Plugins.
4. Click on the Downloaded tab.
5. Click on Add Plugins button and browse to the location you downloaded the NBM file to.
6. Select the file and click Ok.
7. The module will appear in the list of downloaded modules.
8. Click on Install. The NetBeans IDE Installer will appear with a summary of modules ready to be instlled.
9. Click Next and accept the license agreement. Note: there is currently no licensed attached to the module, but it is the author's intention to release it under both CDDL and GPL licenses.
10. The module is currently not signed and NetBeans will warn you about that. If you don't feel comfortable installing unsigned code, click Cancel here and wait for a newer version that has a developer's signature attached. If you are Ok with unsigned code, click Continue.
11. NetBeans will complete the installation. If the version of the IDE does not match the implementation version of the module, you may run into a dependency problem and the IDE will not allow you to proceed.
12. The module is now installed and will show up under the Installed tab as PrimeFaces CRUD Generator.

Generating A Sample App

Creating A New Web Application Project

Important: If you are using a newer version of NetBeans (7.3.1+) that ships with Glassfish 4.0 and JSF 2.2, please be sure to download and add the latest PrimeFaces library from the PrimeFaces Download page. As of this writing, PrimeFaces offers version 4.0 under the Community Downloads section. Add the library to your NetBeans installation under Tools -> Ant Libraries and call it "PrimeFaces 4.0". This will make PrimeFaces 4.0 available to the "Web Applciation" wizard.

1. Click on File->New Project.
2. Choose "Java Web" from Categories and "Web Application" from Projects. Click Next.
3. Give your project a name, e.g. SampleApp and choose the Project Location. Leave the rest as is and click Next.
4. Configure Server Settings settings as follows:
   • Choose your Application Server. In a default installation, this will be the GlassFish server 4.0 that came with NetBeans.
   • Set the Java EE Version to Java EE 7 Web (default)
   • Leave the Context Path as is. Click Next.
5. Configure the Frameworks as follows:
   • Put a check mark next to JavaServer Faces.
   • On Libraries tab, use the server library JSF 2.2
   • On Configuration tab, leave JSF Servlet URL Pattern as /faces/* and select Facelets as Preferred Page Language.
   • On Components tab, put a check mark next to PrimeFaces. Note: this should pull in the latest PrimeFaces library that's added under "Ant Libraries"
     Note: Click on More to select your PrimeFaces version if you have registered more than one. The default is PrimeFaces 3.5. After you selected the PrimeFaces version of your choice, click Ok.*
6. Click Finish to create the project.

Note: If you created a CDI project by adding a beans.xml file to it, be sure to visit the [Context Dependency Injection And Its Impact On The Generator] Wiki page which highlights some of the code differences.

Adding Entities

You have two choices for doing this: you can either program your own entities and persistence unit, or you can let NetBeans generate entities from an existing database. For this sample application, the latter is being used.

1. Highlight the project node.
2. Click on File->New File from the menu.
3. Choose "Persistence" from Categories and "Entity Classes from Database" from File Types. Click Next.
4. Specify Database Tables as follows:
   • Configure Data Source. For this sample application, choose jdbc/sample from the list. NetBeans connects to the server-supplied Derby SAMPLE database and populates Available Tables.
   • For this sample, click on Add All button. NetBeans carries over all database tables. Click Next.
5. Configure Entity Classes as follows:
   • Specify Package. Here we type the "entities" (all lower-case).
   • Leave "Generate Named Query Annotations for Persistent Fields" checked.
   • Leave "Generate JAXB Annotations" checked.
   • Leave the check mark next to "Create Persistence Unit". Click Next.
6. Configure Mapping Options as follows:
   • Association Fetch: default
   • Collection Type: java.util.Collection (default)
   • Leave everything else unchecked except for "Use Column Names in Relationships".
7. Click Finish.

NetBeans generates the entities package and seven entity classes:

• Customer.java
• DiscountCode.java
• Manufacturer.java
• MicroMarket.java
• Product.java
• ProductCode.java
• PurchaseOrder.java

It also added a persistence.xml file to the project for referencing the sample database.

Generating PrimeFaces Pages from Entity Classes

Note: The code generator can now detect PrimeFaces version and Apache MyFaces CODI CDI-Extension version!

1. Highlight the project node.
2. Click on File->New File from the menu.
3. Choose "PrimeFaces CRUD Generator" from Categories and "PrimeFaces Pages from Entity Classes" from File Types. Click Next.
4. Click on "Add All >>" and then click Next.
5. Configure Generate PrimeFaces Pages and Classes as follows:
   • Session Bean Package: controllers
   • Backing Bean Package: beans
   • Converter Package: converters
   • PrimeFaces Pages Folder: [leave blank]
   • Generic Include Folder: /WEB-INF/include
   • Entity Include Folder: /WEB-INF/include/entity
   • Localization Bundle Name: /Bundle
   • Default Rows Displayed: 10
   • Default Page Selector: 10,20,30
     You can change this to whatever you like. It affect the drop-down list that is shown in PrimeFaces DataTable's pager.
   • Field name artifacts for foreign fields: descr,name
   • Leave all check marks in the following fields:
     Create, Edit, Delete, View, Sort, Filter
   • Notice the PrimeFaces Version, MyFaces CODI Version and JSF Version matching your project's Libraries classpath and setup. If you've followed this sample app, you will see 4.0 for PrimeFaces Version, nothing for MyFaces CODI Version and 2.2 for JSF Version. CODI is only important for CDI projects prior to JSF 2.2 to enable @ViewAccessScoped annotations. Recent versions of JSF starting with 2.2 have native support for CDI @ViewScoped annotations.
   • Leave "Override existing files" unchecked, unless you previously had files generated.
6. Click Finish.

Inspecting The Generated Code

NetBeans will now generate multiple files under source packages and under Web Pages. Here is a break-down of what was created:

1. Three packages, called controllers, entities and converters
2. Seven directories under the "Web Pages" node, named after each entity
3. A resources folder containing css/pfcrud.css Cascading Style Sheet
4. Two files under the "Web Pages/WEB-INF/include" node called:
   • apphome.xhtml containing PrimeFaces <p:menubar> and <p:menuitem> tags for each entity
   • template.xhtml containing one PrimeFaces <p:layout> and five <p:layoutUnit> tags, four for each side, and one for the middle, where the body will be inserted for each page. The layoutUnit with position="north" also has the appmenu.xhtml file included so that the menu bar will show on top.
5. One file under the "Web Pages" node called:
   • index.xhtml with a welcome message
6. Entity pages are broken down into include files and publicly exposed files. Include files are put inside "Web Pages/WEB-INF/include/entity" folder, all other pages are inside folders inside the root structure. Each entity will have its own sub-folder named after the entity.
7. Each entity will have five files associated with it:
   • Create.xhtml, Edit.xhtml, View.xhtml and List.xhtml which are include files containing <ui:composition> tags, and the publicly exposed index.xhtml which wraps these files together to one page to be shown to the end-user, containing <ui:include> tags.
   • Create.xhtml and Edit.xhtml containing PrimeFaces <p:dialog> tag an HTML form, and various other PrimeFaces equivalents of JSF tags, such:
     • <p:messages>
     • <p:panelGrid>
     • <p:inputText>
     • <p:selectOneMenu>
     • <p:commandButton>
     • <p:calendar>
   • View.xhtml representing a simple view of the data
   • List.xhtml containing PrimeFaces <p:panel> and <p:dataTable>, various <p:column> tags, two <p:ajax> tags for catching rowSelect and rowUnselect** AJAX events to update the View and Edit buttons, which will be disabled when no row is selected and enabled when a row is selected.
8. The controllers package contains Facade files known from NetBeans' own "JSF Pages from Entity Classes" wizard, with one AbstractFacade.java class encapsulating JPA operations for all kinds of entities, and one EntityFacade.java for each entity
9. The beans package has a structure similar to the Facade pattern, with one AbstractController.java class encapsulating all common JSF operations and then EntityController.java classes for each entity. Since this project does not use Container-managed Dependency Injection, each entity bean is annotated with @ViewScoped. Having every bean inside a Session is not recommended.
10. The converters package contains one converter class per entity. @FacesConverter classes used to be static and embedded inside the EntityController classes. After identifying problems when many-to-many relationships were used and <p:selectManyMenu> is generated, a design change was implemented to give Converters their own package and class.
11. Please also observe how the generator has intelligently identified various foreign key field names where possible to be used as itemLabel attributes in drop-down lists as well as for the outputText in the List.xhtml files. If it was unable to identify such fields, the entity's @Id field was used. This is thanks to the Field name artifacts feature introduced in recent versions of the generator. If an entity field contains either descr or name (in that order), that field is then being used for e.g. the manufacturer name or the product code. This will greatly increase developer productivity as this allows developers to provide their own commonly used field names according to their data model!

Running The Application

If you followed all the steps exactly as described above, you should now be able to Run the application inside GlassFish. Click on the Run button and observe the new pages. You can find some screen shots here:

Dialog showing "View"

Showing sample list and menu

Dialog showing "Create New"

Dialog showing "Edit"

Dialog showing Support for Calendar and OutputLabel

Wizard Pager Customizations, Search Label Artifacts & Library Version Info

---

Known Issues

None at the time of this writing. Be sure to check the Tickets area for any open issues.