This Twitter stream is implemented using a WordPress widget. Widgets are WordPress Plugins that add visual and interactivity options and features, such as sidebar widgets for post categories, tag clouds, navigation, search, etc. Widgets can be added, removed or rearranged via the WordPress Widgets panel and therefore require no code.

Widgets

In this post I will explain how you can implement your own WordPress widget by showing you how I implemented the Twitter widget. The programming languages I used to develop a WordPress widget are PHP and javascript together with some HTML and CSS. I also used the JQuery and JQuery UI libraries for selecting HTML element and animation. PHP is the standard programming language to implement WordPress plugins.

To start with a WordPress plugin you have to create a file with the extension .php. The file name should resemble the name of your plugin. At the top of the file a multi-line comment should be created according to the WordPress plugin format. By using this format WordPress recognizes the file as a WordPress plugin.

/*
Plugin Name: Twitter search smooth scrolling
Plugin URI: http://www.semanticarchitecture.net/writing-a-wordpress-twitter-widget/
Description: This plug-in shows the most recent tweets that match the search term.
Version: 1.0
Author: Patrick Kalkman
Author URI: http://www.semanticarchitecture.net/
License: GPL2
*/

Notice the fields on each line such as “Plugin Name:” and “Version:”. Only the “Plugin Name” is required, the rest of the fields are optional. It is however good practice to fill the complete header. After this header it is normal to place a reference to the license of your plug-in. Most WordPress plugins use the GPL license.

Widget

The easiest way to create a widget is to subclass WP_Widget. This base class defines the basic skeleton for a WordPress widget.

class Foo_Widget extends WP_Widget {
 function __construct() {
   parent::WP_Widget();
  }

 function widget( $args, $instance ) {
 }

 function update( $new_instance, $old_instance ) {
 }

 function form( $instance ) {
 }
}

The constructor and the four methods are going to be used to implement our widget. Let’s define them one by one.

• Constructor – set the name and description of the widget.
• widget – outputs the HTML content of the widget.
• update – processes the options that should be saved.
• form – outputs the HTML for the options form.

Options

Each WordPress widget can create options. Options are fields that can be filled using the WordPress user interface. These can be use to change the default behavior of your widget.

The Twitter widget has 5 options.

• Title – the title of the widget, shown at the top of the widget.
• Search_query – the string used to filter the tweets.
• refresh_interval – the time to wait until reading new tweets from Twitter.
• tweet_interval – the time to wait before a new Tweet is shown.
• tweet_animation_interval – the duration of the scroll and fade-in effect.

The user interface to let the user enter the values of these options is created in the  form method. In this method HTML markup is added to add the form. See the example below which constructs the input field for the Title of the widget.

function form( $instance ) {
 $defaults = array('title' => __('Semantic Tweets', WIDGET_NAME));
 $instance = wp_parse_args((array)$instance, $defaults);
 $title = strip_tags($instance['title']);?>

 <p>
   <?php _e('Title', WIDGET_NAME) ?>:
   <input class="widefat"
     name="<?php echo $this->get_field_name('title'); ?>" type="text"
     value="<?php echo esc_attr($title); ?>"/>
 </p>

 <?php
}

A normal input element is used for entering values. The _e() function is used for localization, it uses the ‘Title’ as the key to search for translations in the context of the widget. esc_attr encodes less than, greater than, ampersand, double quote and single quote. The actual value is output via $title. Multiple input fields can be created by copying this row.

Update

The update method is triggered when the user presses the save button in the options screen.

function update($new_instance, $old_instance) {
 $instance = $old_instance;
 $instance['title'] = strip_tags($new_instance['title']);
 $instance['search_query'] = strip_tags($new_instance['search_query']);
 $instance['refresh_interval'] = strip_tags($new_instance['refresh_interval']);
 $instance['tweet_interval'] = strip_tags($new_instance['tweet_interval']);
 $instance['tweet_animation_duration'] =
   strip_tags($new_instance['tweet_animation_duration']);
 return $instance;
 }

$new_instance contains the values of the fields that the user entered. By copying those values to the $instance and returning the $instance the values get saved to the WordPress database. The strip_tags is a PHP function that removes the HTML and PHP tags from the given string.

Widget

The widget method creates and displays the actual widget. It output HTML that forms the widget.

function widget($args, $instance) {

  echo $before_widget;
  echo $before_title . $title . $after_title; ?>
  <div class="twitter-search-widget">search-query="<?php echo $search_query; ?>"
     refresh-interval="<?php echo $refresh_interval; ?>"
     tweet-interval="<?php echo $tweet_interval; ?>"
     tweet-animation-duration="<?php echo $tweet_animation_duration; ?>">
  </div>
<?php echo $after_widget;
}

The $before_widget and $after_widget are variables that contain markup that can be manipulated by themes. The same goes for $before_title and $after_title. Therefore, to let your widget be theme-able, you should use these variables.

The twitter widget basically is a div with an unordered list, for each new tweet an list item will be created in the unordered list. The list items will be created by javascript.

Registering Javascript

Javascript can be use and is supported by WordPress. Most WordPress version already include JQuery. The proper way to register a JavaScript library is by using the functions wp_register_script and wp_enqueue_script. 

function initialize_script() {
  wp_register_script('twitter-search-widget',
     plugins_url('twitter-search-smooth-scrolling.js',__FILE__ ));
  wp_enqueue_script('twitter-search-widget', array('jquery'));
};

With wp_register_script you assign a key to JavaScript file and specify the location of the file. The plugins_url retrieves the url to the plugins directory or to a specific file within that directory. You can hardcode the plugin slug in $path or pass __FILE__ as a second argument to get the correct folder name.

Wp_enqueue_script provides a safe way of adding JavaScript to a WordPress page. Basically, it includes the script if it hasn’t already been included, and load the one that WordPress ships. Note, the second argument that states that the twitter-search-widget JavaScript file is dependent on JQuery. This makes sure that the JQuery library is loaded before this JavaScript file.

Registering CSS

CSS is registered using the same method as with JavaScript. The functions for registering and queueing are called wp_register_style and wp_enqueue_style. Below the actual initialization script of the twitter widget is shown.

function initialize_script() {
  wp_register_script('twitter-search-widget',
    plugins_url('twitter-search-smooth-scrolling.js',__FILE__ ));
  wp_enqueue_script('twitter-search-widget', array('jquery'));

  wp_register_style('twitter-search-widget-style',
    plugins_url('twitter-search-smooth-scrolling.css',__FILE__ ));
  wp_enqueue_style('twitter-search-widget-style');
};

Directory organization

WordPress stores all its plugins in the plug-in folder under wp-content. To be able to install your plugin you need to add the plugin file to the plugin directory. If you have more than one file it is better to create a folder with the same name as the widget and store all files in there.

Source Code

The source code of this plug-in is can be found on WordPress.org.

Pong

Pong is a game that was originally developed as a electronic version of ping pong. Atari originally created the game in 1972. The goal is to defeat your opponent by getting a higher score. In my implementation,whoever reaches 10 points first, wins the game.

