Skip to content
This repository was archived by the owner on Nov 19, 2024. It is now read-only.

Commit 3594164

Browse files
almarchenkoalmarchenko
authored
Merge pull request #153 from magento/am_55613_2
added changes about renaming files to use grunt
2 parents 3a3e281 + b83ad91 commit 3594164

File tree

1 file changed

+216
-1
lines changed

1 file changed

+216
-1
lines changed

‎guides/v2.1/frontend-dev-guide/css-topics/css_debug.md

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎guides/v2.1/frontend-dev-guide/css-topics/css_debug.md

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
---
2+
layout: default
3+
group: fedg
4+
subgroup: D_CSS
5+
title: Styles debugging
6+
menu_order: 4
7+
menu_title: Styles debugging
8+
version: 2.0
9+
github_link: frontend-dev-guide/css-topics/css_debug.md
10+
redirect_from: /guides/v1.0/frontend-dev-guide/css-topics/css_debug.html
11+
---
12+
13+
<h2>What's in this topic</h2>
14+
15+
<p>
16+
The topic describes how the changes you make in stylesheets are applied in the client-side and server-side LESS <a href="{{page.baseurl}}frontend-dev-guide/css-topics/css-preprocess.html" target="_blank">compilation modes</a>, and suggests the approaches and tools you can use to streamline the process of applying and debugging customizations. </p>
17+
18+
**Contents**
19+
20+
* TOC
21+
{:toc}
22+
23+
## Prerequisites
24+
Make sure that you [set]({{page.baseurl}}config-guide/cli/config-cli-subcommands-mode.html) your Magento application to the developer or default [mode]({{page.baseurl}}config-guide/bootstrap/magento-modes.html).
25+
26+
## Styles debugging in client-side compilation mode {#css_debug_client}
27+
28+
Client-side LESS compilation is implemented using the native `less.js` library. The default configuration is set in <code>lib/web/less/config.less.js</code>; you can change it as needed.
29+
30+
You can find the detailed information about the configuration and other options of the <code>less.js</code> used in a browser at <a href="http://lesscss.org/usage/#using-less-in-the-browser" target="_blank">http://lesscss.org/usage/#using-less-in-the-browser</a>.
31+
32+
In client-side compilation mode, most of the stylesheet customizations display immediately after you reload a page in a browser.
33+
34+
<span id="css_exception">There are certain types of changes</span>, that require you to clear the <code>pub/static/frontend/&lt;Vendor&gt;/&lt;theme&gt;/&lt;locale&gt;</code> directory and trigger the compilation and <a href="{{page.baseurl}}architecture/view/static-process.html#publish-static-view-files" target="_blank">publication</a> processes anew.
35+
36+
This is required in the following cases:
37+
<ul>
38+
<li>If you change the <a href="{{page.baseurl}}frontend-dev-guide/css-topics/css-preprocess.html#css_preprocess_terms" target="_blank">root source files</a> that contain the <code>@magento_import</code> directive, or the <code>@import</code> directive where the imported file is specified without extension.</li>
39+
<li>If you rename, remove, or add a <code>.less</code> file imported with a <code>@magento_import</code> or <code>@import</code> directive but you did not correct the directives accordingly.</li>
40+
41+
</ul>
42+
43+
To clear the <code>pub/static/frontend/&lt;Vendor&gt;/&lt;theme&gt;/&lt;locale&gt;</code> directory, delete the directory in the file system, and reload the store pages in a browser to trigger compilation and publication.
44+
45+
## Styles debugging in server-side compilation mode {#css_debug_server}
46+
47+
In server-side LESS compilation mode, to have your changes applied, clear <code>pub/static/frontend/&lt;Vendor&gt;/&lt;theme&gt;/&lt;locale&gt;</code> by deleting the directory in the file system, and reload the store pages to trigger compilation and publication.
48+
49+
<div class="bs-callout bs-callout-info" id="info">
50+
<p>You might also need to clear the <code>var/cache</code> and <code>var/view_preprocessing</code> directories.</p>
51+
</div>
52+
53+
Alternatively, to streamline the process of applying and debugging styles customizations, in server-side compilation mode, you can use the <a href="http://gruntjs.com/" target="_blank">Grunt JavaScript task runner</a>.
54+
55+
The following section describes in details how to install, configure and use Grunt for styles debugging.
56+
57+
### Installing and configuring Grunt {#grunt_prereq}
58+
59+
Magento has built-in Grunt tasks configured, but there are still several prerequisite steps you need to take to be able to use it:
60+
61+
<ol>
62+
<li>
63+
Install <a href="https://github.com/joyent/node/wiki/installing-node.js-via-package-manager)" target="_blank">node.js</a> to any location on your machine.
64+
</li>
65+
<li>Install Grunt CLI tool globally. To do this, run the following command in a command prompt:<br>
66+
<pre>
67+
npm install -g grunt-cli
68+
</pre>
69+
</li>
70+
<li>
71+
Rename the following files in your Magento root directory:
72+
<ul>
73+
<li><code>package.json.sample</code> to <code>package.json</code></li>
74+
<li><code>Gruntfile.js.sample</code> to <code>Gruntfile.js</code></li>
75+
</ul>
76+
</li>
77+
<li>
78+
Install (or refresh) the <code>node.js</code> project dependency, including Grunt, for your Magento instance. To do this, run the following commands in a command prompt:<br>
79+
80+
<pre>
81+
cd &lt;your_Magento_instance_directory&gt;
82+
npm install
83+
npm update
84+
</pre>
85+
</li>
86+
87+
<li>
88+
Add your theme to Grunt configuration. To do this, in the <code>dev/tools/grunt/configs/themes.js</code> file, add your theme to <code>module.exports</code> like following:
89+
<pre>
90+
module.exports = {
91+
...
92+
&lt;theme&gt;: {
93+
area: 'frontend',
94+
name: '&lt;Vendor&gt;/&lt;theme&gt;',
95+
locale: '&lt;language&gt;',
96+
files: [
97+
'&lt;path_to_file1&gt;', //path to root source file
98+
'&lt;path_to_file2&gt;'
99+
],
100+
dsl: 'less'
101+
...
102+
},
103+
</pre>
104+
105+
Where the following notation is used:
106+
<ul>
107+
<li>
108+
<code>&lt;theme&gt;</code>: your theme code, conventionally should correspond to the theme directory name.
109+
</li>
110+
<li>
111+
<code>&lt;language&gt;</code>: specified in the 'code_subtag' format, for example <code>en_US</code>. Only one locale can be specified here. To debug the theme with another locale, create one more theme declaration, having specified another value for <code>language</code>
112+
</li>
113+
<li>
114+
<code>&lt;path_to_file&gt;</code>: path to the root source file, relative to the <code>app/design/frontend/&lt;Vendor&gt;/&lt;theme/&gt;web</code> directory. You need to specify all <a href="{{page.baseurl}}frontend-dev-guide/css-topics/css-preprocess.html#css_preprocess_terms" target="_blank">root source files of the theme</a>. If your theme <a href="{{page.baseurl}}frontend-dev-guide/themes/theme-inherit.html" target="_blank">inherits</a> from a certain theme, and does not contain its own root source files, specify the root source files of the parent theme.
115+
116+
</li>
117+
118+
</ul>
119+
</li>
120+
<li id="livereload">
121+
(Optional) If you want to use Grunt for "watching" changes automatically, without reloading pages in a browser each time, install the <a href="http://livereload.com/extensions/" target="_blank">LiveReload extension</a> in your browser.
122+
123+
</li>
124+
</ol>
125+
126+
127+
### Grunt commands {#grunt_commands}
128+
129+
The following table describes the grunt commands you can use performing different customization tasks. Run all commands from your Magento installation directory.
130+
131+
<table>
132+
<tr>
133+
<th>
134+
Grunt task
135+
</th>
136+
<th>
137+
Action
138+
</th>
139+
</tr>
140+
<tr>
141+
142+
<td>
143+
<pre>
144+
grunt clean:&lt;theme&gt;
145+
</pre>
146+
147+
For example:
148+
<pre>
149+
grunt clean:blank
150+
</pre>
151+
</td>
152+
<td>
153+
Removes the theme related static files in the <code>pub/static</code> and <code>var</code> directories.
154+
</td>
155+
</tr>
156+
<tr>
157+
158+
<td>
159+
<pre>
160+
grunt exec:&lt;theme&gt;
161+
</pre>
162+
163+
</td>
164+
<td>
165+
Republishes symlinks to the source files to the <code>pub/static/frontend/&lt;Vendor&gt;/&lt;theme&gt;/&lt;locale&gt;</code> directory.
166+
167+
</td>
168+
</tr>
169+
<tr>
170+
<td>
171+
172+
<pre>
173+
grunt less:&lt;theme&gt;
174+
</pre>
175+
</td>
176+
<td>
177+
Compiles <code>.css</code> files using the symlinks published in the <code>pub/static/frontend/&lt;Vendor&gt;/&lt;theme&gt;/&lt;locale&gt;</code> directory
178+
</td>
179+
</tr>
180+
181+
<tr>
182+
183+
<td>
184+
<pre>
185+
grunt watch
186+
</pre>
187+
</td>
188+
<td>
189+
Tracks the changes in the source files, recompiles <code>.css</code> files, and reloads the page in the browser pages
190+
(you need to have <a href="#livereload">LiveReload</a> installed for you browser)
191+
</td>
192+
</tr>
193+
</table>
194+
195+
### Use cases of tracking changes using Grunt {#use_cases}
196+
197+
The following shows which Grunt tasks to use for debugging:
198+
199+
<ul>
200+
<li>After you switch the compilation mode from client-side to server-side, run the <code>exec</code> command.</li>
201+
<li>
202+
After you customize the content of any <code>.less</code> file, except the root source files, run the <code>less</code> task and reload the page. </li>
203+
204+
<li>After you <a href="#css_exception">customize the root source files or move the files included to the root files</a>, run the <code>exec</code> command and reload the page.</li>
205+
206+
207+
</ul>
208+
209+
If you have LiveReload installed, run the <code>grunt watch</code> command, and the flow is even simpler:
210+
<ul>
211+
<li>
212+
After you customize the content of any <code>.less</code> file, changes are applied and the page reloads automatically. No additional changes are required.</li>
213+
214+
<li>After you <a href="#css_exception">customize the root source files or move the files included to the root files</a>, run the <code>clean</code> and <code>exec</code> commands, and the browser page reloads automatically.</li>
215+
216+
</ul>

0 commit comments

Comments
 (0)