# The Evisa Site

Leo
Examples
Tutorial
An explanation of how the evisa.com language applications were programmed using Leo.
evisa language leo literate programming
8/3/2002
draft
C:\testtt\Leo\Examples\Tutorials\B4 The Evisa Site\
<p>This tutorial shows how using Leo greatly simplified the development of the language learning applications online at <a href="http://www.evisa.com">evisa.com</a>, a multilingual information and learning site. (The .leo file containing the code for this application is not available for download, but the leo outline is illustrated via screenshots).</p><p>First, let's take a look at how the site application works, and then we'll examine the .leo file that contains all of the code for the language applications.</p>

[Empty]

# evisa.com

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Here is the <a href="http://www.evisa.com/e/lang.htm">Language Learning Site</a>&#160;at evisa.com. This site contains a number of vocabulary drills and activities for numerous languages.</p>

pic02.png

# Here is the Language Learning Site

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<ol> <li/>In addition to being able to study words, students can take tests, and save their scores. <li/>Saving a score however, requires registration (free). </ol>

pic03.png

# Tests and scores

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Let's choose the <strong>French</strong> language option.</p>

pic04.png

# Choose French

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>This brings us to the French Language Study page. There are two activities available from this page:</p><ol> <li/><strong>Word Study:</strong> a set of language study activities. <li/><strong>My Flashcards:</strong> a page that shows word flashcards saved by the registered user who is viewing the page. </ol>

pic05.png

# French Language Study page.

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Let's take a look at the <strong>Word Study</strong> activities.</p>

pic06.png

# Word Study activities.

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>This presents us with a list of word groups. The word groups are marked with red, green or yellow icons to show which groups have been already been reviewed by the currently logged on user.</p><p>We'll choose the <strong>colors</strong> group.</p>

pic07.png

# Word groups.

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>This brings us to the activity page for the <strong>colors</strong> word group.</p><p>Let's take a look at <strong>View and Listen</strong>.</p>

pic08.png

# Activity page

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>This brings us to a list of colors in French and English. Also, the Merlin character (Microsoft Agent) appears. We can click on any French word to hear Merlin speak the word.</p>

pic09.png

# Word list

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>To try another activity, we can go back to the activity menu, or click on the indicated mark to go to the next activity.</p>

pic10.png

# To try another activity...

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>This brings us to the <strong>Flashcards</strong> page. This presents the colors as a series of cards. Clicking on a card shows the word in the target language. We can also choose to save cards to the<strong> My Flashcards</strong> page, for which we saw a link earlier.</p>

pic11.png

# Flashcards page.

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Now we'll go to the next activity.</p>

pic12.png

# Next activity.

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>This brings us to the <strong>Concentration</strong> card game page. This allows one or two players to play a game of Concentration with the vocabulary items.</p>

pic13.png

# Concentration

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>The final activity is the <strong>Match Test</strong> . This is pairing test. You click on a word first in one column, then in the next. If the words match, you get a point. If you get a score of 100%, and you are logged in, and your pass is automatically saved, so that you can see it later in the <strong>My Achievement</strong> page, to which we saw a link earlier.</p>

pic14.png

# Match Test

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Both the <strong>Match Test</strong> and the <strong>Concentration </strong>card game allow you to configure the sound effects for right and wrong answers.</p>

pic15.png

# Sound effects

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Now, let's consider what will be involved in programming an application like the one we've just seen.</p><ul> <li/>The same words appear in many pages, so we'll want a database of words with the pages inserted into each page as required. <li/>This needs to work with a number of languages, so the database will need tables for each language paired with English. </ul><p>We'll need at least:</p><ul> <li/>A program or module to do the basic word activities <li/>A program or module for registration. This involves sending the user an email and&#160;the user then clicks on a link to register. <li/>A program to display personal achievement. <li/>A program for the My Flashcards page. </ul>

[Empty]

# What does programming this app involve

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>The application is going to be getting words from the database, and inserting them into each activity page. That means we need a template for each of these pages. But evisa.com doesn't just serve an English user base. It also has a complete subsite for Japanese users, with sites for other languages planned. So we'll need templates for other languages.</p><p>We'll need to plan the database, so we'll something explaining that. We need to make input pages for the database so that administrators can add words. Since we want the database to be as fast as possible for reads, we want to make some utilities to replace certain database functions that could slow down reads, such as data constraints.</p><p>Most of the activity pages have a lot of javascript, some of which could be put in a libary file, and all of which should be organized.</p>

