Web controls are .NET classes used by the ASP.NET machinery to generate HTML and JavaScript code; they’re the building blocks of web pages. The programming interface they expose is designed to be similar to the Windows Forms controls, although there are many differences because of the more constrained request-response model of the World Wide Web. ASP.NET includes dozens of web controls, from the common Button and TextBox to the powerful GridView, and it’s easy to write new ones yourself.

An important point to note is that some web controls, such as the Panel and Repeater, act as containers that can hold other controls. They enable you to construct a user interface as a tree of controls, with containers providing structure for the text boxes, labels, check boxes, and buttons.

Web controls are put together using a language that is HTML with extensions to allow adding server code and referring to web controls. Files in this language can be pages (with the .ASPX extension), or they can be reusable components called user controls (in ASCX files), which can then be referenced from ASPX pages or other user controls. Both ASPX pages and user controls can have server code either in the same file or in an associated file, called its code file or code-behind. Separating the page and server code is generally cleaner and easier to read, especially if the behavior of the page or control is complicated.

The extensions that make an ASPX page more than HTML include the following:

So an ASP.NET page is a tree of web controls, constructed according to ASPX and ASCX files. Each web control in the tree knows how to convert itself into HTML and JavaScript code to be displayed in a browser. Where does the code-behind associated with pages and user controls fit into the picture?

The server code is used in two ways. The simplest way is that code-behind can provide methods that can be called from code snippets in the page or user control. This technique can be useful for displaying small pieces of text or turning a part of the markup on or off.

The second way is much more central to the power of the ASP.NET framework. When a page is requested and the tree of controls is being built, the system fires a number of different events that your server code can hook into. Some of these events, such as the Page_Load event, are fired every time a request for the page is made; others, such as button clicks or drop-down list selection change events, are only raised when triggered by the user on the other end of the internet. These events provide a tremendous amount of control over how the page structure is created and how the controls in the page are set up. They also make it much simpler (from the developer’s point of view) to handle user interaction in a web environment. Figure 11.1 shows some of the events fired by the server while handling a request.

Figure 11.1. The ASP.NET page lifecycle

Now that you’ve seen a little of what ASP.NET is and what it has to offer, we add IronPython into the mix and use it to create some ASP.NET pages.

Now that you have all the prerequisites, you’re ready to create an IronPython web project by following these steps:

You’ll see the directory structure in the Solution Explorer panel on the right side of the window (figure 11.3).

Figure 11.3. The skeleton web application structure in Visual Web Developer

Now that the site has been created, you can edit the files to add some behavior. Open Default.aspx by double-clicking it in the Solution Explorer. This is the home page of the application—the word default in the filename means that this page will be shown if someone makes a request for the root directory of your web application. As you can see, the markup in the file looks much like Extensible Hypertext Markup Language (XHTML), but note the following two important differences:

A code-behind file stores the code for this specific page; keeping the ASPX markup and code separate makes them easier to maintain.

If you click the Design button at the bottom of the window, you can see that the page body contains an asp:Literal element. Let’s change that—click the literal and delete it, and then drag a Label onto the page from the Toolbox tab on the left. If you change back to source view by clicking the Source button, you can see that the IDE has added the following ASPX code to create a Label in the body of the page:

<asp:Label id="Label1" runat="server" text="Label"></asp:Label>

Let’s break this down into its separate components:

Edit the asp:Label tag to set the Text property to "" instead of the default text Visual Studio has created, and save the file.

The project skeleton has several other things in the directory—which we’ll look at soon; the most important one for now is the Default.aspx.py file, which is the code-behind file for Default.aspx page. Open this file and you’ll see the definition of a function called Page_Load. This function is what the processing machinery calls when the page is first requested; it passes in the page as sender and any event arguments as e. At the moment, it sets the text of the old literal element you removed.

Change the Page_Load function to the following:

def Page_Load(sender, e):
   Label1.Text = "Hello from IronPython"

Make sure that the second line is indented so that it’s the body of the function. Save the file.

