<section role="NotInToc" id="rich_inplaceInput">
   <title>
				&lt;
				rich:inplaceInput
				&gt;
				<emphasis role="since">
         <superscript> available since <emphasis role="version">3.2.0</emphasis>
         </superscript>
      </emphasis>
   </title>
   <section>
        <title>Description</title>
        <para>The <emphasis role="bold">
            <property>&lt;rich:inplaceInput&gt;</property>
        </emphasis> is an input component used for displaying and editing data inputted. </para>
        <figure>
            <title>
            <emphasis role="bold">
               <property>&lt;rich:inplaceInput&gt;</property>
            </emphasis> component</title>
            <mediaobject> 
                <imageobject>
                    <imagedata fileref="images/inplaceInput_init.png"/> 
                </imageobject>
            </mediaobject>
        </figure>
    </section>
   <section>
        <title>Key Features</title> 
        <itemizedlist>
            <listitem>
                <para>View/changed/edit states in highly customizable representations</para>
            </listitem>
            <listitem>
                <para>Changing state event customization</para>
            </listitem>
            <listitem>
                <para>Possibility to call custom JavaScript function on state changes</para>
            </listitem>
            <listitem>
                <para>Optional "inline" or "block" element rendering on a page</para>
            </listitem>
            <listitem>
                <para>Edit mode activation when the component gets focus with the "Tab"</para>
            </listitem>
            <listitem>
                <para>Sizes synchronizations between modes</para>
            </listitem>
            <listitem>
                <para>Controls customization</para>
            </listitem>
      </itemizedlist>  
    </section>
   <section>
        <title>Details of Usage</title>
    
      <para>    
         The
          <emphasis role="bold">
            <property>&lt;rich:inplaceInput&gt;</property>
         </emphasis>
        component was designed to facilitate displaying and inputting (editing) some data.
        </para>
      
      <para>     
        The  <emphasis>
            <property>"value"</property>
         </emphasis> attribute is a value-binding expression for the current value of the component.      
      </para>                                                                                                                                                                                                                                                                  
      <!--para> 
        However, if
        <emphasis><property>&quot;value&quot;</property></emphasis> 
        attribute is not defined, you can use 
        <emphasis><property>&quot;defaultLabel&quot;</property></emphasis>  attribute 
        which displays some default text while
        <emphasis><property>&quot;value&quot;</property></emphasis>  
        attribute stays undefined.
      </para-->                                                                                                                                                                                                                                                                  <para>     
        The component has three functional states:    
      </para>  
        <itemizedlist>        
          <listitem>
            <para>
              <property>View</property> state displays the default label with the value taken from the
              <emphasis>
                  <property>"value"</property>
               </emphasis> or <emphasis>
                  <property>"defaultLabel"</property>
               </emphasis> attributes. 
            </para>
            <para>
              If the initial value of the <emphasis>
                  <property>"value"</property>
               </emphasis> 
              attribute is "null" or <property>empty string</property>
              the <emphasis>
                  <property>"defaultLabel"</property>
               </emphasis> attribute is used to define default label.
            </para>
            <para>
              <emphasis role="bold">Example:</emphasis>
            </para>  
            <programlisting role="XML"><![CDATA[...
<rich:inplaceInput value="#{bean.value}" defaultLabel="click to edit"/>
... ]]></programlisting>
            
            <!--            <para>
                The managed bean code: 
            </para>-->
