About Rendering Data with ADF Renderers

There are two types of HTML renderer for the Oracle ADF Business Components data sources:

Display Renderer displays the value of the attribute in the JSP page
Edit Renderer displays an edit field in the JSP page to let the user input a value for the attribute

The ADF-enabled web page can make use of these HTML renders when you:

Create JSP forms using the ADF Input Render element
Display data in your JSP page from Business Components attributes using the ADF Render element
Note: The Input Render and Render Value elements from the Data Control Palette insert the <adf:InputRender> and <adf:Render> tags respectively into the JSP page to display any kind of data such as dates or object.

Support for Custom HTML Renderers

You can write a custom HTML renderer class to customize the rendering of a specific attribute. The custom HTML renderer class should extend oracle.jdeveloper.html.HTMLFieldRendererImpl class. After the custom HTML renderer class is created, the user should bind this renderer class to the attribute that he wants to render.

Levels of Renderer-Attribute Binding

There are four different types of the renderer-attribute binding:

ADF tag level binding
View object level binding
Entity object level binding
HTTP session level binding

Each level of binding takes offers a unique level of precedence and scope:

ADF tag level binding takes the highest precedence.
View object level binding takes higher precedence to entity object level binding. The bindings at these two levels bind HTML renderer classes to Business Components attributes.
HTTP session level binding takes the lowest precedence. It binds HTML renderer classes to Business Components domain classes.

According to your requirements, you can choose to bind the renderer class in any of these levels.

HTTP Session Level Binding

HTTP session level binding takes the lowest precedence, but has the widest scope. Oracle ADF Business Components puts the default bindings for attribute types in this level. The default binding of interMedia renderer classes and interMedia types is defined in this level. The rule of binding is this:

The name field of the binding is the attribute class name plus the renderer key ("Renderer" or "EditRenderer"). The value field of the binding is the renderer class name. In the name field of the binding, use underscore (_) to replace dot (.) in the full class name, then append _Renderer for display renderer or _EditRenderer for edit renderer.

For example:

"oracle_ord_im_OrdImageDomain_Renderer"/"oracle.ord.html.OrdBuildURLRenderer"

This is a name/value pair stored in the HTTP session object. This means the display renderer of oracle.ord.im.OrdImageDomain object is an object of oracle.ord.html.OrdBuildURLRenderer.

Another example:

"oracle_ord_im_OrdImageDomain_EditRenderer"/"oracle.ord.html.OrdUploadFileRenderer"

This means that the edit renderer of oracle.ord.im.OrdImageDomain object is an object of oracle.ord.html.OrdUploadFileRenderer.

If there is no preceding level binding, then Business Components needs to render an oracle.ord.im.OrdImageDomain object, Business Components uses a oracle.ord.html.OrdBuildURLRenderer for display renderer and oracle.ord.html.OrdUploadFileRenderer for edit renderer, regardless of the attribute belonging to VO or EO.

You can set the custom renderer class by modify the name/value pair in the HTTP session object. The following code snippet sets the display renderer of oracle.ord.im.OrdImageDomain to user.CustomRenderer:

session.putValue("oracle_ord_im_OrdImageDomain_Renderer", "user.CustomRenderer");

Entity Object Level Binding

Entity object level binding takes higher precedence to HTTP session level binding. However, the scope of the binding becomes limited. The binding only affects the attribute defined in the entity object.

For example, in the HTTP session level, OrdBuildURLRenderer is bound to OrdImageDomain as the display renderer. In the entity object level, CustomRenderer is bound to the "photo" attribute of the Emp entity object. The "photo" attribute is of OrdImageDomain type. When the JSP page displays the "photo" attribute, Business Components runtime picks CustomRenderer to render the OrdImageDomain object. However, if there is a "picture" attribute in the Product entity object. Business Components runtime still uses OrdBuildURLRenderer to render the "picture" attribute.

To set the entity object level binding, the user needs to follow the procedures:

Click on the entity object in the Application Navigator.
You will notice that the lower portion of the Application Navigator (the Structure window) shows the list of attributes.
Right-click on the attribute and choose Edit .
Select the Properties tab.
For display renderer, type Renderer in the Name field, type user.CustomRenderer in Value field. For edit renderer, type EditRenderer in the Name field, type user.CustomRenderer in the Value field. Click Add.
Click Finish. You'll see the entry was added into the entity object XML file.

View Object Level Binding

View object level binding takes higher precedence to entity object level binding. However, the scope of the binding becomes even more restricted. The binding only affects the attribute defined in the view object.

For example, there are two view objects based on Emp entity object: Emp1View and Emp2View. In the view object level, CustomRenderer1 is bound to "photo" attribute of the Emp1View view object. In the entity object level, CustomRenderer2 is bound to "photo" attribute of the Emp entity object. "photo" attribute is of OrdImageDomain type. When the JSP page displays the "photo" attribute of the Emp1View, Business Components runtime picks CustomRenderer1 to render the OrdImageDomain object. However, if there is a "picture" attribute in the Emp2View view object. Business Components runtime still uses CustomRenderer2 to render the "picture" attribute.

To set the view object level binding, the user needs to follow the procedures:

Click the view object in the Application Navigator.
You will notice that the lower portion of the Navigator (the Structure window) shows the list of attributes.
Right-click on the attribute and choose Edit .
Click the Properties tab.
For display renderer, type Renderer in the Name field, type user.CustomRenderer in Value field. For the edit renderer, enter EditRenderer in the Name field, enter user.CustomRenderer in the Value field. Click Add.
Click Finish. You'll see the entry was added into the view object XML file.

ADF Tag Level Binding

Because ADF tags <adf:Render> and <adf:InputRender> use a DataSource object to access data and the HTML renderer object, you can use the DataSource to set the HTML renderer. The DataSource object has HTTP REQUEST scope. Data tag level binding takes higher precedence to view object, entity object, and HTTP session level binding. It affects all the data tags that use this DataSource object in the current HTTP REQUEST scope.


public interface DataSource {

   public void setDisplayFieldRenderer(AttributeDef attrDef, HTMLFieldRenderer rdr);

   public void setDisplayFieldRenderer(int nIndex, HTMLFieldRenderer rdr);

   public void setEditFieldRenderer(AttributeDef attrDef, HTMLFieldRenderer rdr);

   public void setEditFieldRenderer(int nIndex, HTMLFieldRenderer rdr);

}

The following is an example on how to set a custom HTML renderer called user.CustomRenderer to a Business Components RenderValue data tag. The JSP page is DataTableComponent.jsp. This JSP page is used by the DataTable tag to display the records. You need to set the HTML renderer object to the DataSource object used by the <adf:RenderValue> tag. In this example, the RenderValue tag uses a DataSource object called dsBrowse so that we set the renderer object to this dsBrowse DataSource object.