webuijsf
Tag anchor


Use the webuijsf:anchor tag to

The value of the id attribute of the rendered anchor element will be the component id, not the component's client id. In order to obtain the DOM node of the anchor element, on the client, the component id must be used and not the component's client id. This means that the component id must be unique in the page and not just unique within the closest NamingContainer.

Facets

None

Client Side Javascript Functions

When the component is rendered, a DOM object corresponding to the component is created. To manipulate the component on the client side, you can call functions on the DOM object. To disable the component, invoke document.getElementById(id).setProps({disabled: true}).

getProps() Use this function to get widget properties. See setProps() function for a list of supported properties.
refresh(execute)
Use this function to asynchronously refresh the component.
  • [optional] execute: Comma separated string containing a list of client ids against which the execute portion of the request processing lifecycle must be run. If omitted, no other components are executed.
setProps(props) Use this function to change any of the following supported properties:
  • accessKey
  • charset
  • className
  • coords
  • dir
  • disabled
  • href
  • hrefLang
  • id
  • lang
  • onFocus
  • onBlur
  • onClick
  • onDblClick
  • onKeyDown
  • onKeyPress
  • onKeyUp
  • onMouseDown
  • onMouseOut
  • onMouseOver
  • onMouseUp
  • onMouseMove
  • rev
  • rel
  • shape
  • style
  • tabIndex
  • title
  • visible

Client Side JavaScript Events

When the component is manipulated on the client side, some functions may publish event topics for custom Ajax implementations to listen for. Using the Dojo event system, listen for the refresh event topic by using:

<webuijsf:script>
    var processEvents = {                       
        update: function(props) {
            // Do something...
        }
    }

    // Subscribe to refresh event.
    dojo.subscribe(webui.suntheme.widget.anchor.event.<eventname>.endTopic, processEvents, "update");


</webuijsf:script>

The following events are supported.
 
webui.suntheme.widget.anchor.event.refresh.beginTopic Event topic published before asynchronously refreshing the component. Supported properties include:
  • [optional] execute - List of the components to be executed along with this component
  • id - The client id to process the event for
webui.suntheme.widget.anchor.event.refresh.endTopic Event topic published after asynchronously refreshing the component. Supported properties include:See setProps() function.

  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage

Code Examples

Example 1: Create an Anchor That Points to an URL

<webuijsf:anchor id="anchor1" url="http://www.sun.com"/>

Example 2: Create an Anchor That Anchors a Particular Position on the Page. 

<a id="foo" />

Note: To access this on the client side, use document.getElementById("anchor1");

Example 3: Create a Hyperlink to The Anchor Above

<webuijsf:hyperlink id="link1"url="#anchor1" > Go to Anchor </webuijsf:hyperlink >

Example 4: Create a Relative Anchor to the Anchor in Example 1

<webuijsf:anchor id="gotoAnchor1" url="/faces/hyperlink.jsp#anchor1" />

Note:  In the url attribute, you must specify a path that maps to the correct servlet. However, you do not need the context. In this example, the part of the path maps to the servlet through the JSF FacesServlet as defined in the web.xml.

Example 5: Update Client-Side Anchor Properties Using the getProps and setProps Functions

This example shows how to toggle the visible state of an anchor client side using the getProps and setProps functions. When the user clicks the button, the anchor is either shown or hidden.

<webuijsf:anchor id="anchor1" > This is an anchor </webuijsf:anchor >
<webuijsf:button id="button1" text="Hide Anchor" onClick="toggleVisible()"/>

<script type="text/javascript">
    function toggleVisible() {
        var domNode = document.getElementById("anchor1");
        var props = domNode.getProps();
        if (domNode != null) {
            domNode.setProps({"visible":!props.visible});
        }
    }
</script>

Example 6: Asynchronously Update Anchor using refresh Function

