CSC/ECE 517 Fall 2014/OSS S1455 ajp

Add filtering by date in search requests

This article provides an introduction to Sahana Eden Framework and describes our work on fixing a bug in the Open Source Software foundation that is Sahana Eden. Initially we had chosen ticket #1511 but taking our mentors' recommendation into consideration, we looked into a different open bug. We then chose ticket #1225 as our project.

Introduction

Sahana Eden is an Open Source Humanitarian Management Platform developed, managed and maintained by the Sahana Software foundation. The Sahana Software Foundation is dedicated to the mission of saving lives by providing information management solutions that enable organizations and communities to better prepare for and respond to disasters. They develop free and open source software and provide services that help solve concrete problems and bring efficiencies to disaster response coordination between governments, aid organizations, civil society and the survivors themselves.

Some of the services provided by the Sahana Software foundation are:

• Reuniting separated families through registering missing and found persons.
• Tracking and managing requests for help from individuals and organizations.
• Tracking organizations and programs responding to the disaster, including the coverage and balance in the distribution of aid, providing transparency in the response effort.
• Enabling relevant sharing of information across organizations.

Sahana Eden Framework

Overview

The Sahana Eden Software Platform has been built around a Rapid Application Development (RAD) Framework. This provides a high level of automation to ensure that new solutions can be quickly and effectively developed. Once a database table is defined, the Sahana Eden Framework automatically generates HTML pages to handle CRUD (Create, Read, Update, Delete) as well as Search, Map and Pivot Reports. Web Services are available to import and export in XML, CSV, JSON and EXtensible Stylesheet Language (XSL) transforms are supported to produce other data standards. The development is primarily done using Python, HTML, CSS and Javascript.

S3 API

The Sahana Eden modules are developed using the S3 Framework Extension for web2py. The S3 Framework provides a generic RESTful API for many of the Eden data resources. The documentation for the S3 Widgets used in the application can be found here. This contains all the S3 Widgets. Only a subset of these are used in the application. All S3 framework extensions for web2py reside as a Python package in modules/s3. The core classes of the S3 API that are used are

• S3Request
• S3Resource
• SeResourceFilter
• FieldSelector

S3 REST Controller

The REST Controller function s3_rest_controller() is a helper function to easily apply the RESTful API of the S3Resource to the controller.
Some of the main tasks of the S3 REST Controller include:

• Parse and execute the incoming HTTP request on the specified resource
• Populate and hand-over view variables
• Choose and set the responsive view template

Basic Syntax

output = s3_rest_controller(prefix, resourcename)

In this example,

• prefix is the application prefix of the resource
• resourcename is the name of the resource (without prefix)
• output contains the result of the request and can be returned from the controller as-is. In interactive view formats, this is a dict of view variables.

Basic Options

The options are set using the syntax,

s3mgr.configure(table, key=value)

Where,

• table is the respective database table
• key is the setting key
• value is the configuration value

Objective

Our aim is to enhance the functionality of the project search module in the Sahana Eden application by adding filtering by date in the search requests.

Project

Overview

The Eden project is developed using the web2py Web Application Framework. The web2py framework is written in python and development using this framework uses the python programming language. This framework follows the MVC architecture that is popularly used in Web Application Development.

Application

The main purpose of the application is to provide software services to organizations that are interested in helping disaster affected areas. This is achieved through the development of the Sahana Eden Humanitarian Management Platform development platform. The platform allows Organisations and Volunteers to register and add their details, along with any details about infrastructure facilities that they might have which will assist in providing help to the disaster affected areas. For example, the site administrator can add organizations and projects that that particular organization is responsible for along with the start and end dates. User can also add assets such as relief items that can be provided to victims of the disaster. Various other options are available in addition to these for coordination and communication between volunteers and organizations.

Our Assignment

Our assignment is to enhance the search functionality of the 'project' field search by adding an option to search by date and order the search as "to" and "from" a a range of dates. Addition of these filters will help the user narrow her search, thereby improving the ergonomic functionality of the application.

Before adding the S3DateWidget. Option to search by date is not present

Solution

Implementation

This requires an understanding of the application and a fairly detailed understanding of the web2py framework and the interaction of the modules. The Eden application uses special widgets known as S3 widgets for performing tasks such as date searching in addition to many other tasks. Adding an S3DateWidget into the module associated with the projects page display incorporated the search functionality to specify a range of dates to search from. The S3DateWidget had to be mapped to the correct database entry in the Date object.

{
    S3DateFilter("start_date",
    label = T("Start Date")
    ),
    S3DateFilter("end_date",
    label = T("End Date")
    )
}

Here "start_date" and "end_date" are the database fields which have to be mapped. The text after label is the text that appears on the web page

After adding the S3DateWidget and mapping with the database entry.

Testing

The code was manually tested with test data. The projects were being filtered properly based on the start and end dates provided. If a date was not provided while creating the project, the search was not returning that result when searched on that field. For example, if one does not enter the 'State Date' while creating the project, this project will not be displayed if the search for 'Start Date' is performed.

Challenges

The biggest challenge we faced was understanding the flow of code using the Web2py framework. In addition to the application/controller/action code flow, mapping the method calls to the particular separate modules for each controller was something that was not easy at first. Backtracking the code to obtain the database entry for the table mapping was also something that we found challenging.

Future Scope

This project can be further extended to make further enhancements in the application, not just limited to date widgets, but also to the Business Logic and other UI enhancements. There is always a scope to pick up a new ticket and work on it to make Sahana web page better in every aspect.

References

1. Web2py
2. Sahana Eden Demo Site
3. Sahana Software Foundation
4. Sahana Eden Google Forum
5. Sahana Eden Developer Guidelines