[Empty]

# Application components

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Hmmm... this is&#160;starting to look like a major project. Each task is simple, but keeping everything organized so that the job can be done as fast as possible even when the the project is being stopped and started over a period of time... that could be a challenge.</p><p>Here's a look at the .leo file that is actually behind the all of the code.</p>

pic18.png

# Large number of details

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>An explanation of some of the nodes:</p><ul> <li/>phonics: This is a program that allows an administrator to build the phonetic library used for showing the pronunciation of English words. <li/>SQL: utilities for maintaining the word database. <li/>words: the application that takes care of the server side of all of the Language Learning Activities <li/>recorders: small programs that record user information such as passed tests and flashcards <li/>flashbox: the application for My Flashbox </ul><p>&#160;</p>

[Empty]

# The Leo file

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>In addition to the actual code for all programs, the outline contains just about every other useful piece of information for the site programmer, including how to log on to the MySQL database, and other documentation of third party programs used.</p>

[Empty]

# Code plus extra info

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Let's take a look at the words.cgi program, because that does most of the work.</p><p>Here we see the node for the words.cgi program expanded. Already the basic structure of the program is apparent. We are going to get/initialize the cgi object, check to see what browser is being used, connect to the database and retrieve words, and then make the outgoing page.</p>

pic21.png

# Let's take a look at the words.cgi node

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>In the text for the &lt;&lt; make page &gt;&gt; section, we can see that one of the included sections is for &lt;&lt; word groups &gt;&gt;. Looking down the outline, we can see that the word groups page consists of</p><ul> <li/>getting data from the database. <li/>filling in the template with the data. </ul><p>If we were debugging the word groups page, we would have jumped right to this spot in the code immediately. No hunting around trying to remember how the program works and where things are.</p>

pic22.png

# Word groups section

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>In this screen we are viewing the text for the word groups: fill in the template node. All of the code for this node fits in one screen.</p><p>You might note that the code displayed in this node text does not stand on its own. So, to debug it, you might need to look at another node. This code and outline could have been written otherwise, but writing it in this way is not a great impediment, since finding the code that this node is dependent on is just as easy as it was to find this node itself. When you are using literate programming techniques, the whole program simply becomes much easier to navigate.</p>

pic23.png

# Code for word groups

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>We've seen that the program is retrieving these words, and then filling in a template. Where are these templates? In Leo, of course. Underneath the words node, we find the templates node.</p>

pic24.png

# The templates

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Since evisa.com has viewers in langages other than English, there must be a separate set of templates for each language.</p>

pic25.png

# Other languages

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Here we can see that all of the templates are embedded in the .leo file.</p>

pic26.png

# All the templates for English

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>Let's take a look at the speak.htm template. This is the file that will display the page where the user can click to hear a word spoken. The words.cgi program simply fills words into this template. The template contains all of the code for making the page speak in the browser.</p><p>The way it does this, is to embed an ActiveX object for a Microsoft Agent, and then call that ActiveX object with Javascript.&#160;Here the code for embedding the ActiveX objects is shown. Since these same objects are embedded in the same page for each language, this is a clone node. All of the other templates that use this code simply share this node.</p>

pic27.png

# The speak.htm template.

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com
<p>This has been a brief overview of the language applications at evisa.com. As you can see, all of the code, and virtually all of the supplemental information needed to work on this application is embedded in one Leo file. The programmer opens the file, works on the application in Leo, and then tangles the output code files.</p><p>This application was written in Perl, because of Perl's excellent text manipulation capability and speed of development. There is no scalability problem with this kind of Perl application, because it runs with Apache mod_perl. While programming this application in certain other languages would have given it <strong>some</strong> more inherent structure, this would sacrifice some of the advantages of development with Perl. In fact, one can think of Leo doing for the supposed "structure" problem of Perl what mod_perl has done for the scalability problem. The application as written in Leo simply could not be easier to understand.</p><p>Are there alternatives to this approach? There are more than fifty files embedded in this one Leo file. Every file is grouped and described not just with a name, but with whatever additional information is necessary. Some files are sharing components, i.e. nodes. </p><p>This application was developed on a very constrained budget and simply would not have been possible without Leo.</p>

[Empty]

# This has been a brief overview ...

Joe Orr
[Empty]
Copyright 2002 All Rights Reserved
orrj@jserv.com