[richfaces-svn-commits] JBoss Rich Faces SVN: r22975 - modules/docs/trunk/Component_Reference/src/main/docbook/en-US.

Author: bleathem Date: 2011-11-22 18:04:07 -0500 (Tue, 22 Nov 2011) New Revision: 22975 Modified: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Rich_inputs.xml Log: Grammar cleanup of the editor component documentation Modified: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Rich_inputs.xml =================================================================== --- modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Rich_inputs.xml 2011-11-22 19:28:59 UTC (rev 22974) +++ modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Rich_inputs.xml 2011-11-22 23:04:07 UTC (rev 22975) @@ -814,10 +814,10 @@ </mediaobject> </figure> <para> - <sgmltag>&lt;rich:editor&gt;</sgmltag> component is based on CKEditor implementation. + <sgmltag>&lt;rich:editor&gt;</sgmltag> component is based on the CKEditor implementation. </para> <para> - When rendering <sgmltag>&lt;rich:editor&gt;</sgmltag>, textarea is rendered to the page and once the page is completely loaded (ready state), textarea is enhanced using CKEditor script and replaced with full-featured WYSIWYG editor. + When rendering a <sgmltag>&lt;rich:editor&gt;</sgmltag>, a textarea is rendered to the page and once the page is completely loaded (ready state), the textarea is enhanced using a CKEditor script and replaced with a full-featured WYSIWYG editor. </para> <section id="sect-Component_Reference-richeditor-Basic_usage"> @@ -829,45 +829,45 @@ <title>Basic usage of <sgmltag>&lt;rich:editor&gt;</sgmltag></title> <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/exam-Component_Reference-richeditor-Basic_usage.xml_sample" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <para> - Note that editor does produce HTML markup and to be able render it's output, markup needs to be output as unescaped (as with <sgmltag>&lt;h:outputText&gt;</sgmltag> component in example above). + Note that the editor produces HTML markup and to be able to render it's output, the markup needs to be unescaped (as with <sgmltag>&lt;h:outputText&gt;</sgmltag> component in example above). </para> </example> <para> - Dimensions of editor can be managed using <parameter>width</parameter> and <parameter>height</parameter> attributes. + The dimensions of the editor can be managed using <parameter>width</parameter> and <parameter>height</parameter> attributes. </para> <para> - The <parameter>readonly</parameter> attribute can be used to switch editor into read-only mode. + The <parameter>readonly</parameter> attribute can be used to switch the editor into a read-only mode. </para> <para> The <parameter>tabindex</parameter> attribute specifies the position of the current element in the tabbing order for the current document. </para> <note> - <code>ResourceServlet</code> has to be registered for <code>url-pattern</code> <code>/org.richfaces.resources/*</code> in order to serve editor resources (JavaScript, CSS, images) correctly. Check <emphasis>RichFaces Developer's Guide</emphasis> out for details. + The <code>ResourceServlet</code> has to be registered for the <code>url-pattern</code> <code>/org.richfaces.resources/*</code> in order to serve the editor resources (JavaScript, CSS, images) correctly. Check the <emphasis>RichFaces Developer's Guide</emphasis> for further details. </note> <note> - The <sgmltag>&lt;rich:editor&gt;</sgmltag> requires having <sgmltag>&lt;h:body&gt;</sgmltag> component present in the view and being its ancestor for rendering resource dependencies correctly. + The <sgmltag>&lt;rich:editor&gt;</sgmltag> requires the <sgmltag>&lt;h:body&gt;</sgmltag> component to be present in the view and must be an ancestor of the editor in order for the resource dependencies to render correctly. </note> </section> <section id="sect-Component_Reference-richeditor-Styling"> <title>Styling</title> <para> - There are several options to customize style of the editor: + There are several options to customize the style of the editor: </para> <itemizedlist> <listitem> <para> - <parameter>style, styleClass</parameter>: customizes style of the editor and underlying textarea + <parameter>style, styleClass</parameter>: customizes the style of the editor and underlying textarea </para> </listitem> <listitem> <para> - <parameter>editorStyle, editorClass</parameter>: customizes style of the CKEditor instance + <parameter>editorStyle, editorClass</parameter>: customizes the style of the CKEditor instance </para> </listitem> <listitem> <para> - <parameter>textareaStyle, textareaClass</parameter>: customizes style of the underlying textarea + <parameter>textareaStyle, textareaClass</parameter>: customizes the style of the underlying textarea </para> </listitem> </itemizedlist> @@ -876,10 +876,10 @@ <section id="sect-Component_Reference-richeditor-Editor_skins"> <title>Editor skins</title> <para> - The <sgmltag>&lt;rich:editor&gt;</sgmltag> comes with skinnability using attribute <code>skin</code> and two approaches: + The <sgmltag>&lt;rich:editor&gt;</sgmltag> is skinnable using the <code>skin</code> attribute and either of the two approaches: </para> <para> - At first, <sgmltag>&lt;rich:editor&gt;</sgmltag> has default skin called <code>richfaces</code> that is optimized to suit rest of the component suite look &amp; feel and behaves regarding to which RichFaces skin is currently chosen (refer to <emphasis>RichFaces Developer's Guide</emphasis> for details about <emphasis>Skinning and theming</emphasis>). + By default, <sgmltag>&lt;rich:editor&gt;</sgmltag> has a skin called <code>richfaces</code> that is optimized to match rest of the component suite look &amp; feel and changes to match the active RichFaces skin (refer to <emphasis>RichFaces Developer's Guide</emphasis> for details about <emphasis>Skinning and theming</emphasis>). </para> <example> <title>The skin <code>richfaces</code> of <sgmltag>&lt;rich:editor&gt;</sgmltag></title> @@ -890,17 +890,17 @@ </imageobject> <textobject> <para> - A <sgmltag>&lt;rich:editor&gt;</sgmltag> with default <code>richfaces</code> editor skin rendered against several RichFaces Skin options. + A <sgmltag>&lt;rich:editor&gt;</sgmltag> with the default <code>richfaces</code> editor skin rendered against several RichFaces Skin options. </para> </textobject> </mediaobject> </figure> <para> - A <sgmltag>&lt;rich:editor&gt;</sgmltag> with default <code>richfaces</code> editor skin rendered against several RichFaces Skin options. + A <sgmltag>&lt;rich:editor&gt;</sgmltag> with the default <code>richfaces</code> editor skin rendered against several RichFaces Skin options. </para> </example> <para> - Second option gives you possibility to use any other skin for CKEditor, either from standard distribution or downloaded one or custom one. In distribution, there are three skins bundled: <code>kama, v2, office2003</code>. + Alternatively, you can use any other CKeditor skin, either from the standard distribution, a downloaded skin, or a custom skin. In the distribution, there are three skins bundled: <code>kama, v2, office2003</code>. </para> <example> <title>Examples of <sgmltag>&lt;rich:editor&gt;</sgmltag> skins in CKEditor distribution</title> @@ -925,23 +925,19 @@ <section id="sect-Component_Reference-richeditor-Advanced_configuration"> <title>Advanced configuration</title> <para> - Basic set of <sgmltag>&lt;rich:editor&gt;</sgmltag> attributes allows to support common use-cases for WYSIWYG editor. + The basic set of <sgmltag>&lt;rich:editor&gt;</sgmltag> attributes allows you to support common use-cases for a WYSIWYG editor. + However the underlying CKEditor implementation supports many more configuration options. </para> <para> - However CKEditor imlementation supports much more configuration options. + Use the <parameter>config</parameter> attribute to define any of these advanced configuration options supported by the CKEditor. + This configuration is written in JavaScript object format and its value is interpolated for EL expressions (making configuration dynamic). </para> <para> - Attribute <parameter>config</parameter> gives possibility to define any advanced configuration option which CKEditor supports. + There are two ways to define the configuration: the <parameter>config</parameter> attribute or a facet named <parameter>config</parameter>. The facet takes precedence over attribute when both are defined. </para> - <para> - Configuration is written in JavaScript object format and its value is interpolated for EL expressions (making configuration dynamic). - </para> - <para> - There are two options to define configuration: <parameter>config</parameter> attribute and facet with name <parameter>config</parameter>. Facet takes precedence over attribute when both defined. - </para> <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/exam-Component_Reference-richeditor-Advanced_configuration.xml_sample" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <para> - In samples above, <sgmltag>&lt;rich:editor&gt;</sgmltag> is configured to take focus after load of the page regarding to user preferences. Definitions using either attribute or facet are adequate. + In the above samples, the <sgmltag>&lt;rich:editor&gt;</sgmltag> is configured to take focus after loading the page as defined by the userPreference bean. Definitions using either attribute or facet are equivalent. </para> <note> For further configuration options, refer to <ulink url="http://docs.cksource.com/CKEditor_3.x/Developers_Guide/Setting_... 3 Developer Guide</ulink> and <ulink url="http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.h... 3 configuration reference</ulink>. @@ -951,14 +947,12 @@ <section id="sect-Component_Reference-richeditor-Toolbar_customization"> <title>Toolbar customization</title> <para> - <sgmltag>&lt;rich:editor&gt;</sgmltag> supports <parameter>toolbar</parameter> attribute able to switch between configurations of toolbar's button set. + The <sgmltag>&lt;rich:editor&gt;</sgmltag> supports a <parameter>toolbar</parameter> attribute, which is able to change the configuration of the toolbar's button set. + There are two configurations available: <code>basic</code> (default), <code>full</code> (enables all of the features). </para> <para> - There are two configurations available: <code>basic</code> (default), <code>full</code> (enables all of the features). + It is also possible to define a custom toolbar using the CKEditor toolbar configuration in a <code>config</code> facet: </para> - <para> - It is possible to define custom toolbar using CKEditor toolbar configuration in <code>config</code> facet: - </para> <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/exam-Component_Reference-richeditor-Toolbar_customization.xml_sample" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <para> Note that toolbar name (<code>CustomToolbar</code>) needs to match the <code>toolbar_&lt;name&gt;</code> configuration option. @@ -968,9 +962,7 @@ <section id="sect-Component_Reference-richeditor-Internationalization_and_localization"> <title>Internationalization and localization</title> <para> - <sgmltag>&lt;rich:editor&gt;</sgmltag> comes with attribute <parameter>lang</parameter> which allows to change localization of editor. - </para> - <para> + The <sgmltag>&lt;rich:editor&gt;</sgmltag> comes with a <parameter>lang</parameter> attribute which allows you to change the localization of the editor. For language configuration options, refer to <ulink url="http://www.w3.org/TR/html4/struct/dirlang.html">http://...;. </para> <para> @@ -994,14 +986,12 @@ </listitem> </itemizedlist> <para> - However localization of interface is in first place localized using the browser configuration (usually determined by client system settings). + However the interface first localized using the browser configuration (usually determined by client system settings). + To force the editor to use a specific localization for the interface, you use the advanced CKEditor configuration option <code>language</code>, as in following sample: </para> - <para> - To force editor to use specific localization of interface, you can use advanced CKEditor configuration option <code>language</code> as in following sample: - </para> <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/exam-Component_Reference-richeditor-Internationalization_and_localization.xml_sample" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <para> - The sample above force editor to use french interface, supressing the browser preferred settings. + The above sample forces the editor to use a french interface, suppressing the browser preferred settings. </para> </section> @@ -1038,18 +1028,18 @@ </listitem> </itemizedlist> <para> - Events can be handled either by registering JavaScript event handler or by attaching JSF behavior: + Events can be handled either by registering a JavaScript event handler or by attaching JSF behavior: </para> <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/exam-Component_Reference-richeditor-Client_side_event_handlers.xml_sample" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <para> - Example above shows editor and its output, which is updated each 1 sec after each instant change or immediately after user focus leaves editor area. + The example above shows the editor and its output, which is updated every second after each instant change or immediately after user focus leaves the editor area. </para> </section> <section id="sect-Component_Reference-richeditor-JavaScript_API"> <title>JavaScript API</title> <para> - The <sgmltag>&lt;rich:inplaceInput&gt;</sgmltag> component can be controlled through the JavaScript API. The JavaScript API provides the following functions: + The <sgmltag>&lt;rich:editor&gt;</sgmltag> component can be controlled through the JavaScript API. The JavaScript API provides the following functions: </para> <variablelist> <varlistentry>