myfaces-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From an...@apache.org
Subject svn commit: r1303094 - /myfaces/trinidad/branches/andys-skin-pregen/src/site/xdoc/devguide/skinning.xml
Date Tue, 20 Mar 2012 18:51:49 GMT
Author: andys
Date: Tue Mar 20 18:51:49 2012
New Revision: 1303094

URL: http://svn.apache.org/viewvc?rev=1303094&view=rev
Log:
Checkpoint: added skin pregeneration documentation to the Skinning chapter of the dev guide.

Modified:
    myfaces/trinidad/branches/andys-skin-pregen/src/site/xdoc/devguide/skinning.xml

Modified: myfaces/trinidad/branches/andys-skin-pregen/src/site/xdoc/devguide/skinning.xml
URL: http://svn.apache.org/viewvc/myfaces/trinidad/branches/andys-skin-pregen/src/site/xdoc/devguide/skinning.xml?rev=1303094&r1=1303093&r2=1303094&view=diff
==============================================================================
--- myfaces/trinidad/branches/andys-skin-pregen/src/site/xdoc/devguide/skinning.xml (original)
+++ myfaces/trinidad/branches/andys-skin-pregen/src/site/xdoc/devguide/skinning.xml Tue Mar
20 18:51:49 2012
@@ -72,6 +72,13 @@
             <a href="#Custom_Component_Developers">Skinning for Custom Component Developers</a>
           </li>          
           <li>
+            <a href="#Pregen">Pre-generating Skin Style Sheets</a>
+            <ul>
+            <li><a href="#Stable_Names">Stable Names for Generated Style Sheet
Files</a></li>
+            <li><a href="#Stable_Names_Structure">Structure of Stable Style Sheet
File Names</a></li>
+            </ul>
+          </li>
+          <li>
             <a href="#Frequently_Asked_Questions">Frequently Asked Questions</a>
           </li>
         </ul>
@@ -1535,6 +1542,243 @@ public class XYZResourceLoader extends R
         </subsection>
       </section>
 
