<?xml version="1.0" encoding="UTF-8"?>
<section>
    <sectioninfo>
        <keywordset>
            <keyword>rich:inplaceInput</keyword>
            <keyword>inplaceInput</keyword>
        </keywordset>
    </sectioninfo>
    <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>
    <section>
        <title>Creating the Component with a Page Tag</title>
        <para>Here is a simple example of how the component can be used on a page: </para>
        <para>
            <emphasis role="bold">Example:</emphasis>
        </para>
        <programlisting role="XML"><![CDATA[...
<rich:inplaceInput value="#{bean.value}"/>
...]]></programlisting>
    </section>
    <section>
        <title>Creating the Component Dynamically Using Java</title>
        <para>
            <emphasis role="bold">Example:</emphasis>
        </para>
      <programlisting role="JAVA"><![CDATA[import org.richfaces.component.html.inplaceInput;
...	
HtmlInpaceInput myInplaceInput = new InplaceInput();
...]]></programlisting>
    </section>
  
    <!-- Start  Details of Usage-->
    <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>&quot;value&quot;</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 default label with the value taken from 
              <emphasis><property>&quot;value&quot;</property></emphasis> or <emphasis><property>&quot;defaultLabel&quot;</property></emphasis> attributes. 
            </para>
            <para>
              If the initial value of the <emphasis><property>&quot;value&quot;</property></emphasis> 
              attribute is &quot;null&quot; or <property>empty string</property>
              the <emphasis><property>&quot;defaultLabel&quot;</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[...
private String value = null;
...]]> </programlisting>-->
            <para>
              In the example above the <emphasis><property>&quot;value&quot;</property></emphasis> attribute is not initialized
              therefore &quot;<code>click to edit</code>&quot; text, that  
              <emphasis><property>&quot;defaultLabel&quot;</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>&quot;editEvent&quot;</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 &quot;onclick&quot;. 
      </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>&quot;oneditactivation&quot;</property></emphasis> which is fired on <property>edit</property> state activation            
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis><property>&quot;oneditactivated&quot;</property></emphasis> which is fired when <property>edit</property> state is activated          
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis><property>&quot;onviewactivation&quot;</property></emphasis> which is fired on <property>view</property> state activation         
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis><property>&quot;onviewactivated&quot;</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>&quot;oneditactivation&quot;</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>&quot;Are you sure you want to change value?&quot;</code> comes up.
      </para>
      
      <para>      
       Using the boolean <emphasis><property>&quot;selectOnEdit&quot;</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>&quot;selectOnEdit&quot;</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 &quot;Enter&quot; is pressed. 
        Nevertheless, you can use the <emphasis><property>&quot;showControls&quot;</property></emphasis>
        attribute, which makes &quot;Save&quot; and  &quot;Cancel&quot; 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 &quot;Esc&quot; 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>&quot;showControls&quot;</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>&quot;controlsHorizontalPosition&quot;</property></emphasis> attribute 
              with &quot;left&quot;, &quot;right&quot; and  &quot;center&quot; definitions      
            </para>
          </listitem>
          <listitem>
            <para>
              The <emphasis><property>&quot;controlsVerticalPosition &quot;</property></emphasis> attribute
              with &quot;bottom&quot;, &quot;center&quot; and &quot;top&quot; 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 &quot;Save&quot; and &quot;Cancel&quot; buttons</title>  
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/inplaceInput7.png"/>
          </imageobject>
        </mediaobject>     
      </figure>   
      
      <para>
        It is also possible to use <emphasis><property>&quot;controls&quot;</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">
        <button onclick="#{rich:component('inplaceInput')}.save();" type="button">Save</button>
        <button onclick="#{rich:component('inplaceInput')}.cancel();" type="button">Cancel</button>
    </f:facet>
