A"

From Documentation
 
(24 intermediate revisions by 6 users not shown)
Line 6: Line 6:
 
*Java API: <javadoc>org.zkoss.zul.A</javadoc>
 
*Java API: <javadoc>org.zkoss.zul.A</javadoc>
 
*JavaScript API: <javadoc directory="jsdoc">zul.wgt.A</javadoc>
 
*JavaScript API: <javadoc directory="jsdoc">zul.wgt.A</javadoc>
 +
*Style Guide: [[ZK_Style_Guide/XUL_Component_Specification/A | A]]
  
 
= Employment/Purpose =
 
= Employment/Purpose =
The same as HTML A tag.  
+
The same as HTML A tag.
  
 +
=Properties=
 +
== Autodisable ==
  
 +
<javadoc method="setAutodisable(java.lang.String)">org.zkoss.zul.A</javadoc> is used to disable an anchor automatically, when it is clicked. It is useful to prevent the user from clicking it twice (and firing redundant requests), which is common if the request takes long to serve.
 +
 +
The simplest use is to specify it with <code>self</code> as follows. Then, the anchor is disabled when it is clicked.
 +
 +
<source lang="xml">
 +
<a id="ok" label="OK" autodisable="self" />
 +
</source>
 +
 +
If you'd like to disable several anchors, you could specify all of them in this property by separating with a comma. For example, the following disables both anchors, when one of them is clicked.
 +
 +
<source lang="xml">
 +
<a id="ok" label="OK" autodisable="ok,cancel" />
 +
<a id="cancel" label="Cancel" autodisable="ok,cancel" />
 +
</source>
 +
 +
The anchor will be enabled automatically, after the request has been served (i.e., the response has been sent back to the client). If you prefer to enable them manually (i.e., by calling <javadoc method="setDisabled(boolean)">org.zkoss.zul.A</javadoc> explicitly), you could prefix the ID with a plus (<code>+</code>). For example,
 +
 +
<source lang="xml">
 +
<a id="ok" label="OK" autodisable="+self, +cancel" />
 +
</source>
 +
 +
Then, you could enable them manually under the situation depending on your application's requirement, such as
 +
 +
<source lang="java">
 +
if (something_happens) {
 +
  ok.setDisabled(false);
 +
  cancel.setDisabled(false);
 +
}
 +
</source>
 +
 +
=== Enable Autodisable for All Anchors===
 +
 +
As described in [[ZK Developer's Reference/Customization/Component Properties|ZK Developer's Reference: Customization]], you could customize ZK to enable <code>autodisable</code> for all anchors by specifying the following in the custom language addon:
 +
 +
<source lang="xml">
 +
<language-addon>
 +
    <language-name>xul/html</language-name>
 +
    <component>
 +
        <component-name>a</component-name>
 +
        <extends>a</extends>
 +
        <property>
 +
            <property-name>autodisable</property-name>
 +
            <property-value>self</property-value>
 +
        </property>
 +
    </component>
 +
</language-addon>
 +
</source>
 +
 +
=File Download Link=
 +
When a user clicks <code><a/></code> whose <code>target</code> is <code>_self</code> (default value) will cause a browser to trigger the event <code>onbeforeunload</code>, then ZK depends on this event to remove a desktop.
 +
This also apply to browser-processed links. Links that do not open a page, but provide a browser instruction to open a different service, such as <code>mailto:</code>, <code>tel:</code>, etc.
 +
 +
Hence, after clicking the hyperlink, all ZK client ajax doesn't work anymore. Here are several correct ways to create a file download link:
 +
 +
== open a new tab ==
 +
specify <code>_blank</code> and your browser will produce a new tab and close immediately.
 +
 +
<syntaxhighlight lang='xml>
 +
<a href="report.pdf" target='_blank'>download</a>
 +
</syntaxhighlight>
 +
 +
After clicking a link like <code><a href="report.pdf" target='_self'>download</a></code>, you will find ZK doesn't send AJAX requests anymore to the server.
 +
 +
== download attribute ==
 +
A browser will prompt the user to save the linked URL instead of navigating to it.
 +
<syntaxhighlight lang='xml>
 +
<zk xmlns:c="client/attribute">
 +
<a href="report.xls" c:download="" target='_self'>download</a>
 +
</zk>
 +
</syntaxhighlight>
 +
 +
Please refer to [https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-download download attribute]
 +
 +