Now a little magic: click the Start Debugging button (which looks like a green Play button) in the toolbar. By default, the project isn’t configured for debugging, so Visual Web Developer will ask whether you want the configuration changed—say Yes. Then it will start its built-in development web server on our new project, and launch a browser window navigating to the current page. After a brief wait (and maybe a notification from your firewall software asking whether the web server should be allowed to listen for requests), you should see the Hello from IronPython message you entered in the Page_Load function.

That’s the first step: a basic page generated from IronPython code. Now let’s see how to have the page respond to user input.

At this point you have code in the code-behind file that interacts with a control in the ASPX page. Although this technically is handling an event (the Load event of the Page class), extending the page functionality slightly demonstrates a little more of the power of the ASP.NET system. Let’s add some controls to our page: a text box where users can enter their names and a button that will trigger some processing on the server.

Switch back to editing the ASPX page, and add the following lines at the start of the main <div>, before the Label:

Name:
<asp:TextBox id="TextBox1" runat="server"></asp:TextBox>
<asp:Button id="Button1" runat="server" text="Go!" onclick="Button1_Click"
/><br />

You can add the controls by typing them into the Source view, or by dragging them from the toolbox in either Source or Design view. Change the text on the button to something more interesting—like Click Me or Go!—something with a bit of vim. Add the onclick attribute to the button; this tells ASP.NET to call the function Button1_Click when the button is clicked.

Now edit the code-behind page to have the following function definitions:

def Page_Load(sender, e):
   pass
def Button1_Click(sender, e):
   Label1.Text = "Hello, " + TextBox1.Text

Click the Start Debugging button again; and, after a small pause, you should see a web page with a text box and a button. If you type some text into the text box and click the button, the message Hello, <name you typed> will appear below the text box.

So what’s happening? Here are a few points to think about:

Later on in the chapter, we explore how view-state handling works by making something more complex: an application that can display and edit MultiDoc documents. We reuse the MultiDoc modules you already have to create, load, and save documents. To integrate the modules into the project, we need to look at some of the support infrastructure ASP.NET provides.

For code in our web application to use the classes you’ve already written, you need to be able to import the modules. In the normal Python world, you can make one module available for import by another one in the following three ways:

These approaches all work just as well with IronPython in general; but, in the ASP.NET environment, the first option isn’t available (because the current directory is generally the location of the web server, rather than the directory containing the currently executing page), and the second isn’t useful because, by default, sys.path is empty. Instead, the system provides a special folder called App_Script; any packages and modules stored in this folder will be available for import by any other Python code in the web application. (The third option is still available to you, as you’ll see in section 11.3.2.)

Several other special ASP.NET folders can be added to the project, if they’re needed, by right-clicking the project in Web Developer and selecting the Add ASP.NET Folder option. The most important of these folders is the App_Code folder, which is similar to the App_Script folder but is intended to store C# (or other compiled language) library code. This code will then be available to all modules in the web project, along with the extra feature that the ASP.NET system will automatically detect changes to the files and recompile them when necessary.

Because we want to be able to read and write MultiDoc files, you need to add the modules for those tasks to the web project. To do this, right-click the App_Script folder and select Add Existing Item to add the files model.py, xmldocumentreader.py, documentreader.py, and documentwriter.py from chapter 5 to the project. Once this is done, you’ll be able to use them to read and write MultiDocs from any code-behind page in the web application.

The App_Script folder gives you a place to keep support modules that are used by pages in our project, but it’s really meant for library code that you’ll write specifically for this project; if several projects required the same module, you’d need to copy that Python file to each App_Script folder. A better solution in this situation is to put the module in a different location outside your project, and add that project to the sys.path list.

You could modify sys.path by adding a line in your code-behind files, but you’d need to do so on every ASPX page because you don’t necessarily know which page will be visited first. The Global.py file can help because it provides a way to listen for events that affect the application, no matter which page requested to cause the event.

Looking at the Global.py file, you can see that it contains the following empty event handlers:

In our case, if we want to have extra directories in sys.path, the Application_Start event handler is a good place to add them. Because the MultiDoc modules rely on modules in the Python standard library, you should add the Lib directory to the sys.path with the following change:

def Application_Start():
   import sys
   sys.path.append("C:\Python25\Lib")

(This code assumes that Python is installed in C:Python25; change the path accordingly if not.)

