How to create actionLink component

First step is creating user interface component. All user interface components must extend UIComponent class directly or indirectly. In many situations the most convenient way is to extend custom components from UIComponentBase. This class provides useful implementations of nearly every UIComponentmethod, allowing us to focus on the unique characteristics of a particular UIComponent implementation. ActionLink component must to implement ActionSource interface to support functionality to generate action event when user click on link. For begining let us to define two important identifiers of actionLink such as component type and component family. Take a look how it is appears in the code:

public class UIAction extends UIComponentBase implements ActionSource {
  public static final String COMPONENT_TYPE = "org.semanticprogrammer.semanticfaces.Action";
  public static final String COMPONENT_FAMILY ="org.semanticprogrammer.semanticfaces.Action";

  public String getFamily() {
    return COMPONENT_FAMILY;
  }
  
  public UIAction() {
    super();
  }
}
		

Next things that define properties for UIAction class. Because the class is implementing ActionSource interface we need to define properties such as action, actionListener and immediate. Value of immediate property indicates whether ActionListeners executed during the Apply Request Value phase or the Invoke Application phase of the Request Processing Lifecycle. In addition to properties above make sense to implement properties label and disabled. Label property present text that appears on link. Destination of disabled property already has described in this article. See related code:

  public MethodBinding getAction() {
    return action;
  }

  public void setAction(MethodBinding action) {
    this.action = action;
  }

  public MethodBinding getActionListener() {
    return (this.actionListener);
  }

  public void setActionListener(MethodBinding actionListener) {
    this.actionListener = actionListener;
  }

  public boolean isImmediate() {
    if (immediate != null) return immediate;
    ValueBinding vb = getValueBinding("immediate");
    return (vb != null) ? ((Boolean)vb.getValue(getFacesContext())) : false;
  }

  public void setImmediate(boolean immediate) {
    this.immediate = immediate;
  }
  
  public Object getLabel() {
    if (label != null) return label;
    ValueBinding vb = getValueBinding("label");
    return (vb != null) ? vb.getValue(getFacesContext()) : null;
  }

  public void setLabel(Object label) {
    this.label = label;
  }

  public boolean isDisabled() {
    if (disabled != null) return disabled;
    ValueBinding vb = getValueBinding("disabled");
    return (vb != null) ? ((Boolean)vb.getValue(getFacesContext())) : false;
  }

  public void setDisabled(boolean disabled) {
    this.disabled = disabled;
  }
		

Because our class implementing ActionSource interface, we also need to provide the following methods:

  public void addActionListener(ActionListener listener) {
    addFacesListener(listener);
  }

  public ActionListener[] getActionListeners() {
    return (ActionListener [])getFacesListeners(ActionListener.class);
  }

  public void removeActionListener(ActionListener listener) {
    removeFacesListener(listener);
  }
		

Our action component should notify all action listeners and that functionality implemented by method void broadcast(FacesEvent event) located in class UIComponentBase. We need to override this method to support executing action listener registered with our component. Here is code:

  public void broadcast(FacesEvent event) throws AbortProcessingException {
    super.broadcast(event);
    if (event instanceof ActionEvent) {
      FacesContext context = getFacesContext();
      MethodBinding mb = getActionListener();
      if (mb != null)
        mb.invoke(context, new Object[] { event });
      ActionListener listener = context.getApplication().getActionListener();
      if (listener != null)
        listener.processAction((ActionEvent) event);
    }
  }			
			

Earlier we defined property immediate and now let's to define the way of using this property. If immediate is true the component suppose to process action events during Apply Request Values phase and if immediate is false events will process during Invoke Application phase. The queueEvent method is right place to use immediate property because this method provided the possibility for events to be queued. See the code:

  public void queueEvent(FacesEvent e) {
    if (e instanceof ActionEvent) {
      if (isImmediate())
        e.setPhaseId(PhaseId.APPLY_REQUEST_VALUES);
      else
        e.setPhaseId(PhaseId.INVOKE_APPLICATION);
    }
    super.queueEvent(e);
  }
			