This example shows how to asynchronously update an anchor using the refresh function. When the user clicks the button, the anchor is asynchronously updated with new data.
<webuijsf:anchor id="anchor1" text="#{MyBean.text}"/>
<webuijsf:button id="button1" text="#{MyBean.text}" onClick="refreshAnchor();return false;"/>
<webuijsf:script>
    function refreshAnchor() {
        var domNode = document.getElementById("form1:anchor1"); // Get anchor
        return domNode.refresh(); // Asynchronously refresh anchor
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,..."). When no parameter is given, the refresh function acts as a reset. That is, the component will be redrawn using values set server-side, but not updated.

Example 7: Asynchronously Update Anchor Using refresh Function

This example shows how to asynchronously update an anchor using the refresh function. The execute property of the refresh function is used to define the client id which is to be submitted and updated server-side. As the user types in the text field, the input value is updated server-side and the anchor is updated client-side -- all without a page refresh.
<webuijsf:anchor id="anchor1" text="#{MyBean.text}"/>
<webuijsf:textField id="field1" text="#{MyBean.text}" label="Change Anchor Text"
onKeyPress="setTimeout('refreshAnchor();', 0);"/> // Field used to asynchronously update text.
<webuijsf:script>
    function
refreshAnchor() {
        var domNode = document.getElementById("form1:anchor1"); // Get anchor
        return domNode.refresh("form1:field1"); // Asynchronously refresh while submitting field value
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,...")



Tag Information
Tag Classcom.sun.webui.jsf.component.AnchorTag
TagExtraInfo ClassNone
Body ContentJSP
Display NameNone

Attributes
NameRequiredRequest-timeTypeDescription
bindingfalsefalsejava.lang.String A ValueExpression that resolves to the UIComponent that corresponds to this tag. This binding allows the Java bean that contains the UIComponent to manipulate the UIComponent, its properties, and its children.
shapefalsefalsejava.lang.String

The shape of the hot spot on the screen (for use in client-side image maps). Used with the coords attribute.Valid values are: default (entire region); rect (rectangular region); circle (circular region); and poly (polygonal region).

onKeyPressfalsefalsejava.lang.String

Scripting code that is executed when the user presses and releases a key while the component has focus.

targetfalsefalsejava.lang.String

The resource at the specified URL is displayed in the frame that is specified with the target attribute. Values such as "_blank" that are valid for the target attribute of a HTML anchor element are also valid for this attribute in this component

onFocusfalsefalsejava.lang.String

Scripting code that is executed when the anchor component receives focus. An element receives focus when the user selects the element by pressing the tab key or clicking the mouse.

charsetfalsefalsejava.lang.String

Specifies the character encoding of the target URL

urlLangfalsefalsejava.lang.String

The language code of the resource designated by this anchor.

revfalsefalsejava.lang.String

Specifies the relationship between the target URL and the current document

onKeyUpfalsefalsejava.lang.String

Scripting code executed when the user releases a key while the component has focus.

onMouseUpfalsefalsejava.lang.String

Scripting code executed when the user releases a mouse button while the mouse pointer is on the component.

styleClassfalsefalsejava.lang.String

CSS style class or classes to be applied to the outermost HTML element when this component is rendered.

stylefalsefalsejava.lang.String

CSS style or styles to be applied to the outermost HTML element when this component is rendered.

urlfalsefalsejava.lang.String

Absolute, relative, or context relative (starting with "/") URL to the resource selected by this anchor. If the url attribute is specified, clicking the anchor sends the browser to the new location. If UIParameter components are specified as child to the anchor component, then the renderer processes these name value pairs of the UIParameter components and appends them as query parameters to the specified url.

onClickfalsefalsejava.lang.String

Scripting code that is executed when a mouse click occurs over this component. If the component submits the form (by using the action attribute), the script that you use with the onClick attribute should not return from the function. When the action attribute is used, the component handles the return with a script that is appended to the anchor element's onclick property. When you supply an onClick attribute, this return script is appended after your script in the anchor's onclick. You can return from your script to abort the submit process if necessary.

onBlurfalsefalsejava.lang.String

Scripting code executed when this element loses focus.

toolTipfalsefalsejava.lang.String

Sets the value of the title attribute for the HTML element. The specified text will display as a tooltip if the mouse cursor hovers over the HTML element.

onMouseDownfalsefalsejava.lang.String

Scripting code executed when the user presses a mouse button while the mouse pointer is on the component.

typefalsefalsejava.lang.String

The MIME content type of the resource specified by the anchor component.

disabledfalsefalsejava.lang.String

Flag indicating that clicking this component by the user is not currently permitted.

accessKeyfalsefalsejava.lang.String

This attribute assigns an access key to an element. An access key is a single character from the document character set.

onMouseOutfalsefalsejava.lang.String

Scripting code executed when a mouse out movement occurs over this component.

onMouseOverfalsefalsejava.lang.String

Scripting code executed when the user moves the mouse pointer into the boundary of this component.

htmlTemplatefalsefalsejava.lang.String Get alternative HTML template to be used by the anchor component.
onMouseMovefalsefalsejava.lang.String

Scripting code executed when the user moves the mouse pointer while over the component.

textfalsefalsejava.lang.String

The text to be displayed for the anchor element.

relfalsefalsejava.lang.String

Specifies the relationship between the current document and the target URL

visiblefalsefalsejava.lang.String

Use the visible attribute to indicate whether the component should be viewable by the user in the rendered HTML page. If set to false, the HTML code for the component is present in the page, but the component is hidden with style attributes. By default, visible is set to true, so HTML for the component HTML is included and visible to the user. If the component is not visible, it can still be processed on subsequent form submissions because the HTML is present.

onKeyDownfalsefalsejava.lang.String

Scripting code that is executed when the user presses down on a key while the anchor component has focus.

tabIndexfalsefalsejava.lang.String

Position of this element in the tabbing order of the current document. Tabbing order determines the sequence in which elements receive focus when the tab key is pressed. The value must be an integer between 0 and 32767.

coordsfalsefalsejava.lang.String

Specifies the coordinates appropriate to the shape attribute to define a region of an image for image maps

renderedfalsefalsejava.lang.String Use the rendered attribute to indicate whether the HTML code for the component should be included in the rendered HTML page. If set to false, the rendered HTML page does not include the HTML for the component. If the component is not rendered, it is also not processed on any subsequent form submission.
idfalsetruejava.lang.StringNo Description

Variables
No Variables Defined.


Output Generated by Tag Library Documentation Generator. Java, JSP, and JavaServer Pages are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries. Copyright 2002-4 Sun Microsystems, Inc. 4150 Network Circle Santa Clara, CA 95054, U.S.A. All Rights Reserved.