You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@myfaces.apache.org by an...@apache.org on 2012/03/20 19:51:49 UTC
svn commit: r1303094 -
/myfaces/trinidad/branches/andys-skin-pregen/src/site/xdoc/devguide/skinning.xml
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&styleClassType=compressed&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, <web app temp dir>/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>
+ <id>-<version hash>
+</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>
+ <platform>-<agent>-<version>-<locale>-<direction>-<accessibility>
+</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">