The .NET framework provides a comprehensive, extensible configuration system based on an XML format and a wide range of settings for web projects. The skeleton project we’ve used contains a Web.config file for the project with the configuration for our application. In particular, it includes a number of directives that enable IronPython support in the application. For the moment, you don’t need to change the Web.config file—the default settings are fine for what we’re going to do next.

That’s all the setting-up finished; now we can implement the MultiDoc Viewer using the modules we’ve added to the project.

First, we need to decide how to display a MultiDoc object. Each document is essentially a list of pages—we could display each page in order, but that would be quite different from the tab pages the desktop application uses for display. (It also wouldn’t illustrate some of the details that we want to explore in the ASP.NET system.)

Instead, let’s display a MultiDoc as a list of the titles of all the pages it contains, rendered as links that can be clicked on to display the contents of that page. Then the contents of the selected page will be displayed as a title and body (figure 11.4).

Figure 11.4. Sketch of the page layout for the MultiDoc Viewer

We can convert this sketch into ASPX code piece by piece.

First, create a new web form by copying the webform_template.aspx and webform_template.aspx.py files from the chapter 11 source code. Rename these files to viewer.aspx and viewer.aspx.py respectively. Then edit viewer.aspx and change the CodeFile attribute in the <%@ Page %> directive at the top to point to viewer.aspx.py.^[1]

Now that you have an empty web form, add a table with one row containing two cells to the page. You can do this either using the Design view, by dragging-and-dropping a table from the HTML section of the toolbox and deleting cells and rows as desired, or by typing the HTML in Source view. I (Christian) prefer the latter. The design view often generates messy HTML that’s hard to work with later, and has problems round-tripping more complicated page layouts. It can even break your pages in some cases.

The right-hand side of the page is straightforward: it contains a heading and then two labels for the page title and page body respectively. Initially, the page will display the details of the first page in the document and, when a page link is clicked, will display the details of that page instead. Create these by either dragging two Labels into the right-hand table cell from the toolbox, or typing in the asp:Label tags. Give the Label controls the IDs pageTitle and pageContent, and add some formatting.

You’ll create the list of links on the left-hand side of the page using a Repeater control. The Repeater is a container that repeats the controls in its item template once for each item in its data source list. In our case, you’ll use the list of pages in the MultiDoc as the source, and the item template will contain a LinkButton control. LinkButtons are almost identical to Buttons, except that they’re displayed as hyperlinks in the browser. The full ASPX code for the table is shown in listing 11.1.

<table>
 <tr valign="top">
  <td>
    <b>Pages:</b><br />
    <asp:Repeater id="pageRepeater" runat="server">
     <itemtemplate>
      <asp:LinkButton id="pageLink" runat="server" onclick="pageLink_Click"
     text="<%# title %>" enabled="<%# currentPage != title %>"/><br />
     </itemtemplate>
    </asp:Repeater>
   </td>
   <td>
    <b>Current page</b><br />
    <h2><asp:Label id="pageTitle" runat="server" /></h2>
    <asp:Label id="pageContent" runat="server" /><br />
   </td>
 </tr>
</table>

Look at the asp:Repeater element, which creates the Repeater control. It begins in a way similar to the web controls we’ve already created. The tag name is asp:Repeater, and you give it an id and specify that it runs on the server. Next, in the <itemtemplate> element, you specify the child controls that will be repeated. Inside this is the LinkButton, which has similar attributes to the button created in section 11.2.3—id, runat, onclick, and text—as well as a new attribute, enabled, which controls whether the LinkButton should respond to clicks. The values of the text and enabled attributes are also new—they’re data-binding expressions.

pageRepeater.DataSource = document.pages
pageRepeater.DataBind()

Open the code-behind file, viewer.aspx.py (if you’re editing the ASPX page, you can hit F7), and add the code in listing 11.2.

from documentreader import DocumentReader
multidoc = None # the MultiDoc instance
currentPage = None # the title of the selected page

DOCUMENT_LOCATION = "doc.xml"
def getMultiDoc():
   reader = DocumentReader(Page.MapPath(DOCUMENT_LOCATION))
   return reader.read()

def getPage(multidoc, name):
   matches = [page for page in multidoc.pages if page.title == name]
   if matches:
      return matches[0]
   return None

