<?xml version="1.0" encoding="UTF-8"?>
<chapter>
  <chapterinfo>
    <keywordset>
      <keyword>a4j:jsFunction</keyword>
    </keywordset>
  </chapterinfo>
  <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 the Component with a Page Tag</title>
        <para>To create the simpliest example of the component on the page use the following syntax:</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)"/>
      ...
</body>]]>
    
    </programlisting>
        <para>
              The script <code>&quot;myScript&quot;</code> is called after <code>bean.someProperty</code> data is returned from server (e.g. It&apos;ll be object with two subproperties).
        </para>
  </section>
  <section>
    <title>Creating the Component Dynamically Using Java</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>Details of usage</title>
        
        <para>
              As the component uses Ajax request to get data from server it has all common Ajax Action attributes. 
              Hence, <emphasis><property>&quot;action&quot;</property></emphasis> and<emphasis><property> &quot;actionListener&quot; </property></emphasis>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: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 <emphasis role="bold"><property>&lt;h:form&gt;</property></emphasis> and <emphasis role="bold"><property>&lt;/h:form&gt;</property></emphasis> around it.
    </para>
    <para>
          Information about the <emphasis><property>&quot;process&quot;</property></emphasis> attribute usage you can find &quot;<link linkend="process">Decide what to process</link>&quot; guide section.
    </para>
  </section>
  <section>
    <title>Relevant resources links</title>
    <para>
          Vizit the <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/jsFunction.jsf?c=jsFunction">jsFunction page</ulink> at RichFaces LiveDemo for component usage and sources for the given examples.
    </para>
        
        <para>
              Useful articles:
        </para>
                <itemizedlist>
                      <listitem>
                            <para>
                                  &quot;<ulink url="http://www.jboss.org/community/docs/DOC-11856">JsFunctionJson</ulink>&quot; article in the RichFaces Cookbook describes how to use <emphasis role="bold"><property>&quot;a4j:jsFunction&quot;</property></emphasis> to call the jsonTest backing bean that generates some random data in a JSON String;
                            </para>
                      </listitem>
               
                </itemizedlist>
        
  </section>
</chapter>
