Summary

Client API-Enabled DotNetNuke Controls

With DotNetNuke's focus on reusability and making the developer's experience as pleasant as possible, a series of Client API-enabled controls is included with the Core releases. In addition to the Tree control, which has been used in previous examples, all of the controls described in Table 10-3 are part of the DotNetNuke.WebControls project. These controls reside under the DotNetNuke.UI.WebControls namespace and are used in various areas of the Core framework. To make module development less of a task and also offer some nice client-side functionality, try to make use of these controls when appropriate.

Table 10-3: Client API-Enabled Controls

Control Name	Example Usage	Description
DNNLabelEdit	Module title of a container	Allows a label to be edited on the client side with no postback done. Uses callback to update the value in the data store.
DNNMenu	Core skins using solpart navigation	Allows a menu to be dynamically populated from the data store and built on the client side.
DNNTextSuggest	N/A	Allows a user to start typing in the textbox and results are immediately populated. Uses callback.
DNNTree	Core file manager	Enables you to display hierarchical data in a tree view format.

Each of these controls also has its own JavaScript file, located in the js folder, which is named dnn .controls.controlname.js where controlname corresponds to the specific control's name. When using these controls in your own development, they will register the namespaces, variables, and the script blocks that they need. This makes it easier for developers to use these controls with less code. It is possible to use the controls and not be required to prepare anything for the client side — simply using one of these controls in your module will handle all of it for you.

Of course, if you would like to get fancy, you could use callbacks as explained in the previous section. Keep in mind that all of this functionality is relatively new. As time goes on, you will see more examples in modules and throughout the core itself.

If you are looking for some examples to get started with but are not at the point of getting hands-on just yet, visit the webcontrols.dotnetnuke.com site. It is a live example of these controls being used in a simple ASP.NET application and not running within DotNetNuke. It enables you to view how rich the collections of controls are without requiring you to download source and install it locally. This site also displays a live version of the latest developer documentation generated at compile time. If you would like to download the example ASP.NET application utilizing these controls outside of the DotNetNuke environment, please visit the official DotNetNuke project's download page. You can also download any of the latest DotNetNuke source code discussed in this chapter as well as the project's unit tests.

In addition to these controls, there are two series of methods used often in the core that were not covered. The first is the EnableMaxMin series of methods that enable you to show and hide a module's content all from the client side. The capability to use callbacks, if supported, is part of this series as well. The other series is the module drag-and-drop functionality exposed to site or page administrators. This is what enables you to move a module from one content pane to another and save the change to the database using callback.

Writing Custom Web Controls Using the Client API

One of the original goals outlined when the Client API was created was to allow for the API to be extended and enhanced by developers within and outside of the Core Team. It is strongly recommended that anyone attempting to create their own custom web control utilizing the Client API have a solid understanding of both the Client API and ASP.NET Web Controls. Notice that this section is about creating custom web controls, not custom DotNetNuke controls. That's because more likely than not, a custom web control developed using the Client API will be reusable outside of DotNetNuke as long as the DotNetNuke Web Utility and, in projects making use of the pre-built web controls, the DotNetNuke Web Controls projects or binaries are available as well.

The following is a brief outline of steps that should help you start creating your own custom web controls that take advantage of the Client API:

1. Create a new Web Control Library in Visual Studio.

2. Add a reference to DotNetNuke.WebUtility.dll and, if you're using the pre-built web controls, DotNetNuke.WebControls.dll.

3. Create a class and set its inheritance:

   • Completely new web controls inherit from the .NET Framework's WebControl class.

   • Extending an existing control inherits from the control you are extending.

4. Define properties.

5. Create your events and event handlers in the class:

   • Use PreRender to register client-side scripts and postback handler.

   • Handle postback using RaisePostBackEvent.

   • Handle callbacks using RaiseClientAPICallbackEvent.

6. Create the web control's script:

   • Initialize the control using a constructor.

   • Declare and create methods.

   • Create event handlers.

   • Add mandatory script to handle random script order.

In addition, outline what you need to make your own design and functionality decisions, weighing the factors and determining what is best for your control. For example, an abundance of callbacks in a control ruins the end-user experience because each round trip between the client and server consumes valuable resources and Internet bandwidth. When creating a control that makes use of callbacks, you must decide what an appropriate interval is that still maintains the efficiency you want.

An important note about the JavaScript files is that ASP.NET 1.x cannot guarantee the order in which the client-side scripts are sent to the client. This can cause problems when a client-side method relies on another script that should already be present because the parent namespaces should have already been loaded by the browser. Because of this, there is a mandatory script block added to each JavaScript file included in the Client API. When DotNetNuke no longer supports framework 1.x, this script block will no longer be necessary and can be handled using the ClientScriptManager class readily available in the ASP.NET 2.0 framework. Until then, the mandatory script block addition is required in all custom scripts to ensure the proper loading order and the expected behavior from both versions of the ASP.NET framework.