This code provides the DocumentReader class, initializes the two pieces of state that the page will manage, and defines two simple functions; getMultiDoc uses the DocumentReader class to create a MultiDoc instance (using MapPath to avoid having to specify a full path to the doc.xml file), and getPage finds a page in the MultiDoc by its title (or None if there’s no page with the given title).

The state variables are in the global scope; but, because of the way ASP.NET integrates the code-behind file, they aren’t shared between requests (what you might expect if this were a normal Python module). In this case, storing the state in global variables is similar to the way the state would be managed in C#—they would be instance variables of the page subclass.

Now you need to hook into the ASP.NET page lifecycle to interact with the web controls on the page.

Page Lifecycle

A number of different events are raised for a page and its controls in the processing of a request. (See figure 11.1 for a more comprehensive list.) In this case, you need to handle the following:

• Page_Load event—. Happens when the page is requested, after child controls have been created but before any handling of user input to the page has been done

• Click events—. Are triggered when a user clicks on a LinkButton to select a page of the MultiDoc document

• Page_PreRender event—. Is raised when the system is ready to convert the tree of web controls into HTML to be sent to the browser

Let’s look at the code for each of these events in turn, beginning with Page_Load (listing 11.3).

Example 11.3. MultiDoc Viewer Page_Load handler

def Page_Load(sender, event):
   global multidoc, currentPage
   multidoc = getMultiDoc()
   if not IsPostBack:
      currentPage = multidoc.pages[0].title

The Page_Load handler is automatically hooked up to the event by the ASP.NET machinery. In this listing, the code added to the handler loads the MultiDoc from the XML file; and, if this request isn’t a postback (that is, it’s caused by the user navigating to the page, rather than clicking a LinkButton on the page), it sets the currently selected page title to be the first in the document. (The global statement at the start of the function is required so that the assignments rebind the global variables, rather than shadowing them with local variables.) In listing 11.4, you can see the handler for clicking on page links.

Example 11.4. MultiDoc Viewer pageLink_Click handler

def pageLink_Click(sender, event):
   global currentPage
   currentPage = sender.Text

The handler function defined in this listing is attached to each LinkButton created by the Repeater in the ASPX page. When a user clicks one of the page links, the pageLink_Click function will be called. Because the handler is attached to multiple LinkButtons, you use the sender parameter to work out the title that the user clicked, and store that title in the page state for when you render the page. The PreRender handler that uses the page state is shown in listing 11.5.

Example 11.5. MultiDoc Viewer Page_PreRender handler

def Page_PreRender(sender, event):
   pageRepeater.DataSource = multidoc.pages
   pageRepeater.DataBind()
   selectedPage = getPage(multidoc, currentPage)
   pageTitle.Text = selectedPage.title
   pageContent.Text = selectedPage.text

The PreRender handler in this listing is triggered by ASP.NET when all postback event handling is completed, and allows you to use the page state that you’ve loaded and modified in the other handlers to update the state of the web controls on the page. In the MultiDoc Viewer, you create the page links from the list of pages in the MultiDoc using data binding, and then you put the relevant parts of the selected page into the pageTitle and pageContent controls.

The MultiDoc Viewer is now complete. Hit the Play button, and the page should open in a browser window like figure 11.5.

Figure 11.5. The completed MultiDoc Viewer

You can click the links to view different pages. Try editing the XML file to add some extra pages in the document and see that they appear in the Viewer.

The structure of the code-behind may seem a little indirect at first glance: why not have the pageLink_Click handler set the page title and text itself, rather than setting internal page state and relying on the Page_PreRender handler to update the labels? This approach tends to cause duplication of code. You’d need to cater for the nonpostback situation (when the pageLink_Click handler wouldn’t be called), and populate the pageTitle and pageContent controls in the Page_Load handler. Additionally, in more complicated pages, more actions are available than clicking one of a list of links; keeping track of where you need to update which controls quickly becomes unwieldy. Writing the postback handlers (such as Click or TextChanged) to only update internal page state, and then having the PreRender handler translate that page state into the states of the child controls, is much more manageable when the possible interactions are wider.

You can see this clearly when we extend the MultiDoc Viewer to allow editing of the documents.

