doc/filter-css-outline.html - incubator-pagespeed-website - Git at Google

 <!--
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
 -->

 <html>
   <head>
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <title>Outline CSS</title>
     <link rel="stylesheet" href="doc.css">
   </head>
   <body>
 <!--#include virtual="_header.html" -->


   <div id=content>
 <h1>Outline CSS</h1>

 <h2>Configuration</h2>
 <p>
 The 'Outline CSS' filter is enabled by specifying:
 </p>
 <dl>
   <dt>Apache:<dd><pre class="prettyprint"
      >ModPagespeedEnableFilters outline_css</pre>
   <dt>Nginx:<dd><pre class="prettyprint"
      >pagespeed EnableFilters outline_css;</pre>
 </dl>
 <p>
 in the configuration file.
 </p>

 <h2>Description</h2>
 <p>
 This filter is an <strong>experimental</strong> filter which takes inline
 CSS and puts it in an external resource.
 </p>

 <h2>Operation</h2>
 <p>
 The 'Outline CSS' filter outlines all CSS that is larger than a minimum byte
 threshold. The threshold can be set by adding/changing the line:
 </p>
 <dl>
   <dt>Apache:<dd><pre class="prettyprint"
      >ModPagespeedCssOutlineMinBytes 3000</pre>
   <dt>Nginx:<dd><pre class="prettyprint"
      >pagespeed CssOutlineMinBytes 3000;</pre>
 </dl>
 <p>
 in the configuration file.
 </p>
 <p>
 For example, if the HTML document looks like this:
 </p>
 <pre class="prettyprint">
 &lt;html&gt;
   &lt;head&gt;
     &lt;style type="text/css"&gt;
       .yellow {background-color: yellow;}
       .blue {color: blue;}
       .big { font-size: 8em; }
       .bold { font-weight: bold; }
       ...
     &lt;/style&gt;
   &lt;/head&gt;
   &lt;body&gt;
     &lt;div class="blue yellow big bold"&gt;
       Hello, world!
     &lt;/div&gt;
   &lt;/body&gt;
 &lt;/html&gt;
 </pre>
 <p>
 Then PageSpeed will rewrite it into:
 </p>
 <pre class="prettyprint">
 &lt;html&gt;
   &lt;head&gt;
     &lt;link rel="stylesheet" type="text/css" href="of.HASH.css"&gt;
   &lt;/head&gt;
   &lt;body&gt;
     &lt;div class="blue yellow big bold"&gt;
       Hello, world!
     &lt;/div&gt;
   &lt;/body&gt;
 &lt;/html&gt;
 </pre>
 <p>
 And a new CSS file (<code>of.HASH.css</code>) will be:
 </p>
 <pre class="prettyprint">
   .yellow {background-color: yellow;}
   .blue {color: blue;}
   .big { font-size: 8em; }
    .bold { font-weight: bold; }
    ...
 </pre>

 <h3>Example</h3>
 <p>
 You can see the filter in action at <code>www.modpagespeed.com</code> on this
 <a href="https://www.modpagespeed.com/examples/outline_css.html?ModPagespeed=on&amp;ModPagespeedFilters=outline_css">example</a>.
 </p>

 <h2>Pros and Cons</h2>
 <p>
 This could be advantageous if:
 </p>
 <ol>
   <li>The CSS does not change much but the HTML does, then we can cache the
       CSS.</li>
   <li>One has many websites with the same inlined CSS, it will be outlined
       to a consistent name and thus will be cached more or</li>
   <li>The inline CSS is very long, in which case, outlining it will cause it
       to be loaded in parallel with the HTML doc.</li>
 </ol>
 <p>
 However, for some websites it will be dis-advantageous because it will:
 </p>
 <ol>
   <li>Create an extra HTTP request.</li>
   <li>Tie up one of the connections this domain, which could have been used to
       fetch the actually cacheable external resources.</li>
 </ol>

 <h2>Requirements</h2>
 <p>
 Outline filters can currently only run on single-server environments
 because the resource can only be fetched from a server after that server
 has rewritten the HTML page. If a different server rewrote the HTML page,
 then this sever will not have the information needed to create the resource.
 This could be by a network database shared between servers.
 </p>
 <p>
 The Outline CSS filter may need to <em>"absolutify"</em> relative URLs, if
 it is outlined to a different directory than the original HTML.
 </p>
 <p>
 The Outline CSS filter will maintain the order of the CSS contents, as
 class order can be significant.
 </p>

 <h2>Risks</h2>
 <p>
 The 'Outline CSS' filter is considered low risk.  However, JavaScript can be
 written that walks the DOM looking for <code>&lt;link&gt;</code> or
 <code>&lt;style&gt;</code> tags with certain syntax. Such JavaScript
 may behave differently on a page which has added
 <code>&lt;link&gt;</code> or removed <code>&lt;style&gt;</code> tags
 in this way.
 </p>
 <p>
 Additionally we have reproduced an obscure difference that sometimes occurs
 on WebKit-based browsers (such as Safari, Chrome and the Android browser).
 As of January 2011, WebKit does not delay JavaScript evaluation for
 external CSS loading (See
 <a href="https://webkit.org/b/24898">https://webkit.org/b/24898</a>).
 So some CSS attributes, when outlined, can cause slightly different
 rendering depending on whether or not the CSS file is loaded before or
 after the JavaScript is executed.
 </p>


   </div>
   <!--#include virtual="_footer.html" -->
   </body>
 </html>
	<!--
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	-->

	<html>
	<head>
	<meta name="viewport" content="width=device-width, initial-scale=1">
	<title>Outline CSS</title>
	<link rel="stylesheet" href="doc.css">
	</head>
	<body>
	<!--#include virtual="_header.html" -->


	<div id=content>
	<h1>Outline CSS</h1>

	<h2>Configuration</h2>
	<p>
	The 'Outline CSS' filter is enabled by specifying:
	</p>
	<dl>
	<dt>Apache:<dd><pre class="prettyprint"
	>ModPagespeedEnableFilters outline_css</pre>
	<dt>Nginx:<dd><pre class="prettyprint"
	>pagespeed EnableFilters outline_css;</pre>
	</dl>
	<p>
	in the configuration file.
	</p>

	<h2>Description</h2>
	<p>
	This filter is an <strong>experimental</strong> filter which takes inline
	CSS and puts it in an external resource.
	</p>

	<h2>Operation</h2>
	<p>
	The 'Outline CSS' filter outlines all CSS that is larger than a minimum byte
	threshold. The threshold can be set by adding/changing the line:
	</p>
	<dl>
	<dt>Apache:<dd><pre class="prettyprint"
	>ModPagespeedCssOutlineMinBytes 3000</pre>
	<dt>Nginx:<dd><pre class="prettyprint"
	>pagespeed CssOutlineMinBytes 3000;</pre>
	</dl>
	<p>
	in the configuration file.
	</p>
	<p>
	For example, if the HTML document looks like this:
	</p>
	<pre class="prettyprint">
	<html>
	<head>
	<style type="text/css">
	.yellow {background-color: yellow;}
	.blue {color: blue;}
	.big { font-size: 8em; }
	.bold { font-weight: bold; }
	...
	</style>
	</head>
	<body>
	<div class="blue yellow big bold">
	Hello, world!
	</div>
	</body>
	</html>
	</pre>
	<p>
	Then PageSpeed will rewrite it into:
	</p>
	<pre class="prettyprint">
	<html>
	<head>
	<link rel="stylesheet" type="text/css" href="of.HASH.css">
	</head>
	<body>
	<div class="blue yellow big bold">
	Hello, world!
	</div>
	</body>
	</html>
	</pre>
	<p>
	And a new CSS file (<code>of.HASH.css</code>) will be:
	</p>
	<pre class="prettyprint">
	.yellow {background-color: yellow;}
	.blue {color: blue;}
	.big { font-size: 8em; }
	.bold { font-weight: bold; }
	...
	</pre>

	<h3>Example</h3>
	<p>
	You can see the filter in action at <code>www.modpagespeed.com</code> on this
	<a href="https://www.modpagespeed.com/examples/outline_css.html?ModPagespeed=on&ModPagespeedFilters=outline_css">example</a>.
	</p>

	<h2>Pros and Cons</h2>
	<p>
	This could be advantageous if:
	</p>
	<ol>
	<li>The CSS does not change much but the HTML does, then we can cache the
	CSS.</li>
	<li>One has many websites with the same inlined CSS, it will be outlined
	to a consistent name and thus will be cached more or</li>
	<li>The inline CSS is very long, in which case, outlining it will cause it
	to be loaded in parallel with the HTML doc.</li>
	</ol>
	<p>
	However, for some websites it will be dis-advantageous because it will:
	</p>
	<ol>
	<li>Create an extra HTTP request.</li>
	<li>Tie up one of the connections this domain, which could have been used to
	fetch the actually cacheable external resources.</li>
	</ol>

	<h2>Requirements</h2>
	<p>
	Outline filters can currently only run on single-server environments
	because the resource can only be fetched from a server after that server
	has rewritten the HTML page. If a different server rewrote the HTML page,
	then this sever will not have the information needed to create the resource.
	This could be by a network database shared between servers.
	</p>
	<p>
	The Outline CSS filter may need to <em>"absolutify"</em> relative URLs, if
	it is outlined to a different directory than the original HTML.
	</p>
	<p>
	The Outline CSS filter will maintain the order of the CSS contents, as
	class order can be significant.
	</p>

	<h2>Risks</h2>
	<p>
	The 'Outline CSS' filter is considered low risk. However, JavaScript can be
	written that walks the DOM looking for <code><link></code> or
	<code><style></code> tags with certain syntax. Such JavaScript
	may behave differently on a page which has added
	<code><link></code> or removed <code><style></code> tags
	in this way.
	</p>
	<p>
	Additionally we have reproduced an obscure difference that sometimes occurs
	on WebKit-based browsers (such as Safari, Chrome and the Android browser).
	As of January 2011, WebKit does not delay JavaScript evaluation for
	external CSS loading (See
	<a href="https://webkit.org/b/24898">https://webkit.org/b/24898</a>).
	So some CSS attributes, when outlined, can cause slightly different
	rendering depending on whether or not the CSS file is loaded before or
	after the JavaScript is executed.
	</p>


	</div>
	<!--#include virtual="_footer.html" -->
	</body>
	</html>