Now, we can see that action event is executed during the proper lifecycle phase depending on the value of immediate.

Couple more methods that we need to implement inside UIAction class is methods related to state management of component. State management of UIAction is implemented same way like for any typical JSF component, so we will put just code here without any additional explanations.

  public Object saveState(FacesContext context) {
    Object values[] = new Object[6];
    values[0] = super.saveState(context);
    values[1] = saveAttachedState(context, action);
    values[2] = saveAttachedState(context, actionListener);
    values[3] = immediate;
    values[4] = label;
    values[5] = disabled;    
    return (values);
  }

  public void restoreState(FacesContext context, Object state) {
    Object values[] = (Object[]) state;
    super.restoreState(context, values[0]);
    action = (MethodBinding) restoreAttachedState(context, values[1]);
    actionListener = (MethodBinding) restoreAttachedState(context, values[2]);
    immediate = (Boolean)values[3];
    label = values[4];
    disabled = (Boolean)values[5];
  }
			

Custom component must be registered in faces-config.xml file.

We will put here required minimum amount of metadata:

<component>
	<display-name>Action Link</display-name>
	<component-type>org.semanticprogrammer.semanticfaces.Action</component-type>
	<component-class>org.semanticprogrammer.semanticfaces.component.UIAction</component-class>
</component>			
			

The main goal of the rendered component is to provide appearance in HTML of the associated UIAction. All rendered components extend Renderer directly or indirectly. Every rendered component must implement the decoding and encoding functionality. First thing to do is to define name of render type:

  public static final String RENDERER_TYPE = "org.semanticprogrammer.semanticfaces.Link";
			

Our encoding methods must render the following HTML code:

<script type="text/javascript">
<!--
document.getElementById('_id0').addParam = function(paramName, paramValue) {
  var param = document.createElement("input");
  param.type = "hidden";
  param.name = paramName; param.value = paramValue;
  this.appendChild(param);
}
//-->
</script>

<a href="javascript:document.forms['_id0'].addParam('_id0:_id3','_id0:_id3');document.forms['_id0'].addParam('paramName1','paramValue1'); 
	 document.forms['_id0'].submit(); void(0)">My Link</a>
			

Another benefit from using dynamically created elements that we can easy eliminate existing dependency between form and commandLink renderers. For more information regarding this issue see the link: https://javaserverfaces.dev.java.net/issues/show_bug.cgi?id=26

Semanticfaces library included demo application called action-component. There you can open page on wich located only commandLink and actionLink components. In case you open source code of the page you will see how differently render code this two components.

Probably no needs in further explanations regarding how to implement rendering of action link component. Just take a look on the code:

public class ActionLinkRenderer extends Renderer {
  public static final String RENDERER_TYPE = "org.semanticprogrammer.semanticfaces.Link";

  public ActionLinkRenderer() {
    super();
  }

  public void decode(FacesContext context, UIComponent component) {
    if (context == null || component == null) {
      throw new NullPointerException(Util.getExceptionMessageString(
          Message.parameters_null.name()));
    }
    if (Util.componentIsDisabledOrReadonly(component)) 
      return;
    String clientId = component.getClientId(context);
    Map requestParameterMap = context.getExternalContext().getRequestParameterMap();
    String value = (String) requestParameterMap.get(clientId);
    if (value == null || value.equals("") || !clientId.equals(value))
      return;
    ActionEvent actionEvent = new ActionEvent(component);
    component.queueEvent(actionEvent);
  }
  