It’s entirely possible to swap out the labels for editable text boxes by manipulating a web control’s Controls collection. But it’s often simpler and clearer to do so by hiding the controls you want to remove, and making some other (previously hidden) controls visible. A control that makes this technique especially convenient is the Panel, whose sole purpose is to contain other controls.

Let’s update the ASPX page to do this. Change the right-hand cell of the table to contain the code found in listing 11.6.

<b>Current page</b><br />
<asp:Panel id="viewPanel" runat="server" visible="false">
  <h2><asp:Label id="pageTitle" runat="server" /></h2>
  <asp:Label id="pageContent" runat="server" /><br />
  <asp:Button id="editButton" runat="server" text="Edit this page"
     onclick="editButton_Click" />
</asp:Panel>

The code in this listing wraps the pageTitle and pageContent labels in an asp:Panel element, which has its own ID and adds an Edit button after the labels. The panel will start off hidden (because visible is false). You can show the panel from the code-behind with the following code:

viewPanel.Visible = True

Now you add the Panel containing the controls that you want to display when the page is in edit mode (listing 11.7).

<asp:Panel id="editPanel" runat="server" visible="false">
  <asp:TextBox id="pageTitleTextBox" runat="server" columns="40" /><br />
  <asp:TextBox id="pageContentTextBox" runat="server" columns="40" height="100"
     textmode="multiline" /><br />
  <asp:Button id="cancelButton" runat="server" text="Cancel"
     onclick="cancelButton_Click" />
  <asp:Button id="saveButton" runat="server" text="Save"
     onclick="saveButton_Click" />
</asp:Panel>

With the ASPX code in this listing added, the page now has two sets of controls that you can turn on and off, depending on whether it should be in reading mode or edit mode. The next step is to extend the code-behind page to handle the new controls.

We do need to think about one more thing, though. The original MultiDoc Viewer only has one piece of state that changes: the current page title. When someone clicked a page link and changed that state, you were always given the new value for it (as the text of the LinkButton that was the sender argument to the handler), so you could set up the page correctly. In the MultiDoc Editor, there are now two different pieces of state that can be changed: the current page title, and whether the page is in edit mode. When you receive an Edit button Click event, you aren’t also told what the current page should be. Correspondingly, if you receive a page link Click, you don’t know whether the page should be in edit mode. You need some other way to persist this information from the handling of one page request to the next.

The facility that ASP.NET provides to deal with this problem is called view state.

View state is an important concept in ASP.NET. At the end of processing a request, the state of all the controls on the page is serialized and stored in a hidden form field in the HTML page sent back to the client. When the next request from the client is received, serialized state is reconstituted and set back into the controls before any postback events are raised. (To ensure that the client hasn’t monkeyed with the state it sends back, the framework cryptographically signs the view state and validates it before deserializing it.)

View state is managed automatically for web controls (unless it has been turned off for the control by setting EnableViewState to false), but you need to add some extra state to the process. In a C# web project, you could do this by overriding the SaveViewState and LoadViewState methods to inject the extra state to be saved. Unfortunately, because in IronPython you don’t directly inherit from the ASP.NET Page class, the SaveViewState and LoadViewState methods don’t get called in IronPython pages. To hook into the view state system, you need a little C# to call custom methods in the code. You put a CustomScriptPage class into the App_Code folder in the web project (listing 11.8).

using Microsoft.Web.Scripting.UI;
using Microsoft.Web.Scripting.Util;

public class CustomScriptPage: ScriptPage {
   protected override void LoadViewState(object savedState) {
      DynamicFunction f = this.ScriptTemplateControl.GetFunction("ScriptLoadViewState");
      if (f == null) {
         base.LoadViewState(savedState);
      } else {object baseState = this.ScriptTemplateControl.CallFunction(f, savedState);
         base.LoadViewState(baseState);
      }
   }
   protected override object SaveViewState() {
      DynamicFunction f =this.ScriptTemplateControl.GetFunction("ScriptSaveViewState");

      if (f == null) {
         return base.SaveViewState();
      } else {
         object baseState = base.SaveViewState();
         return this.ScriptTemplateControl.CallFunction(f, baseState);
      }
   }
}

