Today we're looking at custom component creation within an NSF. We're not talking about custom controls, though creating a custom control before creating a component is definately a good way to prototype a custom component. Plus the DDE Builder does kind-of turn our custom controls into components, so they are kind-of custom components, but not really. What we're really talking about is a component that shows up in the DDE Component Palette and has it's own properties, methods and visual representation within designer and on an XPage and is serializable. This component can be used in multiple applications without any modification and may require a complex type in order to function (if you're familiar with the application layout in the extension library, all of the different nodes you can add to the various properties are complex types).
So you're asking, but don't I have to include these in a plugin that lives on the server? Well, you can certainly do that and by including your component in a library that resides on the server you won't have to move your custom component from application to application, it would just be available. But that is a whole different topic altogether, we're wanting to create our component in an NSF so we don't have to bug an administrator to put files on the server for us.
Since this will be a rather lengthy article, we will cover this topic in multiple posts. In part 1 we'll setup our DDE environment to allow us to create java class files and come up with what the properties of the component will be. And if it's not too long of a post, going ahead and creating our component class file.
To start with we'll need to setup our NSF so that we have a place to put our class files. So, go ahead and create a new application and in DDE add the package explorer view to your perspective. You do this by clicking "Window\Show Eclipse Views\Other" and in the resulting dialog navigate to "Java\Package Explorer" and click OK. You should now have a new tab next to the Application Explorer called Package Explorer. Go ahead and open that up if you haven't already.
Navigate to your new application and open up the WebContent folder, right click the WEB-INF folder and select "New\Folder" (if you don't have this option click other and select folder from the dialog). Name your folder "src". Now right click the "src" folder and select "Build Path\Use as Source Folder". This will cause the folder to disappear from WebContent\WEB-INF\src and be moved towards the top of the folder list into "WebContent/WEB-INF/src". This is where we'll be placing all of our java files for this series. As a side note, if you're using 8.5.3 you really don't have to do this. You can use the Java section underneath the code category. But I don't like how it organizes the class files as it doesn't "categorize" the class files underneath their respective packages. But that's my personal preference.
Right click the "WebContent/WEB-INF/src" folder and select "New\Package" (if you don't have this option click other and select package from the dialog). This will be where our component classes are stored. I'm naming mine "com.keithstric.components". Follow the same process and add another package called "com.keithstric.renderkit" and this will be where our renderers are stored.
This component will be for a contact type application with some basic information. So for reusability and simplicity sake we'll create a component with a few fields within a fieldset. This should allow us to demonstrate a couple of different methods and show that a component doesn't have to be just a single html element but can be something more complex also.
Now that we've got our basic structure setup we can start writing some code. We'll start off with the component class. This class should have a few different properties and all of these properties will have getters and setters. The properties will be:
-
Boolean showFirstName
-
Boolean showLastName
-
Boolean showEmailAddress
-
Boolean showPhoneNumber
-
String firstName
-
String lastName
-
String emailAddress
-
String phoneNumber
We'll be defining these properties and then let eclipse create getters and setters for us. So, let's start our class by right clicking the com.keithstric.components package we created earlier and pick "Class" from the drop down menu (If you don't have this option click other and select class from the dialog). Give it a name of CommonContactInfo and set the "Super class" to javax.faces.component.UIComponent and click the "Finish" button. This should create a new .java file in our com.keithstric.components package and our class will have a name of com.keithstric.components.CommonContactInfo.
Once that is completed we can now define our properties like below:
private static final String RENDERER_TYPE = "com.keithstric.CommonContactInfo";
private static final String COMPONENT_FAMILY = "com.keithstric";
private Boolean showFirstName;
private Boolean showLastName;
private Boolean showEmailAddress;
private Boolean showPhoneNumber;
private String firstName;
private String lastName;
private String emailAddress;
private String phoneNumber;
Once that is done, right click one of the properties and select "Source\Generate Getters and Setters" from the drop down menu. This will generate all of our getters and setters for us. You can also define a code template to help us stick to any company standards that may be present. I generally try to stick with the IBM standard and format my getters like:
public String getFirstName() {
if (this.firstName != null) {
return this.firstName;
}
ValueBinding _vb = getValueBinding("firstName");
if (_vb != null) {
return (String) _vb.getValue(getFacesContext());
} else {
//Or return a default value of some sort, can be hard coded or
// determined programmatically
return null;
}
}
public void setFirstName(String firstName) {
this.firstName = firstName;
}
Next up for the component class is to define the constructor and override the "getFamily()" method like below. Take note of the "RENDERER_TYPE" and "COMPONENT_FAMILY" constants used in the constructor where we set the renderer type and then in the getFamily() method. This is VERY IMPORTANT as it tells the server via the faces-config and xsp-config which renderer class to use to render this component. If you forget this, your component will not render, or at least won't use your renderer class:
public CommonContactInfo(){
setRendererType(RENDERER_TYPE);
}
@Override
public getFamily() {
return COMPONENT_FAMILY;
}
So, we should end up with this:
package com.keithstric.components;
import javax.faces.component.UIComponent;
import javax.faces.el.ValueBinding;
public class CommonContactInfo extends UIComponent {
private static final String RENDERER_TYPE = "com.keithstric.CommonContactInfo";
private static final String COMPONENT_FAMILY = "com.keithstric";
private Boolean showFirstName;
private Boolean showLastName;
private Boolean showEmailAddress;
private Boolean showPhoneNumber;
private String firstName;
private String lastName;
private String emailAddress;
private String phoneNumber;
public CommonContactInfo(){
setRendererType(RENDERER_TYPE);
}
@Override
public getFamily() {
return COMPONENT_FAMILY;
}
public Boolean isShowFirstName() {
if (showFirstName != null) {
return showFirstName;
}
ValueBinding _vb = getValueBinding("showFirstName");
if (_vb != null) {
return (Boolean) _vb.getValue("showFirstName");
} else {
return null;
}
}
public void setShowFirstName(Boolean showFirstName) {
this.showFirstName = showFirstName;
}
public Boolean isShowLastName() {
if (showLastName != null) {
return showLastName;
}
ValueBinding _vb = getValueBinding("showLastName");
if (_vb != null) {
return (Boolean) _vb.getValue("showLastName");
} else {
return null;
}
}
public void setShowLastName(Boolean showLastName) {
this.showLastName = showLastName;
}
public Boolean isShowEmailAddress() {
if (showEmailAddress != null) {
return showEmailAddress;
}
ValueBinding _vb = getValueBinding("showEmailAddress");
if (_vb != null) {
return (Boolean) _vb.getValue("showEmailAddress");
} else {
return null;
}
}
public void setShowEmailAddress(Boolean showEmailAddress) {
this.showEmailAddress = showEmailAddress;
}
public Boolean isShowPhoneNumber() {
if (showPhoneNumber != null) {
return showPhoneNumber;
}
ValueBinding _vb = getValueBinding("showPhoneNumber");
if (_vb != null) {
return (Boolean) _vb.getValue("showPhoneNumber");
} else {
return null;
}
}
public void setShowPhoneNumber(Boolean showPhoneNumber) {
this.showPhoneNumber = showPhoneNumber;
}
public String getFirstName() {
if (firstName != null) {
return firstName;
}
ValueBinding _vb = getValueBinding("firstName");
if (_vb != null) {
return (String) _vb.getValue("firstName");
} else {
return null;
}
}
public void setFirstName(String firstName) {
this.firstName = firstName;
}
public String getLastName() {
if (lastName != null) {
return lastName;
}
ValueBinding _vb = getValueBinding("lastName");
if (_vb != null) {
return (String) _vb.getValue("lastName");
} else {
return null;
}
}
public void setLastName(String lastName) {
this.lastName = lastName;
}
public String getEmailAddress() {
if (emailAddress != null) {
return emailAddress;
}
ValueBinding _vb = getValueBinding("emailAddress");
if (_vb != null) {
return (String) _vb.getValue("emailAddress");
} else {
return null;
}
}
public void setEmailAddress(String emailAddress) {
this.emailAddress = emailAddress;
}
public String getPhoneNumber() {
if (phoneNumber != null) {
return phoneNumber;
}
ValueBinding _vb = getValueBinding("phoneNumber");
if (_vb != null) {
return (String) _vb.getValue("phoneNumber");
} else {
return null;
}
}
public void setPhoneNumber(String phoneNumber) {
this.phoneNumber = phoneNumber;
}
}
You now have a component definition class with the preliminary structure defined and something to work with. In the next installment we'll create a renderer that will define how the component is represented in the browser. We'll also be coming back to this class to add the Save & Restore State methods with a short discussion around those methods which make the serialization of the component possible.