Telstra Online Standards Effective Date of this standard

Copyright Telstra Corporation 2011 0118/08/2011

Telstra Online Standards

jQuery
Document Owners: Daniel Martin, Online Content Administrator
Joris de Beer, Online Content Administrator
Telstra Digital

Last Revision: 1830/08/2011

Table of Contents
TELSTRA ONLINE STANDARDS ......................................................................................................................1

JQUERY ........................................................................................................................................ 1

TABLE OF CONTENTS ..................................................................................................................... 1

INTRODUCTION............................................................................................................................. 2

THE STANDARD ............................................................................................................................. 2

AVAILABILITY ...........................................................................................................................................2
IMPLEMENTATION...................................................................................................................................32
File Locations .................................................................................................................................32
Implementation Code .....................................................................................................................32
USAGE ...................................................................................................................................................3
Naming Conventions ......................................................................................................................43
Best Practices .................................................................................................................................54
Minify Scripts (Compression) ..........................................................................................................54
DEVELOPMENT REQUIREMENTS .................................................................................................................65
PLUG-INS ..............................................................................................................................................65
Global Plug-ins ...............................................................................................................................65
Page Specific Plug-ins .......................................................................................................................6
In-House Development ...................................................................................................................76
jQuery UI ..........................................................................................................................................7
CSS .................................................................................................................................................87
GLOBAL.JS COMMANDS ............................................................................................................................87
CONTRIBUTION EFFORTS ............................................................................................................................8

PROCESSES ................................................................................................................................. 98

UPDATING JQUERY VERSION .....................................................................................................................98

ADDING A NEW PLUGIN .............................................................................................................................9
UPDATING THE COMMON FUNCTIONS .......................................................................................................109
File name: t.com jQuery Standards v1.7.1.doc Page
1 of 10
This hardcopy version of the standard may be out of date. For the latest copy of this standard visit
http://www.telstra.com.au/standards
 Telstra Online Standards Effective Date of this standard

Copyright Telstra Corporation 2011 0118/08/2011

TELSTRA ONLINE STANDARDS ......................................................................................................................1

JQUERY ........................................................................................................................................ 1

TABLE OF CONTENTS ..................................................................................................................... 1

INTRODUCTION............................................................................................................................. 2

THE STANDARD ............................................................................................................................. 2

AVAILABILITY ...........................................................................................................................................2
IMPLEMENTATION.....................................................................................................................................2
File Locations ...................................................................................................................................2
Implementation Code .......................................................................................................................2
USAGE ...................................................................................................................................................3
Naming Conventions ........................................................................................................................3
Best Practices ...................................................................................................................................4
Minify Scripts (Compression) ............................................................................................................4
DEVELOPMENT REQUIREMENTS ...................................................................................................................5
PLUG-INS ................................................................................................................................................5
Approved & Available.......................................................................................................................5
In-House Development .....................................................................................................................6
jQuery UI ..........................................................................................................................................6
CSS ...................................................................................................................................................7
GLOBAL.JS COMMANDS ..............................................................................................................................7
CONTRIBUTION EFFORTS ............................................................................................................................7

PROCESSES ................................................................................................................................... 8

UPDATING JQUERY VERSION .......................................................................................................................8

ADDING A NEW PLUGIN .............................................................................................................................8
UPDATING THE COMMON FUNCTIONS ...........................................................................................................9

Introduction

This standard provides the guidelines for the use of jQuery in Telstras web
environment. The document covers how jQuery is implemented, how you can take
advantage of it, what plug-ins are available and defines processes for future activities.

Please check the Wiki page for the most up to date information.

The Standard
Availability
- jQuery is available in UCM on a Template by Template basis. Current
templates that include jQuery are:
File name: t.com jQuery Standards v1.7.1.doc Page
2 of 10
This hardcopy version of the standard may be out of date. For the latest copy of this standard visit
http://www.telstra.com.au/standards
 Telstra Online Standards Effective Date of this standard

Copyright Telstra Corporation 2011 0118/08/2011

1. PT_T.COM_TEMPLATE_GENERIC

For Flat Files, each file will require its own inclusion of the jQuery core. See
Implementation Flat Files for more details.

The current version of jQuery to be used throughout Telstra.com is 1.4.4

Implementation

File Locations
Core Directories:

/global/javascript/jquery/
/global/javascript/jquery/plugins/
/global/javascript/jquery/plugins-src/

- All jQuery approved plug-ins are located in:

/global/javascript/jquery/plugins/
- If a plug-in has been minified, the uncompressed source code will be
located in:
/global/javascript/jquery/plugins-src/
- If a plug-in has an associated image files, the files will be located at:
/global/javascript/jquery/plugins/pluginname/images/
Note: You may need to update the plugins references to accommodate this
folder structure

