Author: echatellier Date: 2013-05-30 10:33:28 +0200 (Thu, 30 May 2013) New Revision: 89 Url: http://nuiton.org/projects/nuiton-js/repository/revisions/89 Log: Use templated site file Added: trunk/src/site/fr/rst/index.rst.vm trunk/src/site/rst/index.rst.vm Copied: trunk/src/site/fr/rst/index.rst.vm (from rev 75, trunk/src/site/fr/rst/index.rst) =================================================================== --- trunk/src/site/fr/rst/index.rst.vm (rev 0) +++ trunk/src/site/fr/rst/index.rst.vm 2013-05-30 08:33:28 UTC (rev 89) @@ -0,0 +1,272 @@ +.. - +.. * #%L +.. * Nuiton JS +.. * $Id:$ +.. * $HeadURL:$ +.. * %% +.. * Copyright (C) 2012 - 2013 CodeLutin +.. * %% +.. * This program is free software: you can redistribute it and/or modify +.. * it under the terms of the GNU Lesser General Public License as +.. * published by the Free Software Foundation, either version 3 of the +.. * License, or (at your option) any later version. +.. * +.. * This program is distributed in the hope that it will be useful, +.. * but WITHOUT ANY WARRANTY; without even the implied warranty of +.. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.. * GNU General Lesser Public License for more details. +.. * +.. * You should have received a copy of the GNU General Lesser Public +.. * License along with this program. If not, see +.. * <http://www.gnu.org/licenses/lgpl-3.0.html>. +.. * #L% +.. - + +========= +Nuiton-js +========= + +Utilisation +=========== + +Déclaration pour Servlet 3 +-------------------------- + +Pour utiliser nuiton-js dans un environnement Servlet 3 vous devez déclarer dans +vos dépendances Maven:: + + <dependency> + <groupId>org.nuiton.js</groupId> + <artifactId>nuiton-js-wro</artifactId> + <version>${project.version}</version> + </dependency> + +Déclaration pour Servlet 2 +-------------------------- + +Si vous n'êtes pas dans un environnement Servlet 3, il vous faudra déclarer +vous même le filtre en plus de la déclaration de la dépendance Maven:: + + <filter> + <filter-name>WebResourceOptimizer</filter-name> + <filter-class>org.nuiton.js.wro.NuitonJsFilter</filter-class> + </filter> + <filter-mapping> + <filter-name>WebResourceOptimizer</filter-name> + <url-pattern>/nuiton-js/*</url-pattern> + </filter-mapping> + + +Déclaration commune à toutes les versions de Servlets +----------------------------------------------------- + +Il faut ensuite ajouter en dépendance Maven les librairies JS et CSS que vous +souhaiter utiliser. Ne vous préoccupez par des dépendances Nuiton-js est la pour +ça. + +Par exemple si vous avez besoin de jquery et jquery-ui:: + + <dependency> + <groupId>org.nuiton.js</groupId> + <artifactId>nuiton-js-jquery</artifactId> + <version>${versionJQuery}</version> + </dependency> + + <dependency> + <groupId>org.nuiton.js</groupId> + <artifactId>nuiton-js-jquery-ui</artifactId> + <version>${versionJQueryUI}</version> + </dependency> + +Dans vos pages JSP vous pouvez alors récupérer les ressources via par exemple l'url:: + + /nuiton-js/jquery.js + +ce qui donne dans la page JSP:: + + <%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %> + ... + <script type="text/javascript" src="<c:url value="/nuiton-js/jquery.js"/>"></script> + +Si vous souhaitez que le javascript ne soit pas minimisé, vous pouvez ajouter à +l'url "?minimize=false" ce qui donne (ne fonctionne qu'en mode debug=true:: + + <script type="text/javascript" src="<c:url value="/nuiton-js/jquery.js?minimize=false"/>"></script> + +Lorsque vous voulez passer le site en production vous devez créer le fichier +WEB-INF/nuiton-js.properties et y mettre:: + + debug=false + +Utilisation de wro pour ses propres ressources +============================================== + +Il est possible de définir un fichier WEB-INF/wro.xml pour gérer ses propres +ressources via wro. Vous pouvez aussi dans ce fichier faire références aux +librairies packagées par nuiton-js. Le nom du groupe des librairies de nuiton-js +est le nom de la ressources. Par exemple si vous avez en dépendance +**nuiton-js-jquery** alors le groupe se nommera **jquery** + +Pour plus d'explication sur le format de ce fichier reportez-vous à la documentation +de wro https://code.google.com/p/wro4j/wiki/WroFileFormat + +exemple d'un fichier WEB-INF/wro.xml:: + + <groups xmlns="http://www.isdc.ro/wro"> + <group name='MonApp'> + <group-ref>jquery</group-ref> + <group-ref>bootstrap-responsive</group-ref> + <group-ref>jquery-ui</group-ref> + <group-ref>jqplot</group-ref> + <!-- plugin jqplot --> + <group-ref>jqplot.canvasAxisTickRenderer</group-ref> + <group-ref>jqplot.canvasTextRenderer</group-ref> + <group-ref>jqplot.categoryAxisRenderer</group-ref> + <group-ref>jqplot.cursor</group-ref> + <group-ref>jqplot.highlighter</group-ref> + <!-- js et css specifique a l'application --> + <css>/css/MonApp.css</css> + <js>/js/MonApp.js</js> + </group> + </groups> + +puis dans vos fichier html ou jsp:: + + <link href="<c:url value='/nuiton-js/MonApp.css'/>" rel="stylesheet" type="text/css"/> + <script type="text/javascript" src="<c:url value='/nuiton-js/MonApp.js'/>"></script> + + +Utilisation avancée +=================== + +Il est possible de forcer le rechargement du modèle ou de vider le cache en +demandant les URLs:: + + /nuiton-js/wroAPI/reloadModel + /nuiton-js/wroAPI/reloadCache + +Paramétrage possible +==================== +Via le fichier WEB-INF/nuiton-js.properties vous pouvez modifier le comportement +pour voir toutes les options vous pouvez vous reporter à la documentation de wro +https://code.google.com/p/wro4j/wiki/ConfigurationOptions + +Nuiton-js force par défaut les options suivantes:: + + debug=true + managerFactoryClassName=org.nuiton.js.wro.NuitonJsWroManagerFactory + preProcessors=cssUrlRewriting,cssImport,semicolonAppender,cssMin + postProcessors=cssVariables,jsMin + uriLocators=servletContext,uri,classpath + +Utilisation du plugin Maven pour générer les ressources +======================================================= + +Voici un exemple d'utilisation. La différence avec la configuration standard +est la déclaration de **org.nuiton.js.wro.NuitonJsMavenWroManagerFactory** comme +wroManagerFactory et la déclaration des dépendances vers les ressources js et css:: + + <build> + <plugins> + <plugin> + <groupId>ro.isdc.wro4j</groupId> + <artifactId>wro4j-maven-plugin</artifactId> + <version>1.6.3</version> + + <dependencies> + <dependency> + <groupId>org.nuiton.js</groupId> + <artifactId>nuiton-js-wro</artifactId> + <version>${project.version}</version> + </dependency> + <dependency> + <groupId>org.nuiton.js</groupId> + <artifactId>nuiton-js-jquery</artifactId> + <version>1.9.1-2</version> + </dependency> + <dependency> + <groupId>org.nuiton.js</groupId> + <artifactId>nuiton-js-jqgrid</artifactId> + <version>4.4.1-1</version> + </dependency> + </dependencies> + + <executions> + <execution> + <phase>compile</phase> + <goals> + <goal>run</goal> + </goals> + </execution> + </executions> + + <configuration> + <targetGroups>MyApp</targetGroups> + <minimize>true</minimize> + <wroFile>${basedir}/src/main/resources/nuiton-js/wro.xml</wroFile> + <extraConfigFile>${basedir}/src/main/resources/nuiton-js/wro.properties</extraConfigFile> + <contextFolder>${basedir}/src/main/resources/web/</contextFolder> + <destinationFolder>${basedir}/target/classes/web/</destinationFolder> + <wroManagerFactory>org.nuiton.js.wro.NuitonJsMavenWroManagerFactory</wroManagerFactory> + </configuration> + </plugin> + </plugin> + </build> + +Vous pouvez alors dans vos pages utiliser:: + + <link href="<c:url value='/wro/MonApp.css'/>" rel="stylesheet" type="text/css"/> + <script type="text/javascript" src="<c:url value='/wro/MonApp.js'/>"></script> + + +Création d'un nouveau module +============================ + +Pour créer un nouveau module il faut respecter quelques règles: + +- mettre en numéro de version du module maven le numero de version de la ressource à packager + avec en plus un numero de packaging. Par exemple pour jquery 1.8.3 la version + du module maven doit être 1.8.3-1 pour la première version de packaging +- mettre les ressources dans le répertoire: src/main/resources/nuiton-js-<nom de la ressource> +- créer le fichier de déclaration: src/main/resources/META-INF/nuiton-js/wro-<nom de la ressource>.xml +- il doit y avoir dans ce fichier de déclaration un groupe partant le nom de la ressource. + +Il ne faut mettre que la version normale des fichiers (pas minimisé) car la +librairie s'occupe elle même de minimiser les fichiers. + +le nom du répertoire pourrait être autre chose, mais en le préfixant par +nuiton-js et avec le nom de la ressource, on évite que l'utilisateur ait le même +répertoire dans son classpath ce qui ferait que ces ressources seraient elles aussi +prises en charge sans qu'il le souhaite. + +la déclaration peut ressembler à:: + + <groups xmlns="http://www.isdc.ro/wro"> + <import>classpath:META-INF/nuiton-js/wro-jquery.xml</import> + <group name='jquery-ui'> + <group-ref>jquery</group-ref> + <js>classpath:nuiton-js-jquery-ui/js/**.js</js> + <css>classpath:nuiton-js-jquery-ui/css/**.css</css> + </group> + </groups> + +Pour plus d'explication sur le format de ce fichier reportez-vous à la documentation +de wro https://code.google.com/p/wro4j/wiki/WroFileFormat + +Si la librairie a une dépendance sur une autre, il faut le faire ressortir dans +le pom.xml et aussi dans la déclaration en faisant référence au groupe dont il +dépend (comme dans l'exemple ci-dessus). + +Dans le fichier pom.xml, il ne faut pas mettre la version du dernier package mais +la version annoncé comme minimal par la librairie dont elle dépand. Par exemple +jquery-ui 1.9.2 dépend de jquery 1.6.x il faut donc mettre dans le pom.xml +de nuiton-js-jquery-ui la dépendance:: + + <dependency> + <groupId>org.nuiton.js</groupId> + <artifactId>nuiton-js-jquery</artifactId> + <version>[1.6,)</version> <!-- jquery ui compatible avec jquery >= 1.6 --> + <scope>runtime</scope> + </dependency> + + Copied: trunk/src/site/rst/index.rst.vm (from rev 87, trunk/src/site/rst/index.rst) =================================================================== --- trunk/src/site/rst/index.rst.vm (rev 0) +++ trunk/src/site/rst/index.rst.vm 2013-05-30 08:33:28 UTC (rev 89) @@ -0,0 +1,273 @@ +.. - +.. * #%L +.. * Nuiton JS +.. * $Id:$ +.. * $HeadURL:$ +.. * %% +.. * Copyright (C) 2012 - 2013 CodeLutin, Chatellier Eric +.. * %% +.. * This program is free software: you can redistribute it and/or modify +.. * it under the terms of the GNU Lesser General Public License as +.. * published by the Free Software Foundation, either version 3 of the +.. * License, or (at your option) any later version. +.. * +.. * This program is distributed in the hope that it will be useful, +.. * but WITHOUT ANY WARRANTY; without even the implied warranty of +.. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.. * GNU General Lesser Public License for more details. +.. * +.. * You should have received a copy of the GNU General Lesser Public +.. * License along with this program. If not, see +.. * <http://www.gnu.org/licenses/lgpl-3.0.html>. +.. * #L% +.. - + +========= +Nuiton-js +========= + +Presentation +============ + +Nuiton-js is a libraries used to: + * package javascript and css libraries as `maven <http://maven.apache.org/>`_ artifacts + * aggregate severals libraries into a single file + * minimize and reduce size using wro mechanisms + * simply package new libraries + +Using Servlet 3 API +------------------- + +To use nuiton-js in a servlet 3 container, you just have to add following +dependencies in your project pom.xml file:: + + <dependency> + <groupId>org.nuiton.js</groupId> + <artifactId>nuiton-js-wro</artifactId> + <version>${project.version}</version> + </dependency> + +Using Servlet 2 API +------------------- + +If you're not using a servlet 3 container, you will have to add following +configuration in your application's ``web.xml`` file (in addition to maven +dependencies into your pom file):: + + <filter> + <filter-name>WebResourceOptimizer</filter-name> + <filter-class>org.nuiton.js.wro.NuitonJsFilter</filter-class> + </filter> + <filter-mapping> + <filter-name>WebResourceOptimizer</filter-name> + <url-pattern>/nuiton-js/*</url-pattern> + </filter-mapping> + + +Common configuration +-------------------- + +Then, you will have to add the js or css libraries your want to use packaged +as maven dependencies. Nuiton-js will take care about transitive dependencies. + +For example, to use ``jquery`` and ``jquery-ui``:: + + <dependency> + <groupId>org.nuiton.js</groupId> + <artifactId>nuiton-js-jquery</artifactId> + <version>${versionJQuery}</version> + </dependency> + + <dependency> + <groupId>org.nuiton.js</groupId> + <artifactId>nuiton-js-jquery-ui</artifactId> + <version>${versionJQueryUI}</version> + </dependency> + +In your JSP pages, you could then retrieve ``jquery`` resources with following url:: + + /nuiton-js/jquery.js + +JSP will use following code to import it:: + + <%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %> + ... + <script type="text/javascript" src="<c:url value="/nuiton-js/jquery.js"/>"></script> + +If you don't want javascript code to be minimized by nuiton-js, you could append +``?minimize=false`` to the url (if you're using the default ``debug=true`` configuration):: + + <script type="text/javascript" src="<c:url value="/nuiton-js/jquery.js?minimize=false"/>"></script> + +When deploying your site in production, you could change default configuration +editing file ``WEB-INF/nuiton-js.properties`` by adding:: + + debug=false + +Using wro to manage application own resources +============================================= + +You can create a file in W``EB-INF/wro.xml`` to manage your own resources +with wro. You can also reference libraries package by nuiton-js. Libraries +group name is resources group name. For example, if you use ``nuiton-js-jquery``, +group name will be ``jquery``. + +For more information about wro.xml file format, please refer to wro documentation +at https://code.google.com/p/wro4j/wiki/WroFileFormat + +``WEB-INF/wro.xml`` file example:: + + <groups xmlns="http://www.isdc.ro/wro"> + <group name='MyApp'> + <group-ref>jquery</group-ref> + <group-ref>bootstrap-responsive</group-ref> + <group-ref>jquery-ui</group-ref> + <group-ref>jqplot</group-ref> + <!-- plugin jqplot --> + <group-ref>jqplot.canvasAxisTickRenderer</group-ref> + <group-ref>jqplot.canvasTextRenderer</group-ref> + <group-ref>jqplot.categoryAxisRenderer</group-ref> + <group-ref>jqplot.cursor</group-ref> + <group-ref>jqplot.highlighter</group-ref> + <!-- js et css specifique a l'application --> + <css>/css/MyApp.css</css> + <js>/js/MyApp.js</js> + </group> + </groups> + +and, in your html or jsp files:: + + <link href="<c:url value='/nuiton-js/MyApp.css'/>" rel="stylesheet" type="text/css"/> + <script type="text/javascript" src="<c:url value='/nuiton-js/MyApp.js'/>"></script> + + +Advanced use +============ + +You can force model reload or cache cleaning using following urls:: + + /nuiton-js/wroAPI/reloadModel + /nuiton-js/wroAPI/reloadCache + +Available configuration +======================= +Using file ``WEB-INF/nuiton-js.properties``, you can change wro behaviour. + +Nuiton-js use following options by default:: + + debug=true + managerFactoryClassName=org.nuiton.js.wro.NuitonJsWroManagerFactory + preProcessors=cssUrlRewriting,cssImport,semicolonAppender,cssMin + postProcessors=cssVariables,jsMin + uriLocators=servletContext,uri,classpath + +For more details about wro configuration, refer to following url: +https://code.google.com/p/wro4j/wiki/ConfigurationOptions + +Using maven plugin to generate static resources +=============================================== + +Here is an example of using ``wro4j-maven-plugin`` to generate static resources. +The main difference with standard configuration is the use of +**org.nuiton.js.wro.NuitonJsMavenWroManagerFactory** configuration for +``wroManagerFactory`` and plugin dependencies:: + + <build> + <plugins> + <plugin> + <groupId>ro.isdc.wro4j</groupId> + <artifactId>wro4j-maven-plugin</artifactId> + <version>1.6.3</version> + + <dependencies> + <dependency> + <groupId>org.nuiton.js</groupId> + <artifactId>nuiton-js-wro</artifactId> + <version>${project.version}</version> + </dependency> + <dependency> + <groupId>org.nuiton.js</groupId> + <artifactId>nuiton-js-jquery</artifactId> + <version>1.9.1-2</version> + </dependency> + <dependency> + <groupId>org.nuiton.js</groupId> + <artifactId>nuiton-js-jqgrid</artifactId> + <version>4.4.1-1</version> + </dependency> + </dependencies> + + <executions> + <execution> + <phase>compile</phase> + <goals> + <goal>run</goal> + </goals> + </execution> + </executions> + + <configuration> + <targetGroups>MyApp</targetGroups> + <minimize>true</minimize> + <wroFile>${basedir}/src/main/resources/nuiton-js/wro.xml</wroFile> + <extraConfigFile>${basedir}/src/main/resources/nuiton-js/wro.properties</extraConfigFile> + <contextFolder>${basedir}/src/main/resources/web/</contextFolder> + <destinationFolder>${basedir}/target/classes/web/</destinationFolder> + <wroManagerFactory>org.nuiton.js.wro.NuitonJsMavenWroManagerFactory</wroManagerFactory> + </configuration> + </plugin> + </plugin> + </build> + +Then you could use statics js and css files in your application:: + + <link href="<c:url value='/wro/MyApp.css'/>" rel="stylesheet" type="text/css"/> + <script type="text/javascript" src="<c:url value='/wro/MyApp.js'/>"></script> + +Creating a new module +===================== + +To add a new module for a new javascript or css library, you need to respect +a few rules: + +- setup module version using the same packaged resource's version with an additional + packaging number. For example, to package jquery 1.9.1, module version have to be + ``1.9.1-1`` for the first packaging release +- put resources in directory ``src/main/resources/nuiton-js-<resource name>`` +- add resource configuration file ``src/main/resources/META-INF/nuiton-js/wro-<resource name>.xml`` +- define a group name according to resource name in wro configuration file + +Resource have to be committed unminimized. Nuiton-js will minimize then at runtime. + +It's a good practice to prefix directory name with 'nuiton-js' and resource name. +This will avoid any future problem if use define his own directory with resource +name in the classpath. + +wro.xml file example:: + + <groups xmlns="http://www.isdc.ro/wro"> + <import>classpath:META-INF/nuiton-js/wro-jquery.xml</import> + <group name='jquery-ui'> + <group-ref>jquery</group-ref> + <js>classpath:nuiton-js-jquery-ui/js/**.js</js> + <css>classpath:nuiton-js-jquery-ui/css/**.css</css> + </group> + </groups> + +For more information about this file format, please refer to wro documentation: +https://code.google.com/p/wro4j/wiki/WroFileFormat + +If a library depends on another one, it must be present in pom.xml file too +as maven dependencies. + +In ``pom.xml`` file, you may use a minimum version instead of a hardcoded one. +User will be warned if he use a smaller version of dependencies library. +For example, jquery-ui-1.10.3 depends on jquery at least in version 1.6, +``pom.xml`` file must define following dependency:: + + <dependency> + <groupId>org.nuiton.js</groupId> + <artifactId>nuiton-js-jquery</artifactId> + <version>[1.6,)</version> <!-- jquery ui is compatible with jquery >= 1.6 --> + <scope>runtime</scope> + </dependency>