== [[ZK_Developer%27s_Reference/UI_Patterns/File_Upload_and_Download#File_Download|Filedownload API]] ==
  
 
= Example =
 
= Example =
Line 17: Line 94:
  
 
<source lang="xml" >
 
<source lang="xml" >
  <a href="http://www.zkoss.org">Visit ZK!</a>
+
<a href="http://www.zkoss.org" label="Visit ZK!"/>
 +
</source>
 +
 
 +
In addition, you could add child components to <javadoc>org.zkoss.zul.A</javadoc> too:
 +
 
 +
<source lang="xml">
 +
<a href="http://www.zkoss.org" label="Visit ZK!" image="zk.png">
 +
  <grid>
 +
    <rows>
 +
      <row>What ever content</row>
 +
    </rows>
 +
  </grid>
 +
</a>
 +
</source>
 +
 
 +
Notice that a child component might also handle the mouse click, so the final result of clicking on a child component is really up to which child component is used.
 +
 
 +
The href attribute can be an URI. For example,
 +
 
 +
<source lang="xml">
 +
<a href="/foo" label="Foo" />
 +
<a href="goo" label="Goo" />
 
</source>
 
</source>
  
=Supported events=
+
If the URI starts with "/", ZK will encode it with the application's context path. Otherwise the path is relative to the path given by Desktop.getDirectory().
 +
 
 +
=Supported Events=
  
{| border="1" | width="100%"
+
{| class='wikitable' | width="100%"
 
! <center>Name</center>
 
! <center>Name</center>
 
! <center>Event Type</center>
 
! <center>Event Type</center>
Line 29: Line 129:
 
| None
 
| None
 
|}
 
|}
 +
*Inherited Supported Events: [[ZK_Component_Reference/Base_Components/LabelImageElement#Supported_Events | LabelImageElement]]
  
 
=Supported Children=
 
=Supported Children=
Line 34: Line 135:
 
  *ALL
 
  *ALL
  
=Use cases=
+
=Use Cases=
  
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Version !! Description !! Example Location
 
! Version !! Description !! Example Location
 
|-
 
|-
Line 45: Line 146:
  
 
=Version History=
 
=Version History=
 +
{{LastUpdated}}
  
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Version !! Date !! Content
 
! Version !! Date !! Content
 
|-
 
|-
 
| 5.0.5
 
| 5.0.5
 
| October, 2010
 
| October, 2010
| The A component supports children.
+
| <javadoc>org.zkoss.zul.A</javadoc> supports any children.
 +
|-
 +
| 7.0.2
 +
| May, 2014
 +
| [http://tracker.zkoss.org/browse/ZK-2237 Support autodisable property for A component]
 
|}
 
|}
  
 
{{ZKComponentReferencePageFooter}}
 
{{ZKComponentReferencePageFooter}}

Latest revision as of 10:01, 13 June 2022

A

  • Demonstration: N/A
  • Java API: A
  • JavaScript API: A
  • Style Guide: A

Employment/Purpose

The same as HTML A tag.

Properties

Autodisable

A.setAutodisable(String) is used to disable an anchor automatically, when it is clicked. It is useful to prevent the user from clicking it twice (and firing redundant requests), which is common if the request takes long to serve.

The simplest use is to specify it with self as follows. Then, the anchor is disabled when it is clicked.

<a id="ok" label="OK" autodisable="self" />

If you'd like to disable several anchors, you could specify all of them in this property by separating with a comma. For example, the following disables both anchors, when one of them is clicked.

<a id="ok" label="OK" autodisable="ok,cancel" />
<a id="cancel" label="Cancel" autodisable="ok,cancel" />

The anchor will be enabled automatically, after the request has been served (i.e., the response has been sent back to the client). If you prefer to enable them manually (i.e., by calling A.setDisabled(boolean) explicitly), you could prefix the ID with a plus (+). For example,

<a id="ok" label="OK" autodisable="+self, +cancel" />

Then, you could enable them manually under the situation depending on your application's requirement, such as

if (something_happens) {
   ok.setDisabled(false);
   cancel.setDisabled(false);
}

Enable Autodisable for All Anchors

As described in ZK Developer's Reference: Customization, you could customize ZK to enable autodisable for all anchors by specifying the following in the custom language addon:

<language-addon>
    <language-name>xul/html</language-name>
    <component>
        <component-name>a</component-name>
        <extends>a</extends>
        <property>
            <property-name>autodisable</property-name>
            <property-value>self</property-value>
        </property>
    </component>
</language-addon>

File Download Link

When a user clicks <a/> whose target is _self (default value) will cause a browser to trigger the event onbeforeunload, then ZK depends on this event to remove a desktop. This also apply to browser-processed links. Links that do not open a page, but provide a browser instruction to open a different service, such as mailto:, tel:, etc.

Hence, after clicking the hyperlink, all ZK client ajax doesn't work anymore. Here are several correct ways to create a file download link:

open a new tab

specify _blank and your browser will produce a new tab and close immediately.

<a href="report.pdf" target='_blank'>download</a>

After clicking a link like <a href="report.pdf" target='_self'>download</a>, you will find ZK doesn't send AJAX requests anymore to the server.

download attribute

A browser will prompt the user to save the linked URL instead of navigating to it.

<zk xmlns:c="client/attribute">
<a href="report.xls" c:download="" target='_self'>download</a>
</zk>

Please refer to download attribute

Filedownload API

Example

ZKComRef A Examples.PNG

<a href="http://www.zkoss.org" label="Visit ZK!"/>

In addition, you could add child components to A too:

<a href="http://www.zkoss.org" label="Visit ZK!" image="zk.png">
  <grid>
    <rows>
      <row>What ever content</row>
    </rows>
  </grid>
</a>

Notice that a child component might also handle the mouse click, so the final result of clicking on a child component is really up to which child component is used.

The href attribute can be an URI. For example,

<a href="/foo" label="Foo" />
<a href="goo" label="Goo" />

If the URI starts with "/", ZK will encode it with the application's context path. Otherwise the path is relative to the path given by Desktop.getDirectory().

Supported Events

Name
Event Type
None None

Supported Children

*ALL

Use Cases

Version Description Example Location
     

Version History

Last Update : 2022/06/13


Version Date Content
5.0.5 October, 2010 A supports any children.
7.0.2 May, 2014 Support autodisable property for A component



Last Update : 2022/06/13

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.