Introduction
This article is a quick guide to some features of the DNJ framework. DNJ is an Open Source framework that helps using jQuery with ASP.NET applications. It provide helper functions, an AJAX extender, a transparent RPC, and an implementation of the jQuery UI components as ASP.NET web controls.
Background
The idea of developing this framework came to me when I started working with jQuery in my ASP.NET projects. I started using code snippets to create HTML code for tabs, accordion, sliders... then I wrote some helpers to load needed jQuery scripts automatically ...
I noticed that I repeated the same steps in each new project, and I don't think to be the only developer who have done this.
An important point was the Visual Studio designer rendering. When you use jQuery, you have to run you web application to see the effect applied, and this is a big issue when developing complex user interfaces... I thought that having design time WYSIWYG for jQuery controls would help a lot!
In the following article, I will present the implemented features in the current DNJ release (v0.3.5-beta) and how to use them in your projects.
Please note the at this time, DNJ is in beta stage, and need your help to test, identify bugs, and suggest enhancements, so if you find the idea interesting, download the framework and report any bugs or suggestions.
Prepare the environment
Before you begin, you have to download the DNJ framework here. I recommend you to use the Windows installer package; it contains the DNJ runtime DLLs, a VS template project, a VS demo site, the toolbox installer, and the jQuery UI themes that can be used with DNJ! If you don't want to use the Windows installer, you can download each component alone (runtime DLLs / project template / demo site). If you are creating a new project, use the DNJ template to create it. If you want to enable DNJ for a new project, you have to add references to the DNJ runtime libraries (Org.Eurekaa.DNJ.dll and Org.Eurekaa.DNJ.UI.dll). Then, edit your web.config and add the following to the system.web section:
<httpModules>
<add name="DNJHttpModule"
type="Org.Eurekaa.DNJ.Http.DNJHttpModule,Org.Eurekaa.DNJ" />
</httpModules>
<httpHandlers>
<add path="DNJResources.axd" verb="*"
type="Org.Eurekaa.DNJ.http.DNJHttpHandler, Org.Eurekaa.DNJ" />
</httpHandlers>
Please note that if you don't add the code above, DNJ will ask you to add it automatically when you first use a DNJ web control.
DNJ scripts loader
One important module in DNJ is the script loader; this module allows you to build a minified jQuery+jQuery package on the fly.
You can easily decide which jQuery plug-ins and which jQuery UI components will be loaded. The script loader is an HTTP handler that you can call in a <script> tag.
The following syntax will load all jQuery + jQuery scripts:
<script type="text/javascript" src="DNJResources.axd?load=jquery,ui[all],fx[all]">
</script>
If you need to load only some parts of the jQuery UI for example, you can use this syntax:
<script type="text/javascript"
src="DNJResources.axd?load=jquery,ui[tabs,datepicker],fx[all]"></script>
and for more granularity you can use this syntax (all possible values are represented):
<script type="text/javascript"
src="DNJResources.axd?load=jquery,ui[accordion,core,datepicker,dialog,draggable,
droppable,position,progressbar,resizable,selectable,slider,
sortable,stackfix,tabs], fx[blind,bounce,clip,core,drop,explode,
fold,highlight,pulsate,scale,shake,slide,transfer]"></script>
The script loader is also used to generate JavaScript stubs for the DNJ RPC module (see the next section). The syntax is:
<script type="text/javascript" src="DNJResources.axd?conf=path/to/dnjrpc.conf.js">
</script>
DNJ RPC module
DNJ RPC allows you to call your server methods from JavaScript.
Let's say you have the following C# class where you declare some functions:
namespace MyNameSpace
{
public class ServerProcesses
{
public static string SayHello()
{
return "Hello World from : " +
Assembly.GetExecutingAssembly().FullName;
}
public string Say(string something)
{
return something;
}
public int Add(int a, int b)
{
return a + b;
}
public double Add(double a, double b)
{
return a + b;
}
}
}
DNJ RPC will let you call them from JavaScript using this JavaScript code:
<script>
$(document).ready(function(){
$('#Button1').bind('click', function(){
$.DNJRPC('#SomeTargetSelector').MyNameSpace.ServerProcesses.SayHello();
});
$('#Button2').bind('click', function(){
$.DNJRPC('#target').MyNameSpace.ServerProcesses.Say('Some string here');
});
$('#Button3').bind('click', function(){
var a = GetSomeValueForA();
var b = GetSomeValueForB();
$.DNJRPC('#result').MyNameSpace.ServerProcesses.Add(a , b);
});
});
</script>
Note that the namespace was preserved!
To achieve this, you have to declare the allowed methods in a JSON configuration file (let's say, dnj/config/dnjrpc.conf.js):
{
"Functions": [
{
"Name": "SayHello",
"Assembly": "MyNameSpace",
"Type":"MyNameSpace.ServerProcesses"
},
{
"Name": "Say",
"Assembly": "MyNameSpace",
"Type":"MyNameSpace.ServerProcesses"
},
{
"Name": "Add",
"Assembly": "MyNameSpace",
"Type":"MyNameSpace.ServerProcesses"
}
]
}
Note that for both the C# Add methods, we only declared one entry! The parameters type will be detected automatically.
Then you use the DNJ scripts loader to generate JavaScript stubs and namespaces.
<script type="text/javascript" src="DNJResources.axd?conf=dnj/config/dnjrpc.conf.js">
</script>
Click here to see a live example. (See page source for details.)
AJAXify .NET web controls using the DNJ Panel
This module is an AJAX extender that works like the ASP.NET AJAX Panel. The DNJ Panel doesn't need a script manager, and has some callbacks which can be overloaded to customize some behaviours of the panel. The module requires jQuery to be loaded using the DNJ scripts loader.
To AJAXify a standard .NET web control, all you have to do is put it into a DNJ Panel. This will prevent the control from reloading the current page while doing a postback ... check a live demo here: DNJPanel with default settings.
This will work exactly like the Microsoft ASP.NET AJAX Panel. Now, let's see how we can add fun stuff to DNJPanel.
In the .aspx file, we will add the following code:
<style type="text/css">
.dnj-indicator
{
border:0px;
background: #a00;
color:#fff;
position:absolute;
top:0px;
right:0px;
width:150px;
font:700 11px verdana;
padding:2px 5px;
}
</style>
<script type="text/javascript">
$(document).ready(function() {
var indicator = $('<div>Loading</div>').addClass('dnj-indicator').hide();
$('body').append(indicator);
$(window).scroll(function() {
indicator.css('top', $(this).scrollTop() + "px");
});
$.DNJ.settings.beforeCallBack = function(sender)
{
indicator.show();
sender.fadeTo("fast", 0.50);
};
$.DNJ.settings.afterCallBack = function(sender)
{
indicator.hide();
};
$.DNJ.settings.errorCallBack = function(msg) {
$.nyroModalManual({
bgColor: '#ffaaaa',
title: 'An error has occured',
content: msg
});
};
});
</script>
We ask DNJ Panel to overload its before/after/error callbacks. The before and after callbacks will show/hide an indicator like the one used by GMail.
The error callback will use a third party jQuery plug-in (nyromodal) to display the exception screen when an error occurs.
All this is demonstrated in the following page: DNJPanel advanced demo.
DNJ web controls
If you use the Windows installer to setup DNJ, you will get the following toolbox added to Visual Studio (you can get the Windows installer here):
If the installation process fails, you can download the DNJ runtime libraries and add them manually. The controls are all WYSIWYG, but there is still some incompatibilities with VS2005 that will be fixed in the next release. The web control designers are built to keep both the jQuery and ASP.NET logic. In the following screenshot, you can see the DNJTabs controls in the VS designer.
All DNJ UI controls have a common property called "Settings" which encapsulates all the settings that will be passed to the JQueryUI control.
Note that you can add/modify/remove tab pages using the designer, you can modify the control properties from the Properties box, and you'll see what will be passed to the jQuery plug-in on the fly (the JSON string).
DNJ DatePicker design:
And, here is an example of the ASPX code of a DNJTab component:
<dnj:DNJTabs ID="DNJTabs1"
runat="server" Height="325px" Width="400px">
<Settings cache="True"></Settings>
<BoxList>
<dnj:DNJBox runat="server" Title="Page_0" ID="Page_0">
<Content>
This is a DNJ Tabs demo<br />
you can Add/Remove/Edit tabs' titles
from the source code or from the designer
<br />
<br />
<br />
</Content>
</dnj:DNJBox>
<dnj:DNJBox ID="Page_1" runat="server" Title="Page_1">
<Content>
It works :)
</Content>
</dnj:DNJBox>
<dnj:DNJBox ID="Page_3" runat="server"
Ajax="True"
ContentUrl="~/Demos/UIDemos/AjaxBackend.ashx"
Title="AjaxTab">
<Content>
This content will be replaced with the result of an ajax Call
</Content>
</dnj:DNJBox>
</BoxList>
</dnj:DNJTabs>
and the source code of the DNJ DatePicker:
<dnj:DNJDatePicker ID="DNJDatePicker1" runat="server">
<Settings AppendText="" ButtonImage=""
ChangeMonth="True" ChangeYear="True" InlineMode="True" />
</dnj:DNJDatePicker>
As you can see, the code is clean ;)
Check the live demo here.
Conclusion
In this article, I tried to give you an idea of what's DNJ and what you can do with it. The project is still in development stage, and needs a lot of enhancements, so feedbacks are welcome. I'm working hard to write a complete documentation for the current release that will be released in the DNJ official website. If you are interested in the project, or have ideas you like to see in future DNJ releases, don't hesitate to comment on this article, or use the Google Code project issue tracker to post them.