This listing creates a subclass of ScriptPage (the base class of all IronPython ASP.NET pages) that will look up functions called ScriptLoadViewState and ScriptSaveViewState in the script of the page (the Python code, in this case), and delegate to them. You can then tweak the view state objects in the code-behind. To declare that our page should inherit from this class, you need to change the first line of the ASPX page to add the Inherits option.

<%@ Page Language="IronPython" CodeFile="Default.aspx.py"
Inherits="CustomScriptPage" %>

To simplify much of the state management in the page, you can use a minimal page state class to group the pieces of state together into one object. This lets you leave out most of the global statements in event handlers, and makes it easier to work out where the names being used in a section of code are coming from. As you can see in listing 11.9, we’ve decided to call the object containing the page state self, which is a little non-standard, but seems to have the right feel in code using the state. (If this seems wrong, you can happily call it state instead.)

class PageState(object):
   pass
self = PageState()
self.document = None
self.currentPage = None
self.editing = False

Once you have that, you can save and load the page state (listing 11.10).

from System.Web.UI import Pair
import pickle

def ScriptSaveViewState(baseState):
   state = Pair()
   state.First = baseState
   state.Second = pickle.dumps((self.document, self.currentPage,
     self.editing))
   return state
def ScriptLoadViewState(state):
   self.document, self.currentPage, self.editing = pickle.loads(state.Second)
   return state.First

The ASP.NET view state machinery can’t natively serialize Python types, so in this listing the ScriptSaveViewState function creates a Pair. A Pair is a .NET class, a clumsy version of Python’s tuple, which can contain two other objects (as .First and .Second) and can be serialized in the view state. You store the standard page view state in .First, and use the Python serialization module pickle to create a string from a tuple of the three pieces of state you need to preserve. Then, in ScriptLoadViewState, you receive the view state object that ASP.NET has pulled out of the request, deserialize our custom page state tuple from the pair.Second, and return the other half back to the machinery to restore the child control state.

You can piggyback almost anything in the view state in this way, as long as you ensure that the original view state is maintained and that anything you add can be serialized by ASP.NET. (The pickle module is very useful here.) Also, you need to be careful that the functions loading and saving the view state are symmetrical—any change in the way you store your custom state needs to be reflected in how it’s loaded again. One more thing to keep in mind is that the view state is sent to the client in each response, and then back to the server with the subsequent request, so it can’t be used to store large volumes of data.

As well as code for loading and saving the view state of the page, you need to include the code for loading and saving MultiDoc files (listing 11.11).

from documentreader import DocumentReader
from documentwriter import DocumentWriter

DOCUMENT_FILE = "doc.xml"
def getDocument():
   reader = DocumentReader(Page.MapPath(DOCUMENT_FILE))
   return reader.read()
def saveDocument(document):
   writer = DocumentWriter(Page.MapPath(DOCUMENT_FILE))
   writer.write(document)
def getPage(document, name):
   matches = [page for page in document.pages if page.title == name]
   if matches:
      return matches[0]
   return None
def Page_Load(sender, event):
   if not IsPostBack:
      self.document = getDocument()
      self.currentPage = None
      self.editing = False

This listing shows the familiar getDocument and getPage functions and adds the new saveDocument function. It also includes the Page_Load event that determines how the state is initialized in the first request, when IsPostBack is false and no view state is processed.

Because you’re now storing the page state in a wrapper object named self, you need to change the data-binding expression in the ASPX file from currentPage != title to self.currentPage != title.

Next you handle the Page_PreRender event (to display the state of the page), and the postback events for the controls you’ve added: Click events from the page links; the Edit, Save, and Cancel buttons; and the TextChanged events from the title and body text boxes.

To start with, let’s consider how our page’s state should be displayed in the web controls in the Page_PreRender handler (listing 11.12). This handler will be called after all of the click-type postback events in the page’s lifecycle.

def Page_PreRender(sender, event):
   pageRepeater.DataSource = self.document.pages
   pageRepeater.DataBind()
   viewPanel.Visible = self.currentPage and not self.editing
   editPanel.Visible = self.editing

   if self.currentPage:
      selectedPage = getPage(self.document, self.currentPage)
      pageTitle.Text = pageTitleTextBox.Text = selectedPage.title
      pageContent.Text = pageContentTextBox.Text = selectedPage.text