Implementation Code
To implement jQuery into a template or page, use the following command

UCM Template

<!--$jquerypath = HttpRelativeWebRoot & "global/javascript/jquery"-->

<script type="text/javascript" src="<!--$jquerypath-->/jquery-
core.min.js"></script>

Flat File Page

<script type=text/javascript src=/global/javascript/jquery/jquery-

core.min.js></script>

If you experience namespace issues when implementing jQuery, you can attempt
to load it in no-conflict mode as per the jQuery documentation.

Usage

File name: t.com jQuery Standards v1.7.1.doc Page

3 of 10
This hardcopy version of the standard may be out of date. For the latest copy of this standard visit
http://www.telstra.com.au/standards
 Telstra Online Standards Effective Date of this standard

Copyright Telstra Corporation 2011 0118/08/2011

As all the minimum files needed to take advantage of the jQuery framework have been
loaded for you, you are able to add commands on the fly.

For jQuery code to work it must be within a document/window ready function. This
ensures that the jQuery code has fully loaded before trying to execute the command.
This command where possible, should be placed towards the end of the page code,
just before the closing </body> tag, not within the <head> section.

To achieve this, use a script block similar to the one below:

<script type=text/javascript>
$(document).ready( function() {
// Code Goes Here
});
</script>

OR the shorthand method:

<script type=text/javascript>
$(function() {
// Code Goes Here
});
</script>

Please refer to the jQuery documentation for detailed instructions on using jQuery and
its functions: docs.jquery.com

Naming Conventions

As JavaScript is not a strict language it is possible for people to have significantly

different development methods. To ensure that all of Telstras scripts are fairly similar,
please abide by the conventions stated below.
Upper and lower case can be used in naming in the following format
firstWordSecondWord for the definitions of variables and functions.
Numbers must not be used in file function and variable names.
Functions must be named uniquely to identify their purpose, and exist
inside the $ jQuery object
Variables must be named to allow easy identification of purpose. Variables
should be scoped inside the $ jQuery object.
For further recommended conventions, please visit:
http://javascript.crockford.com/code.html

File name: t.com jQuery Standards v1.7.1.doc Page

4 of 10
This hardcopy version of the standard may be out of date. For the latest copy of this standard visit
http://www.telstra.com.au/standards
 Telstra Online Standards Effective Date of this standard

Copyright Telstra Corporation 2011 0118/08/2011

Best Practices

To ensure that all Telstras scripts are professionally written and perform to their
maximum capability, adopt the following practices whenever creating jQuery scripts.

Place all scripts and codes at the base of the page, just before the closing
body tag
Appropriate tab indenting and line breaks must be used to enhance the
readability of code. This also applies when chaining many events to one
selector.
Be specific with your selectors. The more defined a selector is the less that
jQuery has to navigate the DOM to locate it and the less chance there is for
conflicts on other pages.
Avoid over-looping through the DOM use functions such as .find() and
.each() only when needed on specified selectors
Convert functions into a plug-in where appropriate and provide options.
Refer to the jQuery documentation for plug-in development
Avoid using multiple JavaScript files where possible more scripts will mean
more HTTP requests and larger page load.
Comment your functions with a short description of the purpose the serve
Ensure that your scripts do not reduce the accessibility of the site. Using
display: none; to hide content before jQuery loads is bad practice, if
unavoidable then use a <noscript> tag to change this property to visible.
jQuery commands are always slower than native JavaScript if there is a
native command available use it in preference to jQuery. Eg:
$(this).attr(id) is slower than this.id

Minify Scripts (Compression)

Currently our files are not minified as standard. Though this practice is highly
recommended it is imperative that both versions of the file are accessible for future
updates, please see File Locations for details on where to store the files.

To minify your code, visit http://fmarcia.info/jsmin/test.html Select Conservative for

the Level of minification This is the best method as it will compress the code but
does not alter all line breaks.
There are cautions to be aware of when minifying your code. When you use minfication
there is the chance that some of your code may not work as expected. It is your
responsibility to test your code after minification to verify that it all still works
accordingly.
This technique was created by Douglas Crockford and is widely used throughout the
web. For more information, visit: http://www.crockford.com/javascript/jsmin.html

File name: t.com jQuery Standards v1.7.1.doc Page

5 of 10
This hardcopy version of the standard may be out of date. For the latest copy of this standard visit
http://www.telstra.com.au/standards
 Telstra Online Standards Effective Date of this standard

Copyright Telstra Corporation 2011 0118/08/2011

Development Requirements

