Using jQuery Impromptu With ASP.NET

Posted by: Aaron Goldenthal 11/11/2009 5:13 PM

I’ve been using jQuery a lot recently, and one of my favorite extensions is Trent Richardson's Impromptu.  Impromptu provides a very easy way to prompt the user for input, and is a much more flexible replacement for JavaScript alert, prompt, and confirm.  The syntax is actually very straightforward, but especially for more complex prompts it can be a little cumbersome to build the prompts.  To help simplify this, I’ve created a set of helper classes to work with Impromptu prompts in ASP.NET. There are a handful of overall goals I had in mind when starting this project: Provide the capability to automate the generation of Impromptu JavaScript (with all possible client-side capabilities) Provide helper classes for common Impromptu tasks (e.g. displaying an Impromptu prompt on page load by specifying only the message) Only output properties to the client that are explicitly set Provide reasonable server side validation (e.g. do not validate that callback/submit javaScript functions are valid, but do validate that either a message or a collection of state is specified) Provide a mechanism for setting default prompt parameters in web.config This project uses JSON.Net for serialization (Version 3.5 Beta 4 or later). Version 3.5 beta 4 (the latest when this project was created) is included so the samples will run, but it's recommended that you download the latest version. The rest of this article assumes you have a working knowledge of Impromptu, so if you’ve never used it please see the documentation. Impromptu Helper Classes The two primary classes that you’ll interact with are ImpromptuHelper and ImpromptuPrompt. ImpromptuHelper ImpromptuHelper includes several helper methods to register the JavaScript to display an Impromptu prompt (e.g. passing just the message string to generate a prompt with the default properties, passing an ImpromptuPrompt object). ImpromptuPrompt ImpromptuPrompt provides an ASP.NET server side representation of an Impromptu prompt. It includes all properties available on the client, including: Message - The text or HTML to be displayed in the prompt. Either a Message or a collection of States can be specified. States - A collection of ImpromptuStates representing the states of the prompt. Either a Message or a collection of States can be specified. Options - A collection of all available options for the prompt. Examples The ImpromptuHelper.ShowPrompt method can be used to register the JavaScript to display and Impromptu prompt (registered through ScriptManager or Page.ClientScript as appropriate for the given Page). The following example shows how to display an Impromptu prompt specifying only the message. 1: ImpromptuHelper.ShowPrompt("This is a test prompt"); There are several overloads to this method for other common scenarios, including specifying the message, timeout, prefix, and scriptKey.  If these are insufficient, there’s also an overload accepting an ImpromptuPrompt object, and shown in the following example. 1: ImpromptuPrompt prompt = new ImpromptuPrompt(); 2: prompt.Message = "This is a test prompt"; 3: prompt.Options.Submit = "function(v,m,f) { alert('You selected: ' + v);}"; 4: prompt.Options.Buttons.Add("Foo", "Bar"); 5: prompt.Options.Focus = 2; 6: prompt.Options.Show = "fadeIn"; 7: ImpromptuHelper.ShowPrompt(prompt); For all of the examples above, the Impromptu script is generated and registered as a startup script.  If you need to generate the Impromptu script and tie it to something else (e.g. a Button’s OnClientClick), the ImpromptuPrompt.GenerateScript method can be used.  This method includes several overloads that control the wrapper around that script (e.g. wrapped within a $(document).ready(), using a custom format string to append another jQuery function), as seen in the following example. 1: ImpromptuPrompt prompt = new ImpromptuPrompt(); 2: prompt.Message = "Are you sure?"; 3: prompt.Options.Timeout = 0; 4: prompt.Options.Callback = String.Format("function(v,m,f){{ if (v) {0}.click(); }}", 5: Button2.ClientID); 6: Button1.OnClientClick = prompt.GenerateScript(ImpromptuScriptWrapper.Custom, 7: "{0}; return false;"); There are a variety of other examples included in the sample website below. Default Values in web.config This library also includes classes to specify Impromptu prompt defaults in a web.config file (any properties in the Impromptu Options collection can be specified), as seen in the example below. 1: <configuration> 2: <configSections> 3: <section name="impromptuOptions" requirePermission="false" 4: type="ADG.JQueryExtenders.Impromptu.Configuration.ImpromptuConfigurationOptions, ADG.JQueryExtenders" /> 5: </configSections> 6:  7: <impromptuOptions opacity="0.5" focus="1" timeout="5000"> 8: <buttons> 9: <add key="Ok" value="true"></add> 10: <add key="Cancel" value="false"></add> 11: </buttons> 12: </impromptuOptions> 13: </configuration> As you can see, the ConfigurationSection must first be declared.  The requiresPermission property must be set to false to allow reading of the impromptuOptions configuration section without full trust (see here for more details).  Once this is done, the default values are then specified in an <impromptuOptions/> section.  As previously mentioned, any property in the ImpromptuPrompt.Options collection can be specified (including a collection of buttons). These defaults can also be specified in multiple web.config files at various levels within your application. If this capability is used, remember that web.config settings cascade to child directories, so if you have a property specified in a parent web.config that you do not want in a child web.config, those properties must be overridden in the child web.config.  An example of this is included in the sample website. Setup For any page that will show an Impromptu prompt, the Impromptu jQuery extension JavaScript file must be explicitly linked to the page.  I chose this method primarily because I typically combine several jQuery extension into one minified file to reduce the number of file downloads to the client. jQuery Browser Detection Issue There’s a known jQuery issue (at least in jQuery 1.3.2) with browser detection where IE7/IE8 are sometimes interpreted by jQuery as IE6 (as documented here among other places).  Since Impromptu uses browser detection (for special handling in IE6), this can be an issue.  There are a handful of solutions to this, but the simplest I think is to use Jonathan Neals’ jQuery Prowser Plugin.  This plugin will correctly populate the jQuery.Browser object, so Impromptu will correctly detect the browser. Download sample website: (912 kb)
Tags: ,
E-mail | Kick it! | DZone it! | Permalink | Comments (2) | Post RSSRSS comment feed