+      <a name="Pregen"></a>
+      <section name="Pre-generating Skin Style Sheets">
+<p>
+Trinidad skin definitions are dynamically converted into browser-consumable style sheets
(.css files) at runtime.  While a runtime-based approach is suitable for most application
deployments, in some cases it may be desirable to offload style sheet delivery to some other
server, eg. to a server that is managed by a CDN provider, or even just to a static http server
that can be shared across multiple applications.  Trinidad provides a skin pre-generation
"service" to address such cases.
+</p>
+<p>
+The skin pre-generation service can be accessed from any Trinidad-based application.  To
enable this service, simply specify the following system property when starting up the application
server:
+</p>
+<source>
+-Dorg.apache.myfaces.trinidad.SKIN_PREGENERATION_SERVICE=on
+</source>
+<p>
+Enabling the skin pre-generation service causes a special "/-pregenerate-skins" view id to
be exposed.  Requests into this view trigger pre-generation, which produces a set of static
style sheet files that can then be copied/uploaded to some other server.
+</p>
+<p>
+The /-pregenerate-skins view id requires one mandatory request parameter: id.  The value
of this parameter must be an id of one of the skins registered with Trinidad.
+</p>
+<p>
+For example, in an application that uses prefix mapping for the FacesServlet, enabling the
skin pre-generation service exposes the following uri:
+</p>
+<source>
+/context root/faces/-pregenerate-skins?id=minimal.desktop
+</source>
+<p>
+Hitting this uri triggers pre-generation of style sheets for the minimal.desktop skin.
+</p>
+<p>
+Skin pre-generation can be slow and can produce a significant amount of content, particularly
for large skins with many variants.  To compensate for this, only style sheets for the most
common variant values are generated by default. In particular, style sheets corresponding
to the following variants are generated:
+</p>
+<p>
+<ul>
+<li>plaform: android | iphone | linux | macos | windows</li>
+<li>agent: ie | gecko | webkit</li>
+<li>locale: default (unmatched) locale</li>
+<li>reading direction: ltr</li>
+<li>accessibility: standard contrast, medium fonts</li>
+</ul>
+</p>
+<p>
+The "variants" request parameter can be used to force generation of all
+possible style sheets.  For example, specifying variants=all:
+</p>
+<source>
+/context root/faces/-pregenerate-skins?id=minimal.desktop?variants=all
+</source>
+<p>
+Will result in in pre-generation of every possible style sheet for the minimal.desktop skin.
+</p>
+<p>
+In addition to the "variants" request parameter, the following optional request may be used
to provide information about how pre-generation should be performed:
+</p>
+<p>
+<ul>
+<li>containerType: servlet | portlet. (Defaults to "servlet".)</li>
+<li>requestType: nonsecure | secure.  (Defaults to "nonsecure".)</li>
+<li>styleClassType: compressed | uncompressed.  (Defaults to "compressed".)</li></ul>
+</p>
+<p>
+All of the contextual request parameters support multiple values.  For example,
+the following request:
+</p>
+<source>
+/context-root/-pregenerate-skins?id=minimal.desktop&amp;styleClassType=compressed&amp;styleClassType=uncompressed
+</source>
+<p> 
+Pre-generates both servlet and portlet style sheets for the common variants of the the minimal.desktop
skin.
+</p>
+<p>
+By default, pre-generated style sheets are written into the web application's style sheet
cache directory (typically, &lt;web app temp dir&gt;/adf/styles/cache).  However,
an alternate target directory for the pre-generated output can be specified via the following
system property:
+</p>
+<source>
+-Dorg.apache.myfaces.trinidad.SKIN_PREGENERATION_SERVICE_TARGET_DIRECTORY=directory path
+</source>
+<p>
+Requests that result in successful skin pre-generation produce status 200
+responses.  Failed requests (eg. for invalid skin ids) result in non-200
+status codes.
+</p>
+<p>
+For security purposes, pre-generation must never be enabled in end user facing, production
deployments - ie. skin pregeneration is CPU and I/O intensive, and must not be exposed to
arbitrary users.  To avoid the potential for abuse, enabling skin pregeneration has the side
effect of disabling the rest of the application.  As such, application servers that are enabled
for skin pregeneration can only be used for this single purpose.
+</p>
+      <a name="Stable_Names"></a>
+      <subsection name="Stable Names for Generated Style Sheet Files">
+<p>
+By default, the file names that are used for generated style sheets are not guaranteed to
be stable across runs.  In cases where a style sheet is shared across multiple variants, eg:
+</p>
+<source>
+  @locale ja, cz, ko {
+    /* Shared styles here */
+  }
+</source>
+<p>
+The file name may change after a server restart depending on which variant is requested first.
+</p>
+<p>
+The lack of consistent file names poses problems for cases where pre-generated style sheets
are hosted on a remote server.  Since the file names are not predictable, it is not possible
to ensure that the names used by the source application match the pre-generated file names
hosted elsewhere.
+</p>
+<p>
+Trinidad provides the following servlet context initialization parameter for such scenarios:
+</p>
+<source>
+org.apache.myfaces.trinidad.STYLE_SHEET_NAMING_STRATEGY
+</source>
+<p>
+When this parameter is set to "stable", generated style sheets will use file names that are
guaranteed to be consistent across runs.
+</p>
+<p>
+The style sheet naming strategy is automatically forced to "stable" during skin pre-generation.
 Thus, the context parameter only needs to be set for applications that depend on previously
