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)
 
(13 intermediate revisions by 3 users not shown)
Line 1: Line 1:
To optimize working with CSS and JavaScript, smarty tags load_defer and load_defer_code have been added.
+
== General info ==
  
Both tags are used to organize assembling and displaying code for two data types: JavaScript and CSS.
+
To optimize operations with CSS and JavaScript, we have added new Smarty tags:
  
* load_defer - code assembling tag
+
* load_defer
* load_defer_code - code displaying tag
+
* load_defer_code
  
The logic of 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]]
+
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 disabled, the tag load_defer displays the entered code immediately and the tag load_defer_code doesn't do anything.
+
* [[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]]
  
The code is assembled in two variants:
+
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).
  
# the code is contained in an external file
+
If these variables are disabled, 'load_defer' outputs the code added to X-Cart templates immediately, and 'load_defer_code' doesn't do anything.
# the code is entered directly in the template
 
  
In the first case the 'file' parameter is passed - the path from the skin to the file (JavaScript or CSS). For example:
+
== 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.
 +
 
 +
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 the 'direct_info' parameter is passed: it contains code, 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 32: Line 45:
 
</pre>
 
</pre>
  
The 'load_defer' tag accumulates code of a certain type in a 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:
  
The 'load_defer_code' tag registers in the optimizer all the accumulated code of a certain type,  - регистрирует в оптимизаторе весь накопившийся код определенного типа, производит по месту в коде подключение точки входа оптимизатора с регистрированным идентификатором и очищает текущий глобальный поток для данного типа.
+
* <tt>skin/common_files/customer/service_js.tpl</tt>
 +
* <tt>skin/common_files/customer/service_css.tpl</tt>
  
 +
Besides, the above files are the best location for your custom JS code and CSS.
  
Скрипт - точка входа оптимизатора же в свою очередь - выбирает код для данного типа и данного идентификатора - проверяет его актуальность (если потребуется то перестраивает кеш кода) и отдает код как внешний файл (с соответствующими хидерами).
+
== CSS code optimization ==
  
Regarding CSS, it is best when CSS is declared and called before the <body> tag (specifically between <head> and </head> tags). In this case stylesheets will not be rebuilt as DOM and styles (if they are specified later) are being loaded. It is also recommended that it is contained in a single file.
+
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 {load_defer_code type="css"} tag is included into <tt>skin/common_files/customer/service_head.tpl</tt>, and all CSS is included earlier in <tt>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
Line 55: Line 83:
 
</pre>
 
</pre>
  
Regarding JavaScript, assembling and registering code for JavaScript is done 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.
 +
 
 +
== JS code optimization ==
 +
 
 +
Regarding JavaScript, assembling and outputting JavaScript code goes in two stages:
  
* immediately before the <tt></body></tt> tag.
+
# Immediately before the </body> tag.
* before the <tt><body></tt> tag (specifically between <head> and </head> tags)
+
# Before the <body> tag (specifically, between the <head> and </head> tags).
  
In the first case {load_defer_code type="js"} tag is included into <tt>skin/common_files/customer/home.tpl</tt>, and all JS is included earlier in other files. For example:
+
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
 
skin/common_files/customer/home.tpl
Line 77: Line 115:
 
</pre>
 
</pre>
  
In the second case, {load_defer_code type="js"} tag is included into <tt>skin/common_files/customer/service_head.tpl</tt>, and all JS is included earlier in <tt>skin/common_files/customer/service_css.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
Line 91: Line 129:
 
</pre>
 
</pre>
  
It is best to place JavaScript code at the bottom - i.e. immediately before 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 consideration and JavaScript code is placed before the <tt><body></tt> tag, so JavaScript code is being executed during the page loading.
+
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.
  
Also for the current functionality it is not always possible to use 'load_defer' tags and 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 flexibility and introduce code execution order, the parameter "queue" has been introduced for the load_defer tag. The parameter defaults to 0 and determines the order of execution of code within the resulting code which is given by the 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
 
<pre>
 
<pre>
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"}
 +
</pre>
 +
 
 +
== Caching for buy_now.tpl and other templates ==
 +
 
 +
{{XC 4.4}}
 +
 
 +
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>
 +
$smarty->caching = 2;
 +
</pre>
 +
 
 +
with
  
{load_defer file="onload_js" direct_info=$smarty.capture.onload_js type="js" queue="1"}
+
<pre>
 +
$smarty->caching = 0;
 
</pre>
 
</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.
 +
 +
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.
 +
 +
[[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]]
 +
 +
[[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.