custom components with javaserver faces technology
the march 24, 2004 tech tip improving designs with the mvc design pattern introduced the architectural pattern known as model, view, controller (mvc or model2). mvc is a pervasive pattern throughout the world of computer science, and is fundamental to understanding javaserver faces (jsf) technology. the pattern separates the data and business logic of an application from its visual representation. the data and business logic is stored in an object called the model. the visual representation is stored in a separate object called the view. the two objects are linked together with a third object called the controller. the controller reacts to input from the view and updates the model data accordingly. the advantage of using this design is that any changes to the business logic or data can be isolated to the model without affecting the view. you can create multiple views without affecting the model.

a second tip in the march 24, 2004, titled introducing javaserver faces technology showed how to create a jsf application that includes gui components that are modeled by the jsf framework. in this tip, you'll learn how to create custom components using jsf technology. more specifically, you'll learn how to create a custom jsf technology component that represents a simple stock display. through an accompanying javaserver pages (jsp) page, a user can enter a stock symbol into a input text field and then press the submit button. in response, the custom component displays a table below the text field. the table contains the stock's symbol, the current price of the stock, and the daily change in the stock price.

this tip assumes that you are familiar with the basics of jsf technology, and you know how to create jsp technology custom tag libraries. for information on the basics of jsf technology, see an introduction to javaserver faces. for information on creating your own jsp custom tag libraries, see using custom tags in the j2ee 1.4 tutorial.

to create the custom component, you need to:

create a javabean model class that can be used to retrieve the stock data


create a custom jsf view output component class that extends javax.faces.component.uicomponent.


create a custom jsf view class that extends javax.faces.render.renderer.


integrate the custom component into the jsf framework using a custom tag.


create a jsp page, including an input text field, and a backing bean for the input text field to assist the custom component.


here is a visual representaion of how these objects fit in the mvc architecture.


create a javabean model

the model for the stock component is simple javabean class that has get and set accessor methods to store and retrieve data. the bean also has a method, retrievestock(), that the ui component calls when the user enters the stock symbol. this method takes the entered stock symbol and updates the model information accordingly.

the sample archive that accompanies this tip includes all the source code for the stock component. in it you'll find the following source code for the class stockmodel, the model component:
public class stockmodel {

private string selectedstock = "unknown";
private string currentvalue = "0";
private string dailychange = "0";

public string getselectedstock() { return selectedstock; }
public string getcurrentvalue() { return currentvalue; }
public string getdailychange() { return dailychange; }

public void retrievestock(string stocksubmitted) {
selectedstock = stocksubmitted;
currentvalue = "23.5";
dailychange = "+2.5";
}
}

typically a method such as retrievestock() would query a database to obtain the data, but for simplicity, the method in this class updates the rest of the model with the constant strings specified in the class.

create a ui component

the primary purpose of the ui component, which is part of the view, is to take data from the model and either display it itself, or relay it to a custom renderer to display the data as necessary. a custom ui component extends javax.faces.component.uicomponent. this class extends javax.faces.component.uioutput, where the uioutput class is a subclass of the uicomponent class. with uioutput, most of the view functionality that is needed by the custom component is already provided. the only addition that this class needs is the getfamily() method, which returns a string that describes the component family (this must match an entry in the resource descriptor later). here is the source code for the class uistockchoiceoutput:
public class uistockchoiceoutput extends uioutput {

public static final string stock_family = "stockfamily";

public uistockchoiceoutput() {
super();
}

public string getfamily() {
return stock_family;
}

}

create a custom renderer

the next step is to create a renderer for how this jsf component should appear in the client browser. this is a custom view class that extends the javax.faces.render.renderer class. the purpose of this renderer is to create the output html table for the stock information display. although it is not the case here, renderers can also be responsible for rendering input. hence, a renderer can perform two types of translation services: decoding any input data into a format that can be passed on to the controller, and encoding any data from the controller object and rendering it to the browser. decoding is done by the decode() method in the renderer. encoding can be done by a number of encoding methods. this example uses the encodeend() method. here is an extract of the source code for simplestockrenderer, the renderer (and custom view component):

public class simplestockrenderer extends renderer {

public void encodeend(facescontext context,
uicomponent component) throws ioexception
{
if (!component.isrendered())
return;

string selectedstock =
(string)component.getattributes().get("selectedstock");
string currentvalue =
(string)component.getattributes().get("currentvalue");
string dailychange =
(string)component.getattributes().get("dailychange");
string id = (string)component.getclientid(context);

responsewriter out = context.getresponsewriter();

out.startelement("table", component);
out.writeattribute("border", "0", "border");

out.startelement("tr", component);
out.writeattribute("bgcolor", "#000077", "bgcolor");

writetableheader(out, component, "stock symbol");
writetableheader(out, component, "current value");
writetableheader(out, component, "daily change");

out.endelement("tr");

out.startelement("tr", component);
out.writeattribute("bgcolor", "#ffffff", "bgcolor");

writetableentry(out, component, selectedstock);
writetableen