Author: bpoussin Date: 2012-12-25 03:51:50 +0100 (Tue, 25 Dec 2012) New Revision: 4 Url: http://nuiton.org/projects/nuiton-js/repository/revisions/4 Log: ajout de la documentation Modified: trunk/src/site/rst/index.rst Modified: trunk/src/site/rst/index.rst =================================================================== --- trunk/src/site/rst/index.rst 2012-12-25 02:11:04 UTC (rev 3) +++ trunk/src/site/rst/index.rst 2012-12-25 02:51:50 UTC (rev 4) @@ -1,18 +1,136 @@ Utilisation =========== -dependence: nuiton-js-wro nuiton-js-<nom> +Pour utiliser nuiton-js dans un environnement Servlet 3 vous devez déclarer dans +vos dépendances Maven:: -<%@page contentType="text/html; charset=UTF-8" pageEncoding="UTF-8"%> -<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %> -<script type="text/javascript" src="<c:url value="/nuiton-js/jquery.js"/>"></script> + <dependency> + <groupId>org.nuiton.js</groupId> + <artifactId>nuiton-js-wro</artifactId> + <version>${versionNuitonJs}</version> + </dependency> -?minimize=false +Il faut ensuite ajouter en dépendance Maven les librairies JS et CSS que vous +souhaiter utiliser. Ne vous préocupé 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 resources 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:: + + <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 ces propres ressources +============================================== + +Il est possible de définir un fichier WEB-INF/wro.xml pour gérer ces 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épendans +**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 + +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 + + Création d'un nouveau module ============================ -- wro-<nom>.xml a la racine de resources qui liste les fichiers (css et js) du répertoire <nom> +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. -Issue 593: cannot use resource wildcards for the same classpath in multiple JARs \ No newline at end of file +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"> + <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> + +