  public void encodeBegin(FacesContext context, UIComponent component) throws IOException {
    if (context == null || component == null) {
      throw new NullPointerException(Util.getExceptionMessageString(
          Message.parameters_null.name()));
    }
    if (!component.isRendered()) 
      return;
    ResponseWriter writer = context.getResponseWriter();
    assert (writer != null);
    String clientId = component.getClientId(context);
    UIForm uiform = Util.getParentForm(component);
    if (uiform == null) 
      return;
    String formClientId = uiform.getClientId(context);
    Param paramList[] = Util.getParamList(component);
    Map requestMap = context.getExternalContext().getRequestMap();   
    String key = Util.ADD_PARAM_METHOD_NAME + "_" + formClientId;
    if (requestMap.get(key) == null) {
      Util.renderAddParamToFormJavaScript(writer, formClientId);
      requestMap.put(key, Boolean.TRUE);
    }
    writer.startElement("a", component);
    Util.writeIdAttributeIfNecessary(context, writer, component);
    Util.renderPassThruAttributes(context, writer, component, new String[]{"target"});
    if (!((UIAction)component).isDisabled()) {
      StringBuffer sb = new StringBuffer();
      sb.append("document.forms['");
      sb.append(formClientId);
      sb.append("']." + Util.ADD_PARAM_METHOD_NAME + "('");
      sb.append(clientId);
      sb.append("','");
      sb.append(clientId);
      sb.append("');");
      for (Param param : paramList) {
        sb.append("document.forms['");
        sb.append(formClientId);
        sb.append("']." + Util.ADD_PARAM_METHOD_NAME + "('");
        sb.append(param.getName());
        sb.append("','");
        sb.append(param.getValue());
        sb.append("');");
      }
      String target = (String) component.getAttributes().get("target");
      if (target != null && target.trim().length() > 0) {
        sb.append(" document.forms[");
        sb.append("'");
        sb.append(formClientId);
        sb.append("'");
        sb.append("].target='");
        sb.append(target);
        sb.append("';");
      }    
      sb.append(" document.forms['");
      sb.append(formClientId);
      sb.append("'].submit(); void(0)");
      writer.writeAttribute("href", "javascript:" + sb.toString(), "href");
      String styleClass = (String)component.getAttributes().get("styleClass");
      if (styleClass != null) {
        writer.writeAttribute("class", styleClass, "styleClass");
      }
    }
    else {
      writer.writeAttribute("href", "javascript:void(0)", "href");
      String disabledClass = (String)component.getAttributes().get("disabledClass");
      if (disabledClass != null)
        writer.writeAttribute("class", disabledClass, "disabledClass");
      else
        writer.writeAttribute("style", "color: GrayText;", "style");
    }
    Object label = ((UIAction)component).getLabel();
    if (label != null) {
      String s = label.toString();
      if (s != null && s.length() != 0) 
        writer.write(s);
    }    
    writer.flush();
  }

  public void encodeEnd(FacesContext context, UIComponent component) throws IOException {
    if (context == null || component == null) {
      throw new NullPointerException(Util.getExceptionMessageString(
          Message.parameters_null.name()));
    }
    if (!component.isRendered()) {
      return;
    }
    ResponseWriter writer = context.getResponseWriter();
    assert (writer != null);
    writer.endElement("a");
  }
}
			

Custom renderer must be registered in faces-config.xml file. See how to do it below:

<renderer>
	<display-name>Action Link</display-name>
	<component-family>org.semanticprogrammer.semanticfaces.Action</component-family>
	<renderer-type>org.semanticprogrammer.semanticfaces.Link</renderer-type>
	<renderer-class>org.semanticprogrammer.semanticfaces.renderkit.ActionLinkRenderer</renderer-class>
</renderer>
			

Tag handler class used to define tag for action link component. The tag provided reference to associated component on the page and provides the rendering of it. All tag handler classes must:

The tag can be registered in the Tag Library Descriptor (TLD). The TLD file is an XML document that describes all custom tags.

<renderer>
	<display-name>Action Link</display-name>
	<component-family>org.semanticprogrammer.semanticfaces.Action</component-family>
	<renderer-type>org.semanticprogrammer.semanticfaces.Link</renderer-type>
	<renderer-class>org.semanticprogrammer.semanticfaces.renderkit.ActionLinkRenderer</renderer-class>
</renderer>