Using CouncilSoft.BootstrapAlert NuGet package

I recently worked on some of the code with the good people of www.CouncilSoft.com, for this open source NuGet package and wanted to share how it works.

The purpose of this package was to have a well at the top of the page where either the client-side or server-side code could post messages for the end-user, on any web page. For example, “Save successful!” or “Error – not found.” etc. Really, any real-time messages you want to send to the user.

The goals:
You might note that there is an “alert” facility in Bootstrap which lets you show a formatted message, with various levels of implied severity:

image

That’s great, but we had a few other things in mind:

  • Automatically include an icon, based on severity. Potentially include a title too like “Error”, “Warning”, etc
  • Optionally allow each alert to be “dismissible” with an “x” over to the right. Bootstrap supports this, but requires custom code each time.
  • Optionally auto-dismiss each message after a certain number of seconds. Have this settable on a per-message basis.
  • Be able to easily generate a message from both ASP.NET MVC code, and from JavaScript.

For this first version, that is what now exists. By default, here is what those same messages look like – with titles, icons, and dismiss buttons, using this NuGet package:

image

Getting Started:
To add this package to your ASP.NET MVC project, right-click on your project and click “Manage NuGet Packages”:

image

Now search for “CouncilSoft.BootstrapAlert” (or any fragment of that):

image

You’ll see that this requires jQuery 2.1.1, Bootstrap 3.2, and MVC 5.2.2. Click Install. What this does is the following:

  • Copies the .dll and .xml file (for Intellisense) to your Bin folder, and adds a Project reference to your MVC project.
  • Adds a required script to your Scripts folder.
  • Modifies your root web.config to add a late-binding assembly reference to the assembly. You’ll see that in <system.web><compilation><assemblies>

Setting up the core elements:
With the right references in place, there are really just a few things you have to do:

  • Add a reference to the script file in your _Layout.cshtml if you have one, or one particular page.
  • Use an HtmlHelper to render all of the queued messages – typically also in the _Layout.cshtml
  • Use an HtmlHelper to render the container where the messages should be shown – typically on individual pages, or in the _Layout.cshtml.

I’ll assume you have a “master page” setup and have a ViewsShared_Layout.cshtml file. In that file, go to the end after all of the scripts (and especially after jQuery) has been rendered or been referenced. Add these two lines:

<script src="~/Scripts/CouncilSoft.BootstrapAlert.js"></script>
@Html.Raw(Html.RenderAlertMessagesFromQueue())

.csharpcode, .csharpcode pre
{
font-size: small;
color: black;
font-family: consolas, “Courier New”, courier, monospace;
background-color: #ffffff;
/*white-space: pre;*/
}
.csharpcode pre { margin: 0em; }
.csharpcode .rem { color: #008000; }
.csharpcode .kwrd { color: #0000ff; }
.csharpcode .str { color: #006080; }
.csharpcode .op { color: #0000c0; }
.csharpcode .preproc { color: #cc6633; }
.csharpcode .asp { background-color: #ffff00; }
.csharpcode .html { color: #800000; }
.csharpcode .attr { color: #ff0000; }
.csharpcode .alt
{
background-color: #f4f4f4;
width: 100%;
margin: 0em;
}
.csharpcode .lnum { color: #606060; }

If you have ReSharper, it will prompt you to import the namespace – if not, manually add the following to the first line of the file:

@using CouncilSoft.BootstrapAlert.Extensions

.csharpcode, .csharpcode pre
{
font-size: small;
color: black;
font-family: consolas, “Courier New”, courier, monospace;
background-color: #ffffff;
/*white-space: pre;*/
}
.csharpcode pre { margin: 0em; }
.csharpcode .rem { color: #008000; }
.csharpcode .kwrd { color: #0000ff; }
.csharpcode .str { color: #006080; }
.csharpcode .op { color: #0000c0; }
.csharpcode .preproc { color: #cc6633; }
.csharpcode .asp { background-color: #ffff00; }
.csharpcode .html { color: #800000; }
.csharpcode .attr { color: #ff0000; }
.csharpcode .alt
{
background-color: #f4f4f4;
width: 100%;
margin: 0em;
}
.csharpcode .lnum { color: #606060; }

You should end up with a file that has these components:

image

Now, on individual pages – perhaps ViewsHomeIndex.cshtml – you need to add the container, the place where the messages will actually render. Pick a spot on the page and use this HtmlHelper:

@Html.Raw(Html.RenderAlertMessageContainer())

Again, you might notice that you need to include the “using” statement at the top. In the end, your page might look something like this:

image

At this point, we have everything we need to show the messages. Now, we just need to actually send some messages to this facility!

Queuing messages from MVC, .NET code:
There are several reasons you might want to show a message in the view – in a nice, simple way:

  • There were multiple validation errors.
  • There were back-end problems.
  • You want to let them know that something was successful – like “Item created successfully!” or “Item deleted.”

Not only that, you might want to show a message on another view. For example, you might be on the /Customer/Edit controller action. When you are done updating the database, you probably want to RedirectToAction(“Index”) and show a message on THAT screen, right?

This utility addresses all of that. You can specify how you want each message to act, simply by setting some properties. For example:

image

A few things to note, here. If the update is successful, we queue an alert, then redirect the user to /Customer/Index – where the message will be displayed automatically. No other code is needed!

If there was a problem during the edit, we queue the alert in ViewData instead of TempData, and redirect them back to the same edit page with the same model – where they will see the queued alert.

Also, I set every property for display purposes, above. You can leave them to be default if you’d like. The defaults are: an information message, with no auto-dismiss, but with a manual dismiss button, and with cross-view disabled.

Queuing messages from JavaScript/jQuery code:
The code above is great if you are in an MVC controller, but what about when you are client-side making AJAX calls? Well, the same functionality is available here. With no additional setup, you can wire up buttons like this, for example:

image

In this case, we’re just using some jQuery to wire up to the “click” event. The “addAlertToMessageArea(severity, message, autoDismissInMilliseconds, showDismissButton)” is what will make the message show up in the alert container on your page, immediately.

Going forward…
As of today, version 1.0.0.0 was cut in GitHub and published on NuGet. You can find them here:

Source at Github: https://github.com/councilsoft/CouncilSoft.BootstrapAlert
Package at NuGet: http://www.nuget.org/packages/CouncilSoft.BootstrapAlert/

There are some enhancements coming, but as of now, this already offers a very convenient way to queue, show, and stack multiple messages for the user, from both MVC server-side code, as well as client-side JavaScript code.

Posted in Computers and Internet, Development Tools, General, JQuery, Organization will set you free, Professional Development, Uncategorized

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Archives
Categories

Enter your email address to follow this blog and receive notifications of new posts by email.

Join 5 other followers

%d bloggers like this: