general specifications

1. Constraints

The components, Activities, iReader, iWriter and Resources will be embedded into the website, and therefore must be done with the same constraints that the website itself.

They must be compatible with the following browsers and devices:

Desktop Internet Explorer 9+, Firefox 11+, Chrome 17+, Safari 5+
Mobile Default browser Galaxy S3/S4, Chrome for Android 4.0+, Safari for iOS 4+

About the responsive GUI: the responsive layout of the website is done already, the 3rd party components will be embedded into the content of some pages, such as the iWriter page ( http://old.proofing.idm.fr/iwriter/).

The only constraint is that the new modules are not fixed in width, so that the content is visible for desktop, tablet and mobile screen's resolutions without having to scroll horizontally.

2. Access and upload resources

The website is accessible at the following address:

To upload the package, please use the FTP with provided credentials. See below for the ftp server host:

  • Host of the Ftp server: old.proofing.idm.fr

The iWriter module will be emebedded into "/templates-main/iwriter/home.html", and will be visible at http://old.proofing.idm.fr/iwriter/. Other resources must be uploaded to the appropriate directory in "/assets-main/" (depending of the type of the resource: image, javascript file etc).

3. Which files can be modified?

Please do not modify the existing files, at the exception of the following HTML pages, in which you can include your modules

Following are the files which can be modified:

  • /activities/home.html
  • /ireader/home.html
  • /iwriter/home.html
  • /resources/home.html

some useful velocity functions

1. To make dynamic links

At IDM we use a Velocity macro to generate absolute URLs of any page of the website.
That will allow developpers to generate dynamic links.
Here are some examples:

Velocity macro call Result
#skLicensedUrl('/') http://www.oxfordlearnersdictionaries.com/
#skLicensedUrl('/about/') http://www.oxfordlearnersdictionaries.com/about/
#skLicensedUrl('/mywordlist/home.html') http://www.oxfordlearnersdictionaries.com/mywordlist/home.html

To get the root path of the website, please use:

#skLicensedUrl('/')

2. To get dictionary codes

The website can host many dictionaries (or even non-dictionary data-sets).
To use them you need their internal code. Here are the dictionaries that are currently available on the website:

Dictionary code Dictionary label
englishOxford Advanced Learner's Dictionary
american_englishOxford Advanced American Dictionary

To get dynamically the code of the dictionary used, please call this velocity function : $services.configuration.getAutocompleteDictionaries()
It returns an array which contains dictionary codes

How to make your design responsive?

There are 2 files that you should use in order to make your pages responsive:

Css File : http://www.oxfordlearnersdictionaries.com/external/styles/responsive.css
JavaScript File : http://www.oxfordlearnersdictionaries.com/external/scripts/responsive.js

We have 4 differents screen sizes:

HD : width > 1220px
DESKTOP : 928px < width < 1220px
TABLET : 762px <width < 928px
SMARTPHONE : width < 762px

the JavaScript file detects the size of the browser and refreshes the page when we modify its size

the Css file handles the position of each blocs depending on the screen resolution

how to use the file api?

IDM has developed an API that allows you to upload/retrieve files to/from a bucket on Amazon S3.
Below are listed the different operations that can be done with this so-called "File API".

We propose that you use the JavaScript interface named "FileApiService" (defined in tools.js) instead of requesting the API directly.

1. get a file/folder information

To get information about a file or a folder, we need to request the amazon bucket.
Therefore ajax will be used. The response of the server is a Json file

getHttp(pathname, callbackFunction)
  • returns : Array,
  • parameters :
    • pathname: String
    • callback function: function which is called once the ajax request is over
        FileApiService.prototype.getHttp = function(pathname, cb){
            $.ajax({
                 url : pathname,
                 type : 'GET',
                 async : false,
                 success : function() {
                     console.log("Get ok");
                 },
                 complete : function() {
                     console.log("Get complete.");
                 },
                 error : function(data) {
                     console.log("ERROR in get :");
                    $.each($.parseJSON(data), function(item, value) {
                        $.each(value, function(i, object) {
                            $.each(object, function(subI, subObject) {
                                 console.log(subI + "=" + subObject);
                             });
                         });
                     });
                 }
            }).done(function(data) {
                cb(data);
            });
        }
    

the main point of the ajax function is the url: "/fileapi/v1/info/USER_ID"

  • the sub url : 'fileapi/v1' should be there to trigger our controller for the request
  • 'info' for retrieving the information about the following user directory
  • USER_ID is the name of the folder we want to retrieve information from

the output of the ajax request: toReturn is a json object array

here is an example of how to iterate over it:

        for(var i = 0; i < toReturn.length; i++){
            var filename = toReturn[i][0]
            var filesize = toReturn[i][1]
            var fileLastModified= toReturn[i][2]
        }
    

2. get a file

We can get the file directly from the bucket if it does not need to be pre-processed before using it. Such as for image files

        <img style="width:100px;" 
            src="http://www.oxfordlearnersdictionaries.com/fileapi/v1/file/<filename>" />
    

If we need to process the file, we have to use Ajax.

Here is an example of getting a Json file from the bucket

function getJson(pathname, cb, jsonpCb)
  • returns : Json object,
  • parameters :
    • pathname: String
    • cb: callback function
    • jsonpCb: String, name of the jsonpCallback
        FileApiService.prototype.getJson = function (pathname, cb, jsonpCb){
            jsonpCb = (jsonpCb==null)?"jsonpCallbackFunction":jsonpCb;
            $.ajax({
                type:'GET',
                url: pathname,
                dataType: 'jsonp',
                jsonp: false,
                jsonpCallback: jsonpCb,
                crossDomain:true,
                success: function(){
                    console.log("get JSON success");
                },
                error:function(){
                    console.log("ajax error");
                }
            }).done(function(data){
                cb(data);
            });
        }
    

Note: In order to make the application cross-domain and works on every common browser, please don't forget these lines in the Ajax call

        dataType: 'jsonp',
        jsonp: false,
        jsonpCallback: jsonpCall,
        crossDomain:true,
    

3. upload a file

function fileUpload(pathname, file, cb)
  • returns : Boolean, true if the file has been uploaded correctly ; false otherwise
  • parameters :
    • pathname: String
    • file: File
    • cb: callback function
        FileApiService.prototype.fileUpload = function(pathname, file, cb) {
            var fd = new FormData();
            fd.append("file", file);
            fd.append("redirect", true);
        
            $.ajax({
                url : pathname,
                type : 'POST',
                method : 'PUT',
                cache : false,
                data : fd,
                // Options to tell jQuery not to process data or worry about content-type.
                cache : false,
                contentType : false,
                processData : false,
                crossDomain : true,
                success : function() {
                    console.log("Upload ok");
                    cb(true);
                },
                complete : function() {
                    console.log("upload complete.");
                },
                error : function(res) {
                    console.log("ERROR in upload " + res);
                    cb(false);
                }
            });
        }
    

This Ajax call is linked to a form which allows the user to supply the file to upload

        <form name="apiUploadForm" enctype="multipart/form-data">
            <input type="file" id="file" name="file" size="10" />
            <input type="button" data-id="buttonUpload" 
                    id="buttonUpload" value="Upload" />
        </form>
    

4. delete a file

function httpDel(pathname, cb)
  • returns : Boolean, true if the file has been deleted correctly ; false otherwise
  • parameters :
    • pathname: String
    • cb: callback function
        FileApiService.prototype.httpDel = function(pathname, cb) {
            $.ajax({
                url : pathname,
                type : 'DELETE',
                success : function() {
                    console.log("Deletion ok");
                    cb(true);
                },
                complete : function() {
                    console.log("Deletion complete.");
                },
                error : function(data) {
                    console.log("ERROR in deletion " + data);
                    cb(false);
                }
            });
        }