Développer pour la BOEW - nschonni/wet-boew GitHub Wiki
- Les demandes de retrait sont les bienvenues. Assurez-vous d'apporter les changements dans la dernière version du code et de limiter le champ de validation (commit range) seulement aux fichiers que vous aviez l’intention de modifier (pour éviter les conflits).
- Les nouvelles composantes devraient être ajoutées dans un branchement de type feature-* (p. ex., feature-lightbox).
- Les licences de toutes les nouvelles composantes et du code afférent doivent être compatibles avec la licence MIT utilisée par la Boîte à outils de l’expérience Web (BOEW).
- Les nouveaux modules d’extension devraient se servir de pluginTemplate.js comme base pour le code JavaScript.
- Inclure le bloc de texte sur les conditions d’utilisation de la BOEW dans tous les fichiers sources textuels soumis aux droits d’auteur de la Couronne.
-
Valider votre balisage HTML. Le balisage devrait être en HTML5 bien formé.
- Pour vérifier si le balisage est bien formé, valider à l’aide d’un préréglage XHTML5 et cocher la case « Be lax about HTTP Content-Type ».
-
Valider votre CSS en apportant les changements suivants aux paramètres par défaut :
- Profil : CSS niveau 3
- Extensions Propriétaires : Avertissements
-
Valider votre code JavaScript en apportant le changement suivant aux paramètres par défaut :
- Warn - When code is not in strict mode: false
- Optimiser votre code JavaScript, CSS et HTML
- Recommandations quant au formatage :
- Ajouter les tabulations en utilisant le style d'indentation K&R
- Utiliser les guillemets simples pour les chaînes de caractères en JavaScript (de façon à ce que les guillemets doubles non échappés (unescaped) puissent être utilisés pour les attributs dans les données de sortie HTML)
- Fureteurs pris en charge (cet élément devrait faire l’objet d’une vérification) :
- Browser test baseline - YUI Graded Browser Support (sauf Internet Explorer 6)
root - The most important file to note in the root is the build.xml file. This is what you will run to build the project. See [Building](#buildwet).
build - This directory contains the resulting files/directories created using the WET 3.0 build process. This folder includes most of the code files that a web project using WET will need. (Such as the CSS and jQuery files). The original contents of build reside in the src folder. This folder includes the components used to build a WET website.
- grids: Includes CSS and images for Grid system. CSS files were originally coded in SASS, and then converted to CSS during the build process.
- js: Includes files for JQuery functionality and CSS to style them.
- lib: Contains libraries used as part of the build process. This folder is not necessary for implementation; but is important for WET developement.
- theme-gcwu-fegc: The GC Web Usability theme is currently the only theme supported in WET 3.0. Any files specific to this theme will be built here.
- ruby build scripts: Responsible for SASS to CSS conversion during the build process.
- base: Some base SASS files to format your website under certain conditions. (different browsers, mobile, etc) These files are used for all pages, regardless of theme.
- grids: SASS files and images for Grid add-on. This add-on provides users with a series of css styles to use. The SASS is converted to CSS during the build process. View different ways to use the grid system here: http://wet-boew.github.com/wet-boew/demos/grids/grid-utilities-eng.html
- js: Contains the Javascript Framework which includes plugins, libraries and polyfills.
- theme-gcwu-fegc: This is where theme specific code is developed. The GC web usability theme is made up of both CSS and jQuery.
The build process allow developers to add new functionality (such as jQuery plugins) to an initial source folder and process these files into a final build folder. Publishers and developers are also free to add new functionality without using the build process. However, there are many benefits to adding code to the src folder and building it:
- Automate optimization tasks
- Fewer files, therefore less concurrent HTTP request that slow down mobile devices
- Smaller files for quicker download
WET 3.0 components are compiled through a build process, which is run using a variety of ant scripts. The build.xml file on the root is the main ant build file for the project. In addition, each folder under the src folder has its own build.xml file. The main purpose of the ant script at the root is to run the other ant scripts in the project and clean up existing files.
These additional ant build files in the src folder do a variety of different things depending upon what is included in the folder associated with the build.xml file. For example, if there is a SASS component in a folder with a build script, a compile.rb script will be run (located in the build folder) to compile SASS code into CSS.
These build files shouldn't have to be changed unless new functionality is added or new directories are included in src folder. For example, new themes need their own ant scripts as they are seperate entities with many different components. However, changes to the build are not needed when adding a new jQuery plugin or modifying existing functionality.
This image illustrates the folder structure and the location of the build files.
ANT - Version 1.8.x Download: http://ant.apache.org/bindownload.cgi Java SE - Version 6+ Download: http://www.oracle.com/technetwork/java/javase/downloads/index.html
In order to run Ant from within any directory on the command line, you need to set up your environment variables. They can be found under My Computer > Properties > Advanced > Environment Variables. Create two new system variables and call them ANT_HOME and JAVA_HOME. ANT_HOME should point to the directory where ant is located and JAVA_HOME should point to the location of your Java directory. Append %ANT_HOME %/bin and %JAVA_HOME%/bin to the end of the existing PATH variable. You can test if ant and java are running properly by typing ant -version and java -version into the command line. If you get a version number as the output then it has been installed correctly.
The window where the ANT_Home environment variable is being set.
Run build.xml from the root by navigating to your wet-boew folder and run: > build.cmd. This will run a series of different ant scripts depending upon what is included in the main build.xml file. Notice that there are a series of paths in the root build.xml which point to different build.xml files in other nested folders. These build.xml files are located under each sub-folder in the src folder.
If you’d prefer to use an IDE to run your scripts and view your files, download the "Eclipse IDE for Java EE Developers" as it will have everything you need to run your project.
Eclipse - Eclipse IDE for Java EE Developers Download: http://www.eclipse.org/downloads/
Open up eclipse and create a new general project. Right click on your project folder in the project explorer window and select "Import". Select General > File System and navigate to the WET folder. Once imported, you should see all the directories and files the wet project on the left hand side. Run the build.xml file by right clicking on it and selecting Run As > Ant Build.
Ant script being run from Eclipse.
You can see the progress of the build below your code view in the Console window. If you cannot see it, select Window > Show View > Console. This view allows you to debug errors in the build.
The build will download several files during the first build so those behind restrictive firewalls may encounter issues.
You will need to set your proxy information in the ANT_OPTS environmental variable. See the Ant Proxy manual http://ant.apache.org/manual/proxy.html for further information.
- On Windows you can use the build.cmd to set the ANT_OPTS variable:
build.cmd -Dhttp.proxyHost=PROXY -Dhttp.proxyPort=PORT
- If issues are still encountered, you may manually download the required files to their expected location before running Ant.
2. Create the folder build/lib/jruby-compiled and copy the gems inside with version number removed from the file name
- [sass.gem] - http://production.cf.rubygems.org/gems/sass-3.1.19.gem
- [chunky_png.gem] - http://production.cf.rubygems.org/gems/chunky_png-1.2.5.gem
- [fssm.gem] - http://production.cf.rubygems.org/gems/fssm-0.2.9.gem)
- [compass.gem] - http://production.cf.rubygems.org/gems/compass-0.12.1.gem
In order to add new functionality, such as a JQuery plugin, you will want to develop within the appropriate src folder and build the finished code with an ant script.
WET 3.0 jQuery integration is different from previous versions. There are a few major changes to how jQuery is intergrated into WET that developers should be aware of.
- jQuery is called at the end of the body of an HTML page instead of in the header. The reason for this is to allow asynchronous loading of PE object. This means that the plugins are loaded at the same time as the DOM, not after.
- The new PE object does not employ the progress method call in the head anymore. Everything is handled by the PE file at the bottom of the page.
- Plugins are called using a class-based system, eliminating the param tag in the header. (ex:
<table class="wet-boew-zebra">)
<script src="../js/lib/jquery.min.js"></script>
<script src="../js/pe-ap.js" id="progressive"></script>
<script>
/* <![CDATA[ */
var params = {
};
PE.progress(params);
/* ]]> */
</script>
</head>
WET 3.0
<script src="../../build/theme-gcwu-fegc/js/theme-min.js"></script> <script src="../../build/js/settings.js"></script> <script src="../../build/js/pe-ap-min.js"></script> </body> </html>
To create a new plugin navigate to **src/js/workers** and add your code in a separate .js file. Make sure to follow the coding conventions used in the other jQuery plugins so your code will properly compile during the build process. You can view a sample template on the root called **pluginTemplate.js**. Fortunately, there is already an ant script which will build our plugin. All you have to do is worry about the plugin file.
You will need to always follow these conventions when creating a jQuery plugin:
- Begin your code with
(function ($) {
var _pe = window.pe || {
fn: {} };
- Specify your plug-in name in
_pe.fn.pluginName. This will be the name of your file. Also the class name you will use to call the plugin is always wet-boew-pluginname - Run the plugin using
_exec: function (elm) { }. - Finally, end the plugin with the following:
window.pe = _pe; return _pe; }(jQuery));
The following is optional:
- Specify any dependencies. These are a series of libraries located in src/js/dependencies. (ex:
depends: (pe.mobile ? [] : ['metadata', 'easytabs', 'equalheights']),) - Include a mobile function if your plugin should run in mobile mode. (ex:
mobile: function (elm) {)
Note 1: You can test your plugin without building the entire project. Simply include the path at the bottom of your html page where the rest of the javascript files are added. Once you see that it works, start the build process.
Note 2: You can still create or add additional plugins that do not depend on the PE object or WET and leverage the $(document).ready(function(), it should not cause a conflict with WET.
The wb_load function (pe.wb_load(options, finished_event)) allows you to execute plugins on unenhanced content (e.g., content that was added to the page after the initial page load). It's useful to developers who want to dynamically add a tabbed interface or a multimedia player after the page has already loaded.
The first parameter is an object with all the options and the second is the event name to use for the event handler (used to determine when loading has finished).
Here are the options that can be included in the options object (all optional) that handle the loading of the plugins, dependencies and polyfills:
- plugins: {"plugin_name1": elms1, "plugin_name2": elms2, ...} - Names of plugins to load and elements to load them on (no longer need to specify dependencies or polyfills separately)
- global: [plugin_name1, plugin_name2, ...] - Names of global plugins to load
- deps: [dependency_name1, dependency_name2, ...] - Names of dependencies to load
- poly: [polyfill_name1, polyfill_name2, ...] - Names of polyfills to load
- checkdom: true/false - Enable/disable checking the DOM for "wet-boew-*" triggers
- polycheckdom: true/false - Enable/disable checking the DOM for elements to polyfill
$(document).on('my-event-name', function () {
... do something ...
});
pe.wb_load({"plugins": {["tabbedinterface": $(".target")]}}, "my-event-name");
To load a polyfill when it's already declared in your plugin, you would just do this:
pe.polyfills.enhance('polyfill_name', objs);
Where polyfill_name is the key in pe.polyfills.polyfill and objs is either a DOM object (preferred) or a jQuery object. For example:
pe.polyfills.enhance('detailssummary', document.getElementsByTagName('details'));
[or]
pe.polyfills.enhance('detailssummary', tblSrcContainer); // where tblSrcContainer is already a jQuery object
Otherwise, to load a polyfill only on request, you would just do this:
$(document).on('my-event-name', function () {
... do something ...
});
pe.wb_load({'datepicker', "my-event-name");
Pour charger un library dépendante, vous pouvez faire ce qui suit:
$(document).on('my-event-name', function () {
... votre code ici ...
});
pe.wb_load({'dep': ['parserTable']}, 'my-event-name');
Target Audience: Intermediate and Advance WET developer
Well, as previously described in the section "Executing Plugins on Unenhanced Content" you would just do this to load a dependency:
$(document).on('my-event-name', function () {
... do something ...
});
pe.wb_load({'dep': ['parserTable']}, 'my-event-name');
The rule is simple, make sure that your make only one call to load the dependency. So the previous code snippet would do the work as long it's not included in a loop.
You wont be noticed of any error until you have two or more call to the "_exec" function in the plugins.
For example, the zebra stripping applied on a complex table require the dependency "parserTable" to complete the styling. If there is only one complex table on the webpage, that are not causing any issue, but if there is more than one complex table that required the zebra stripping can break the rule of make only one call. For reference you can take a look at the issue #508
// 1. Function that would be executed once the dependency is loaded // 2. Check the dependency requirement // 3. Check if your dependency is already loaded, if yes just call it // 4. Check if your already defined a plugin execution stack, if yes just stack it and return // 5. Stack initialization and insertion of the first item // 6. Function Event triggered once the dependency is loaded // 7. Load your dependency
1. Function that would be executed once the dependency is loaded
Create your function at the same level of your "._exec" declaration, but before the "_exec" method.
_pe.fn.yourPluginName = {
type: 'plugin',
fnExecutedOnDependencyLoad: function (elem) {
},
_exec: function (elem) {
}
};
2. Check the dependency requirement
_pe.fn.yourPluginName = {
type: 'plugin',
fnExecutedOnDependencyLoad: function (elem) {
},
_exec: function (elem) {
[...] Put your logic here about if the dependency is required [...]
}
};
3. Check if your dependency is already loaded, if yes just call it
Before to stack each plugin execution call, let check if the dependency is already loaded.
if (_pe.fn.parsertable) {
_pe.fn.yourPluginName.fnExecutedOnDependencyLoad(elem);
return;
}
Replace the "_pe.fn.parsertable" by the function name from the dependency that you would attemps to use later.
4. Check if your already defined a plugin execution stack, if yes just stack it and return
if (_pe.fn.yourPluginName.execStack) {
_pe.fn.yourPluginName.execStack.push(elem);
return;
}
5. Stack initialisation and insertion of the first item
_pe.fn.yourPluginName.execStack = []; _pe.fn.yourPluginName.execStack.push(elem);
6. Function Event triggered once the dependency is loaded
It is here where your stack would be processed one at the time.
$(document).on('my-event-name', function () {
while (_pe.fn.yourPluginName.execStack.length > 0) {
__pe.fn.yourPluginName.fnExecutedOnDependencyLoad(_pe.fn.yourPluginName.execStack.shift());
}
});
7. Load your dependency
pe.wb_load({'dep': ['parserTable']}, 'my-event-name');
The Zebra Stripping plugin have implented this method
SASS is an extension to the CSS format that adds extra feature like variables, nested rules, math, mixins, etc. SASS needs to be converted into CSS when used on the web, so part of the build process involves converting your SASS into CSS usable in your web project. In WET, there are different SASS files which style the website depending upon how it is being viewed. (ex: base-print.scss is for print view while base-ie7.scss includes internet explorer 7 specific styling.)
You can view information about SASS here: http://sass-lang.com/
Compass is a helper library for SASS which is also used in WET. It includes libraries of shared mixins, a package manager to add additional extension libraries, and an executable that can easily convert SASS files into CSS.
To learn more about Compass, visit: http://compass-style.org
When creating new SASS code, make sure to add it in the appropriate directory inside the src folder in the root. Where to add the SASS depends on what you want to do. For example, if you would like to add CSS for your jQuery plugins, you will add your files to src/js/sass.
In order to test your code, you may want to compile it from SASS to CSS prior to building since the build process takes some time. A great tool to do this is Scout, which does not require that you have a working knowledge of Ruby and the command line: http://mhs.github.com/scout-app/
There are a series of different SASS files that are used in the website:
- src/base/sass: The SASS in this folder includes the basic css that is used in any WET site. It is not template dependant; as all templates include these SASS files.
- src/grids/sass: This folder includes SASS used for the grid system.
- src/js/sass: jQuery plugin specific SASS files. The scss files should be seperated into a different file for each plugin.
- src/theme-gcwu-fegc/sass: This folder includes a series of different theme-specific SASS files. The SASS is initially broken up into different files based upon how your website can be viewed. These files are located in the "includes" folder.
The following details the steps for creating a new theme in WET.
In order to create a new theme, you will have to add a folder named after your theme to src. This folder will contain any theme specific components you want to build into your website.
Your new theme should generally follow the theme-gcwu-fegc folder structure which includes folders called images, jquery.mobile, js and sass. In order to remain consistent, and to modify less of the build script, use these naming conventions.
There are a few different things to add/modify when building a new theme. Note: "new-theme" is used below to represent a new theme folder name.
- The build.xml in the root needs to have some additional code to call the build.xml file for your new theme.
- Simply copy + paste the code from the root build.xml under "---Building GCWU Theme---" into that same file.
- Change the comment to reflect the name of your new theme.
- Add your new theme folder name to the directory path:
<ant dir="${src.dir}/new-theme" antfile="build.xml" target="build" inheritAll="false"/> - Add code to clean up your new theme folder under
<target name="clean-css">and<target name="clean">. Just copy paste the code used for another theme and change the path to point to your new theme folder.
<target name="clean-css">
<ant dir="${src.dir}/base" target="clean-css" antfile="build.xml" inheritAll="false"/>
...
<target name="clean">
<ant dir="${src.dir}/base" target="clean" antfile="build.xml" inheritAll="false"/>
...
- The build.xml in your theme folder needs to be created, as well as other build-related files. The easiest way to do this is to copy paste the following from an existing theme, and just edit the files as needed.
- build.properties: Change the build.dir path so that it points to where your theme folder will be located in the build.
- build.xml:
- Change
<project name="new-theme" default="default" basedir=".">to your new theme name.
- folders: images, jquery,mobile, js, sass
- files: build.properties, build.xml, build.tasks.xml, compile.rb
- Edit your SASS and jQuery files for your theme. Use the file names used in existing themes.