Introduction:

kääntää is a web application built on top of the Django web framework. It allows view, edit and create their own translations of words into various languages. The web application can be found here: http://kaanta.pioverpi.net/

Note: The documentation below was a part of our design document that was a part of the assignment submission, so parts of it won’t make sense because it assumes you’re looking at the code

Usage

The basic functionality is as follows:

• if you are not registered and logged in, you can view translations and translation details by clicking on words
• if you are registered, you can:
  • double click on words to edit them
  • add new translation words
  • add new languages
  • change a translation’s rating when you view translation details (i.e. in the popup when you click on a word)

Design

The Kääntää project is divided into two Django applications: accounts and core.  accounts handles all security-related tasks, while core handles the presentation and processing of the translation tables.

accounts

The accounts application uses the built-in django.contrib.auth application to handle user authentication, registration, session creation, and other related tasks.

The accounts application has a set of customized templates that is passed through to the relevant django.contrib.auth view in urls.py.  The only view that we implement ourselves is the register view.

Although we don’t have any Models in the accounts application, you’ll notice that there is an empty models.py file.  This is done to work around a Django bug that prevents the execution of unit tests on applications that do not have a models.py file (description here).

core

The core application handles the logic behind displaying and updating both the translation tables and the translation information.

The core model manages the information about the languages used (Languages), the translation information (Translations), and meta-information about each translation (Translation_Data).  A full database schema can be found in the Database Scheme section below.

The home view and the translationData views serve up HTML pages that display the Kääntää home page and the translation information.  The translationData page is REST-like in the sense that it takes a formatted url  translationData/[root_word]-[translated word]/ and serves up an HTML page with information on the specific (root_word, translated word) pair.

addLanguage, addTranslations, updateCell, and updateRating are views that handle POST requests to modify information about the translations models.  These views return a JSON response object that serve to notify the client whether or not the operation was successful.  The response object is follows this format:  {success: True/False}

Template Composition

The composition of a webpage in Kääntää is a little tricky and deserves some explanation.  For the sake of brevity, home page will be used as an example; but most of the other pages in Kääntää follow the same template composition.

The home page is constructed using a combination of three templates: 

1. base.html

Base templates are stored in the CSC309/templates/base_templates folder.  Whereas accounts and core have their own templates, the base templates are stored outside of the application folders because they are used across both accounts and core.

base.html is very basic page that acts as the foundation for all Kääntää pages.  base.html sets the page’s title and displays the h1 header that is seen on pages all over Kääntää.

2. base_security.html/base_nosecurity.html

Either one of base_security.html or base_nosecurity.html will extend base.html.  The template used will depend on whether or not a user is logged in.  If the user is logged in, then base_security.html will be used along with extra js files that will allow users to edit table information.

3. datatable.html

Finally, datatable.html is included in the base_security.html/base_nosecurity.html template. Datatable.html handles the construction of the main translation table.

You can refer to diagram below for an illustrated view of how the templates are composed.

AJAX

There are four places where AJAX is used.

Editing a Cell

Editing a cell can be done by double-clicking on a cell.  When the user presses ENTER on the textbox, a POST request will be sent to upadateCell/.  This makes the page more responsive and lets the user edit multiple translations without a page refresh.

Add Translation

Adding a translation can be done by clicking the Add Translation button below the table.  The operation is very similar to the edit cell operation. In A2, the completion of the action would send a POST to updateCell/.  However, we felt that the operations were distinct enough to be separated into a separate view.  Adding a translation will now POST to addTranslation/ instead.  Again, AJAX is used here so that the user can continue editing and adding languages without a page refresh

Add Language

Add Translations will make a POST request to addLanguage/ when the user clicks submit.  This is used so that the user can still view the translations while the server is processing the request.  A  spinning loading image will show up beside the submit button while the operation is still going on.  The page will still have to refresh due to a limitation of the DataTables plugin.

Update Rating

Users can “vote” on a translation’s rating in the translation information popup.  In A2 the star ranking would be overridden; but the current implementation now takes the averages of all rating submissions.  When a user clicks on a star, they are essentially submitting their ranking of the translation.  The ranking is POST-ed to updateRating/.

We use AJAX here so that the user can submit ratings while still being able to read information about the particular translation (because once it refreshes the page will be gone and he’ll have to re-click it).

Plugins

Due to time restrictions, the project relies on a lot of external Javascript libraries.  Because of this, the YSlow Firefox plugin gives the Kääntää application a speed grade of D.  Given more time, packages like django-compress could compress and minify our javascript and css files to increase transaction speeds.

Limitations of DataTables

DataTables is a nice JQuery plugin that implements many of the required features from A1 and 2.  It implements sorting, zebra striping, pagination, search, etc.  One of the downsides of the plugin is that it does not support overflow/underflowed rows and columns, and it does not support the addition of columns.

To deal with the overflow/underflow problem, blank entries must be created in the database whenever a new language or translation is added.  For example, if Kääntää supports {English (lang_id = 0), French (lang_id = 1), German (lang_id = 2)}, the addition of the translation for “Car” would create entries (Car, 1, “”) and (Car, 2, “”).  Similarly, if we add a new language Finnish (lang_id = 3), we would need to create a new entry in Translations for each unique root_word x: (x, 3, “”).  This is problematic for a sufficiently large database because it creates an explosion of dummy data in the database.

To work around the lack of support for dynamic columns, Kääntää is forced to do a full page refresh whenever a new language is added. This is a potentially slow operation because of the high number of database writes required and the slow speed of the site due to the lack of compression

Libraries/Modules Used:

Javscript, CSS, and images are stored in the project folder site_media/

Javascript:

• JQuery v1.4.1
• DataTables v1.6
• FancyBox v1.3.0
• Star Rating v3.2.0

CSS:

• Blueprint CSS v0.9.1

Django:

• django.contrib.auth
• django.contrib.admin (required, or else unit tests will complain)

Database Schema:

The application has three tables: Languages, Translations and Translation_Data.  The tables are described below, along with some sample entries.

Language

Lang  (CHAR)	lang_id (INTEGER)
English	1
French	2

Translations

Root_word   (CHAR)	Lang_id  (INTEGER)	Translated_word  (CHAR)
Car	2	Voiture

Translation_Data

Root_word  (CHAR)	Word (CHAR)	Edit_author (CHAR)	Edit_time (DATE)	Rating (FLOAT)
Car	Voiture	User1	10/10/2010 10:30:30	2.34