</rich:inplaceInput>
...]]> </programlisting>   
      <para>
        This is the result:
      </para>
      <figure>
        <title><emphasis><property>&quot;controls&quot;</property></emphasis> facet usage</title>  
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/inplaceInput8.png"/>
          </imageobject>
        </mediaobject>     
      </figure>   

      <note>
        <title>Note:</title>
        <para>
          The <emphasis> <property>&quot;controls&quot;</property></emphasis>facet also implies using 
          <emphasis><property>&quot;showControls&quot;</property></emphasis> 
          attribute and it has to be defined as &quot;true&quot;.
        </para>     
      </note>
      <para>
        Redefinition of the
        &quot;save&quot; and &quot;cancel&quot; icons can be performed using 
        <emphasis><property>&quot;saveControlIcon&quot;</property></emphasis>
        and  
        <emphasis><property>&quot;cancelControlIcon&quot;</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 &quot;save&quot; and &quot;cancel&quot; 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>&quot;layout&quot;</property></emphasis> attribute with &quot;block&quot; value.
      </para>
     
      <para>
        The <emphasis role="bold"><property>&lt;rich:inplaceInput&gt;</property></emphasis> component supports standard
        <emphasis><property>&quot;tabindex&quot;</property></emphasis> attribute. 
        When the component gets focus the <property>edit</property> mode is activated.
      </para>  
      
      <para>
        The 
        <emphasis><property>&quot;inputWidth&quot;</property></emphasis>, 
        <emphasis><property>&quot;minInputWidth&quot;</property></emphasis>,
        <emphasis><property>&quot;maxInputWidth&quot;</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>
    <!-- End. Details of Usage-->


    <!-- JavaScript API-->  
  <section>
    <title>JavaScript API</title>
    <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  role="tbi">setValue(newValue) </entry>
                    <entry  role="tbi">Sets the current value (to be implemented)</entry>
                  </row>
        </tbody>
      </tgroup>
    </table>
  </section>
    <!-- End of JavaScript API-->   
    
    <!-- Look-and-Feel Customization-->  
    
    <section>
        <title>Look-and-Feel Customization</title>
        <para>For skinnability implementation, the components use a <emphasis>
            <property>style class redefinition method.</property>
        </emphasis> Default style classes are mapped on <emphasis>
            <property>skin parameters.</property>
        </emphasis></para>
        <para>There are two ways to redefine the appearance of all <emphasis role="bold">
            <property>&lt;rich:inplaceInput&gt;</property>
        </emphasis> components at once: <itemizedlist>
            <listitem><para>Redefine the corresponding skin parameters</para></listitem>
            <listitem><para> Add to your style sheets style classes used by a <emphasis role="bold">
                <property>&lt;rich:inplaceInput&gt;</property>
            </emphasis> component</para></listitem>
        </itemizedlist>
        </para>
    </section>
       

 <section>
    <title>Skin Parameters Redefinition</title>

    <table>
      <title>Skin parameters redefinition for &quot;save&quot; and &quot;cancel&quot; controls</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</entry>
            <entry>CSS properties</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry>tabBackgroundColor</entry>
            <entry>background-color</entry>
          </row>
          
          <row>
            <entry>panelBorderColor</entry>
            <entry>border-color</entry>
          </row>
          
          <row>
            <entry>panelBorderColor</entry>
            <entry>border-color</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <table>
      <title>Skin parameters redefinition for view state</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</entry>
            <entry>CSS properties</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry>editorBackgroundColor</entry>
            <entry>background-color</entry>
          </row>
          <row>
            <entry>generalTextColor</entry>
            <entry>border-bottom-color</entry>
          </row>
           </tbody>
      </tgroup>
    </table>



    <table>
      <title>Skin parameters redefinition for &quot;Changed&quot; state</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</entry>
            <entry>CSS properties</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry>editorBackgroundColor</entry>
            <entry>background-color</entry>
          </row>

          <row>
            <entry>generalTextColo</entry>
            <entry>border-bottom-color</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <table>
      <title>Classes names that define input field look and feel in edit state </title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</entry>
            <entry>CSS properties</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry>editBackgroundColor</entry>
            <entry>background-color</entry>
          </row>

          <row>
            <entry>panelBorderColor</entry>
            <entry>border-color</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    
  </section>-->
  <!-- END Skin Parameters Redefinition-->  

  <!-- Definition of Custom Style Classes-->  

  <section>
    <title>Definition of Custom Style Classes</title>
    <para>On the screenshot there are classes names that define styles for component elements.</para>

    <figure>
      <title>Classes names</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/inplaceInput_cn.png"/>
        </imageobject>
      </mediaobject>
    </figure>    

    <table  id="tab_cn_iI">
      <title>Class name for the view state</title>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Class name</entry>
            <entry>Description</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>rich-inplace-view</entry>
            <entry>Defines styles for the view state</entry>
          </row>
          <row>
            <entry>rich-inplace-input-view-hover</entry>
            <entry>Defines styles for hovered text in  the view state  </entry>
          </row>
        </tbody>
      </tgroup>
    </table>
    
    <table>
      <title>Class name for the input field in  edit state</title>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Class name</entry>
            <entry>Description</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>rich-inplace-field</entry>
            <entry>Defines styles for input field look and feel in edit state</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
    
    <table>
      <title>Class name for the &quot;Changed&quot; state</title>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Class name</entry>
            <entry>Description</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>rich-inplace-changed</entry>
            <entry>Defines styles for the &quot;Changed&quot; state</entry>
          </row>
          <row>
            <entry> rich-inplace-input-changed-hover </entry>
            <entry>Defines styles for the hovered text in  the &quot;Changed&quot; state</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
    
    
    
    
    <table>
      <title>Classes names &quot;save&quot; and &quot;cancel&quot; controls in Edit state</title>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Class name</entry>
            <entry>Description</entry>
          </row>
        </thead>
        <tbody>
          
          <row>
            <entry>rich-inplace-control</entry>
            <entry>Defines styles for the controls</entry>
          </row>
          <row>
            <entry>rich-inplace-control-press</entry>
            <entry>Defines styles for the controls when either of the buttons is pressed</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>
      In order to redefine styles for all <emphasis role="bold"><property>&lt;rich:inplaceInput&gt;</property></emphasis> components on a page using CSS, 
      it&apos;s enough to create classes with the
      same names (possible classes could be found in the tables <link linkend="tab_cn_iI"> above</link>) and define necessary properties in them. 
    </para> 
    
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="CSS"><![CDATA[...
.rich-inplace-field {
    font-style: italic;
}						
	
...]]></programlisting>  
    
    <para>This is the result:</para>
    
    <figure>
      <title>Redefinition styles with predefined classes</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/inplaceInput_pc.png"/>
        </imageobject>
      </mediaobject>
    </figure>
    <para>In the shown example the font in <property>edit</property> state is changed to bold.</para>
    
    <para>
      It&apos;s aslo possible to change styles of a particular <emphasis role="bold"> <property>&lt;rich:inplaceInput&gt;</property></emphasis> component. 
      In this case you should create own style classes and use them in corresponding 
      <emphasis role="bold"><property>&lt;rich:inplaceInput&gt;</property></emphasis><emphasis><property>styleClass</property></emphasis> attributes. 
      An example is placed below:
    </para>
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="CSS"><![CDATA[...
.myClass {
    color:  #008cca;
}
...]]></programlisting>  
    <para>
      The <emphasis><property>&quot;viewClass&quot;</property></emphasis> attribute for 
      the <emphasis role="bold"><property>&lt;rich:inplaceInput&gt;</property></emphasis> is defined as it&apos;s shown in the example below:
    </para>
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...<rich:inplaceInput value="click to edit" styleClass="myClass"/>
]]></programlisting>    
    
    <para>This is a result:</para>
    
    <figure>
      <title>Modificaton of a look and feel with own classes and <emphasis><property>styleClass</property></emphasis> attributes</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/inplaceInput_oc.png"/>
        </imageobject>
      </mediaobject>
    </figure>  
    
    <para>As it could be seen on the picture above, the font color of the text on the component was changed.</para>
        
  </section>
  <section>
    <title>Relevant Resources Links</title>
    <para>
      <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/inplaceInput.jsf?c=inplaceInput">Here</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>