Android

Android is an operating system for mobile devices based on the Linux 2.6 kernel. Android Inc developed Android and Google bought Android in 2005. Although it is an operating system for mobile devices, the operating system itself is big. It consists of more than 12 millions lines of code. Android supports a multitude of different mobile devices and a special version of Android (version 3.0 Honeycomb) will be available for tablet devices.

You can develop Android apps in C++ and .Net but most Android development is done in Java. The reason that I used Java is that it is close to C#, the language I use during my day job. To develop Java applications for Android you need the Android SDK, the Java SDK and an Integrated Development Environment (IDE) such as Eclipse or IntelliJ®.

I used the community edition of IntelliJ®, which is free. This because during my day job I use Visual Studio® and Resharper® which shares many similarities with IntelliJ®. Resharper® and IntelliJ® share a lot of  keyboard shortcuts, they are both developed by the company JetBrains® . Note, that although Java can be used for development not all Java libraries are available, only those supported by the Android runtime.

Android Game development

When you start developing games on Android, you have three possible graphics implementation. You can use the drawable package and use a view or a canvas. On the other hand, you can use the OpenGL ES API that is a special implementation of the OpenGL specification for embedded devices. OpenGL ES includes support for 3D graphics. For Androng, I decided to use the graphics package and draw using a canvas. The canvas package is fast enough to support the animation and movement needed for this game.

Activities

An Android application revolves around Activities and Views. An activity is a part of the application that provides a screen to interact with. An application can consists of multiple activities. Android starts the activity specified in the manifest of an application. This manifest is important, it is a configuration file that specifies information the system needs before it can start your application. For example, which permissions are necessary for the application to run. When starting, Android calls the onCreate method of the specified activity. The source code below shows the main activity of Androng. All activities should derive from the Activity class.

public class AndrongActivity extends Activity
{
  private AndrongSurfaceView pongSurfaceView;

  @Override
  public void onCreate(Bundle savedInstanceState)
  {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);
    pongSurfaceView = (AndrongSurfaceView) findViewById(R.id.androng);
    pongSurfaceView.setTextView((TextView) findViewById(R.id.text));
  }

....
}

Views

A view creates the user interface of an activity and derives from the View class. A total view can consists of view groups and views. View groups are used to group views. They follow the composite design pattern. The user interface of an application can consist of multiple views, a so-called hierarchy of views. You can use code or a resource file to define the layout of a view. The flexibility of your user interface increases by using a resource layout file. It becomes easier to maintain and includes support for localisation. The layout resource file is implemented using XML. The resource file below shows the layout of Androng.

<!--?xml version="1.0" encoding="utf-8"?--></pre>
<pre id="pre1" lang="xml"><?xml version="1.0" encoding="utf-8"?>
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent">
    <net.semantic.games.AndrongSurfaceView
      android:id="@+id/androng"
      android:layout_width="match_parent"
      android:layout_height="match_parent"/>
    <RelativeLayout
        android:layout_width="match_parent"
        android:layout_height="match_parent" >
        <TextView
          android:id="@+id/text"
          android:text="Androng"
          android:visibility="visible"
          android:layout_width="wrap_content"
          android:layout_height="wrap_content"
          android:layout_centerInParent="true"
          android:layout_alignParentBottom="true"
          android:layout_marginBottom="10px"
          android:gravity="center_horizontal"
          android:textColor="#99FFFFFF"
          android:textSize="16sp"/>
     </RelativeLayout>
</FrameLayout>

All layouts types are viewgroups and are used to create hierarchical models. Androng uses a FrameLayout which is the simplest layout object. A FrameLayout is a blank reserved space on the screen that can be filled with one object. All the child objects are pinned to the left top corner. It is not possible to specify a location for a child, each consecutive child is drawn over earlier objects which can obscure the previous one.

In the case of Androng, the AndrongSurfaceView and the TextView are drawn on top of each other. Loading the XML in the user interface is done in the onCreate method of the activity setContentView(R.layout.main); where R.layout.main identifies the XML file in the resource.

Other layout types are possible. There is a LineairLayout, a RelativeLayout, a TableLayout and an AbsoluteLayout. Each of these layouts  have their own strength. I would not recommend using the AbsoluteLayout for your application because it may look good on your device but may well differ on another device.

We now have a user interface, lets see if we can draw resources to the screen.

Drawing using Canvas

Before you can draw a resource on to a canvas, you need to have a resource to draw and acquire a canvas to draw upon. The Canvas is acquired using a SurfaceView, this is a drawable surface that lies beneath the active view window. For Androng, I implemented a class named AndrongSurfaceView which extends SurfaceView, this is the same view as mentioned in the layout file. The source code below shows a part of the AndrongSurfaceView class.

