<?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></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>    
          As it was mentioned earlier the 
          <emphasis role="bold"><property>&lt;rich:inplaceInput&gt;</property>  </emphasis>
          component was designed to facilitate inputting and editing some parts of text.
        </para>
      
      <para>     
        The component has three logical states:    
        <itemizedlist>        
          <listitem>
            <para><property>View</property> state displays the text containing in a <emphasis><property>&quot;value&quot;</property></emphasis>  attribute;</para>
          <figure>
            <title>View state</title>  
            <mediaobject>
              <imageobject>
                <imagedata fileref="images/inplaceInputViewState_shadow.png"/>
              </imageobject>
            </mediaobject>     
          </figure>        
          </listitem>
         <listitem>
            <para><property>Edit</property> state  - the text can be edited and saved;</para>       
                      <figure>
            <title>Edit state</title>  
            <mediaobject>
              <imageobject>
                <imagedata fileref="images/inplaceInputEditState_shadow.png"/>
              </imageobject>
            </mediaobject>     
          </figure>
          </listitem>
          <listitem>
            <para><property>Changed</property> state - displays the edited text and indicates that it was edited, changed;</para>     
                    <figure>
            <title>Changed state</title>  
            <mediaobject>
              <imageobject>
                <imagedata fileref="images/inplaceInputChangedState_shadow.png"/>
              </imageobject>
            </mediaobject>     
          </figure>      
          </listitem>
    </itemizedlist>
   
      </para>  
      
      
      
      
      
      
        <para>     
          The main attribute of the component is 
          <emphasis><property>&quot;value&quot;</property></emphasis> 
          it displays the text on a page, the text can be edited by clicking (default action, which can be redefined) on it.         
        </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>
        <emphasis role="bold">Example:</emphasis>
      </para>   
      
      <programlisting role="XML"><![CDATA[...
<rich:inplaceInput value="#{bean.value}" defaultLabel="click to edit"/>
...]]> </programlisting>      
      <para>
        In the shown example,
        <emphasis><property>&quot;value&quot;</property></emphasis> attribute is not defined; 
        therefore default text &quot;Click to edit&quot; is displayed 
        since it is placed into the 
        <emphasis><property>&quot;defaultLabel&quot;</property></emphasis> attribute.       
      </para>
      
      
      <para>
      Input data is saved (submitted) automatically whenever the input field loses focus. 
      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. 
     </para>
      <para>
        <emphasis role="bold">Example:</emphasis>
      </para>      
      
      <programlisting role="XML"><![CDATA[...
<rich:inplaceInput value="#{bean.value}" defaultLabel='click to edit' showControls="true"/>
...]]> </programlisting>    
      
      <figure>
        <title>Usage <emphasis><property>&quot;showControls&quot;</property></emphasis> attribute</title>  
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/inplaceInputShowControls.png"/>
          </imageobject>
        </mediaobject>     
      </figure>  
      <para>
        You can also position the controls relatively to the input field, by means of 
        <emphasis><property>&quot;  controlsHorizontalPosition&quot;</property></emphasis> 
        <emphasis><property>&quot; controlsVerticalPosition &quot;</property></emphasis>
        attributes.
        
        The 
        <emphasis><property>&quot;  controlsHorizontalPosition&quot;</property></emphasis> attribute has 
        &quot;left&quot;, &quot;right&quot; and  &quot;center&quot; definitions. 
        
        The 
        <emphasis><property>&quot; controlsVerticalPosition &quot;</property></emphasis>
        attribute has &quot;bottom&quot;, &quot;center&quot; and &quot;top&quot; definitions.
         </para>
      
      <figure>
        <title>Positioning of &quot;save&quot; and &quot;cancel&quot; buttons</title>  
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/inplaceInputShowControlsAlignLeft.png"/>
          </imageobject>
        </mediaobject>     
      </figure>   
      
      <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="/richfaces-demo/richfaces/cancel.gif"
    cancelControlIcon="/richfaces-demo/richfaces/save.gif"/> 
    ...]]> </programlisting>   
      <figure>
        <title>Redefining of &quot;save&quot; and &quot;cancel&quot; buttons</title>  
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/inplaceInputShowControlsCustom.png"/>
          </imageobject>
        </mediaobject>     
      </figure>   
    <para>
      The 
      <emphasis><property>&quot;inputWidth&quot;</property></emphasis>, 
      <emphasis><property>&quot;minInputWidth&quot;</property></emphasis>, and 
      <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>  
      
      
      <para>
        The 
        <emphasis><property>&quot;editEvent&quot;</property></emphasis>         
        attribute provides an option to assign an JavaScript action that initiates the change of the state  from
      <property>view</property>
        to 
        <property>edit</property>. 
        
        
        The default value is &quot;click&quot;. 
   
      </para>
      
   
      
      <note>
        <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>
   Having multiple
   <emphasis role="bold"><property>&lt;rich:inplaceInput&gt;</property></emphasis>
   components 
   on a page you can use <emphasis><property>&quot;tabindex&quot;</property></emphasis>  attribute that enables switching (tabbing)
   between the components by pressing the “Tab” key. 
   Switching order is determined by the value of the attribute which is an integer between 0 and 32767.
 </para>  
  
  
 <para> 
 
 The 

   <emphasis><property>&quot;selectOnEdit&quot;</property></emphasis>  
   (with possible values &quot;true&quot;, &quot;false&quot;) gives you an 
   option to make the text in the input area selected right after the change from 
   <property>view</property> state to <property>edit</property> occurs. 
 
  </para>