You are responsible for validating that code works with version 1.4.4 of the
jQuery JavaScript library.
You must not link to an additional copy (newer or older) of the jQuery
library. If you are working on a page that has a reference to any jQuery
library, please remove it as this reference is no longer required.
You must not link to external plugins. Only the features listed within the
Plug-ins section are available. If you wish to make use of a new plug in,
please follow the process to submit a plug-in for a team discussion and
investigation before proceeding.

Plug-ins

Approved & AvailableGlobal Plug-ins

The following features will be available on a page by page basis by including a
standardised plug-in file and associated CSS:

Lightbox (OrangeBox)
(/global/javascript/jquery/plugins/orangebox/orangebox.min.js
, /global/javascript/jquery/pluginss/orangebox/orangebox.css)
Accordion (/global/javascript/jquery/plugins/accordion/jquery-
contentAccordion.js)
Feature Banner (Under Review)
(/global/javascript/plugins/featurebanner/jquery-
featureBanner.js,
/global/javascript/jquery/plugins/featurebanner/featureBanner.cs
s)
Tabs
(/global/javascript/plugins/labeloverlay/jquery.tabs.js)
Label Overlay
(/global/javascript/plugins/labeloverlay/jquery-labeloverlay-
0.0.1.min.js)

For more information on each jQuery plug-in including initialisation, structure and
options, please see the corresponding WIKI page.
Custom plug-ins must contain a commented link to their respective WIKI page and
their appropriate Copyright disclaimer

There are many advantages to restricting the plugins used on Telstra.com, please see
the Adding a Plugin section for further details.

Con formato: Ttulo 3

Page Specific Plug-ins

File name: t.com jQuery Standards v1.7.1.doc Page

6 of 10
This hardcopy version of the standard may be out of date. For the latest copy of this standard visit
http://www.telstra.com.au/standards
 Telstra Online Standards Effective Date of this standard

Copyright Telstra Corporation 2011 0118/08/2011

If the page requires a particular plug-in to be loaded and it is not required globally, an
exception can be made.
Page specific plug-ins should be stored within the appropriate folder for the site.
Example if a plug-in was required for a page within the home-phones section of the
site, it should be stored in a directory similar to:
Con formato: Fuente:
/home-phone/javascript/plugin/ (Predeterminado) Courier New, Color
de fuente: Color personalizado(RGB(12
8,100,162))
The same guidelines apply to the implementation of the plug-in, the main Con formato: Sangra: Primera lnea:
considerations are: 1.27 cm

- Page load impact Con formato: Esquema numerado +

Nivel: 1 + Estilo de numeracin: Vieta
- Code quality and assurance + Alineacin: 1.27 cm + Tabulacin
- Plug-in maintenance despus de: 1.27 cm + Sangra: 1.27
cm
- Accessibility requirements

InIn-House Development
Cases that require a plug-in to be developed are usually when there is functionality
that needs to be used on multiple pages in multiple sitelets. There is no need to
develop a plug-in for page specific functionality.

Always consult the jQuery Documentation when developing a plug-in, below