In this listing, the Page_PreRender handler databinds the pageRepeater in the same way as the previous version of the handler (listing 11.5), creating the page links on the left-hand side of the page. Then you decide which (if either) of the right-hand side panels should be displayed. Finally, if you have a current page, you populate the labels and text boxes for the view and edit panels.

The other event handlers, in listing 11.13, are simple—they merely record the user input in the page state, and rely on the PreRender handler to display the page in a consistent way, whereas the view state is managed by the Save and Load functions. Using the PageState holder class means that the handlers don’t need any global statements cluttering up the code.

def pageLink_Click(sender, event):
   self.currentPage = sender.Text

def editButton_Click(sender, event):
   self.editing = True

def cancelButton_Click(sender, event):
   self.editing = False
   # throw away any changes that have been made
   self.document = getDocument()

def saveButton_Click(sender, event):
   saveDocument(self.document)
   self.editing = False

def pageTitleTextBox_TextChanged(sender, event):
   selectedPage = getPage(self.document, self.currentPage)
   selectedPage.title = self.currentPage = pageTitleTextBox.Text

def pageContentTextBox_TextChanged(sender, event):
   selectedPage = getPage(self.document, self.currentPage)
   selectedPage.text = pageContentTextBox.Text

In this listing, the TextChanged event handlers for the page title and page body are interesting because typing into the text box doesn’t trigger a postback by default (although it can if the text box has AutoPostBack set to True). In this case, when ASP.NET restores the view state and then applies the posted data to the controls, it detects that the text has changed and raises the event. You use this notification to update the document before the Save button or page link Click events are raised.

Try running the MultiDoc Editor now. You can view the different pages and click the Edit button to change page titles and bodies. When you click the Save button, the file is updated on the disk.

Beware, though! If you enter anything that looks like HTML tags, you’ll see a rather alarming error page, beginning with the message: A potentially dangerous Request. Form value was detected from the client. This is a security feature in ASP.NET intended to prevent cross-site scripting (XSS) attacks, but it’s so heavy-handed that the idea must be to shock developers into crafting a strategy to handle HTML in user input, after turning the validation off. Obviously, how you prevent cross-site scripting depends on the extent to which you trust the user—in this case, it’s you. To turn off validation, edit the Web.config file, and add validateRequest="false" to the <pages/> element.

At this point, the MultiDoc Editor is largely complete. The only significant feature missing is a New Page button; adding this is straightforward with the techniques used so far, so we don’t cover it here. Another consideration that we haven’t examined is how to handle two people editing the document at the same time. Obviously, the second person to save changes will overwrite those of the first. You can handle this in many ways—for example, using a timestamp on the document or a locking protocol. A robust solution might involve a database; we discuss using the .NET facilities to communicate with databases in the next chapter.

You can see an example of what the Editor looks like in figure 11.6.

Figure 11.6. Editing a MultiDoc page in a browser

Now that you have a MultiDoc Editor, you might want to use it within a larger website. In ASP.NET, packaging up the ASPX and Python code is done by creating a user control. The control can then be embedded into ASPX pages or other user controls, in almost the same way as you’d incorporate standard web controls. Let’s look at what changes you need to make the Editor reusable.

When implementing the Editor as a web page, our page inherited from a custom subclass of ScriptPage. User controls can also inherit from a custom base class, but it needs to be a subclass of ScriptUserControl. You can create a custom subclass to forward the view state handling methods with the code in listing 11.14.

using Microsoft.Web.Scripting.UI;
using Microsoft.Web.Scripting.Util;

public class CustomScriptUserControl: ScriptUserControl {
   protected override void LoadViewState(object savedState) {
      ScriptTemplateControl stc = (this as
     IScriptTemplateControl).ScriptTemplateControl;
      DynamicFunction f = stc.GetFunction("ScriptLoadViewState");
      if (f == null) {
         base.LoadViewState(savedState);
      } else {
         object baseState = stc.CallFunction(f, savedState);
         base.LoadViewState(baseState);
      }
}
 protected override object SaveViewState() {
    ScriptTemplateControl stc = (this as
   IScriptTemplateControl).ScriptTemplateControl;
    DynamicFunction f = stc.GetFunction("ScriptSaveViewState");
    if (f == null) {
       return base.SaveViewState();
    } else {
       object baseState = base.SaveViewState();
       return stc.CallFunction(f, baseState);
    }
  }
}

