<?xml version="1.0" encoding="UTF-8"?>
<chapter>

  <table>
    <title>Component identification parameters </title>
    <tgroup cols="2">
      <thead>
        <row>
          <entry>Name</entry>
          <entry>Value</entry>
        </row>
      </thead>
      <tbody>
        <row>
          <entry>component-type</entry>
          <entry>org.ajax4jsf.Function</entry>
        </row>
        <row>
          <entry>component-family</entry>
          <entry>org.ajax4jsf.components.AjaxFunction</entry>
        </row>
        <row>
          <entry>component-class</entry>
          <entry>org.ajax4jsf.component.html.HtmlAjaxFunction</entry>
        </row>
        <row>
          <entry>renderer-type</entry>
          <entry>org.ajax4jsf.components.AjaxFunctionRenderer</entry>
        </row>
      </tbody>
    </tgroup>
  </table>

  <section>
    <title>Creating on a page</title>
    <para>Simple component definition example:</para>

  <para>
      <emphasis role="bold">Example:</emphasis>
 </para>
    <programlisting role="XML"><![CDATA[...
<head>
	<script>
		<!--There is some script named "myScript" that uses parameters which will be taken from server-->
	</script>
</head>
<body>
...
<a4j:jsFunction data="#{bean.someProperty}" name="callScript" oncomplete="myScript(data.subProperty1, data.subProperty2)"/>
...]]>
	</programlisting>
    <para> The script <emphasis><property>&quot;myScript&quot;</property></emphasis> will be called after
      <property>bean.someProperty</property> data will be returned from server(e.g. It&apos;ll
      be object with two subproperties). </para>
  </section>
  <section>
    <title>Dynamical creation of a component from Java code</title>

  <para>
      <emphasis role="bold">Example:</emphasis>
 </para>
    <programlisting role="JAVA"><![CDATA[import org.ajax4jsf.component.html.HtmlAjaxFunction;
...
HtmlAjaxFunction myFunction = new HtmlAjaxFunction();
...
]]></programlisting>
  </section>
  <section>
    <title>Key attributes and ways of usage</title>
    <para> As the component uses Ajax request to get data from server - it has all common Ajax
      Action attributes. Hence, action and actionListener can be invoked, and reRendering some parts of
      the page fired after calling function. </para>
    <para> When using the <emphasis role="bold">
        <property>&lt;a4j:jsFunction&gt;</property>
      </emphasis> it&apos;s possible to initiate the Ajax request from the JavaScript and
      perform partial update of a page and/or invoke the JavaScript function with data returned by
      Ajax response. </para>
    <programlisting role="XML"><![CDATA[...
<body onload="callScript()">
    ...
    <h:form>
    ...
    <a4j:jsFunction name="callScript" data="#{bean.someProperty1 }
                    "reRender="someComponent" oncomplete="myScript(data.subProperty1, data.subProperty2)">
        <a4j:actionparam name="param_name" assignTo="#{bean.someProperty2}">
        </a4j:actionparam>
    </a4j:jsFunction>
    ...
    </h:form>
    ...
</body>
...]]></programlisting>
    <para> The <emphasis role="bold">
        <property>&lt;a4j:jsFunction&gt;</property>
      </emphasis> allows to use <emphasis role="bold">
        <property>&lt;a4j:actionparam&gt;</property>
      </emphasis> or pure <emphasis role="bold">
        <property>&lt;f:param&gt;</property>
      </emphasis> for passing any number of parameters of the JavaScript function into Ajax request.
        <emphasis role="bold">
        <property>&lt;a4j:jsFunction&gt;</property>
      </emphasis> is similar to <emphasis role="bold">
        <property>&lt;a4j:commandButton&gt;</property>
      </emphasis>, but it could be activated from the JavaScript code. It allows to invoke some
      server side functionality and use the returned data in the JavaScript function invoked from
      <emphasis><property>&quot;oncomplete&quot;</property></emphasis> attribute. Hence it&apos;s possible to use <emphasis
        role="bold">
        <property>&lt;a4j:jsFunction&gt;</property>
      </emphasis> instead of <emphasis role="bold">
        <property>&lt;a4j:commandButton&gt;</property>
      </emphasis>. You can put it anywhere, just don&apos;t forget to use
      &lt;h:form&gt; ... &lt;/h:form&gt; around it. </para>
  </section>
  <section>
    <title>Relevant resources links</title>
    <para> To see how <emphasis role="bold">
        <property>&lt;a4j:jsFunction&gt;</property>
      </emphasis> works on practice, look at a4j-jsFunction example from <ulink
        url="http://livedemo.exadel.com/richfaces-demo/richfaces/jsFunction.jsf?c=jsFunction">here</ulink>.</para>
  </section>
</chapter>
