Author: atsebro Date: 2009-07-06 07:02:17 -0400 (Mon, 06 Jul 2009) New Revision: 14782 Modified: branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/mediaOutput.desc.xml branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/mediaOutput.xml Log: RF-7427: a4j:mediaOutput component description review Modified: branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/mediaOutput.desc.xml =================================================================== --- branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/mediaOutput.desc.xml 2009-07-06 08:55:10 UTC (rev 14781) +++ branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/mediaOutput.desc.xml 2009-07-06 11:02:17 UTC (rev 14782) @@ -8,8 +8,8 @@ </sectioninfo> <title>Description</title> - <para>The <emphasis role="bold"> - <property>&lt;a4j:mediaOutput&gt;</property> - </emphasis> component implements one of the basic features specified in the framework. The component is a facility for generating images, video, sounds and other binary resources defined by you on-the-fly.</para> + <para> + The <emphasis role="bold"><property>&lt;a4j:mediaOutput&gt;</property></emphasis> component is a facility for generating images, video, sounds and other binary resources defined by you on-the-fly. + </para> </section> </root> \ No newline at end of file Modified: branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/mediaOutput.xml =================================================================== --- branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/mediaOutput.xml 2009-07-06 08:55:10 UTC (rev 14781) +++ branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/mediaOutput.xml 2009-07-06 11:02:17 UTC (rev 14782) @@ -36,18 +36,13 @@ </table> <section> - <title>Creating on a page</title> + <title>Creating the Component with a Page Tag</title> <para>Component definition on a page for graphical data output</para> <para> <emphasis role="bold">Example:</emphasis> </para> - <programlisting role="XML"><![CDATA[... -<a4j:mediaOutput element="img" cacheable="false" session="true" - createContent="#{paintBean.paint}" value="#{paintData}" - mimeType="image/jpeg"/> -... -]]></programlisting> + <programlisting role="XML"><![CDATA[<a4j:mediaOutput element="img" cacheable="false" session="true" createContent="#{paintBean.paint}" value="#{paintData}" mimeType="image/jpeg"/>]]></programlisting> </section> <section> @@ -62,54 +57,138 @@ ... ]]></programlisting> </section> - <section> - <title>Key attributes and ways of usage</title> - <para>To use the component it&apos;s necessary to define it on a page and set Java methods for data keeping and data transmission to output stream. </para> - <para>Here is the content of <code>paintData</code> that is a bean containing output data</para> - <para> - <emphasis role="bold">Example:</emphasis> - </para> - <programlisting role="JAVA"><![CDATA[package demo; + + <section> + <title>Details of usage</title> + <para> + The <emphasis role="bold"><property>&lt;a4j:mediaOutput&gt;</property></emphasis> component is used for generating images, videos or sounds on-the-fly. + Let's consider an image creation and generate a JPEG image with verification digits for captcha (the image will include just digits without any graphical noise and distortion). + </para> + <para> + Write the following line on the page: + </para> + <programlisting role="XML"><![CDATA[<a4j:mediaOutput element="img" cacheable="false" session="false" createContent="#{mediaBean.paint}" value="#{mediaData}" mimeType="image/jpeg"/>]]></programlisting> + + <para> + As You see from the example above, first it is necessary to specify the kind of media data You want to generate. + This can be done with the help of <emphasis><property>&quot;element&quot;</property></emphasis> attribute, which possible values are <code>img</code>, <code>object</code>, <code>applet</code>, <code>script</code>, <code>link</code> or <code>a</code>. + </para> + <para> + The <emphasis><property>&quot;cacheable&quot;</property></emphasis> defines whether the response will be cached or not. In our case we don't need our image to be cached, cause we need it to be changed every time we refresh the page. + </para> + <para> + The <emphasis><property>&quot;mimeType&quot;</property></emphasis> attribute defines the type of output content. It is used to define the corresponded type in the header of an HTTP response. + </para> + + <para>The <emphasis role="bold"><property>&lt;a4j:mediaOutput&gt;</property></emphasis> attribute has two main attributes:</para> + <itemizedlist> + <listitem> + <para> + <emphasis><property>&quot;createContent&quot;</property></emphasis> specifies a method that will be used for content creating. + The method accepts two parameters. + The first one — with an <code>java.io.OutputStream</code> type — is a reference to the stream that should be used for output. + An output stream accepts output bytes and sends them to a recipient. + The second parameter is a reference to the component&apos;s <emphasis><property>&quot;value&quot;</property></emphasis> attribute and has <code>java.lang.Object</code> type. + This parameter contains deserialized object with data specified in the <emphasis><property>&quot;value&quot;</property></emphasis> attribute. + </para> + </listitem> + <listitem> + <para> + <emphasis><property>&quot;value&quot;</property></emphasis> attribute specifies a bean class that keeps data for transmitting it into a stream in the method specified with <emphasis><property>&quot;createContent&quot;</property></emphasis> . + </para> + </listitem> + </itemizedlist> + + <para> + Now let's create the <code>MediaBean</code> class and specify there a primitive random-number generator and <code>paint</code> method that will convert the generated numbers into an output stream and give a JPEG image as a result. + The code for <code>MediaBean</code> class is going to look as following: + </para> + <para> + <emphasis role="bold">Example:</emphasis> + </para> + <programlisting role="JAVA"><![CDATA[package demo; -public class PaintData implements Serializable{ - private static final long serialVersionUID = 1L; - Integer width=100; - Integer weight=50; - ... -} -]]></programlisting> - <para>The Paint method of the <code>paintBean</code> class is a method transmitting graphical data into output stream.</para> +import java.awt.Graphics2D; +import java.awt.image.BufferedImage; +import java.io.IOException; +import java.io.OutputStream; +import java.util.Random; +import javax.imageio.ImageIO; + +public class MediaBean { + public void paint(OutputStream out, Object data) throws IOException{ + Integer high = 9999; + Integer low = 1000; + Random generator = new Random(); + Integer digits = generator.nextInt(high - low + 1) + low; + if (data instanceof MediaData) { + MediaData paintData = (MediaData) data; + BufferedImage img = new BufferedImage(paintData.getWidth(),paintData.getHeight(),BufferedImage.TYPE_INT_RGB); + Graphics2D graphics2D = img.createGraphics(); + graphics2D.setBackground(paintData.getBackground()); + graphics2D.setColor(paintData.getDrawColor()); + graphics2D.clearRect(0,0,paintData.getWidth(),paintData.getHeight()); + graphics2D.setFont(paintData.getFont()); + graphics2D.drawString(digits.toString(), 20, 35); + ImageIO.write(img,"png",out); + } + } +}]]></programlisting> + +<para> + Now it is necessary to create a class that will keep transmissional data that will be used as input data for a content creation method. + The code for <code>MediaData</code> class is going to be as following: +</para> + <note> + <title>Note:</title> + <para>A bean class transmitted into value should implement <code>Serializable</code> interface in order to be encoded to the URL of the resource. + </para> + </note> + + <para> + <emphasis role="bold">Example:</emphasis> + </para> + <programlisting role="JAVA"><![CDATA[package demo; + +import java.awt.Color; +import java.awt.Font; +import java.io.Serializable; + +public class MediaData implements Serializable{ + + private static final long serialVersionUID = 1L; + Integer Width=110; + Integer Height=50; + Color Background=new Color(190, 214, 248); + Color DrawColor=new Color(0,0,0); + Font font = new Font("Serif", Font.TRUETYPE_FONT, 30); - <para> - <emphasis role="bold">Example:</emphasis> - </para> - <programlisting role="JAVA"><![CDATA[public void paint(OutputStream out, Object data) throws IOException{ - //Some code that puts binary data to "out" Stream -} -]]></programlisting> - <para>As it was shown in the example above there are two main components:</para> - <itemizedlist> - <listitem><para> - <emphasis><property> &quot;createContent&quot; </property></emphasis>specifies a method accepting 2 parameters. The first (of <code>java.io.OutputStream</code> type) defines a stream, where any binary data is output. The second (of <code>java.lang.Object</code> type) contains deserialized object with data specified in the <emphasis > - <property>&quot;value&quot;</property> - </emphasis> attribute. - </para></listitem> - <listitem><para> - Value specifies a bean class keeping data for transmitting into a method that transmits it into a stream. - </para></listitem> - </itemizedlist> - <note><title>Note:</title><para>A bean class transmitted into value should <code>implement Serializable</code> interface. - </para> - </note> - <para>Hence, when using the component it&apos;s possible to output your data of any type on a page with Ajax requests.</para> + // Corresponding getters and setters + +}]]></programlisting> + + <para> + As a result the <emphasis role="bold"><property>&lt;a4j:mediaOutput&gt;</property></emphasis> component will generate the following image that will be updated on each page refresh: + </para> + <figure> + <title> + Using the <emphasis role="bold"><property>&lt;a4j:mediaOutput&gt;</property></emphasis> for generating an image for captcha</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/mediaOutput_init.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>Hence, when using the component it&apos;s possible to output your data of any type on a page with Ajax requests.</para> </section> <section> <title>Relevant resources links</title> - <para> - <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/mediaOutput... the component LiveDemo page</ulink> you can see the example of <emphasis role="bold" - ><property>&lt;a4j:mediaOutput &gt;</property></emphasis> usage and sources for the given example. - </para> + <para> + Vizit the <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/mediaOutput... page</ulink> at RichFaces LiveDemo for more examples of component usage and their sources. + </para> </section> </chapter> \ No newline at end of file