Compile LESS"

From Documentation
m (correct highlight (via JWB))
(28 intermediate revisions by 2 users not shown)
Line 2: Line 2:
  
 
= Install Node.js =
 
= Install Node.js =
Node.js is now required is now required for our ZK-Less Engine since 7.0.3.
+
Node.js is now required for our ZK-Less Engine since ZK 7.0.3.
  
 
If you don't have Node.js installed yet, please follow the steps given by the [http://nodejs.org/ official-website] to install Node.js.
 
If you don't have Node.js installed yet, please follow the steps given by the [http://nodejs.org/ official-website] to install Node.js.
 +
 +
Node version 0.10.30 or above is required. To check your Node.js version, simply run:
 +
 +
<source lang="bash">node --version</source>
  
 
= Compile LESS to DSP =
 
= Compile LESS to DSP =
  
If you are using DSP pages, here we introduce how to compile LESS to DSP files by Ant and Maven.
+
Here we introduce two ways to compile LESS files to DSP files. One is by Ant and the other is by Maven.
 +
 
 +
You could choose either one of them depends on your preferences. 
  
 
== Compile LESS by Ant ==
 
== Compile LESS by Ant ==
 
* Have Node.js installed in your environment.
 
* Have Node.js installed in your environment.
 
* Follow the online [http://ant.apache.org/manual/install.html document] to install Apache Ant.
 
* Follow the online [http://ant.apache.org/manual/install.html document] to install Apache Ant.
* Download the following necessary jars in your '''''project/lib''''' folder from [https://github.com/zkoss/zk/tree/7.0-Stable/dist/lib/ext zk repository] (right click -> save as).
+
* Download the following necessary jars into your '''''project/lib''''' folder from [https://github.com/zkoss/zk/tree/7.0-Stable/dist/lib/ext zk repository] (right click -> save as).
 
** yuicompressor.jar
 
** yuicompressor.jar
 
** zkjszips.jar
 
** zkjszips.jar
Line 21: Line 27:
 
* Execute the following command under your project folder to install ZK-Less' node package.
 
* Execute the following command under your project folder to install ZK-Less' node package.
 
<source lang=bash>
 
<source lang=bash>
cd root_of_your_project
+
cd project_folder
 
npm install zkless-engine
 
npm install zkless-engine
 
</source>
 
</source>
Line 28: Line 34:
 
<?xml version="1.0"?>
 
<?xml version="1.0"?>
 
<project name="less.compile" default="lessc" basedir=".">
 
<project name="less.compile" default="lessc" basedir=".">
<target name="lessc">
+
    <target name="lessc">
<exec executable="node">
+
        <exec executable="node">
<arg value="${basedir}/node_modules/zkless-engine/lib/CpLess.js" /> <!-- location of the engine's core file -->
+
            <!-- location of the engine's core file -->
<arg value="${basedir}/src/main/webapp"/>   <!-- input folder that contains less files-->
+
            <arg value="${basedir}/node_modules/zkless-engine/lib/CpLess.js"/>
            <arg value="${basedir}/src/main/webapp"/>   <!-- output folder -->
+
            <!-- input folder that contains less files-->
            <arg value="${basedir}/lib/zul.jar"/>    <!-- path of zul.jar -->
+
            <arg value="${basedir}/src/main/webapp"/>
</exec>
+
            <!-- output folder -->
                <!-- compress the result using zk's Css Compressor -->
+
            <arg value="${basedir}/src/main/webapp"/>
<java classname="CompressCss" fork="true">
+
            <!-- path of zul.jar -->
<arg value="${basedir}/src/main/webapp"/>   <!-- input folder (same as above) -->
+
            <arg value="${basedir}/lib/zul.jar"/>
<arg value="${basedir}/src/main/webapp"/>    <!-- output folder (same as above) -->
+
        </exec>
<classpath>
+
        <!-- compress the result using zk's Css Compressor -->
    <!-- required jars -->
+
        <java classname="CompressCss" fork="true">
    <pathelement location="${basedir}/lib/zkjszips.jar"/>
+
            <!-- input folder (same as above) -->
    <pathelement location="${basedir}/lib/yuicompressor.jar"/>
+
            <arg value="${basedir}/src/main/webapp"/>
    <pathelement location="${basedir}/lib/commons-io.jar"/>
+
            <!-- output folder (same as above) -->
    <pathelement location="${basedir}/lib/CssCompressor.jar"/>
+
            <arg value="${basedir}/src/main/webapp"/>
</classpath>
+
            <classpath>
</java>
+
                <!-- required jars -->
</target>
+
                <pathelement location="${basedir}/lib/zkjszips.jar"/>
 +
                <pathelement location="${basedir}/lib/yuicompressor.jar"/>
 +
                <pathelement location="${basedir}/lib/commons-io.jar"/>
 +
                <pathelement location="${basedir}/lib/CssCompressor.jar"/>
 +
            </classpath>
 +
        </java>
 +
    </target>
 
</project>
 
</project>
 
</source>
 
</source>
* Execute '''<tt>ant</tt>''' command in command line tool, i.e:  
+
* Execute '''<code>ant</code>''' command in command line tool, i.e:  
 
<source lang=bash>
 
<source lang=bash>
cd root_of_your_project
+
cd project_folder
 
ant lessc
 
ant lessc
 
</source>
 
</source>
Line 58: Line 70:
 
== Compile LESS by Maven ==
 
== Compile LESS by Maven ==
 
* Have Node.js installed in your environment.
 
* Have Node.js installed in your environment.
* Execute the following command to install the native less engine by Less.js
+
* Execute the following command to install the native LESS engine by [http://lesscss.org/ Less.js]
 
<source lang=bash>
 
<source lang=bash>
 
npm install -g less
 
npm install -g less
Line 66: Line 78:
 
<!-- Add Plugin Repository -->
 
<!-- Add Plugin Repository -->
 
<pluginRepositories>
 
<pluginRepositories>
<pluginRepository>
+
    <pluginRepository>
<id>zkmaven</id>
+
        <id>zkmaven</id>
<name>ZK Maven Plugin Repository</name>
+
        <name>ZK Maven Plugin Repository</name>
<url>http://mavensync.zkoss.org/maven2/</url>
+
        <url>http://mavensync.zkoss.org/maven2/</url>
</pluginRepository>
+
    </pluginRepository>
 
</pluginRepositories>
 
</pluginRepositories>
 
<dependencies>
 
<dependencies>
<!-- only needed if using _zkmixins.less provided by ZK -->
+
    <!-- only needed if using _zkmixins.less provided by ZK -->
<dependency>
+
    <dependency>
<groupId>org.zkoss.zk</groupId>
+
        <groupId>org.zkoss.zk</groupId>
<artifactId>zul</artifactId>
+
        <artifactId>zul</artifactId>
<version>7.0.3</version>
+
        <version>7.0.3</version>
</dependency>
+
    </dependency>
 
</dependencies>
 
</dependencies>
 
<build>
 
<build>
<plugins>
+
    <plugins>
<!-- Add zkless-engine-maven-plugin -->
+
        <!-- Add zkless-engine-maven-plugin -->
<plugin>
+
        <plugin>
<groupId>org.zkoss.maven</groupId>
+
            <groupId>org.zkoss.maven</groupId>
<artifactId>zkless-engine-maven-plugin</artifactId>
+
            <artifactId>zkless-engine-maven-plugin</artifactId>
<version>0.9.2</version>
+
            <version>0.9.6</version>
<executions>
+
            <executions>
<execution>
+
                <execution>
<id>compile-less</id>
+
                    <id>compile-less</id>
<goals>
+
                    <goals>
<goal>lessc</goal>
+
                        <goal>lessc</goal>
</goals>
+
                    </goals>
<configuration>
+
                    <configuration>
<!-- LESS source folder -->
+
                        <!-- LESS source folder -->
<sourceDirectory>${project.basedir}/src/main/resources</sourceDirectory>
+
                        <sourceDirectory>
<!-- *.CSS.DSP output folder -->
+
                            ${project.basedir}/src/main/resources
<outputDirectory>${project.basedir}/src/main/resources</outputDirectory>
+
                        </sourceDirectory>
</configuration>
+
                        <!-- *.CSS.DSP output folder -->
</execution>
+
                        <outputDirectory>
</executions>
+
                            ${project.basedir}/src/main/resources
</plugin>
+
                        </outputDirectory>
</plugins>
+
                       <!-- Compress Option, default is true -->
 +
                        <!--  <compress>false</compress> -->
 +
                    </configuration>
 +
                </execution>
 +
            </executions>
 +
        </plugin>
 +
    </plugins>
 
</build>
 
</build>
 
</source>
 
</source>
  
* Execute <tt>'''mvn install'''</tt> command to trigger LESS compilation.
+
* Execute <code>'''mvn install'''</code> command to trigger LESS compilation.
  
 
= Compile LESS to DSP during Development phase =
 
= Compile LESS to DSP during Development phase =
  
It is not friendly to debug LESS during development by running Ant or Maven each time you modify LESS files. Therefore, we provide a servlet named '''ZKLessServlet''' that can be used in web project to develop LESS by simply refreshing the browser page.
+
It is not friendly to debug LESS during development by running Ant or Maven each time you modify your LESS files.  
 +
 
 +
Therefore, we provide a servlet named '''ZKLessServlet''' that can be used in web project to develop LESS by simply refreshing the browser page.
  
 
'''Note:''' This is only recommended in development environment.
 
'''Note:''' This is only recommended in development environment.
Line 116: Line 136:
 
Steps to use '''ZKLessServlet''' within a Maven Project:
 
Steps to use '''ZKLessServlet''' within a Maven Project:
 
* Have Node.js installed in your environment.
 
* Have Node.js installed in your environment.
* Install the native less engine by the following command:
+
* Install the native LESS engine by the following command:
 
<source lang=bash>
 
<source lang=bash>
 
npm install -g less
 
npm install -g less
Line 134: Line 154:
 
         <groupId>org.zkoss.maven</groupId>
 
         <groupId>org.zkoss.maven</groupId>
 
         <artifactId>zkless-servlet</artifactId>
 
         <artifactId>zkless-servlet</artifactId>
         <version>0.9.2</version>
+
         <version>0.9.6</version>
 
     </dependency>
 
     </dependency>
 
     <!-- omitted other dependency -->
 
     <!-- omitted other dependency -->
Line 144: Line 164:
 
<source lang="xml">
 
<source lang="xml">
 
<web-app>
 
<web-app>
    <!-- omitted other servlets -->
+
    <!-- omitted other servlets -->
    <servlet>
+
    <servlet>
        <servlet-name>zkLess</servlet-name>
+
        <servlet-name>zkLess</servlet-name>
        <servlet-class>org.zkoss.less.ZKLessServlet</servlet-class>
+
        <servlet-class>org.zkoss.less.ZKLessServlet</servlet-class>
        <init-param>
+
        <init-param>
            <param-name>org.zkoss.less.LessResource</param-name>
+
            <param-name>org.zkoss.less.LessResource</param-name>
            <param-value>/less</param-value><!-- specify to the folder that contains *.less -->
+
            <!-- specify to the folder that contains *.less -->
        </init-param>
+
            <param-value>/less</param-value>
        <init-param>
+
        </init-param>
            <param-name>org.zkoss.less.OutputFormat</param-name>
+
        <init-param>
            <param-value>.css.dsp</param-value><!-- specify output file suffix, default .css.dsp -->
+
            <param-name>org.zkoss.less.OutputFormat</param-name>
        </init-param>
+
            <!-- specify output file suffix, default .css.dsp -->
        <init-param>
+
            <param-value>.css.dsp</param-value>
            <param-name>org.zkoss.less.CompressOutput</param-name>
+
        </init-param>
            <param-value>true</param-value><!-- compress output, default true -->
+
        <init-param>
        </init-param>
+
            <param-name>org.zkoss.less.CompressOutput</param-name>
        <load-on-startup>1</load-on-startup>
+
            <!-- compress output, default true -->
    </servlet>
+
            <param-value>true</param-value>
    <servlet-mapping>
+
        </init-param>
        <servlet-name>zkLess</servlet-name>
+
        <load-on-startup>1</load-on-startup>
        <url-pattern>/less/*</url-pattern><!-- specify to folder that contains *.less -->
+
    </servlet>
    </servlet-mapping>
+
    <servlet-mapping>
 +
        <servlet-name>zkLess</servlet-name>
 +
        <!-- specify to folder that contains *.less -->
 +
        <url-pattern>/less/*</url-pattern>
 +
    </servlet-mapping>
 
</web-app>
 
</web-app>
 
</source>
 
</source>
  
 
* Project structure and use LESS directly in zul page.
 
* Project structure and use LESS directly in zul page.
 +
: Remember to put all your LESS files and import resources under '''webapp/less''' which is the folder specified in web.xml
 
: Project structure should look like the following:  
 
: Project structure should look like the following:  
  
<source lang="java" high="6, 8">
+
<source lang="java" highlight="6, 8">
 
zkMavenWebProject - src/main/webapp
 
zkMavenWebProject - src/main/webapp
 
     WEB-INF
 
     WEB-INF
Line 183: Line 208:
 
</source>
 
</source>
  
: Use test.less inside test.zul as follows
+
* Use test.less inside test.zul as follows
  
<source lang="xml" high="2">
+
<source lang="xml" highlight="2">
 
<!-- test.zul -->
 
<!-- test.zul -->
 
<?link rel="stylesheet" href="../less/test.less"?>
 
<?link rel="stylesheet" href="../less/test.less"?>

Revision as of 13:23, 19 January 2022


Install Node.js

Node.js is now required for our ZK-Less Engine since ZK 7.0.3.

If you don't have Node.js installed yet, please follow the steps given by the official-website to install Node.js.

Node version 0.10.30 or above is required. To check your Node.js version, simply run:

node --version

Compile LESS to DSP

Here we introduce two ways to compile LESS files to DSP files. One is by Ant and the other is by Maven.

You could choose either one of them depends on your preferences.

Compile LESS by Ant

  • Have Node.js installed in your environment.
  • Follow the online document to install Apache Ant.
  • Download the following necessary jars into your project/lib folder from zk repository (right click -> save as).
    • yuicompressor.jar
    • zkjszips.jar
    • commons-io.jar
    • CssCompressor.jar
    • zul.jar (extract zk-bin-7.0.X.zip file from sourceforge)
  • Execute the following command under your project folder to install ZK-Less' node package.
cd project_folder
npm install zkless-engine
  • Write an ant script build.xml file like the following sample under project folder, and change the input folder and output folder as needed.
<?xml version="1.0"?>
<project name="less.compile" default="lessc" basedir=".">
    <target name="lessc">
        <exec executable="node">
            <!-- location of the engine's core file -->
            <arg value="${basedir}/node_modules/zkless-engine/lib/CpLess.js"/>
            <!-- input folder that contains less files-->
            <arg value="${basedir}/src/main/webapp"/>
            <!-- output folder -->
            <arg value="${basedir}/src/main/webapp"/>
            <!-- path of zul.jar -->
            <arg value="${basedir}/lib/zul.jar"/>
        </exec>
        <!-- compress the result using zk's Css Compressor -->
        <java classname="CompressCss" fork="true">
            <!-- input folder (same as above) -->
            <arg value="${basedir}/src/main/webapp"/>
            <!-- output folder (same as above) -->
            <arg value="${basedir}/src/main/webapp"/>
            <classpath>
                <!-- required jars -->
                <pathelement location="${basedir}/lib/zkjszips.jar"/>
                <pathelement location="${basedir}/lib/yuicompressor.jar"/>
                <pathelement location="${basedir}/lib/commons-io.jar"/>
                <pathelement location="${basedir}/lib/CssCompressor.jar"/>
            </classpath>
        </java>
    </target>
</project>
  • Execute ant command in command line tool, i.e:
cd project_folder
ant lessc

Compile LESS by Maven

  • Have Node.js installed in your environment.
  • Execute the following command to install the native LESS engine by Less.js
npm install -g less
  • Modify pom.xml in maven project
<!-- Add Plugin Repository -->
<pluginRepositories>
    <pluginRepository>
        <id>zkmaven</id>
        <name>ZK Maven Plugin Repository</name>
        <url>http://mavensync.zkoss.org/maven2/</url>
    </pluginRepository>
</pluginRepositories>
<dependencies>
    <!-- only needed if using _zkmixins.less provided by ZK -->
    <dependency>
        <groupId>org.zkoss.zk</groupId>
        <artifactId>zul</artifactId>
        <version>7.0.3</version>
    </dependency>
</dependencies>
<build>
    <plugins>
        <!-- Add zkless-engine-maven-plugin -->
        <plugin>
            <groupId>org.zkoss.maven</groupId>
            <artifactId>zkless-engine-maven-plugin</artifactId>
            <version>0.9.6</version>
            <executions>
                <execution>
                    <id>compile-less</id>
                    <goals>
                        <goal>lessc</goal>
                    </goals>
                    <configuration>
                        <!-- LESS source folder -->
                        <sourceDirectory>
                            ${project.basedir}/src/main/resources
                        </sourceDirectory>
                        <!-- *.CSS.DSP output folder -->
                        <outputDirectory>
                            ${project.basedir}/src/main/resources
                        </outputDirectory>
                        <!-- Compress Option, default is true -->
                        <!--  <compress>false</compress> -->
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>
  • Execute mvn install command to trigger LESS compilation.

Compile LESS to DSP during Development phase

It is not friendly to debug LESS during development by running Ant or Maven each time you modify your LESS files.

Therefore, we provide a servlet named ZKLessServlet that can be used in web project to develop LESS by simply refreshing the browser page.

Note: This is only recommended in development environment.

Steps to use ZKLessServlet within a Maven Project:

  • Have Node.js installed in your environment.
  • Install the native LESS engine by the following command:
npm install -g less
  • Add maven dependency if you are using maven.
<repositories>
    <repository>
        <id>ZK CE</id>
        <name>ZK CE Repository</name>
        <url>http://mavensync.zkoss.org/maven2</url>
    </repository>
    <!-- omitted other repository -->
</repositories>
<dependencies>
    <dependency>
        <groupId>org.zkoss.maven</groupId>
        <artifactId>zkless-servlet</artifactId>
        <version>0.9.6</version>
    </dependency>
    <!-- omitted other dependency -->
</dependencies>
  • Add servlet settings in web.xml
<web-app>
    <!-- omitted other servlets -->
    <servlet>
        <servlet-name>zkLess</servlet-name>
        <servlet-class>org.zkoss.less.ZKLessServlet</servlet-class>
        <init-param>
            <param-name>org.zkoss.less.LessResource</param-name>
            <!-- specify to the folder that contains *.less -->
            <param-value>/less</param-value>
        </init-param>
        <init-param>
            <param-name>org.zkoss.less.OutputFormat</param-name>
            <!-- specify output file suffix, default .css.dsp -->
            <param-value>.css.dsp</param-value>
        </init-param>
        <init-param>
            <param-name>org.zkoss.less.CompressOutput</param-name>
            <!-- compress output, default true -->
            <param-value>true</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>zkLess</servlet-name>
        <!-- specify to folder that contains *.less -->
        <url-pattern>/less/*</url-pattern>
    </servlet-mapping>
</web-app>
  • Project structure and use LESS directly in zul page.
Remember to put all your LESS files and import resources under webapp/less which is the folder specified in web.xml
Project structure should look like the following:
zkMavenWebProject - src/main/webapp
    WEB-INF
        web.xml
        zk.xml
    less
        test.less
    pages
        test.zul
  • Use test.less inside test.zul as follows
<!-- test.zul -->
<?link rel="stylesheet" href="../less/test.less"?>
<zk>
    <button label="test" />
</zk>
  • Now you can modify LESS and see the result by refreshing your browser page.

Version History

Last Update : 2022/01/19


Version Date Content
     



Last Update : 2022/01/19

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.