Difference between revisions of "X-Cart:CSS and JavaScript optimization"

From X-Cart 4 Classic
Jump to: navigation, search
(Adding JS and CSS code to X-Cart templates)
 
(11 intermediate revisions by 2 users not shown)
Line 1: Line 1:
To optimize operations with CSS and JavaScript, we have added the load_defer and load_defer_code Smarty tags. Both these tags handle the operations of assembling and displaying of code for JavaScript and CSS:
+
== General info ==
  
* <tt>load_defer</tt> - assembles code
+
To optimize operations with CSS and JavaScript, we have added new Smarty tags:
* <tt>load_defer_code</tt> - displays code.
 
  
The logic of the tags depends on the store configuration variables: [[X-Cart:General_Options#CSS_and_JavaScript_optimization_tools | Use speed-up tool for CSS]] and [[X-Cart:General_Options#CSS_and_JavaScript_optimization_tools | Use speed-up tool for Javascript]].
+
* load_defer
 +
* load_defer_code
  
If these variables are disabled, load_defer displays the entered code immediately and load_defer_code doesn't do anything.
+
Both these tags handle the operations of assembling and outputting of code for JavaScript and CSS. The logic of the tags depends on the store configuration variables:
  
Code can be assembled two ways:
+
* [[X-Cart:General_Options#CSS_and_JavaScript_optimization_tools | Use speed-up tool for CSS]]
 +
* [[X-Cart:General_Options#CSS_and_JavaScript_optimization_tools | Use speed-up tool for Javascript]]
  
# Contained in an external file.
+
If these variables are enabled, 'load_defer' assembles the code added to X-Cart templates to a single JS or CSS file, then 'load_defer_code' outputs the assembled code (by including the corresponding JS and CSS files to the page source).
 +
 
 +
If these variables are disabled, 'load_defer' outputs the code added to X-Cart templates immediately, and 'load_defer_code' doesn't do anything.
 +
 
 +
== Adding JS and CSS code to X-Cart templates==
 +
 
 +
JS and CSS code can be added to X-Cart templates in two ways:
 +
 
 +
# Included from an external file.
 
# Entered directly in a template.
 
# Entered directly in a template.
  
In the first case, you pass the 'file' parameter, which is the path from the skin to the file (JavaScript or CSS). For example:
+
In the first case, you should pass the 'file' parameter, which is the path to the JS or CSS file to be included. For example:
  
 
<pre>
 
<pre>
 +
{load_defer file="lib/jcarousel.js" type="js"}
 
{load_defer file="js/popup_open.js" type="js"}
 
{load_defer file="js/popup_open.js" type="js"}
 
</pre>
 
</pre>
  
In the second case, you pass the 'direct_info' parameter, which contains the code to be passed to the optimizer. For example:
+
<pre>
 +
{load_defer file="lib/cluetip/jquery.cluetip.css" type="css"}
 +
{load_defer file="modules/Wishlist/main_carousel.css" type="css"}
 +
</pre>
 +
 
 +
In the second case, you should include your JS/CSS code between {capture}...{/capture} tags , and pass the additional 'direct_info' parameter, which contains the code to be assembled. For example:
  
 
<pre>
 
<pre>
Line 30: Line 45:
 
</pre>
 
</pre>
  
<tt>'load_defer'</tt> – accumulates code of a certain type in the global stream for the optimizer.
+
<pre>
 +
{capture name=my_css}
 +
<style type="text/css">
 +
#myUserStyle
 +
{background:#212121;}
 +
</style>
 +
{/capture}
 +
 
 +
{load_defer file="my_css" direct_info=$smarty.capture.my_css type="css"}
 +
</pre>
 +
 
 +
You can find code examples in the following X-Cart files:
 +
 
 +
* <tt>skin/common_files/customer/service_js.tpl</tt>
 +
* <tt>skin/common_files/customer/service_css.tpl</tt>
  
<tt>'load_defer_code'</tt> – registers accumulated code of a certain type with optimizer, connects the entry point of an optimizer with a registered identifier by the place in the code and clears the global stream for this type.
+
Besides, the above files are the best location for your custom JS code and CSS.
  
Script – optimizer’s point of entry to its own queue – selects code for this type and this identifier – checks its relevance (if necessary, rebuilds code cache) and returns the code as an external file (with the respective headers).
+
== CSS code optimization ==
  
 
CSS is considered optimal when it is entirely declared and called prior to the <body> tag (specifically, between the <head> and </head> tags). Another recommendation is to keep it all in a single file. If these are observed, the style is not going to be rebuilt while loading DOM and the styles if they are specified below.
 
CSS is considered optimal when it is entirely declared and called prior to the <body> tag (specifically, between the <head> and </head> tags). Another recommendation is to keep it all in a single file. If these are observed, the style is not going to be rebuilt while loading DOM and the styles if they are specified below.
  
That is why <tt>/skin/common_files/customer/service_head.tpl</tt> includes the {load_defer_code type="css"} tag, and the entire CSS is included earlier, in <tt>{include file="/skin/common_files/customer/service_css.tpl"}</tt>. For example:
+
That is why 'skin/common_files/customer/service_head.tpl' includes the {load_defer_code type="css"} tag. The entire CSS is included earlier, in 'skin/common_files/customer/service_css.tpl'.
 +
 
 +
For example:
  
/skin/common_files/customer/service_head.tpl
+
skin/common_files/customer/service_head.tpl
 
<pre>
 
<pre>
 
{include file="customer/service_css.tpl"}
 
{include file="customer/service_css.tpl"}
Line 47: Line 78:
 
</pre>
 
</pre>
  
/skin/common_files/customer/service_css.tpl
+
skin/common_files/customer/service_css.tpl
 
<pre>
 
<pre>
 
{load_defer file="lib/cluetip/jquery.cluetip.css" type="css"}
 
{load_defer file="lib/cluetip/jquery.cluetip.css" type="css"}
 
</pre>
 
</pre>
  
Regarding JavaScript, assembling and registering JavaScript code goes in two stages:
+
It is also recommended to use relative paths in such construction as shown below:
 +
 
 +
<pre>
 +
url(path_to_css)
 +
</pre>
 +
 
 +
Besides, make sure to have no spaces in the 'path_to_css' parameter.
  
* Immediately before the <tt></body></tt> tag.
+
== JS code optimization ==
* Before the <tt><body></tt> tag (specifically, between the <head> and </head> tags).
 
  
In the first case, the {load_defer_code type="js"} tag is included into <tt>/skin/common_files/customer/home.tpl</tt>, and all the JS is included earlier in other files. For example:
+
Regarding JavaScript, assembling and outputting JavaScript code goes in two stages:
  
/skin/common_files/customer/home.tpl
+
# Immediately before the </body> tag.
 +
# Before the <body> tag (specifically, between the <head> and </head> tags).
 +
 
 +
In the first case, the {load_defer_code type="js"} tag is included into 'skin/common_files/customer/home.tpl', and all the JS is included earlier in other files. For example:
 +
 
 +
skin/common_files/customer/home.tpl
 
<pre>
 
<pre>
 
{include file="customer/content.tpl"}
 
{include file="customer/content.tpl"}
Line 66: Line 107:
 
</pre>
 
</pre>
  
/skin/common_files/customer/content.tpl =>
+
skin/common_files/customer/content.tpl =>
:/skin/common_files/customer/right_bar.tpl =>
+
:skin/common_files/customer/right_bar.tpl =>
::/skin/common_files/customer/menu_cart.tpl =>
+
::skin/common_files/customer/menu_cart.tpl =>
:::/skin/common_files/customer/ajax.minicart.tpl
+
:::skin/common_files/customer/ajax.minicart.tpl
 
<pre>
 
<pre>
 
{load_defer file="js/ajax.minicart.js" type="js"}
 
{load_defer file="js/ajax.minicart.js" type="js"}
 
</pre>
 
</pre>
  
In the second case, {load_defer_code type="js"} tag is included in <tt>/skin/common_files/customer/service_head.tpl</tt>, and all the JS is included earlier in <tt>/skin/common_files/customer/service_js.tpl"}</tt>. For example:
+
In the second case, {load_defer_code type="js"} tag is included in 'skin/common_files/customer/service_head.tpl', and all the JS is included earlier in 'skin/common_files/customer/service_js.tpl'. For example:
  
/skin/common_files/customer/service_js.tpl
+
skin/common_files/customer/service_js.tpl
 
<pre>
 
<pre>
 
{load_defer file="js/common.js" type="js"}
 
{load_defer file="js/common.js" type="js"}
 
</pre>
 
</pre>
  
/skin/common_files/customer/service_head.tpl
+
skin/common_files/customer/service_head.tpl
 
<pre>
 
<pre>
 
{include file="customer/service_js.tpl"}
 
{include file="customer/service_js.tpl"}
Line 88: Line 129:
 
</pre>
 
</pre>
  
It is highly recommended to place JavaScript code at the bottom, i.e. right above the <tt></body></tt> tag. In this case, the code will be loaded and executed after the browser has built the DOM.
+
It is highly recommended to place JavaScript code at the bottom, i.e. right above the </body> tag. In this case, the code will be loaded and executed after the browser has built the DOM.
  
Much of X-Cart functionality does not take this into account and place JavaScript code before the <tt><body></tt> tag, thus making JavaScript code run while the page is being loaded.
+
Much of X-Cart functionality does not take this into account and place JavaScript code before the <body> tag, thus making JavaScript code run while the page is being loaded.
  
 
Besides that, with the current functionality, it is not always possible to use the 'load_defer' tags, so sometimes JavaScript code is included directly.
 
Besides that, with the current functionality, it is not always possible to use the 'load_defer' tags, so sometimes JavaScript code is included directly.
  
'''<tt>queue</tt> parameter'''
+
== "queue" parameter ==
  
 
To improve the flexibility and define a code execution order, we are introducing the "queue" parameter for the load_defer tag (set to 0 by default), which determines the order for the execution of code within a resulting code given by optimizer.
 
To improve the flexibility and define a code execution order, we are introducing the "queue" parameter for the load_defer tag (set to 0 by default), which determines the order for the execution of code within a resulting code given by optimizer.
  
For example, the code in /skin/common_files/onload_js.tpl
+
For example, the code in skin/common_files/onload_js.tpl
 
<pre>
 
<pre>
 
{load_defer file="onload_js" direct_info=$smarty.capture.onload_js type="js" queue="1"}
 
{load_defer file="onload_js" direct_info=$smarty.capture.onload_js type="js" queue="1"}
 
</pre>
 
</pre>
  
When using the
+
== Caching for buy_now.tpl and other templates ==
<pre>
+
 
url(path_to_css)
+
{{XC 4.4}}
</pre>
 
construction in your CSS, use relative paths in it. And make sure to have no spaces in the <tt>path_to_css</tt> parameter.
 
  
 
When working on the design, you can disable caching for buy_now.tpl and other templates. Since version 4.4.3, you can do that by adjusting the 'Use cached buy_now.tpl template calls' option. In version 4.4.2, you can disable caching for buy_now.tpl by manually replacing
 
When working on the design, you can disable caching for buy_now.tpl and other templates. Since version 4.4.3, you can do that by adjusting the 'Use cached buy_now.tpl template calls' option. In version 4.4.2, you can disable caching for buy_now.tpl by manually replacing
 +
 
<pre>
 
<pre>
 
$smarty->caching = 2;
 
$smarty->caching = 2;
 
</pre>
 
</pre>
 +
 
with
 
with
 +
 +
<pre>
 
$smarty->caching = 0;
 
$smarty->caching = 0;
in <tt>/include/templater/plugins/function.include_cache.php</tt>. The older versions do not use template caching.
+
</pre>
 +
 
 +
in 'include/templater/plugins/function.include_cache.php'. The older versions do not use template caching.
  
 
Also, when working on the design, you may want to turn off the 'Do not check if templates are changed (Smarty compile_check)' option. This is applicable to versions 4.4.2 and newer.
 
Also, when working on the design, you may want to turn off the 'Do not check if templates are changed (Smarty compile_check)' option. This is applicable to versions 4.4.2 and newer.
  
 
You can force rebuilding the target files by removing all the
 
You can force rebuilding the target files by removing all the
<tt>/var/cache/*.css</tt> and <tt>/var/cache/*.js</tt> files (versions 4.4.2 and newer).
+
'var/cache/*.css' and 'var/cache/*.js' files (versions 4.4.2 and newer).
 +
 
 +
To ensure the correct operation of CSS/JS optimizers, make sure that the CSS and JS files are available for reading and writing in the 'var/cache' directory (according to the rules set in the default 'var/.htacess' and 'var/cache/.htaccess'). This also applies to versions 4.4.2 and newer.
 +
 
 +
[[Category:X-Cart user manual]]
 +
[[Category:X-Cart developer guide]]
 +
[[Category:X-Cart user manual]]
 +
[[Category:X-Cart developer guide]]
 +
[[Category:X-Cart user manual]]
 +
[[Category:X-Cart developer guide]]
 +
[[Category:X-Cart user manual]]
 +
[[Category:X-Cart developer guide]]
 +
[[Category:X-Cart user manual]]
 +
[[Category:X-Cart developer guide]]
 +
[[Category:X-Cart user manual]]
 +
[[Category:X-Cart developer guide]]
 +
[[Category:X-Cart user manual]]
 +
[[Category:X-Cart developer guide]]
 +
[[Category:X-Cart user manual]]
 +
[[Category:X-Cart developer guide]]
  
To ensure the correct operation of CSS/JS optimizers, make sure that the CSS and JS files are available for reading and writing in the <tt>/var/cache</tt> directory (according to the rules set in the default /var/.htacess and var/cache/.htaccess). This also applies to versions 4.4.2 and newer.
+
[[Category:X-Cart user manual]]
 +
[[Category:X-Cart developer guide]]
 +
[[Category:X-Cart user manual]]
 +
[[Category:X-Cart developer guide]]
 +
[[Category:X-Cart user manual]]
 +
[[Category:X-Cart developer guide]]
 +
[[Category:X-Cart user manual]]
 +
[[Category:X-Cart developer guide]]
 +
[[Category:X-Cart user manual]]
 +
[[Category:X-Cart developer guide]]
 +
[[Category:X-Cart user manual]]
 +
[[Category:X-Cart developer guide]]
 +
[[Category:X-Cart user manual]]
 +
[[Category:X-Cart developer guide]]
 +
[[Category:X-Cart user manual]]
 +
[[Category:X-Cart developer guide]]

Latest revision as of 10:34, 11 October 2012

General info

To optimize operations with CSS and JavaScript, we have added new Smarty tags:

  • load_defer
  • load_defer_code

Both these tags handle the operations of assembling and outputting of code for JavaScript and CSS. The logic of the tags depends on the store configuration variables:

If these variables are enabled, 'load_defer' assembles the code added to X-Cart templates to a single JS or CSS file, then 'load_defer_code' outputs the assembled code (by including the corresponding JS and CSS files to the page source).

If these variables are disabled, 'load_defer' outputs the code added to X-Cart templates immediately, and 'load_defer_code' doesn't do anything.

Adding JS and CSS code to X-Cart templates

JS and CSS code can be added to X-Cart templates in two ways:

  1. Included from an external file.
  2. Entered directly in a template.

In the first case, you should pass the 'file' parameter, which is the path to the JS or CSS file to be included. For example:

{load_defer file="lib/jcarousel.js" type="js"}
{load_defer file="js/popup_open.js" type="js"}
{load_defer file="lib/cluetip/jquery.cluetip.css" type="css"}
{load_defer file="modules/Wishlist/main_carousel.css" type="css"}

In the second case, you should include your JS/CSS code between {capture}...{/capture} tags , and pass the additional 'direct_info' parameter, which contains the code to be assembled. For example:

{capture name=admin_preview_js}
var txt_this_form_is_for_demo_purposes = '{$lng.txt_this_form_is_for_demo_purposes|wm_remove|escape:javascript}';
var txt_this_link_is_for_demo_purposes = '{$lng.txt_this_link_is_for_demo_purposes|wm_remove|escape:javascript}';
{/capture}

{load_defer file="admin_preview_js" direct_info=$smarty.capture.admin_preview_js type="js"}
{capture name=my_css}
<style type="text/css">
#myUserStyle
{background:#212121;}
</style>
{/capture}

{load_defer file="my_css" direct_info=$smarty.capture.my_css type="css"}

You can find code examples in the following X-Cart files:

  • skin/common_files/customer/service_js.tpl
  • skin/common_files/customer/service_css.tpl

Besides, the above files are the best location for your custom JS code and CSS.

CSS code optimization

CSS is considered optimal when it is entirely declared and called prior to the <body> tag (specifically, between the <head> and </head> tags). Another recommendation is to keep it all in a single file. If these are observed, the style is not going to be rebuilt while loading DOM and the styles if they are specified below.

That is why 'skin/common_files/customer/service_head.tpl' includes the {load_defer_code type="css"} tag. The entire CSS is included earlier, in 'skin/common_files/customer/service_css.tpl'.

For example:

skin/common_files/customer/service_head.tpl

{include file="customer/service_css.tpl"}
... skipped code ...
{load_defer_code type="css"}

skin/common_files/customer/service_css.tpl

{load_defer file="lib/cluetip/jquery.cluetip.css" type="css"}

It is also recommended to use relative paths in such construction as shown below:

url(path_to_css)

Besides, make sure to have no spaces in the 'path_to_css' parameter.

JS code optimization

Regarding JavaScript, assembling and outputting JavaScript code goes in two stages:

  1. Immediately before the </body> tag.
  2. Before the <body> tag (specifically, between the <head> and </head> tags).

In the first case, the {load_defer_code type="js"} tag is included into 'skin/common_files/customer/home.tpl', and all the JS is included earlier in other files. For example:

skin/common_files/customer/home.tpl

{include file="customer/content.tpl"}
... skipped code ...
{load_defer_code type="js"}

skin/common_files/customer/content.tpl =>

skin/common_files/customer/right_bar.tpl =>
skin/common_files/customer/menu_cart.tpl =>
skin/common_files/customer/ajax.minicart.tpl
{load_defer file="js/ajax.minicart.js" type="js"}

In the second case, {load_defer_code type="js"} tag is included in 'skin/common_files/customer/service_head.tpl', and all the JS is included earlier in 'skin/common_files/customer/service_js.tpl'. For example:

skin/common_files/customer/service_js.tpl

{load_defer file="js/common.js" type="js"}

skin/common_files/customer/service_head.tpl

{include file="customer/service_js.tpl"}
... skipped code ...
{load_defer_code type="js"}

It is highly recommended to place JavaScript code at the bottom, i.e. right above the </body> tag. In this case, the code will be loaded and executed after the browser has built the DOM.

Much of X-Cart functionality does not take this into account and place JavaScript code before the <body> tag, thus making JavaScript code run while the page is being loaded.

Besides that, with the current functionality, it is not always possible to use the 'load_defer' tags, so sometimes JavaScript code is included directly.

"queue" parameter

To improve the flexibility and define a code execution order, we are introducing the "queue" parameter for the load_defer tag (set to 0 by default), which determines the order for the execution of code within a resulting code given by optimizer.

For example, the code in skin/common_files/onload_js.tpl

{load_defer file="onload_js" direct_info=$smarty.capture.onload_js type="js" queue="1"}

Caching for buy_now.tpl and other templates

X-Cart 4.4or above

When working on the design, you can disable caching for buy_now.tpl and other templates. Since version 4.4.3, you can do that by adjusting the 'Use cached buy_now.tpl template calls' option. In version 4.4.2, you can disable caching for buy_now.tpl by manually replacing

$smarty->caching = 2;

with

$smarty->caching = 0;

in 'include/templater/plugins/function.include_cache.php'. The older versions do not use template caching.

Also, when working on the design, you may want to turn off the 'Do not check if templates are changed (Smarty compile_check)' option. This is applicable to versions 4.4.2 and newer.

You can force rebuilding the target files by removing all the 'var/cache/*.css' and 'var/cache/*.js' files (versions 4.4.2 and newer).

To ensure the correct operation of CSS/JS optimizers, make sure that the CSS and JS files are available for reading and writing in the 'var/cache' directory (according to the rules set in the default 'var/.htacess' and 'var/cache/.htaccess'). This also applies to versions 4.4.2 and newer.