is a shortlist of their recommended practices:
Always wrap your plug-in in (function( $ ){ // plug-in goes here })( jQuery
);
Don't redundantly wrap the this keyword in the immediate scope of your
plug-in's function
Unless you're returning an intrinsic value from your plug-in, always have
your plug-ins function return the 'this' keyword to maintain chainability.
Rather than requiring a lengthy amount of arguments, pass your plug-in
settings in an object literal that can be extended over the plug-ins defaults.
Don't clutter the jQuery.fn object with more than one namespace per plug-
in.
Always namespace your methods, events and data.

Please see the Adding a new Plug-in within the Processes section of this document to
submit your plug-in for release.

jQuery UI

Currently there is no support for jQuery UI or its add-ons. This is primarily due to the
page weight this would add and the CSS methods employed by the UI addition.

jQuery UI additions rely heavily on a style sheet created via the jQuery Themeroller
(http://jqueryui.com/themeroller/) which is incompatible with the way Telstra.com has
been developed.

File name: t.com jQuery Standards v1.7.1.doc Page

7 of 10
This hardcopy version of the standard may be out of date. For the latest copy of this standard visit
http://www.telstra.com.au/standards
 Telstra Online Standards Effective Date of this standard

Copyright Telstra Corporation 2011 0118/08/2011

If you require a UI function that does not exist in an alternative external plug-in or
cannot be created in-house there may be the case for a page specific exception. Please
consult with your Manager before proceeding with any UI implementations.

CSS

It is understood that there is usually the requirement to develop a CSS sheet to layout
the content of the jQuery plug-in. To handle this effectively you may store your CSS
file under the following rules.

Store CSS files in: /global/javascript/jquery/plugins/pluginname/

Store Images in: /global/javascript/jquery/plugins/pluginname/images/

Must be named to match the plug-in e.g.: jquery-featureBanner.js will have

a CSS named jquery-featureBanner.css
Must NOT use !important tags as this sheet must be able to be overwritten
by page specific styles
Try to make the style as flexible as possible avoid fixed widths and
heights, allow a wrapping element or image sizes to control this
Be very specific with your classes to avoid namespace collisions within CSS
e.g.:
o .contentWrap {} is BAD
o .featureBanner .contentWrap {} is GOOD
o .featureBanner .fb-contentWrap {} is BETTER

global.js Commands

Location: /global/javascript/global.js

The common file is designed to hold functions that are implemented site-wide. This is
not for page specific functions and additions should be carefully considered as the size
of this file will add weight to every page load.

The types of functions within this file are style elements (such as table striping), hover
effects and possibly pop-up events. Please see the Updating the Common functions in
the Processes section of this document.

Detailed lists of commands are available on the Telstra Wiki.

Contribution Efforts

File name: t.com jQuery Standards v1.7.1.doc Page

8 of 10
This hardcopy version of the standard may be out of date. For the latest copy of this standard visit
http://www.telstra.com.au/standards
 Telstra Online Standards Effective Date of this standard

Copyright Telstra Corporation 2011 0118/08/2011

There are no current contribution-friendly methods available to create jQuery

commands on the fly.

This is a purposeful decision designed to increase the consistency and implementation

of jQuery across the site. If you see a need to create a contributable method for
adding jQuery commands to UCM please discuss this with your Manager.

Processes

Updating jQuery Version

Upgrading the minified jQuery file to a newer version is an involved process that
requires extensive test.
First, read the change log provided for the new version, note any significant
changes and backward compatibility issues.
If there are any obvious issues or changes that will affect existing scripts
you must determine what, where and how these will be dealt with.
Inform the team that the update is going to occur this will allow other
members to flag any issues they may be aware of and also indicates that
they may start to use the new features soon.
The update process will follow the standard End to End Project Delivery
Process and require an Impact assessment to be completed and approved
before any testing can occur
Create a test case on the DEV server. Before updating the file site wide on
the DEV server it is suggested that you create a standalone page that
custom calls the new jQuery version. This will allow you to do extensive
testing on all plug-ins and common scripts to ensure normal functionality.
With initial testing complete you are now able to update the master jQuery
file on the UAT server. Once this has occurred, you must conduct an in-
depth test of all existing pages to ensure that there is no conflict or
unexpected behaviours.
With the DEV testing completed you may now co-ordinate with your
configuration manager to release the file across to Production.
You have now updated the jQuery core file.

Adding a new Plugin

As there are hundreds of existing plug-ins and it is possible to create your own within
minutes, strict processes have been created to ensure that plug-ins abide by Telstra
Standards.
Primary concerns are:
Duplicated functionality

File name: t.com jQuery Standards v1.7.1.doc Page

9 of 10
This hardcopy version of the standard may be out of date. For the latest copy of this standard visit
http://www.telstra.com.au/standards
 Telstra Online Standards Effective Date of this standard

Copyright Telstra Corporation 2011 0118/08/2011

Accessibility
Page load & cache
Consistent with the feel of the site
Add to user experience

If you wish to have either your own plug-in or an external plug-in added to the
approved plug-in list, you must follow the steps below:

Develop an example page that illustrates the functionality

Make the plug-in available for code review and inspection by other team
members

Updating the Common functions

The common functions file is for commands that are used site wide, this file is not for
page specific functions.
If your function has limited purpose, first consider adding it to a sitelet specific or page
specific file first.

If your function does have an applicable use site wide then you may follow the
following steps to incorporate it into the common js file.

1. First you must do an investigation into the effects your function may have
some questions for consideration:
a. Is it class specific and does that class apply site wide?
b. Are there other functions that may collide with it?
c. Do all sitelets perform the expected way?
2. Complete an Impact Assessment and distribute out to developers for peer
review. The IA must contain the exact function you would like to add.
3. Once feedback has been received and any appropriate adjustments have
been made you can start the End to End Project Delivery Process.
4. First, complete your work in the Dev environment and move it through to
UAT
5. Thoroughly test your function not just on the page / section you are
concentrating on but all sites and various page. You may need to add
content to UAT to test your changes
6. Confirm with your Configuration Manager that it is okay to move from UAT
to production
7. Upon approval you may migrate the change to Production.

File name: t.com jQuery Standards v1.7.1.doc Page

10 of 10
This hardcopy version of the standard may be out of date. For the latest copy of this standard visit
http://www.telstra.com.au/standards