This code is almost the same as the CustomScriptPage definition in listing 11.8, with one odd difference—for some reason, ScriptUserControl doesn’t expose a .ScriptTemplateControl directly. Instead, it explicitly implements the property on the IScriptTemplateControl interface; the definition of the property looks something like this:

public virtual ScriptTemplateControl
IScriptTemplateControl.ScriptTemplateControl { get {...} }

You need to cast this ScriptUserControl to an IScriptTemplateControl before you can get hold of the .ScriptTemplateControl property. Ordinarily, you’d use explicit interface implementation to disambiguate when inheriting from two interfaces that expose the same member and you’d need to provide different implementations, but that doesn’t seem to be the situation here.

At this point in the section, you could be forgiven for thinking that wrapping up a page into a user control is rather a lot of work. Forwarding the view state between the C# and Python code of a control is definitely one part of the ASP.NET–IronPython integration that’s still fairly nasty, and it’s something that we expect will be fixed in future versions as the IronPython support matures. In any case, the classes you have work well now, so you can simply reuse the classes when you need to manage view state from IronPython pages and user controls, without worrying too much about the fact that they’re workarounds for gaps in the system.

Once the CustomScriptUserControl class is in App_Code, you can change the user control to inherit from it by adding Inherits="CustomScriptUserControl" to the Control directive in MultiDocEditor.ascx. The view state handling in the code-behind file will now be called by the ASP.NET machinery, and the MultiDocEditor user control will work! The only problem is that it’s not reusable except in a very basic sense: you can put it on different pages, or several instances on one page, but each instance will be editing the same file. That isn’t especially useful. You need to be able to specify which file a particular editor should be using. You can do this by adding a filename parameter to the control.

If you were implementing the user control in C#, you’d expose a filename parameter by creating a property on the class. In IronPython, you make the filename settable in essentially the same way, although it doesn’t use the Python property system (because the IronPython code-behind file doesn’t directly define a class). Add the functions in listing 11.15 to the MultiDocEditor code-behind file to give the user control a Filename property.

def GetFilename():
   return self.filename
def SetFilename(filename):
   self.filename = filename

These functions will be called by the ASP.NET infrastructure when you specify the filename in ASPX pages that embed the control. (The case of the attribute needs to match the name of the getter and setter functions.)

<ipia:multidoceditor id="editor" runat="server" Filename="doc.xml" />

Alternatively, the getter and setter functions can be called from the code of the container page.

def Page_Load(sender, e):
   editor.SetFilename("doc.xml")

To complete the process, the code-behind needs a few changes to make use of the filename that’s passed in. First, the filename needs to be added to the page state.

self = PageState()
self.filename = None
self.document = None
self.currentPage = None
self.editing = False

Then it needs to be loaded and saved with the view state.

def ScriptLoadViewState(state):
   self.filename, self.document, self.currentPage, self.editing = pickle.loads(state.Second)
   return state.First

def ScriptSaveViewState(baseState):
   state = Pair()
   state.First = baseState
   state.Second = pickle.dumps((self.filename, self.document,
     self.currentPage, self.editing))
   return state

And of course it should be used to load and save the MultiDoc file:

def getDocument():
   reader = DocumentReader(Page.MapPath(self.filename ))
   return reader.read()

def saveDocument(document):
   writer = DocumentWriter(Page.MapPath(self.filename ))
   writer.write(document)

With these changes, the MultiDoc Editor user control is complete! You can view the container page in the browser and edit the document as you could in the case of the single web page. You can add another <ipia:multidoceditor/> element to the container page, specify a different MultiDoc file, and edit the two documents independently in one page. Or you can even create another user control that wraps the MultiDocEditor control—perhaps one that lists the MultiDoc files in a directory in a drop-down list, and allows the user to select which file to edit. As you can see, user controls provide a flexible mechanism for packaging and reusing components when constructing a web application.