generated style sheet files.
+</p>
+      </subsection>
+
+      <a name="Stable_Names_Structure"></a>
+      <subsection name="Structure of Stable Style Sheet Names">
+<p>
+Some applications may need to write regular expressions that target specific style sheet
file names (eg. for selective uri rewriting purposes).  For such cases, applications may depend
on the stable file name structure described below.
+</p>
+<p>
+Stable style sheet file names are broken up into three major sections:
+</p>
+<p>
+<ol>
+<li>Skin identifier section</li>
+<li>Variant identifier section (eg. agent, locale, etc...)</li>
+<li>Contextual identifier section (eg. portlet vs. servlet, etc...)</li>
+</ol>
+</p>
+<p>
+These major sections are separated by double dashes ("--").
+</p>
+<p>
+Within each major section, minor subsections appear in a predictable order, separated by
single dashs ("-").
+</p>
+<p>
+The skin identifier section (section #1) contains the following subsections:
+</p>
+<source>
+  &lt;id&gt;-&lt;version hash&gt;
+</source>
+<p>
+Where:
+</p>
+<p>
+<ul>
+<li>id: the skin id.  Note that the skin id itself may include dash characters
+    (eg. "simple-desktop").</li>
+<li>version hash: a hash of the skin contents, which typically varies from version
to version.</li>
+</ul>
+</p>
+<p>
+The variant identifiers section (section #2) contains the following subsections:
+</p>
+<source>
+  &lt;platform&gt;-&lt;agent&gt;-&lt;version&gt;-&lt;locale&gt;-&lt;direction&gt;-&lt;accessibility&gt;
+</source>
+<p>
+Where:
+</p>
+<p>
+<ul>
+<li>platform: the platform name (eg. linux, windows, iphone)</li>
+<li>agent: the agent name (eg. ie, gecko, safari)</li>
+<li>version: the agent version (eg. 7, 1.9.2, 534)</li>
+<li>locale: the locale (eg. en, en_US, ja).</li>
+<li>direction: the reading direction (ltr|rtl)</li>
+<li>accessibility: accessibility profile preferences for high contrast and large fonts
(hc|lf).</li>
+</ul>
+</p>    
+<p>
+In the event that no @-rule variant is expicitly matched, only default styles
+(ie. styles that apply to all requests) are included in the generated style sheet.  The token
"d" is used to identify this case.  For example, if the skin does not define any @locale rules,
the locale portion of the file name will be the token "d".
+</p>
+<p>
+In some cases it is not possible to determine a unique value
+for a particular variant, because only @-rules that specify multiple values
+are matched.  In this case, a combination of the matched values will be used
+for the segment.  For example, if the  skin defines a single @locale rule 
+matching the ja, zh, and ko locales, the locale portion of the file name for 
+generated style sheets corresponding to these
+locales will be "ja_ko_zh".
+</p>
+<p>
+The contextual identifiers section (section #3) contains the following subsections:
+</p>
+<p>
+<ul>
+<li>container type: identifies whether the application is hosted within a servlet or
 portlet (s|p).</li>
+<li>request type: identifies whether the style sheet is used for a secure or non-secure
request (s|n).</li>
+<li>style class type: identifies whether the style sheet is generated with compressed
or uncompressed style classes (c|u).</li>
+</ul>
+</p>
+<p>
+The following sample stable style sheet name:
+</p>
+<source>
+sample-desktop-jh4phm--linux-gecko-1.9.0-ja_ko_zh-ltr-lf--s-n-c.css
+</source>
+<p>
+Is composed of these pieces:
+</p>
+<p>
+<ul>
+<li>Skin identifier section
+  <ul>
+  <li>id: sample-desktop</li>
+  <li>jh4phm</li>
+  </ul>
+</li>
+<li>Variant identifier section
+  <ul>
+  <li>platform: linux</li>
+  <li>agent: gecko</li>
+  <li>version: 1.9.0</li>
+  <li>locale: ja_ko_zh (style sheet is used for Japanese, Korean and Chinese languages)</li>
+  <li>direction: ltr (left-to-right)</li>
+  <li>accessibility: lf (large fonts)</li>
+  </ul>
+</li>
+<li>Contextual identifier section
+  <ul>
+  <li>container type: s (servlet)</li>
+  <li>request type: n (non-secure)</li>
+  <li>style class type: c (compressed style classes)</li>
+  </ul>
+</li>
+</ul>
+</p>
+<p>
+When writing regulard expressions that target this structure, the following recommendations
should be observed:
+</p>
+<p>
+<ul>
+<li>The identifier section contains a variable number of subsection separators: skin
ids may contain dashes.  As such, when targeting regular expressions at items in the subsequent
major sections, it is best to anchor these regular expressions to the major section separators
(double-dash).</li>
+<li>In the future it is possible that new subsections may need to be added to the variant
or contextual identifier sections.  If the need for additional information arises, new subsections
will be added at the end of the appropriate  major section.  As such, regular expressions
should be written in a way that they can tolerate new subsections later appearing at the end
of each major section.</li>
+</ul>
+</p>
+      </subsection>      
+      </section>
 
       <a name="Frequently_Asked_Questions"></a>
       <section name="Frequently Asked Questions">



Mime
View raw message