public class AndrongSurfaceView extends SurfaceView
  implements SurfaceHolder.Callback
{
  private AndrongThread androngThread;
  private TextView statusText;
  private SurfaceHolder holder;
  private Context context;

  public AndrongSurfaceView(Context context, AttributeSet attrs)
  {
    super(context, attrs);
    this.context = context;
    this.holder = getHolder();
    holder.addCallback(this);
    setFocusable(true);
  }
......

By calling a method lockCanvas on the SurfaceHolder we get an instance of the Canvas class which can be used to manipulate the pixels on a surface.

Canvas canvas = surfaceHolder.lockCanvas(null);

A resource can be obtained through the context of the application. For example, the following source code draws the background of the game each frame.

Bitmap backgroundImage =
  BitmapFactory.decodeResource(resources, R.drawable.background2);
canvas.drawBitmap(backgroundImage, 0, 0, null);

Frame speed independent animation

Android runs on many devices, each with their own hardware specification. This means that the processing speed of the devices that run your application will be different. This in its turn means that the animation speed of a sprite, such as the ball of the Androng game differs per device. This is an unwanted situation, game play could differ per device. Therefore, we want to animate the game independently of the processing power of the device. We achieve this by incorporating time into the application and specify animation speed in pixel movement per time.

Getting high-resolution timing from Android

There 3 different ways to get time from the Android OS.

1. currentTimeMillis()
2. upTimeMillis()
3. elapsedRealtime()

The first is System.currentTimeMillis() which expresses the number of milliseconds since the epoch. Epoch on Unix based system is January 1, 1970. This obviously depends on the current time of the device, when the time switches due to the phone network or due to a user, this number can jump back or forth.

The second System.upTimeMillis is the number of milliseconds since the device was booted. This clock stops when the device goes into sleep mode, but isn’t affected by time shifts.

The third and last option is elapsedRealtime(), this is also the number of milliseconds since the device booted. The difference with the second option is that this keeps running when the device goes into sleep mode.

For our frame speed independent animation I choose upTimeMillis because the first option may jump forward or backward which is not good for calculating the frame speed and the third option keeps running while the game is paused which is also troubling for calculating the frame speed. The following code calculates the number of frames per second using the second option.

while (isRunning)
{
  currentTimeInMillis = System.upTimeMillis();
  double timeNeededToDrawFrame = (currentTimeInMillis – previousTimeInMillis) / 1000;
  previousTimeInMillis = currentTimeInMillis;
  DrawFrame(time);
  UpdatePhysics(timeNeededToDrawFrame);
}

The variable timeNeededToDrawFrame is send to all the objects that make up the game screen. For example, the Ball receives this and has a speed of 2 horizontal pixels per second. By multiplying this with the time needed to draw this frame we get the number of pixels that the ball should move. The same is done with the vertical speed. This enables frame speed independent animation.

Collision Detection

Most, if not all games need collision detection. There are many ways of detecting if two game objects collide. Androng combines both the bounding box and pixel methods. The bounding box method can be easily illustrated with the following picture.

The following algorithm detects if the virtual boxes around each sprite overlaps with the other.

if (bottom1 < top2)   return false; if (top1 > bottom2)
  return false;
if (right1 < left2)   return false; if (left1 > right2)
  return false;

//bounding box do overlap

The bounding box collision detection algorithm is a fast way to detect a collision, but if the shapes are not rectangular such as the ball we could get false positives. For example, in the following situation the bounding box detection would detect a collision while in fact there isn’t one.

Pixel Perfect Detection

We could solve this by using a bounding circle for the ball, but I wanted to solve this using a more generic approach, using the pixels of the sprite. Therefore, when the bounding box algorithm detects a collision we scan the overlap in both sprites for pixels. If the same location in both sprites contains a pixel (color != 0) we have a collision.

The algorithm determines the width and height of the overlapping box and where in each sprite the box is. The algorithm scans each pixel in the box for a collision. Reading the pixel from the bitmap is possible by calling the getBitmap() method on the Drawable. See the method CollidesWith of the sprite class in the source code for the full collision detection routine.

Sound Management

Androng plays a sound whenever the ball collides with a paddle, the wall or when a player scores. Playing a sound using Android is easy. The media player or Sound Pool classes can play sounds. I used the Sound Pool classes because they offer more flexibility. Playing sounds using the Sound Pool classes use the AudioManager,  the AudioManager is a so called Android system service. Below the source code is shown to get the AudioManager system service and to play the media file “hit”. Hit is played when the ball hits a paddle or the side.

AudioManager mAudioManager =
  (AudioManager) mContext.getSystemService(Context.AUDIO_SERVICE);
SoundPool mSoundPool = new SoundPool(1, AudioManager.STREAM_MUSIC, 0);
mSoundPool.play(R.raw.hit, streamVolume, streamVolume, 1, 0, 1);

All the sounds of the game are pre-loaded into a SoundPoolMap and are played from this SoundPoolMap. All sound management methods are grouped into a single class SoundManager, see the sourcecode for the class. The class is based on an example provided by Stephen Flockton, who writes a blog around Android development. Score State Management

Input Management

The game can be controlled using the touch screen of an Android device, this is called the Touch mode. The touch mode is activated if you touch a button on the screen with your finger. Handling touch mode events is as simple as overriding the onTochEvent of the SurfaceView.  Below the signature of the onTouchEvent is shown.

public boolean onTouchEvent(MotionEvent event)

This event gets thrown when you touch the screen with one or more fingers. The MotionEvent argument has a method called getPointerCount(), this method returns the number of fingers that are placed on the screen. Although this actually depends on the capability of the device and the version of Android. Androng has a two player mode where two players can play against each other using there fingers on the same device. In this mode the getPointerCount() method is used. If there are two fingers touching the screen of the device, the index = 0 represents the first finger,  while index = 1 represents the second finger. Using the index in the method getX or getY on the event the position of the fingers can be determined.

float xPosition1 = event.getX(pointerIndex);
float yPosition1 = event.getY(pointerIndex);

The xPosition1 and yPosition1 are used to place the paddle on the screen.

Notifications

Androng uses Toast notifications to tell the user about certain events such as how to start the game and which player has won the game. A toast notification is a message that pops up on the surface of the window. The message automatically fades in and out and stays on the screen for a predetermined amount of time. The following code places a toast notification on the Androng game screen.

Toast toast =
  Toast.makeText(context, "Select Menu for a new game.", Toast.LENGTH_LONG);
toast.show();

The constant Toast.LENGTH_LONG according to the Android documentation will say to Android that the text notification should be shown for a long period. Default, Toast.LENGHT_LONG corresponds to 3.5s. Show() will actually show the text on the screen.

Application Life-Cycle Management

As Android is an operating system for mobile devices, it needs special attention for managing the scares resources of such a device. Each Android application runs in its own process and is able to perform a specific task. A task can consists of multiple activities. Each Android application should manage the Application Lifecycle. For example, it is possible that the Android OS decides to suspend or destroy your application when it needs extra resources. Therefore, your application should be able save and restore its state when this is needed.

Activity Life-Cycle

As mentioned before, an Android application consists of activities, it is in these activities you should manage your applications lifecycle. There are three possible scenarios possible for starting or restarting your application.

All these “on*” methods are part of an activity. The fresh start scenario happens when you normally start your application. The Fresh restart scenario happens after Android has stopped your activity, just before it starts again. The last scenario Restart from pause, happens when the system is about to start resuming a previous activity. When an other application gets to the foreground your activity gets paused. This show a total graphical overview of the application life-cycle.

Note, that also when you change the orientation of an Android device, your application gets restarted

Restart Thread

Drawing of the game screen and physics calculation runs on a separate thread.

While (isRunning)
{
  .....
}

The thread runs continuously in a loop guarded by a single Boolean isRunning. When the program stops the isRunning Boolean gets set to false and the thread stops running. In the method surfaceDestroyed that gets called by the Android OS, I waited using a Join statement.

public void surfaceDestroyed(SurfaceHolder surfaceHolder)
{
  androngThread.setRunning(false);
  boolean retry = true;
  while (retry)
  {
    try
    {
      androngThread.join();
      retry = false;
    }
    catch (InterruptedException e)
    {
    }
  }
}

The method sets the boolean isRunning to false using the setRunning method, this stops the thread from running. Next, the code calls androngThread.join() which according to the documentation blocks the current thread until the receiver finishes its execution and dies.

Exactly the behavior I was looking for. However, during a restart or resume of the application I got the error “Thread already started” while trying to (re)start the thread.  It seems that the join statement succeeded but did not stopped the thread. There are other methods available on the thread class such as stop() and destroy() but according to the documentation they are all deprecated and shouldn’t be used. I decided to solve this problem while creating the thread.

The code below shows my solution, I do not find it an elegant one but it works.

public void surfaceCreated(SurfaceHolder surfaceHolder)
{
  androngThread.setRunning(true);
  try
  {
    androngThread.start();
  }
  catch (Exception error)
  {
    androngThread = CreateNewAndrongThread();
    androngThread.start();
    androngThread.setRunning(true);
  }
}

The method tries to start the thread, when it fails, the exception handler creates a new thread and starts the newly created thread.

Android Market

I wanted to publish Androng on Android Market. Android Market is an open distribution platform for Android applications. Open means that your applications are not policed and there is no approval process. The visibility of your application depends on the rating you get from customers. Android market is not the only distribution platform for Android applications, another publication channel is Amazon. Currently, this is only open to customers from the United States.

There is a one time $25 registration fee before you can publish your games on Android Market. Besides that, for every app sold on Android Market, Google receives a 30% fee. Which to my opinion is reasonable compared with other publication channel.  Androng is free and can be downloaded from Android market.

The community edition of IntelliJ gives you the opportunity to package the application. Before you publish your application, you must sign the application using a public private key combination. Updates of the application must use the same key for signing.  This package with .apk extension can be published on Android market. You have to fill in some fields before publishing such as a description and some screenshots, logo’s etc. If you have an Android phone you can download the game here via Android market. The nice thing about Android market is that you get insight into the users of your application. It shows if the users got any errors, which Android versions they use and the type of devices they have. For example, the screenshot below shows the type of devices that downloaded Androng.

Source Code

The source code of Androng can be found at CodeProject. if you use the community edition of IntelliJ, you can open the project file. Otherwise, you can open the individual source or java files.

Next version

For the next version of Androng, I have the following features planned, in no particular order.

• Usage of a real physics engine such as Box2d or AndEngine
• High score list, with central storage on the web
• Usage of Google Juice for dependency injection
• Better graphics
• Increased freedom of movement of the bats
• Support for Android version 1.6
• Promotion video

Background

iTextSharp is a free C# PDF library that is ported from the Java-PDF Library iText. iText was launched in 2000 and is a popular open source Java library for programmatic creation and manipulation of PDF. As with many successful open-source Java libraries it was ported to C# under the name iTextSharp. iTextSharp has been under development since 2008 and is distributed under the GNU Affero General Public License version 3.

At its core iTextSharp is an api to manipulate PDF creation. For a recent project I was looking for a solution that would enable me to create PDF documents from existing HTML documents or Views used in an ASP.NET MVC3 project. The ideal solution for me would be to throw an existing ASP.NET MVC3 view at it and let it generate a PDF that is exactly the same as the HTML rendered by a browser.

The solution described here uses the HTMLWorker class from iTextSharp to generate a PDF from an HTML view. HTMLWorker is a iTextSharp class that is able to parse an HTML document and generate a PDF using the what is called the SimpleParser of iTextSharp. Notice the name SimpleParser which indicates that not all HTML elements and css styles are supported. However, I was able to get good results using this solution.

To add reporting to your ASP.NET MVC3 project, first add the PDFReportGenerator project to your solution and add the iTextSharp.dll binary to your solution. PDFReportGenerator needs a reference to the binary. By adding the binary to the solution you are able to build the project directly from source control. Check the demo src for an example.

Creating a report.

Follow the following steps to generate an actual report from your web application.

1. Create a controller that derives from PdfViewController.
2. Create a view that generates the HTML which should be translated to a PDF report.
3. Create an action on a controller which calls the ViewPDF method on the PdfViewController.
4. Create a link to trigger the action on the controller.

The following paragraph describes these steps in more detail.

Create a controller that derives from PdfViewController

Create a new or reuse an existing Controller and let it derive from PdfViewController from the PdfReportGenerator project.

This enables your controller to call the ViewPDF method of the PDFViewController which generates the real PDF. In the demo project this is the HomeController.

Create a view that generates the HTML

Create a View that should be translated to a report. This could be an existing view or a new view specially for reporting. I usually create a new view as it lets me control the HTML markup for the report. As stated earlier the report generator does not support all the HTML markup. In the demo project this is the PrintDemo view.

Below the PrintDemo view from the demo project is shown. This is just a simple ASP.NET Razor view with a table and some rows. It uses a strongly typed model but that it not necessary. A tip when trying to design your report is to add borders to your table or div. Using these borders when looking at the generated PDF you can clearly see the start and end of the areas of your report.

@using MvcReportGeneratorDemo.Models
@model CustomerList
<br />
<table cellpadding="3" cellspacing="3">
    <tr border="1" bgcolor="#777777" color="#ffffff">
        <td>Name</td>
        <td>Address</td>
        <td>Place</td>
    </tr>
    @foreach (Customer customer in Model)
    {
        <tr border="1">
            <td>@customer.Name</td>
            <td>@customer.Address</td>
            <td>@customer.Place</td>
        </tr>
    }
</table>

Create an action which calls the ViewPDF method

The PdfViewController class from which your controller derives, contains a ViewPDF method. This method has the following signature.

protected ActionResult ViewPdf(string pageTitle,
            string viewName, object model)

Parameters

pageTitle

Type: System.StringThe title of the report which appears on the header of the page.

viewName

Type: System.StringThe name of the view which should be converterd to a report.

model

Type: System.Object

The model that is rendered by the view.

This methods generates the HTML view and converts into a PDF report and sends this PDF as a binary stream back to the client. This means that when the client has a PDF plugin installed, the PDF is shown inside the browser.

From an action inside your controller this method should be called to generate the report and send it to the cliënt. The following action from the Demo application generates the PDF. “Customer report” is the title of the report, “PrintDemo is the name of the view and the model is returned by the CreateCustomerList() which as its name implies generates a dummy list with customers.

public ActionResult PrintCustomers()
{
   return this.ViewPdf("Customer report",
        "PrintDemo", CreateCustomerList());
}

The last step is to create a link on a page that calls this action to actually print the report.

Trigger the action on the controller

A simple method to create a link to trigger the action on the controller is by using an ActionLink. This link calls the action that we defined on the controller.

@Html.ActionLink("Print customers",
      "PrintCustomers", null,
      new { target = "_blank" })

These are the steps you need to create PDF reports from your ASP.NET MVC3 projects.

Read the next part of the article if you are interested how into the details of how the PdfReportGenerator actually converts the ASP.NET MVC3 view into a report.

Detailed Reporting Project Overview

The PdfReportGenerator project consist of 6 classes which can be seen in the image below. The PdfReportGenerator assembly works by rendering the ASP.NET MVC3 view into a string and converting this string with HTML using the iTextSharp into a PDF report.

Rendering an ASP.NET MVC3 view into a string

The class HtmlViewRenderer is responsible for rendering the ASP.NET view into a string. The method RenderViewToString has the following signature.

public string RenderViewToString(Controller controller,
      string viewName, object viewData)

The arguments are viewName which is the name of the view that should get rendered to a string including the model viewData that is needed by the view. The controller is necessary

to be able to use to render the view using the view engine of ASP.NET MVC.

Convert the html string into a PDF byte array

Once we have the html in a string the StandardPdfRenderer converts the html string into a PDF byte array. The class StandardPdfRenderer has a method Render with the following signature.

public byte[] Render(string htmlText, string reportTitle)

The htmlText is the rendered view as a string that was produced by the HtmlViewRender, the pageTitle is as the name suggests the title of the report.

Send the byte array back to the client as a stream

The last step is to convert the byte array into an instance of the BinaryContentResult class. The class BinaryContentResult derives from the ASP.NET MVC ActionResult. It overrides the ExecuteResult and returns the content as a binary stream.

The class PdfViewController is the class that combines these classes. The method ViewPdf uses all the three previously mentioned classes to generate the PDF as shown in the code below

protected ActionResult ViewPdf(string pageTitle,
                    string viewName, object model)
{
 // Render the view html to a string.
 string htmlText =
       this.htmlViewRenderer.RenderViewToString(this,
           viewName, model);
 // Let the html be rendered into a PDF document
 // through iTextSharp.
 byte[] buffer = standardPdfRenderer.Render(htmlText,
           pageTitle);
 // Return the PDF as a binary stream to the client.
 return new BinaryContentResult(buffer,
           "application/pdf");
}

Points of Interest

Colors
iTextsharp supports color out of the box, in the demo application the background colors of the rows are alternated using different colors. These colors are visible in the report.

New page support
One thing that I needed with my project that was not supported by the HTML conversion in iTextSharp was functionality to force a page break.Most of the time with reporting you need to be able to force a page break, for example if you want a graph to start always on a new page. The way I solved this was to add support for it to iTextSharp.

As it is open-source you are able to add new features to it. I added support for a non existing HTML tag called <np /> which forces iTextSharp to create a new page. I created a patch so that it could be committed to the iTextSharp project. I do not know if it will be included in the main trunk of the project as it feels somewhat strange to invent new html tags just to support a page break. But if you need it, you can use the patch to compile iTextSharp with new page support.

Images
It is possible to add images to the report by using an <img src="" /> tag. I had no success with dynamically generated images. So therefore, I generated the images that I needed before the action conversion process took place.

ASP.Net Support
It should be possible to use the same kind of solution using older versions of ASP.NET MVC. However, I have not tried it.

Other Options
After I wrote this post several people mentioned other alternatives for generating PDF reports using ASP.NET MVC. Michael Johnson wrote a blog post about using WkHtmlToPDF and someone mentioned using Flying Saucer for generating PDF’s.

The source code of the solution can be found on CodeProject

This article explains a different authentication mechanism called Digest Authentication which provides an alternative. This security mechanism is more secure than Basic Authentication and does not have the drawbacks from using a https tunnel.

Digest Authentication is available on multiple web servers and supported by multiple internet browsers. The drawback when using Digest Authentication with Internet Information server is that it automatically authenticates credentials against active directory. This article describes an implementation which enables you to secure a WCF REST service with Digest Authentication and authenticate against any back-end.

Digest Authentication was first described in RFC 2069 as an extension to HTTP Basic Authentication. Later, the verification algorithm and security was improved by RFC 2617. This is the current stable specification. The implementation in this article is based on that RFC 2617 specification. Digest Authentication is more secure because it uses MD5 cryptographic hashing and the use of a nonce to discourage cryptanalysis.

Overview of Digest Communication

Digest communication starts with a client that requests a resource from a web server. If the resource is secured with Digest Authentication, the server will respond with the http status code 401, which means Unauthorized.

In the same response, the server indicates in the HTTP header with which mechanism the resource is secured. The HTTP header contains the following “WWW-Authenticate: Digest realm=”realm”, nonce=”IVjZjc3Yg==”, qop=”auth”. The first thing you should notice is the string Digest in the response, here the server indicates that the resource that was requested by the client is secured using Digest Authentication. Secondly, the server indicates the type of Digest Authentication algorithm to use by the client with Quality Of Protection (QOP) and the string called nonce which I will explain later in this article.

An internet browser responds to this by presenting the user a dialog, in this dialog the user is able to enter his username and password. Note, that this dialog does not show the warning about transmitting the credentials in clear text as with a Basic Authentication secured site.

When the user enters the credentials in this dialog, the browser requests the resource from the server again. This time, the client adds additional information to the HTTP header regarding Digest Authentication.

The server validates the information and returns the requested resource to the client. The details of the response from the server and the additional request of the client will be described in the following part of this article.

Digest Authentication

When the server responds to an unauthenticated client request, the server adds a nonce and a qop key to the header of the HTTP response. Both are typical for Digest Authentication. First, the nonce will be described and second the QOP quality of protection.

The Nonce

The Nonce stands for “Number used Once”, this is a pseudo random number that ensures that old communications between a client and a server cannot be reused in replay attacks. A replay attack is a network attack in which previous valid data transmission is repeated. This is done by an adversary who intercepts the data and retransmit it. According to the RFC 2716 specification, the Nonce is a server specified data string which should be uniquely generated each time a 401 response is returned by the server. The 401 response that is sent back to the client includes the Nonce generated by the server. According to RFC 2716, the client should add this nonce to the header of next requests.

Generating the Nonce

The format of the nonce depends on the implementation. Each RFC 2617 digest authentication implementation may define their own nonce format. However, one should carefully design the format of the nonce as it is a part of the quality of the security. For my implementation, I choose to include a date time stamp and the IP address of the client into the nonce. The implementation generates the nonce as follows.

Nonce = Base64( TimeStamp : PrivateHash)

The nonce is generated by base64 encoding the string that is constructed by concatenating the time stamp, a colon and a generated private hash. In the source code, this is handled by the NonceGenerator class which has a Generate method that generates the Nonce string.

public string Generate(string ipAddress)
{
   double dateTimeInMilliSeconds =
      (DateTime.UtcNow - DateTime.MinValue).TotalMilliseconds;

   string dateTimeInMilliSecondsString =
      dateTimeInMilliSeconds.ToString();

   string privateHash = privateHashEncoder.Encode(
      dateTimeInMilliSecondsString,
      ipAddress);

   string stringToBase64Encode =
      string.Format("{0}:{1}", dateTimeInMilliSecondsString,
       privateHash);

   return base64Converter.Encode(stringToBase64Encode);
}

MD5 is used to generate the private hash of the string that is constructed by concatenating the time stamp, a colon, the IP address of the client, a colon and a private key that is only known to the server. As MD5 is used, the generation is one-way. It is not possible to reconstruct this information from the private hash.

PrivateHash = MD5Hash( TimeStamp : IP Address : Private key)

In the source code, generating the private hash is handled by the method Encode in the PrivateHashEncoder class. It uses the MD5Encoder class to actually generate the MD5 hash.

public string Encode(string dateTimeInMilliSecondsString,
    string ipAddress)
{
  string stringToEncode = string.Format(
     "{0}:{1}:{2}",
     dateTimeInMilliSecondsString,
     ipAddress,
     privateKey);

  return md5Encoder.Encode(stringToEncode);
}

Validating the Nonce

Every time the client sends the nonce to the server, the server validates if this is the nonce that the server sends to the client. The server validates the nonce in two steps:

The first thing that this implementation on the server does is validate if this PrivateHash was generated by this server and returned to this client. The server does this by generating the PrivateHash with the time stamp that is available in the Nonce and the IP address of the client. If this does not deliver the same PrivateHash as in the nonce from the client, the nonce is incorrect and the server responds with a 401. The NonceValidator is responsible in the source code for validating this nonce.

public virtual bool Validate(string nonce,
   string ipAddress)
{
   string[] decodedParts = GetDecodedParts(nonce);
   string md5EncodedString = privateHashEncoder.Encode(
      decodedParts[0],
      ipAddress);

   return string.CompareOrdinal(
      decodedParts[1],
      md5EncodedString) == 0;
}

Secondly, the server checks if the Time Stamp is too old. The server holds a certain time-out for a nonce. For example, the time-out is 300 seconds. The server validates if the time stamp in the nonce is not older than 300 seconds. If the nonce is older than 300 seconds, the server returns an indication in the HTTP header that the received nonce is too old together with a new nonce. RFC 2617 uses a special key called Stale in the header that is sets to true when the Nonce is too old. The NonceValidator is also responsible for checking if the time stamp is too old.

public virtual bool IsStale(string nonce)
{
   string[] decodedParts = GetDecodedParts(nonce);

   DateTime dateTimeFromNonce =
     nonceTimeStampParser.Parse(decodedParts[0]);

   return dateTimeFromNonce.AddSeconds(
      staleTimeOutInSeconds) < DateTime.UtcNow;
}

By using a time stamp and the IP address in the nonce, we make sure that the request is recent and comes from the client that requested the resource.

Quality Of Protection

Digest Authentication allows the server to ask which algorithm the client should use to encrypt the credentials of the user. Digest Authentication allows the following Quality Of Protection.

• none = Default protection compatible with RFC 2069
• auth = Increased protection that includes a client nonce and a client nonce counter
• auth-int = Increased protection and integrity that included all of auth and a hash of the contents of the body

Note that it is a request from the server, the client itself is allowed to choose a lesser secure qop algorithm. If the server requests for auth, it is ok for the client to start communicating with the default or none qop.

The implementation with this article supports both default/none and auth. The class DefaultDigestEncoder and the class AuthDigestEncoder implement the default and the auth type of quality of protection. Both classes derive from DigestEncodeBase which holds common functionality.

At runtime, the server instantiates both types of encoders and stores them in a dictionary with the qop algorithm as the key. This enables the server to easily switch between different types of encoders at runtime.

internal class DigestEncoders :
   Dictionary
{
 public DigestEncoders(MD5Encoder md5Encoder)
 {
  Add(DigestQop.None, new DefaultDigestEncoder(md5Encoder));
  Add(DigestQop.Auth, new AuthDigestEncoder(md5Encoder));
 }

 public virtual DigestEncoderBase GetEncoder(
    DigestQop digestQop)
 {
  return this[digestQop];
 }
}

None or Default QOP

When an internet browser receives 401 HTTP status code with Digest in the authentication header, it will show a dialog for entering the username and password. When the client uses the default qop which is compatible with RFC 2069, the client encrypts the user name and password as follows.

HA1 = MD5( username : realm : password)
HA2 = MD5( method : digestURI)
response = MD5( HA1 : nonce : HA2)

An MD5 hash is created from the user name, realm and password, a separate MD5 hash is created from the HTTP method and the URI of the resource that the client requests. The response is created through a MD5 hash that combines the previous two MD5 hashes and the server generated nonce. The DigestEncoderBase class holds the functionality to generate both the HA1 and HA2 hashes.

private string CreateHa1(DigestHeader digestHeader,
   string password)
{
  return md5Encoder.Encode(
    string.Format(
    "{0}:{1}:{2}",
    digestHeader.UserName,
    digestHeader.Realm,
    password));
}

private string CreateHa2(DigestHeader digestHeader)
{
  return md5Encoder.Encode(
    string.Format(
    "{0}:{1}",
    digestHeader.Method,
    digestHeader.Uri));
}

The base classes AuthDigestEncoder and DefaultDigestEncoder are responsible for generating the response. This last step, generating the response, is what differs in the two derived classes. The response of the Auth algorithm should be generated differently. The Auth algorithm includes a nonceCount and a client generated Nonce in the response. Also, the actual qop string is concatenated before the hash is calculated.

response = MD5(HA1:nonce:nonceCount:clientNonce:qop:HA2)

This is why the Auth algorithm is more secure than Default, the server performs an additional check to see if the nonceCount is incremented by the client with every request. The CreateResponse method of the AuthDigestEncoder generates the Auth response.

public override string CreateResponse(
   DigestHeader digestHeader,
   string ha1,
   string ha2)
{
  return
   md5Encoder.Encode(
     string.Format(
     "{0}:{1}:{2}:{3}:{4}:{5}",
     ha1,
     digestHeader.Nonce,
     digestHeader.NounceCounter,
     digestHeader.Cnonce,
     digestHeader.Qop.ToString(),
     ha2));
}

Extending WCF REST

To be able to integrate Digest Authentication with WCF REST, the WCF REST framework has to be extended. This is done by creating a custom RequestInterceptor. For more information, take a look at my previous article on CodeProject which explains this extension in more detail.

Retrieving and Storing User Credentials

The password of the user is transmitted as part of the response generated by the client to the server. It is not possible for the server to extract the password from the response. The server generates a response and checks if the response is equal to the response that was given by the client. This means that there are two options for storing and retrieval of user credentials using Digest Authentication.

• The first and most secure option is for every user to store the HA1 key in the credentials data storage and validate using the stored HA1 key. This has a disadvantage because you have to change the HA1 key in the data storage if the username, password or realm changes.
• The second option is to store the password of the use in the credentials data storage in such a way that it is possible to retrieve the original password. This is obviously less secure than the first option.

Using the Source Code

If you want to secure your own WCF REST service with Basic Authentication using the provided source code, you need to execute the following steps:

• Add a reference to the DigestAuthenticationUsingWCF assembly
• Create a custom membership provider derived from MembershipProvider
• Implement the ValidateUser method against your back-end security storage
• Create a custom membership user derived from Membership user
• Implement the GetUser method against your back-end security storage
• Create a custom DigestAuthenticationHostFactory, see the example in the provided source code
• Add the new DigestAuthenticationHostFactory to the markup of the .svc file

Points of Interest

The provided source code is developed using TDD and uses the NUnit framework for creating and executing tests. Rhino mocks is used as a mocking framework inside the unit tests.

Which visible, tangible benefit would be reached using a DI framework? This blog post describes the arguments we used to successfully convince management.

Dependency Injection Framework

A dependency injection framework is a software module that manages the dependencies of your application. Dependency Injection is a specific form of inversion of control where the concern being inverted is the process of obtaining the needed dependency. An excellent discussion on how to use a DI container can be found here by Uncle Bob. Inversion of Control is one of the SOLID design principles. There are many types of dependency injection frameworks, for a comparison take a look at this and this blog post from Andrey Shchekin.

Convincing management

Recently at LetsGrow we started using a dependency injection or DI framework for the LetsGrow.com platform. We are using Test Driven Development (TDD) and using a DI framework seemed to be the next logical step. This would remove the implementation of several builder patterns and would make implementing tests easier. It would also make the LetsGrow.com platform more flexible. Although these benefits were clear to me, I had a hard time convincing management of the business benefits of a DI framework.

Who makes the design decision?

One could argue that the design decision of using a DI Framework should be made by an architect. I think that introducing a DI framework also comes at a cost. Surely the benefits will be greater in the long run, but the development of new functionality will be slower during the introduction of a DI framework. The development team has to learn how to use such a framework, some existing code will change with no visible benefit for the user of the application. Therefore, I think that such a decision should be made in cooperation with management.

Business benefits

The primary benefits of using a DI framework are that it makes the source code of an application easier to understand, to maintain and to extend. Using a DI framework will reduce the amount of source code which will decrease the time it takes to implement new functionality in your application. In the long-term, this results in reduced maintenance costs, lower bug rates and thus increased customer satisfaction.

Secondary benefits are that configuration of an application will be more obvious as it sits in a central place. All instances of objects will be created the same way (consistency). When using a DI framework it becomes possible to switch implementations at run-time. For end-to-end tests it becomes possible to replace key components of the application with fake implementations.

Risks

We also looked at the possible risks of introducing a DI framework. We identified the following risks:

• increased memory usage
• performance overhead
• complexity in configuration
• less transparent source code

After some research we found that there was indeed an increase in memory and some performance overhead but they were marginal. I think that everyone that wants to use a DI framework should also do this research themselves because this could differ per application.

Complexity in configuration is a real risk. If you describe each dependency of each class in the configuration file,  the configuration file becomes too large and complex. Only these dependencies that should be managed by the framework should be described using the configuration file. Hartmut Wilms also discusses this risk in this blog post.  The last risk, less transparent source code we think will be temporary. Developers will have to get used to using a DI framework and the fact that the DI framework takes care of creating instances of objects.

Conclusion

My conclusion is that with the arguments mentioned in this post you should have no trouble convincing management of the business benefits of using a DI framework for your application. If you have more benefits or convinced your organization using a totally different arguments let me know. I would love to hear it.

For example authenticate against active directory, custom file or a database. Default, Basic Authentication is possible in combination with WCF and IIS, authentication is only possible then against active directory. This article and provided source code can be used in two ways. First just download the code, go down to the use the code part and implement your WCF service using Basic authentication. Second you can use the article to learn about what exactly is Basic Authentication and how can WCF be extended in a simple way.

Basic Authentication

Basic authentication is a standard protocol defined within Http 1.0 that defines an authentication scheme. In this scheme the client must authenticate itself with a user-id and password. Basic authentication is described in RFC 2617. When a client requests a resource from a site that is protected using Basic Authentication the server returns a 401 “Not authorized” response. Inside this response the server has added an sign that the site is protected using Basic Authentication. The server adds WWW-Authenticate: Basic realm=”site” to the header of the response, Basic indicates that the authentication scheme is Basic Authentication. Realm is an string that indicates which part of the site is protected. It has no further usage in the actual authentication mechanism itself.

An internet browser generates a dialog based on this response message, this dialog shows the realm and allows a user to enter a user name and password.

When a user enters the user name and password, the client resents the request but adds “Authorization: Basic SGVsbG8gQmFzZTY0″ to the header of the request. The strange characters after Basic are the user name and password separated by a single colon “:” in a base64 encoded string. The server decodes the string, extracts the credentials and validates them against the back-end. When the credentials are correctly validated the server returns the requested content to the client.

Extending WCF Rest

WCF REST is part of the WCF Rest starter kit. Unlike standard WCF, the WCF starter kit provides a simple way to apply behaviour to all server operations. Adding this behavior to normal WCF can get fairly complex. WCF Rest uses Request Interceptors. Request interceptors shield you from the more complex extensibility points. Request Interceptors are executed at the WCF channel level and enable you to interpret the incoming request and generate an appropriate response.

public class MyRequestInterceptor : RequestInterceptor
{
  public override void ProcessRequest
        (ref RequestContext requestContext)
  {
    //Access request with requextContext.RequestMessage
  }
}

By deriving a new class from the RequestInterceptor base class you create a custom request interceptor. The method ProcessRequest is executed for every request that arrives at the service. Inside this method we read the header of the request and decode the base64 encoded string if it is present. If it is not present we generate a response that includes WWW-Authenticate: Basic realm=”site” in the header.

Linking the custom RequestInterceptor to the service

The RequestInterceptor can be linked to the service by creating a custom ServiceHostFactory. The ServiceHostFactory is responsible for provides instances of ServiceHost in managed hosting environments. By Managed hosting environments Microsoft means IIS hosted services. The CreateServiceHost method of the ServiceHostFactory creates a new WebServiceHost and adds the new RequestInceptor to the Interceptors collection.

public class BasicAuthenticationHostFactory :
   ServiceHostFactory
{
  protected override ServiceHost CreateServiceHost
         (Type serviceType, Uri[] baseAddresses)
  {
    var serviceHost = new WebServiceHost2(serviceType,
        true, baseAddresses);
    serviceHost.Interceptors.Add(
        requestInterceptorFactory.Create("DataWebService",
            new CustomMembershipProvider()));
    return serviceHost;
  }
}

This new ServiceHostFactory is linked to the service through the markup file (.svc) of the service. Inside the markup, you override the host factory of the service.

ServiceHost Language="C#" Debug="true"
   Service="WCFServer.Service"
   Factory="WCFServer.BasicAuthenticationHostFactory"

Custom MembershipProvider

The provided source code uses a MembershipProvider to actually authenticate the credentials of the client. You can write your own MembershipProvider by deriving from MembershipProvider. The only method that needs to be implemented is the ValidateUser method. This is the method the code uses to validate the user. This customer MembershipProvider is linked to the RequestInterceptor in the CreateServiceHost method of the ServiceHostFactory.

public class CustomMembershipProvider : MembershipProvider
{
  public override bool ValidateUser(string username,
        string password)
  {
    //perform validation return false;
  }
  ...

Security context

After we have authenticated the incoming request, we have to create and set the security context. This enables the usage of the client credentials inside a service method. WCF uses the thread local ServiceSecurityContext for this. After the request has been authenticated, a new ServiceSecurityContext is created and added to the incoming request. This enables retrieving the user name inside the service method with ServiceSecurityContext.Current.PrimaryIdentity.Name

Using the code

If you want to secure your own WCF REST service with Basic Authentication, you need to execute the following steps:

• Add a reference to the BasicAuthenticationUsingWCF assembly
• Create a new membership provider derived from MembershipProvider
• Implement the ValidateUser method against your back-end security storage
• Create a custom BasicAuthenticationHostFactory
• Add the new BasicAuthenticationHostFactory to the markup of the .svc file

Points of Interest

Although Basic Authentication is a method to secure a web site or service, the authentication mechanism itself is not secure. The user name and password are send base64 encoded over the internet. To make this more secure, the server should offer the service using https. Https secures the channel so that the base64 encoded user name and password cannot be decrypted.

This article and source code are based on the example of Pablo M. Cibraro who deserves the credit for the solution. The provided sourcecode is developed using TDD and uses the NUnit framework for creating and executing tests. Rhino mocks is used as a mocking framework inside the unit tests.

Source Code

The source can be found at CodeProject

These principles can help a software developer manage dependencies between software components. Bob Martin the author of the principles writes “So dependency management, and therefore these principles, are at the foundation of the -ilities that software developers desire”. You can read the original article here.

These -ilities that Bob Martin refers to are the non functional requirements of a software product. I think that a software architecture is responsible for implementing the non functional or quality attributes of a software product. Therefore, I think that the SOLID design principles are one of the most fundamental rules for designing a robust software architecture. During the workshop we showed the following pictures to introduce a single principle. Can you spot the principle just by looking at a picture? The pictures are from this site which also explains the SOLID design principles.

LetsGrow SOLID Software development

The nice thing about the SOLID principles that they can be used on many levels. For example, the Single Responsibility principle can be used on method level, class level, library level and even on (sub)system level. The same goes for the other principles. The slide show below shows the slides on slide-share that we used for the workshop.

My preferred method when it comes to requirements gathering, functional or Non-functional, is through interactive workshops. During these workshops you facilitate the requirements gathering using interactive methods. I find that workshops with the main stakeholders are very time effective and create a common ground.

You should decide a standard set of Non-functional requirements for your company. This list of standard Non-functional requirements will function as your checklist at the start of a project. By using a standard you create consistency through all of your projects. You can choose from a number of existing standards or you could create your own. The thing is that not all of these standard will fit your organization, some will be too small, too complex or too large.

You can use any of the following standards or a combination as your Non-functional requirements checklist

• ISO 9126
• QUINT (Quality In Information Technology) a superset of 9126
• FURPS (Functionality Usability Reliability Performance Supportability)
• ISO/IEC SQuaRE (Software product Quality Requirements and Evaluation)
• SUMI (Software Usability Measurement Inventory)

A workshop is the process in which you find the Non-functional requirements of your application. If you have done a number of these requirements workshops, you often find a stable set that are important for all the applications that you develop. For example, in industrial applications, reliability and time behavior are often the most important. What would be the contents of such a workshop?

Depending on the maturity of your organization, you first need to create awareness about the importance of Non-functional requirements. Next,  invite the stakeholders of your application to a QUINT workshop. In this first workshop you are going to find the most important Non functional requirements of your application. For this first step I often use the main categories of QUINT (Functionality, Reliability, Usability, Efficiency, Maintainability and Portability). In the invitation of the workshop add some home-work for the participants which explains these categories.

At the start of the workshop explain the main categories and answer any questions about the home-work. The goal of this workshop is to determine a prioritized list with the most important QUINT categories for your application. An effective method to create this list is dot-voting. Each participant gets three dots that he or she can use to vote on a category. The total number of votes on a category determines the order.

After a first voting round, the stakeholders need to discuss the outcome, is this what they expected? Reassure the stakeholders that all Non-functional requirements are important and will get a place in the software architecture. This prioritized list is used as a basis for our design decisions. After the discussion, do another voting round to create the final list.

This workshop, which can be done in one or two hours creates a prioritized list of Non-functional requirements. This list will be the basis of the software architecture of your application. In a follow-up of this workshop you could descend to the real attributes of QUINT.

The sidebar of this page shows the LetsGrow.com WordPress Weather plug-in. This WordPress plug-in shows a map of the Netherlands together with real-time temperature and radiation data. The plug-in retrieves the data directly from LetsGrow.com using LetsGrow Services.

LetsGrow Services is a module that enables customers or partners of LetsGrow.com to develop third-party applications that use the data from the LetsGrow platform. The LetsGrow.com WordPress Weather plug-in shows the power and flexibility of the LetsGrow.com platform.

LetsGrow has been collecting data from different brands of climate computers and plant sensors for over five years. A customer can use and integrate this information into custom applications through LetsGrow Services.

As the figure shows LetsGrow Services run on machines in the LetsGrow Data Centre. Businesses can create applications that consume these services and offer new services to their customers.

Here are some examples of the kinds of applications that could be built using LetsGrow Services.

• A research institute or university could combine the large amount of historically data that is available in LetsGrow. This may lead to better understanding and insights in the growing process of crops that can help reduce the energy demand of a greenhouse. Note that a customer maintains ownership of the data in LetsGrow. First, a customer gives explicit consent to use the data. Then a  research institute can use the data.

• A horticultural advisor of a customer could extract the data of the customer and perform calculations on the data. The results of these calculations could be stored in LetsGrow using LetsGrow Services. A customer can see the original data combined with the results of the calculation in one single view.

• Affiliates or partners of LetsGrow could create custom modules using LetsGrow data. For example, a flowering prediction module that has a model that predicts the flowering date of a crop. These extra modules may even lead to automatic changes in the greenhouse settings to aim for a specific flowering date.  These extra modules could be offered to the customers of LetsGrow.

For more information about LetsGrow Services take a look at the document Introducing LetsGrow Services (PDF, 750K) which describes LetsGrow services in more detail.

Semantic Architecture?

Ok, but how is this related to Semantic Architecture and the Semantic Web? It isn’t! Currently the LetsGrow platform doesn’t use a Semantic Architecture or Semantic Web technologies. In the next post I will explain how a Semantic Architecture could be used to solve the problems I had during the implementation. Also I will describe the details about how I created this WordPress plug-in.

It is possible to calculate the sunrise, sunset and maximum solar radiation using some well-known formulas. For those of you who are interested in these formulas take a look at the following pages at Wikipedia (Declination of the Sun, Sunrise, Sunset). If you just want to calculate the sunrise, sunset and maximum solar radiation take a look below on how to use the code.

I wrote the code in C# and packed it in a Visual Studio 2008 solution. It has two assemblies, Astronomy and AstronomyTest. The assembly Astronomy has the SolarCalculator class which performs the real calculation. The assembly AstronomyTest has several unit-tests that validates the calculations against external sources. The SolarCalculator class needs the longitude, latitude, time-zone and whether to use daylight savings. You can create  an instance of the SolarCalculator like this:

const Double Longitute = 5.127869;
const Double Latitude = 52.108192;
const int LongituteTimeZone = 15;
const bool UseSummerTime = true;
SunCalculator calculator = new
  SunCalculator(Longitute, Latitude,
  LongituteTimeZone, UseSummerTime);

The actual calculation of sunrise, sunset and maximum solar radiation can be seen below.

DateTime sunRise = calculator.CalculateSunRise(
   new DateTime(2010, 4, 1));
DateTime sunSet = calculator.CalculateSunSet(
   new DateTime(2010, 4, 1));
Double maximumSolarRadiation =
   calculator.CalculateMaximumSolarRadiation(
      new DateTime(2010, 1, 1, 1, 3, 0));

The DateTime returned from CalculateSunRise and CalculateSunSet includes the sunrise and sunset time. For more information take a look at the unit-tests in the assembly AstronomyTest which explain the usage in more detail.

I added an article to The Code Project which also explains the usage of the library including a download link of the source code.