<!--            <programlisting role="JAVA"><![CDATA[<![CDATA[...
private String value = null;
...]]> ]]></programlisting>-->
            <para>
              In the example above the <emphasis>
                  <property>"value"</property>
               </emphasis> attribute is not initialized
              therefore the &quot;<code>click to edit</code>&quot; text, that  
              <emphasis>
                  <property>"defaultLabel"</property>
               </emphasis> contains, is displayed.
            </para>
            <para>
              This is the result:
            </para>
            <figure>
               <title>View state</title>  
               <mediaobject>
                  <imageobject>
                     <imagedata fileref="images/inplaceInput2.png"/>
                  </imageobject>
               </mediaobject>     
            </figure>    
         </listitem>
         <listitem>
           <para>
               <property>Edit</property> state  - input representation to allow value edit
           </para>       
            <figure>
               <title>Edit state</title>  
               <mediaobject>
                  <imageobject>
                     <imagedata fileref="images/inplaceInput3.png"/>
                  </imageobject>
               </mediaobject>     
            </figure>
          </listitem>
          <listitem>
            <para>
               <property>Changed</property> state - value representation after it was changed</para>     
            <figure>
               <title>Changed state</title>  
               <mediaobject>
                  <imageobject>
                     <imagedata fileref="images/inplaceInput4.png"/>
                  </imageobject>
               </mediaobject>     
            </figure>      
          </listitem>
        </itemizedlist>
      
      <para>
        The <emphasis>
            <property>"editEvent"</property>
         </emphasis> attribute provides an option to assign a JavaScript action 
        to initiate the change of the state from <property>view</property>/<property>changed</property> to <property>edit</property>. 
        The default value is "onclick". 
      </para>
      <para>
        <emphasis role="bold">Example:</emphasis>
      </para>  
      <programlisting role="XML"><![CDATA[...
<rich:inplaceInput value="#{bean.value}" editEvent="ondblclick"/> 
... ]]></programlisting>
      
      <!--note>
        <title>Note:</title> 
        <para>
          Do not use &quot;on&quot; prefix applying event action. E.g. use &quot;click&quot; instead of &quot;onClick&quot;, use &quot;mouseover&quot; instead of &quot;onMouseOver&quot;. 
        </para>
      </note-->
      
     
      <para>
        The <emphasis role="bold">
            <property>&lt;rich:inplaceInput&gt;</property>
         </emphasis>
        component provides specific event attributes:
      </para>
      <itemizedlist>
        <listitem>
            <para>
               <emphasis>
                  <property>"oneditactivation"</property>
               </emphasis> which is fired on <property>edit</property> state activation            
          </para>
        </listitem>
        <listitem>
            <para>
               <emphasis>
                  <property>"oneditactivated"</property>
               </emphasis> which is fired when <property>edit</property> state is activated          
          </para>
        </listitem>
        <listitem>
            <para>
               <emphasis>
                  <property>"onviewactivation"</property>
               </emphasis> which is fired on <property>view</property> state activation         
          </para>
        </listitem>
        <listitem>
            <para>
               <emphasis>
                  <property>"onviewactivated"</property>
               </emphasis> which is fired after the component is changed to representation state
          </para>
        </listitem>
      </itemizedlist>
      
      <para>
        <emphasis role="bold">Example:</emphasis>
      </para>      
      <programlisting role="XML"><![CDATA[...
<rich:inplaceInput value="#{bean.value}" oneditactivation="if (!confirm('Are you sure you want to change the value?')){return false;}" />
... ]]></programlisting>  
      <para>
        The given code illustrates how <emphasis>
            <property>"oneditactivation"</property>
         </emphasis> attribute works, 
        namely when the state is being changed from <property>view</property> to <property>edit</property>, 
        a confirmation window with a message <code>"Are you sure you want to change value?"</code> comes up.
      </para>
      
      <para>      
       Using the boolean <emphasis>
            <property>"selectOnEdit"</property>
         </emphasis> attribute set to true, 
        the text in the input field will be selected when 
        the  change from <property>view</property>/<property>changed</property> state to <property>edit</property> occurs. 
      </para>
      
      <para>This is the result:</para>
     
      <figure>
        <title>Usage of  the <emphasis>
               <property>"selectOnEdit"</property>
            </emphasis> attribute</title>
        <mediaobject>
            <imageobject>
               <imagedata fileref="images/inplaceInput5.png"/>
            </imageobject>
        </mediaobject>
      </figure>

      
      
      <para>
        If the <emphasis role="bold">
            <property>&lt;rich:inplaceInput&gt;</property>
         </emphasis> loses focus, input data is saved automatically 
        and the component displays  a new value. Additionally, the data is saved when "Enter" is pressed. 
        Nevertheless, you can use the <emphasis>
            <property>"showControls"</property>
         </emphasis>
        attribute, which makes "Save" and  "Cancel" buttons appear next to the input field.
        If the controls are used, data is not saved automatically when the form loses focus: user has to confirm that he/she wants to save/discard the data explicitly. 
       In both cases (with controls or without them) the input data can be discarded by pressing "Esc" key.
      
      </para>
      <para>
        <emphasis role="bold">Example:</emphasis>
      </para>                                                                                                                                                                                                                                                                  
      <programlisting role="XML"><![CDATA[...
<rich:inplaceInput value="#{bean.value}" showControls="true"/>
... ]]></programlisting>                                                                                                                                                                                                                                                                  
      <figure>
        <title>Usage <emphasis>
               <property>"showControls"</property>
            </emphasis> attribute</title>  
        <mediaobject>
            <imageobject>
               <imagedata fileref="images/inplaceInput6.png"/>
            </imageobject>
        </mediaobject>     
      </figure>  
      <para>
        You can also position the controls relatively to the input field, by means of 
      </para>
        <itemizedlist>
          <listitem>
            <para>
              the <emphasis>
                  <property>"controlsHorizontalPosition"</property>
               </emphasis> attribute 
              with "left", "right" and  "center" definitions      
            </para>
          </listitem>
          <listitem>
            <para>
              the <emphasis>
                  <property>"controlsVerticalPosition "</property>
               </emphasis> attribute
              with "bottom", "center" and "top" definitions
            </para>
          </listitem>
        </itemizedlist>
      <para>
        <emphasis role="bold">Example:</emphasis>
      </para>     
        <programlisting role="XML"><![CDATA[...
<rich:inplaceInput value="#{bean.value}" showControls="true" controlsVerticalPosition="bottom" controlsHorizontalPosition="left"/>
... ]]></programlisting>  
      <para>
        This is the result:
      </para>
      <figure>
         <title>Positioning of "Save" and "Cancel" buttons</title>  
        <mediaobject>
            <imageobject>
               <imagedata fileref="images/inplaceInput7.png"/>
            </imageobject>
        </mediaobject>     
      </figure>                                                                                                                                                                                                                                                                  
      <para>
        It is also possible to use <emphasis>
            <property>"controls"</property>
         </emphasis> facet in order to replace the default controls with facets content.
        See the example below.        
      </para>
      <para>
        <emphasis role="bold">Example:</emphasis>
      </para>
      <programlisting role="XML"><![CDATA[...
<rich:inplaceInput defaultLabel="Click here to edit" showControls="true" controlsHorizontalPosition="left" controlsVerticalPosition="bottom" id="inplaceInput">
    <f:facet name="controls">
        <h:commandButton value="Save" onclick="#{rich:component('inplaceInput')}.save();" type="button" />
        <h:commandButton value="Cancel" onclick="#{rich:component('inplaceInput')}.cancel();" type="button" />
    </f:facet>
</rich:inplaceInput>
... ]]></programlisting>   
      <para>
        This is the result:
      </para>
      <figure>
        <title>
            <emphasis>
               <property>"controls"</property>
            </emphasis> facet usage</title>  
        <mediaobject>
            <imageobject>
               <imagedata fileref="images/inplaceInput8.png"/>
            </imageobject>
        </mediaobject>     
      </figure>   

      <note>
        <title>Note:</title>
        <para>
          The <emphasis> 
               <property>"controls"</property>
            </emphasis>facet also implies using 
          <emphasis>
               <property>"showControls"</property>
            </emphasis> 
          attribute and it has to be defined as "true".
        </para>     
      </note>
      <para>
        Redefinition of the
        "save" and "cancel" icons can be performed using 
        <emphasis>
            <property>"saveControlIcon"</property>
         </emphasis>
        and  
        <emphasis>
            <property>"cancelControlIcon"</property>
         </emphasis>
        attributes.  You need to define the path to where your  images are located. 
      </para>
      <para>
        <emphasis role="bold">Example:</emphasis>
      </para>                                                                                                                                                                                                                                                                  
      <programlisting role="XML"><![CDATA[...
<rich:inplaceInput value="#{bean.value}" defaultLabel='click to edit'
    showControls="true"
    controlsHorizontalPosition="left"
    controlsVerticalPosition="top"
    saveControlIcon="/images/cancel.gif"
    cancelControlIcon="/images/save.gif"/> 
    ... ]]></programlisting>   
      <figure>
        <title>Redefining of "save" and "cancel" buttons</title>  
        <mediaobject>
            <imageobject>
               <imagedata fileref="images/inplaceInput9.png"/>
            </imageobject>
        </mediaobject>     
      </figure>
      <para>
        The <emphasis role="bold">
            <property>&lt;rich:inplaceInput&gt;</property>
         </emphasis> component could be rendered with 
        <emphasis role="bold">
            <property>&lt;span&gt;</property>
         </emphasis> or <emphasis role="bold">
            <property>&lt;div&gt;</property>
         </emphasis>  
        elements to display its value.
        In order to change default <emphasis role="bold">
            <property>&lt;span&gt;</property>
         </emphasis> output, 
        use  <emphasis>
            <property>"layout"</property>
         </emphasis> attribute with "block" value.
      </para>
     
      <para>
        The <emphasis role="bold">
            <property>&lt;rich:inplaceInput&gt;</property>
         </emphasis> component supports the standard
        <emphasis>
            <property>"tabindex"</property>
         </emphasis> attribute. 
        When the component gets focus the <property>edit</property> mode is activated.
      </para>                                                                                                                                                                                                                                                                  
      <para>
        The 
        <emphasis>
            <property>"inputWidth"</property>
         </emphasis>, 
        <emphasis>
            <property>"minInputWidth"</property>
         </emphasis>,
        <emphasis>
            <property>"maxInputWidth"</property>
         </emphasis> 
        attributes are provided to specify the width, minimal width and maximal width for the input element respectively. 
      </para>                                                                                                                                                                                                                                                                  
      <table>
        <title>Keyboard usage</title>
        <tgroup cols="2">
            <thead>
               <row>
                  <entry>Keys and combinations </entry>
                  <entry>Description</entry>
               </row>
            </thead>
            <tbody>
               <row>
                  <entry>ENTER</entry>
                  <entry>Saves the input data, and changes the state from edit to changed</entry>
               </row>
               <row>
                  <entry>ESC</entry>
                  <entry>Changes the state from edit to view or changed, value is not affected</entry>
               </row>
               <row>
                  <entry>TAB</entry>
                  <entry>Switches between the components</entry>
               </row>
              </tbody>
        </tgroup>
      </table>
    
    
    </section>
   <section>
      <title>Reference Data</title>
      <para>
         <ulink url="&tlddoc;rich/inplaceInput.html">Table of 
							&lt;rich:inplaceInput&gt; 
							 attributes</ulink>.
						</para>
      <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.richfaces.inplaceInput</entry>
                </row>
                <row>
                    <entry>component-class</entry>
                    <entry>org.richfaces.component.html.HtmlInplaceInput</entry>
                </row>
                <row>
                    <entry>component-family</entry>
                  <entry>org.richfaces.inplaceInput</entry>
                </row>
                <row>
                    <entry>renderer-type</entry>
                  <entry>org.richfaces.renderkit.inplaceInputRenderer</entry>
                </row>
                <row>
                    <entry>tag-class</entry>
                  <entry>org.richfaces.taglib.inplaceInputTag</entry>
                </row>
            </tbody>
        </tgroup>
      </table>
      <table> 
         <title>JavaScript API</title>
         <tgroup cols="2">
            <thead>
               <row>
                  <entry>Function</entry>
                  <entry>Description</entry>
            
               </row>
            </thead>
            <tbody>
                    <!--Sorting API -->
                    <row>
                      <entry>edit()</entry>
                      <entry>Changes the  state to edit </entry>
                    </row>
                    <row>
                      <entry>cancel()</entry>
                      <entry>Changes its state to the previous one before editing (changed or view)</entry>
                    </row>       
                  <row>
                    <entry>save()</entry>
                    <entry>Changes its state to  changed with a new value</entry>
                  </row>
                  <row>
                    <entry>getValue()</entry>
                    <entry>Gets the current value</entry>
                  </row>
                  <row>
                    <entry>setValue(newValue) </entry>
                    <entry>Sets the current value (to be implemented)</entry>
                  </row>
            </tbody>
         </tgroup>
      </table>
      <table>
			      <title>Facets</title>
				     <tgroup cols="2">
					       <thead>
						         <row>
							           <entry>Facet name</entry>
							           <entry>Description</entry>
						         </row>
					       </thead>
					       <tbody>
						         <row>
							           <entry>controls</entry>
							           <entry>Defines the contols contents. Related attributes are "saveControlIcon" and "cancelControlIcon"</entry>
						         </row>
					       </tbody>
				     </tgroup>
      </table>
				
   	<table>
   		<title>Style classes (selectors) with the corresponding skin parameters</title>
   		<tgroup cols="4">
   			<thead>
   				<row>
   					<entry>Class (selector) name</entry>
   					<entry>Description</entry>
   					<entry>Skin Parameters</entry>
   					<entry>CSS properties mapped</entry>
   					
   				</row>
   			</thead>
   			<tbody>
   				<row>
   					<entry morerows="1">.rich-inplace-control</entry>
   					<entry morerows="1">Defines styles for the controls</entry>
   					<entry>tabBackgroundColor</entry>
   					<entry>background-color</entry>
   				</row>
   				<row>
   					<entry>panelBorderColor</entry>
   					<entry>border-color</entry>
   				</row>
   				
   				<row>
   					<entry morerows="1">.rich-inplace-control-press</entry>
   					<entry morerows="1">Defines styles for the controls when either of the buttons is pressed</entry>
   					<entry>tabBackgroundColor</entry>
   					<entry>background-color</entry>
   				</row>
   				<row>
   					<entry>panelBorderColor</entry>
   					<entry>border-color</entry>
   				</row>
   				
   				<row>
   					<entry morerows="1">.rich-inplace-view</entry>
   					<entry morerows="1">Defines styles for the view state</entry>
   					<entry>editorBackgroundColor</entry>
   					<entry>background-color</entry>
   				</row>
   				<row>
   					<entry>generalTextColor</entry>
   					<entry>border-bottom-color</entry>
   				</row>
   				
   				<row>
   					<entry morerows="1">.rich-inplace-changed</entry>
   					<entry morerows="1">Defines styles for the &quot;Changed&quot; state</entry>
   					<entry>editorBackgroundColor</entry>
   					<entry>background-color</entry>
   				</row>
   				<row>
   					<entry>generalTextColor</entry>
   					<entry>border-bottom-color</entry>
   				</row>
   				
   				<row>
   					<entry morerows="1">input.rich-inplace-field</entry>
   					<entry morerows="1">Defines styles for the input field in edit state</entry>
   					<entry>editorBackgroundColor</entry>
   					<entry>background-color</entry>
   				</row>
   				<row>
   					<entry>panelBorderColor</entry>
   					<entry>border-color</entry>
   				</row>
   			</tbody>
   		</tgroup>
   	</table>
   	
   	<table>
   		<title>Style classes (selectors) without skin parameters</title>
   		<tgroup cols="2">
   			<thead>
   				<row>
   					<entry>Class name</entry>
   					<entry>Description</entry>
   				</row>
   			</thead>
   			<tbody>
   				<row>
   					<entry>.rich-inplace</entry>
   					<entry>Defines styles for a wrapper &lt;span&gt; (or &lt;div&gt;) element of a component</entry>
   				</row>
   				
   				<row>
   					<entry>.rich-inplace-input</entry>
   					<entry>Defines styles for the component input field</entry>
   				</row>
   				
   				<row>
   					<entry>.rich-inplace-input-view-hover</entry>
   					<entry>Defines styles for hovered text in  the view state  </entry>
   				</row>
   				
   				<row>
   					<entry>.rich-inplace-field</entry>
   					<entry>Defines styles for the input field look and feel in edit state</entry>
   				</row>
   				
   				<row>
   					<entry>.rich-inplace-input-changed-hover </entry>
   					<entry>Defines styles for the hovered text in  the "Changed" state</entry>
   				</row>
   				
   				<row>
   					<entry>.rich-inplace-shadow-size</entry>
   					<entry>Defines size of the shadow</entry>
   				</row>
   				
   				<row>
   					<entry>.rich-inplace-shadow-tl</entry>
   					<entry>Defines styles for the shadow in the top left corner </entry>
   				</row>
   				
   				<row>
   					<entry>.rich-inplace-shadow-tr</entry>
   					<entry>Defines styles for the shadow in the top right corner</entry>
   				</row>
   				
   				<row>
   					<entry>.rich-inplace-shadow-bl</entry>
   					<entry>Defines styles for the shadow in the bottom left corner</entry>
   				</row>
   				
   				<row>
   					<entry>.rich-inplace-shadow-br</entry>
   					<entry>Defines styles for the shadow in the bottom right corner</entry>
   				</row>
   			</tbody>
   		</tgroup>
   	</table>
   	
	 <para>You can find all necessary information about style classes redefinition in 
						<link linkend="customstyles">Definition of Custom Style Classes</link> 
							section.</para>
						</section>
   <section>
      <title>Relevant Resources Links</title>
      <para>
         <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/inplaceInput.jsf?c=inplaceInput">On the component Live Demo page</ulink>
      you can see the example of <emphasis role="bold">
            <property>&lt;rich:inplaceIput&gt;</property>
         </emphasis> usage and sources for the given example. </para>
  </section>
</section>
