Developing for WET - nschonni/wet-boew GitHub Wiki
- Pull requests are welcome. Please make sure your changes are to the latest code and limit the commit range to just the files you intended to change (to avoid conflicts).
- New components should be added in a feature-* branch (e.g., feature-lightbox).
- Licensing for all new components and supporting code must be compatible with the MIT license used by WET.
- New plugins should use pluginTemplate.js as the basis for the JavaScript code.
- Include the WET terms and conditions comment block in all text-based source files that fall under Crown Copyright.
-
Validate your HTML markup. Markup should be well-formed HTML5.
- To test for well-formed markup, validate with an XHTML5 preset and a checkmark next to "Be lax about HTTP Content-Type".
-
Validate your CSS with the following changes to the default settings:
- Profile: CSS level 3
- Vendor extensions: Warnings
-
Validate your JavaScript code with the following change to the default settings:
- Warn - When code is not in strict mode: false
- Optimize your JavaScript, CSS and HTML code
- Formatting recommendations:
- Indent with tabs using the K&R indenting style
- Use single quotes for strings in JavaScript (so unescaped double quotes can be used for attributes in HTML output)
- Supported browsers (should be tested against):
- Browser test baseline - YUI Graded Browser Support (excluding IE6)
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.
The "build.xml" file is the main build script and sits on the root. "Build" is the final build folder, "demos" includes sample web pages and the "src" folder has the initial source files. The "build" folder also includes some other build components, including ruby scripts which are responsible for SASS to CSS conversion. The "src" folder includes a series of sub folders with their own build scripts.
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 "Environment Variables" window where the ANT_Home environment variable is 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.
The ant script being run using 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. See the Ant Proxy manual http://ant.apache.org/manual/proxy.html for further information.
The first way to get Ant to work through the proxy is by using the "autoproxy" flag at the command line
ant -autoproxy
If the "autoproxy" flag doesn't work, you should try manually setting your proxy information in the ANT_OPTS environmental variable.
- 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. Note that the below versions may change, you may verify the versions required in https://github.com/wet-boew/wet-boew/blob/master/build/build-tasks.properties
2. Create the folder build/lib/jruby-compiled and copy the gems inside
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");
To load a dependency, you would just do this:
$(document).on('my-event-name', function () {
... do something ...
});
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 web page, 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 attempts 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 initialization 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 implanted 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.