Flexible Dialog Development Guide

Sample Application

The sample application has been kept clean so it can be used as a template for your own project. The FlexibleDialog control has been placed in the Site.Master Master page where it's accessible to all pages in the application. It relies on the AjaxControlToolkit and its scripts which have also been added to the project. Under the Application tab in project properties, change the default namespace and assembly name to suit your needs and then you will be ready to create dialog forms of your own.

Script Setup

The FlexibleDialog control requires the AjaxControlToolkit's ToolkitScriptManager for managing its scripts including: jQuery, Microsoft Script Loader (start.js), MicrosoftAjax.js, and MicrosoftAjaxWebForms.js. In order to take advantage of the Script Loader, the latter two files need to be replaced with those found in the AjaxControlToolkit. For an example of how to do this, refer to the ToolkitScriptManager declaration in the Site.Master Master file of the sample application.

Two additional files (ExtendedControls.js and ScriptDefinitions.js) are included which instruct the Script Loader which script files need to be downloaded to the browser and when. The requirements for each AjaxControlToolkit behavior are contained in ExtendedControls.js and the requirements for the custom scripts and behaviors utilized by the sample dialog forms are contained in ScriptDefinitions.js.

The scripts added by the ToolkitScriptManager (with the exception of ScriptDefinitions.js) can all be found in the May 2011 release of the AjaxControlToolkit. We recommend you copy the entire ScriptOutput directory to your application for easy setup and future reference and need.

Navigation

Each form can have any number of links that connect them to each other. The FlexibleDialog handles the navigation for you automatically as long as you add the "dialog-action" attribute and its definition to whatever HTML element you want to use as a link (typically a hyperlink or button).

Each form hosted by the FlexibleDialog can be served by any combination of web service, service method, and context key. The dialog-action attribute provides these settings and instructs the FlexibleDialog where to get its next form from.

The dialog-action attribute only needs to supply the delta between the current form's settings and the next form's settings. For example, when navigating to a form served by the same web service and service method as the current form, simply add dialog-action="{'contextKey': 'insertContextHere'}" to the desired navigation element.

In the worst case scenario, the next form will be coming from another web service, in which case all three settings are required as such: dialog-action="{'servicePath': 'AjaxService.svc', 'serviceMethod': 'GetFormContent', 'contextKey': 'insertContextHere'}".

Persistence

When navigation to a new form, the state of the previous form is saved by the FlexibleDialog. Returning to a form will repopulate the data that was present at the time the user navigated away from the form last. The elements supported by this data persistence include input (type text), textarea, and select.

Scripting

In order to bring a loaded form alive, an accompanied behavior script is required since normal post and get operations are not possible since it would refresh the entire page (which is what you do not want in a Ajax application). The responsibility of the main form behavior script is to orchestrate the form as needed and communicate any data back to a Web service for further processing. This behavior will be initialized and disposed with each form load and unload respectively. It may refer other scripts and create other behaviors as needed.

The main behavior script for a form must be specified using the dialog-behaviors expando attribute on the outer <div> tag which wraps the form content. The value for this attribute is a json array containing the necessary information for creating each behavior. For example, the dialog-behaviors value for the Login sample form is "{'name': 'LoginBehavior', 'type': SCS.LoginBehavior}". The properties for the objects in this array are: name, type, properties, events, and references. Name and type are required and most likely are the only two properties you will ever need to set. Internally they map to the parameters of the Sys.Component.Create ($create) method to create the behavior once it's dependencies have been downloaded to the browser. The name property is not used by the Create method and instead is used by the script loader as a reference point for determining dependencies.

Scripts for each form also need to be registered with the script loader (start.js) by calling the Sys.loader.defineScripts method when the dialog markup is first sent to the browser (before any forms can be loaded). The defineScripts methods informs the script loader what scripts need to be downloaded to the browser in order for the active form to operate. When a new form is loaded, the dialog-behaviors attribute tells the script loader what behaviors are required. The script loader then determines what scripts are needed and downloads them according to the information provided to it through the defineScripts method. When all the required scripts are downloaded, the initialize method for each behavior will be called allowing you to perform the setup required by your form.

Styling

The FlexibleDialog control can be styled by assigning a CSS class to the control's CssClass property. This class is added to the root element of the control's markup and is used as a starting point for applying style to the areas within the dialog. The recommending styling practice is place all common dialog style information into your main style sheet, and for each form loaded by the dialog, provide a separate style sheet which will be lazy loaded along with the form.

As mentioned above, the common dialog styling should be added to your main style sheet. This style sheet needs to be present in the <head> tag whenever the FlexibleDialog is to be displayed. Style sheets for each loaded form must be associated with the form through the dialog-data expand attribute, which is added to the form's containing <div> tag. The dialog-data attribute value is a set of settings in json format that can be used to update the current state of the FlexibleDialog. To download a style sheet to the browser for any given form, the "styleURl" property must be set in the attribute value. For example, dialog-data="{'styleUrl': 'membership/login.css'}".

The dialog-data attribute definition also provides a means to change the CSS class (or classes) assigned to the root element of the FlexibleDialog. For example, dialog-data="{'className': 'dialog loginDialog', 'styleUrl': 'membership/login.css'}". This definition will not only download a style sheet for the form, but will also add the loginDialog class to the already present dialog class on the control's root element. This allows you to style the entire dialog's content and not just the form content. A common need for this feature involves loading a new form which is larger than the previous form. By placing the form class with its own height and width settings after the common class, the height and width settings in the common class will be overwritten with the new form settings.

Software Requirements

The supplied runtime binary and source code are compiled using Visual Studio 2010 and require the .NET 4.0 framework. In addition, jQuery and the AjaxControlToolkit are also required at runtime and the Ajax Minifier is required to compile the source code. The sample Login, Forgot Password, and Register dialog forms require the Validity jQuery validation plug-in and some of the AjaxControlToolkit scripts.

Last edited Oct 2, 2011 at 3:47 PM by wdavidsen, version 1

Comments

No comments yet.