<para>
  The 
  <emphasis><property>&quot; oneditactivation&quot;</property></emphasis> , 
  <emphasis><property>&quot;oneditactivated&quot;</property></emphasis> , 
  <emphasis><property>&quot;onviewactivation&quot;</property></emphasis> 
  and  
  <emphasis><property>&quot; onviewactivated&quot;</property></emphasis>  attributes
  provide a possibility to assign JavaScript code on 
  <property>edit</property> state activation, on 
  <property>edit</property> state activated,on 
<property>view</property> state activation and on 
<property>view</property> state activated respectively. 
</para>

      
      <para>
        <emphasis role="bold">Example:</emphasis>
      </para>      
      <programlisting role="XML"><![CDATA[...
<rich:inplaceInput value="#{bean.value}" defaultLabel='click to edit'
 onviewactivated="if (confirm('Are you sure you want to change value?')){return false;}" />
...]]> </programlisting>  
      <para>
        The given code illustrates how onviewactivation attribute works, 
        namely when the state is being changed from 
        <property>edit</property> to 
      <property>view</property>, 
        a confirmation window with a message
        &quot;Are you sure you want to change value?&quot; comes up.
      </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>the component hanges the state to the previous one before editing (changed or view)</entry>
                    </row>
                    <row>
                      <entry>save()</entry>
                      <entry>the component changes its state to  changed with a new value</entry>
                    </row>
                  <row>
                    <entry>save()</entry>
                    <entry>the component 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</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>Redefine the corresponding skin parameters</listitem>
            <listitem> Add to your style sheets style classes used by a <emphasis role="bold">
                <property>&lt;rich:inplaceInput&gt;</property>
            </emphasis> component</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/inplaceInputClasses.png"/>
        </imageobject>
      </mediaobject>
    </figure>    
    
    
    <table>
      <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> 
          
          rich-inplace-input-changed-hover 
        </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_cn3"> 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: bold;
}						
	
...]]></programlisting>  
    
    <para>This is the result:</para>
    
    <figure>
      <title>Redefinition styles with predefined classes</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/inplaceInputRich-inplace-field.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> <property>styleClass</property> 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;styleClass&quot;</property></emphasis> attribute for <emphasis role="bold"
      ><property>&lt;rich:inplaceInput&gt; </property></emphasis> is defined as it’s shown in the example below:</para>
    
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="CSS"><![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/inplaceInputMyClass.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/progressbar.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>