Developing Ajax Applications using EWD and Python Tutorial: Part 2 Chapter 1: A Logon Form Introduction This second part of our tutorial on developing Ajax applications using EWD and Python will carry on from where the first part left off. If you haven't read part one, you should do so first before attempting this part of the tutorial, as it will assume you already understand the key EWD concepts that were introduced in part 1. A Simple Ajax Login Form Many EWD applications are secure ones where users must identify themselves by logging on, so this part of the tutorial focuses on building a simple logon form using EWD's Ajax techniques. This will introduce several important EWD concepts, in particular how data is passed from the browser to the Python back-end where it can be validated, and how EWD's Session is automatically linked to HTML forms. We'll start by first designing a Container Page for this exercise. As you'll discover, a Container Page can be an almost empty shell that gets progressively built up over time into as complex a page as you like. Create a file named logondemo.ewd containing the following text and save it in the tutorial directory: <ewd:config isfirstpage="true"> <html> <head> <title>ewd Python Tutorial: Logon Demo</title> <script language="javascript"> PYDEMO = {} ; PYDEMO.getLogonForm = function(){ ewd.ajaxrequest("logonform","content"); }; </script> </head> <body onload="pydemo.getlogonform()"> <div id="header"> <h3>ewd Python Tutorial: Logon Demo</h3> </div> <div id="content" /> </body> </html> 1
Now create a file named logonform.ewd containing the following text and again save it in the tutorial directory: <ewd:config isfirstpage="false" pagetype="ajax"> <div> <form method="post" action="ewd"> <table border="0"> <tr> <td>username: </td> <td> <input type="text" name="username" value="*" /> </td> </tr> <tr> <td>password: </td> <td> <input type="password" name="password" /> </td> </tr> <tr> <td colspan="2"> <input type="submit" name="submit" value="logon" ajax="true" action="py:tutorial.testlogon" nextpage="loggedon" targetid="content"/> </td> </tr> </table> </form> </div> Finally create a file named loggedon.ewd containing the following text and again save it in the tutorial directory: <ewd:config isfirstpage="false" pagetype="ajax"> <div> Welcome <?= #username?>! You have successfully logged on. </div> Now compile these pages. For example, using the GT.M shell: ewd@mdb:/$ cd /usr/local/gtm/ewd ewd@mdb:/usr/local/gtm/ewd$ $gtm GTM>d compileall^%zewdapi("tutorial") /usr/ewdapps/tutorial/ewdajaxerror.ewd /usr/ewdapps/tutorial/ewdajaxerrorredirect.ewd /usr/ewdapps/tutorial/ewderrorredirect.ewd /usr/ewdapps/tutorial/loggedon.ewd /usr/ewdapps/tutorial/logondemo.ewd /usr/ewdapps/tutorial/logonform.ewd GTM> 2
Next we'll add a Python function to the tutorial.py module that we created in Part 1: def testlogon(sessid): username = ewd.getsessionvalue("username",sessid) password = ewd.getsessionvalue("password",sessid) if username <> "demouser": return "Invalid username" if password <> "secret": return "Invalid password" return "" Remember, this module should be saved in the /usr/local/gtm/ewd directory and should have the following line at the top: import ewd OK we should now be ready to try out this application using the URL: http://[ipaddress]/ewd/tutorial/logondemo.ewd where [ipaddress] is the IP address or domain name allocated to your M/DB Appliance. You should see the logon form in the browser: Try clicking the Logon button without entering anything in the Username and Password fields. You should get an alert: 3
Click OK on the alert window and now enter the correct username (demouser) and click the Logon button (ie leaving the password blank). You should get a different alert: Finally put in the correct password (secret) into the Password field and click the Logon button and you should see the following: The form has disappeared and had been replaced by a greeting showing the username. Let's now take a look in more detail at how this worked. 4
Chapter 2: Anatomy of the Logon Example EWD URLs First let's take a look at that URL that we used to run the application: http://[ipaddress]/ewd/tutorial/logondemo.ewd In order to start any EWD application, you use a URL with the following structure: http://[ipaddress]/ewd/[applicationname]/[pagename].ewd The application name is the same as the name of the directory in which the EWD pages reside, in this case tutorial. You can have as many EWD applications as you want, and each one is represented by a subdirectory of what is termed the Application Root Directory. In the M/DB Appliance, the Application Root Directory is pre-defined for you as /usr/ewdapps. The page name must be the name of an EWD page that is defined in its <ewd:config> tag as a FirstPage. Only FirstPages can be accessed by an untokenised URL, and when invoked, a new EWD session will start. The Container Page We asked to start the tutorial application using the logondemo page which is the Container page for this application. As such it's a complete HTML page with an <html>, <head> and <body> tag. If you look at the source EWD logondemo.ewd page, you'll see a number of features: in the <body> section there are two <div> placeholder tags with id's of header and content respectively. The header div contains a bold text title, but the content div is empty. The <body> tag includes an onload event handler. This will fire when this Container Page is fully loaded into the browser The onload event handler is described in the <script> tag in the <head> section. Throughout this tutorial I'll be defining event handlers and other Javascript function as methods belonging to a Javascript object named PYDEMO. This is recommended practice as it ensures that your Javascript functions are uniquely namespaced and are unlikely to clash with any other third-party ones that you might use. At the top of the <script> tag is the declaration that instantiates PYDEMO as a new, empty object: PYDEMO = {} ; Once instantiated, we can add methods and properties to this object whenever we want. The onload Event Handler PYDEMO.getLogonForm() makes an asynchronous request via the browser's XMLHttpRequest object (XHR) to fetch a fragment named logonform that 5
will be targetted into the tag whose id is content. So, when this Container Page is loaded into the browser, it immediately fetches the fragment containing the logon form and it appears inside the content div. If you look at the browser's URL location field, it is still pointing at the one we used to fetch the Container page. As far as the browser is concerned, the page in the browser is still the same one it started with, but its contents have been dynamically changed by EWD's Ajax functionality. The Logon Form Fragment Now let's look at the Fragment that contains our logon form: logonform.ewd, in particular the following features: apart from the <ewd:config> tag, the entire fragment contents are wrapped in a single outer <div> tag. A fragment's contents should always be contained within a single outer tag. <div> or <span> tags are good benign ones to use. In our example, we could have actually used the <form>..</form> tag as the outer wrapper. The <form> tag has two attributes: method= post and action= ewd. You should always include these two attributes. The action attribute tells EWD's compiler to process the form contents and apply its built-in form automation functionality. The Username <input> tag includes a special value of *. The purpose of this will described later. The two <input> tags in our form each have a name attribute. Each form element in an EWD form must have either a name or id attribute. It is not recommended that you define both an id and a name: just define one or the other. EWD's compiler will add the missing one using the value you defined for the other. So EWD will automatically add an id attribute to our two <input> tags with a value of username and attribute respectively. The submit button includes several special EWD-specific attributes: ajax= true tells the compiler to process the submission of this form through the XHR and return a fragment rather than swapping the Container Page out action= py:tutorial.testlogon instructs EWD to invoke the named Action Script, in this case a Python function testlogon() from the tutorial.py module, when the submit button is clicked. nextpage= loggedon instructs EWD to fetch the fragment named loggedon.ewd if the Action Script above completes without error targetid= content instructs EWD to replace the innerhtml of the tag whose id is content with the contents of the fragment loggedon.ewd. This submit button syntax with the action and nextpage attributes is unique to EWD and provides an intuitive and quick mechanism of describing the key steps that apply to every HTML form used anywhere in web applications: what back-end method to invoke to process the submitted form what page or fragment to return if the method runs to completion without error The compiler converts these attributes to the run-time code and syntax needed to make these steps work. This is a great example of how EWD allows you to forget the complexities of how form 6
processing actually works and just focus on what you want to do instead. It also makes it dead easy to make a form with multiple submit buttons, with each button running a different back-end method (action) and returning a different fragment (nextpage). Every other web development technology makes the task of form handling a tedious, error-prone, non-intuitive and complex process, yet form submission is something you need to do numerous times throughout your web applications. So when this form fragment gets fetched into the container page, the form is rendered and the user can now enter his/her logon details. Now let's examine what happens when they click that Submit button. EWD Form/Session Mapping and The Action Script Our form had two <input> tags, each with a name (and an automatically added id) attribute with values of username and password respectively. When you click the submit button, EWD automatically saves these form field values in the EWD Session, so in our example it will automatically create two EWD Session variables, named username and password respectfully, ie it uses the value of the name/id attribute as the name of the EWD Session variable. The productivity that this simple piece of Session automation adds to EWD is quite surprising: yet again when you start using EWD you'll wonder why all other frameworks make such a meal of form field processing. By the time EWD invokes your Action Script, it will already have saved the submitted form values into the EWD Session, so the first thing your Action Script will usually do is get hold of those Session values. That's exactly what our Python function does: username = ewd.getsessionvalue("username",sessid) password = ewd.getsessionvalue("password",sessid) Note that the name of the EWD Session variables is case-sensitive, based on the name as specified in the name/id attributes of the form field tags. Now that we've got the username and password, the Action Script's task of validating the logon credentials can be carried out. In this simple initial example Action Script, we've just hard-coded a single valid username/password pair of demouser/secret. In a real-world example, we'd check the values against some kind of user authentication file or database. However, this simple example clearly demonstrates the next piece of automation that is built-in to EWD: if the function returns a non-null value, it signifies to EWD that a validation error has occurred, and the returned string is used as the text within a Javascript alert window. So if the username isn't demouser, an alert will pop up saying Invalid username ; if the username is OK but the password isn't secret, an alert will pop up saying Invalid password. Only if the correct username/password combination is entered will the Python function return a null value. Note that this alert behaviour is fixed behaviour in EWD. If you want to control error/warning alerting in some other way, you can easily do it, but you'll have to write/design the mechanism yourself: your Python function would always return a null value in this case to prevent the automatic generation of a Javascript alert. 7
Note also that when a non-null value was returned by the Action Script, the nextpage attribute was ignored. EWD will only fetch the nextpage fragment if the Action Script returns a null value. Note also that the action attribute is optional: a submit button does not need to have an Action Script associated with it. If an Action Script is not defined, then EWD will always fetch the fragment indicated by the nextpage attribute. The NextPage Fragment If the Action Script returns a null value, EWD will now fetch the nextpage fragment and target its contents as defined by the targetid attribute. In our example, the targetid is content which was the same tag into which the form fragment was targetted. The result is that the form disappears and is replaced by the contents of the fragment named loggedon.ewd. Notice one last thing: loggedon.ewd included the following markup: Welcome <?= #username?>! You have successfully logged on. #username is a reference to an EWD Session variable named username. What this example is demonstrating is that once created, an EWD Session variable is available for use in any subsequent page in the user's session. The EWD Session variable username was created automatically by EWD when the logon form was submitted, so we can now use it in this fragment using the syntax shown. If you were to use the EWD portal application ewdmgr, you'd be able to examine the EWD Session contents for our demo example. You'll be able to see the submitted values of username and password: 8
The value= * Attribute Just one last thing to cover in this part of the tutorial: what was that value= * attribute in the username field all about? ie: <input type="text" name="username" value="*" /> It's actually a short-hand for: <input type="text" name="username" value="<?= #username?>" /> In our example it's somewhat superfluous, but in many Ajax applications you'll want to bring back an instance of a form into the container page and pre-populate it with the same values that the user submitted in the original instance. There's nothing more annoying for a user to get a form back and be forced to re-enter all the values again. Pre-populating forms is another thing that most other web application frameworks manage to turn into a surprisingly complex and non-intuitive process, yet it's one of the commonest things you'll need to do. In EWD, because the previously submitted values are sitting in the Session, they can be redisplayed very simply, and if it's a text field, just use the value= * attribute and if a value is available in the EWD Session, EWD will automatically display it. Simple as that! Conclusions This concludes Part 2 of our EWD Python tutorial. You've now seen how EWD automates and simplifies the task of defining forms and linking them to a Python back-end when the contents can be evaluated. You've also seen how EWD automatically saves the contents of your forms into the EWD Session where the values will persist for the lifetime of the user's session. In our logon form we just used a text and password field, but HTML includes other form field types including radio buttons, checkboxes, select tags and textarea fields. In the next part we'll examine how EWD handles these other form field types and simplifies and automates their use. We'll also look at the other role of an Action Script: saving data back into a database. 9