User:Psdeo: Difference between revisions

From Expertiza_Wiki
Jump to navigation Jump to search
No edit summary
No edit summary
 
(One intermediate revision by the same user not shown)
Line 1: Line 1:
== Introduction: Automated Refactoring Techniques for AppCode ==
This wiki page contains design details for the project for Sahana Eden Humanitarian Platform, on their Central African Republic deployment.


AppCode<ref>http://en.wikipedia.org/wiki/AppCode</ref> is an [http://en.wikipedia.org/wiki/Integrated_development_environment Integrated Development Environment] (IDE) for Objective-C,C, C++, and JavaScript development built on [http://en.wikipedia.org/wiki/JetBrains JetBrains’] [http://en.wikipedia.org/wiki/IntelliJ_IDEA IntelliJ IDEA] platform, which is built on Java. Users can extend its abilities by either installing plug-ins created for IntelliJ Platform, or they can write their own plug-ins.
{| border="1" class="wikitable" style="float:{{{align|right}}}"
|colspan="2" align="center" |[[File:SahanaLogo.png|center|Sahana]]
|-


Code refactoring<ref>http://en.wikipedia.org/wiki/Code_refactoring </ref> is the process of restructuring existing computer code – changing the factoring – without changing its external behavior. Many a times, we face the need to change the name of a variable in our code- mostly because we find another one better suited for its functionality. Doing this manually can be time consuming & often leads to many mistakes. That is why, many new IDEs (Integrated Development Environments) come with inbuilt functions for refactoring. As you read further, you will know that refactoring is not limited to changing variable name. There are many things IDEs allow programmers to do to edit their code. These changes are not logical, in the sense that they do not make any change to functionality or behavior of the program; but are needed to improve code in terms of understanding & user friendliness.
== Background Information ==
====About Sahana Eden====
Sahana Eden is an Open Source Humanitarian Platform, which can be used to provide solutions for Disaster Management, Development, and Environmental Management sectors. It is supported by the  Sahana Software Foundation, Used in many Deployments, such as Ebola, Kashmir Floods, Hurricane Sandy, just to name a few. It is highly configurable so that it can be used in a wide variety of different contexts and is easy to modify to build custom solutions. Different levels of support are available from both the voluntary Sahana Eden community and professional companies. Sahana focuses on Community and Professional Support.


== Background ==
====Getting to know the domain====


"By continuously improving the design of code, we make it easier and easier to work with. This is in sharp contrast to what typically happens: little refactoring and a great deal of attention paid to expediently adding new features. If you get into the hygienic habit of refactoring continuously, you'll find that it is easier to extend and maintain code."
Their [http://eden.sahanafoundation.org/wiki/Domain domain] page elaborately describes various major management projects and deployments that are done in the past or are ongoing. Spending some time to understand goals and purposes of Sahana before starting with actual development might help making the code better and more sensible from Sahana's perspective.
—Joshua Kerievsky, Refactoring to Patterns


Refactoring improves nonfunctional attributes of the software. Advantages include improved code readability and reduced complexity to improve source code maintainability, and create a more expressive internal architecture or object model to improve extensibility. To help programmers easily improve code design as it evolves over time, AppCode provides a solid set of reliable code refactorings. These include vital ones like Rename, Extract Method, Introduce Variable and Inline, as well as more powerful ones, e.g. Extract Block Parameter/Protocol/Category/Superclass, Change Signature, Convert Method to Function and back, Pull Members Up/Push Members Down, and others. First public preview version of AppCode became available in April 2011. The latest stable release is version 3.0 and is available at JetBrains’ official web site.
====Installation & tutorials====


== Features of AppCode <ref>http://www.jetbrains.com/objc/features/</ref> ==
Anyone who wishes to contribute their development skill to Sahana, can do so with the help of an elaborate guide they have provided, that covers everything from [http://eden.sahanafoundation.org/wiki/InstallationGuidelines installation] to [http://eden.sahanafoundation.org/wiki/Book tutorials] on Python. Once the installations are complete, you can simply identify a task you are interested in, and start working on it. You may also want to sign their [https://docs.google.com/a/ncsu.edu/spreadsheet/viewform?formkey=dEp5czdPYThPY2htX2pNM1JGaTBrRGc6MQ#gid=0 Contributor's License Agreement] before making any pull request.


Below is a high level overview to begin contributing to Sahana-


'''Finest coding assistance'''
The code is in the folder: web2py/applications/eden
Context-aware editor gives you precise code completion choices due to deep understanding of your code structure, saves you from unnecessary typing by generating code, allows you to program by intention and minimize the routine tasks. AppCode automatically imports a class if it is not imported by the programmer in the code. Parameter Info(ctrl+P) assists the programmer in determining what exact parameters need to be passed to a method or function. Code reordering allows you to order your code. For example, to move block of code up or down, the following commands can be used:Cmd+Shift+Up/Down and for lines of code: Alt+Shift+Up/Down.
Such assistance allows user to concentrate more on the logic of program than its structure.


'''Reliable refactorings'''
Inside that folder are folders for Models (define the data structure), Controllers (provide URLs to enable access to the data) & Views (HTML templates).
Safe, accurate and reliable refactorings in AppCode allow you to modify and improve your code at any time. Whether you need to revive old code base, or brush up the project structure, you can always lean on AppCode. Various refactoring techniques mentioned below make it easy to refactor code.


'''Fast project navigation'''
Each module within Sahana Eden will normally consist of one of each of these files:
Navigations from a method to its declaration or any of its usages, through classes hierarchy or from one file to another are very easy to follow. Programmer can jump to any file, class, or symbol in your project in no time, or see all real usages of a symbol, not just text matches.


'''Code quality tracking'''
    Model: modules/s3db/modulename.py
On-the-fly code quality analysis for Objective-C, C, C++, JavaScript, CSS, HTML, XML and Xpath is done in AppCode. AppCode saves you from potential errors, and gives you hints when your code can be improved. Moreover, it comes with integrated [http://clang-analyzer.llvm.org Clang Static Analyzer].
    Controller: controllers/modulename.py
    View: views/modulename/index.html
'''Powerful debugger'''
Programmers can fine-tune apps or unit tests using a convenient debugger with flexible breakpoints, watches, frames view and evaluate expressions. With the help of conditional breakpoints in AppCode, one can have more control over the debugging process, and an option to log an evaluated message when a breakpoint is hit.


'''Seamless integrations'''
In order to know which file to edit in order to change a particular function, you need to look at the URL. The Web2Py web framework maps URLs as follows:
AppCode seamlessly integrates with the most popular version control systems, like Git, Mercurial, Perforce, etc.; Kiwi testing framework, Dash and Ingredients documentation tools, a number of issue trackers and provides 100% interoperability with Xcode. AppCode is also integrated with Reveal , a fantastic tool from Itty Bitty Apps  that helps debug iOS applications. You can experience the benefits of this tool right from AppCode, including the ability to inspect view elements and hierarchies of your iOS apps in real time, use the 2D and 3D visualization possibilities, and apply the view's editing on the fly, which is a convenient way to tweak the interface without recompiling.


== Refactoring Techniques in AppCode: <ref>http://www.integralist.co.uk/posts/refactoring-techniques/</ref> <ref>==
    http://host/application/controller/function
Automated Techniques used by AppCode are listed below:
=== Rename ===
By using this, one can rename a file, class, method, property, ivar, local variable, and so on. In the file or project view, the shortcut triggers renaming a file or a class. If you just are renaming a file (such as a plist or an image), AppCode will rename the file, and also change where it is referenced. If you are renaming a class, both the header, and the implementation of the class is renamed, and the references of the files in the project file. If you select Rename when the cursor is on a class name used by the class, the selected class is renamed. If you triggers the rename from inside the source file, the name of the class, variable, and so on, is entering a “edit mode,” like “Edit all in Scope,” in Xcode. The difference is that while in Xcode you renamed only the names inside the current class.


[[File:Rename.jpg]]
So, if you want to edit the Home page with the URL:


=== Change Signature ===
    http://host/eden/default/index
Often, a programmer needs to alter  a method signature. This can be to include an additional argument, or maybe the argument is not needed anymore, or even the order of the arguments is not right. If the method is called from several places, this can be a time-consuming and error prone task. By using AppCode, this is done in a simple and safe way. This is a really powerful feature in AppCode. You can also change the return type, and even convert a method to a function or a block, or vice versa.


=== Convert===
This implies that you should look at the file eden/controllers/default.py and the index function within it which can be found by searching for the function title "def index():"
Converting a method to a function or a block can also be done by using one of the Convert to menu items. In addition to these, you also have Convert to Property and Convert to Instance Variable.


=== Move===
Tip: Sahana Eden makes heavy use of integrated resource controllers so the typical mapping is:
Sometimes, a method may be defined in the wrong class. The Move refactoring tehnique allows you to move a property, variables and methods from one class to another. If the target class does not exist, you get a warning that tells you that. Once the method is moved, the previous parameters that were being sent to the method need to be cleaned up and it should be checked whether additional data needs to be passed over now via the method invocation.


=== Copy===
    http://host/eden/module/resource
In the project browser, when selecting a header, or an implementation file, or when inside one of these files, F5 will prompt you to enter the name of the new copy of the files, and where to copy them. While in the “To directory” input field ⌃␣ will provide path completion. When accepting, the class name inside the source files is changed as well.


===Safe Delete ===
The resource refers to a table with the name module_resource in the file modules/s3db/<module>.py
It is not very uncommon to implement something that you later find redundant or irrelevant in the code. Removing such implementations can be tricky. Manual deletions can lead to many misses & references to undefined data. That is where AppCode comes in handy. While deleting a class or a file, the programmer checks if that class or file is being used anywhere else in the program. Using Safe Delete, the programmer can be warned of any such multiple usages through a warning message. The search is also extended to comments and strings.


=== Extract===
==Introduction to project==


To quickly move code around in a full swing of refactoring, one can extract an expression to a variable or extract a full code block into a new method, and add a parameter to it using Introduce Parameter refactoring. This is a much mode tedious job than one can imagine & programmer can often lose the link of what needs to be changed while manipulating code for this.
====Overview====
In the Central African Republic page, some data needs new models, and some models need tweaking. The purpose of this project is to identify any such requirement and make necessary changes. The general steps to follow in Sahana development are mentioned below-


With Ctrl+T, AppCode shows what refactorings are suitable for the current context. The new Move refactoring allows you to move any class or member, or even a top level element, say a namespace through your project. Not only will AppCode move an element, but it will update the references, automatically manage imports and escalate visibility if needed. These might look as far fetched cases to a beginner; but when operating on a complex application that is being used for decades and has gone through many changes and additions over the years, these advanced refactoring techniques pose much more need than anticipated.
1. Add/modify the core models in modules/s3db


There are several Extract factoring’s, and here is a short description of each:
2. Add REST controllers for new models


'''Extract Method''' This is one of the most frequently used refactoring. Let say a method has too much responsibility, and you want to move some of the logic into a new method. AppCode generates a new method for you, including necessary parameters.
3. Check basic operations using automatic CRUD interface- tweak list_fields to the most-relevant fields perhaps


'''Extract Variable''' If there are some hard coded values in the code and we later feel the need to generalize the concept to a set of values, we would need to "Extract a variable". Here, AppCode will declare a variable above where it’s used, with the correct type, and the name of the new variable selected. To change the proposed name, just begin to type the name of the variable. If no value or expression is explicitly selected, AppCode gives you a suggestion of what to base the value of the introduced value from.
4. Add menu entries (modules/s3menus.py)


'''Extract Constant''' This refactoring is similar to Extract Variable, but this introduces a constant instead. If no actual value is selected, AppCode gives you an opportunity to select what the constant is based on from values and expressions in scope. When the constant is selected, AppCode asks for you if you would like to replace only this one, or all similar values found in the current file.
5. Develop XSLT & CSV templates (static/formats/s3csv) to bulk import the data


'''Extract Parameter''' This can be used if you are creating a variable inside a method, but you would like it to be passed as a parameter.
6. Convert the data to these CSV templates- use ogr2ogr for this


'''Extract Property''' By using this property on a variable, AppCode shows a dialog where the declaration of the property is shown, togheter with a checkbox. If you check the checkbox, the property is generated in a private category. If not, the property is declared in the header.
7. Add layers to the map (private/templates/<TEMPLATE>/gis_layer_feature.csv. Look at default for now) including Markers and tooltips (popup_format)


'''Extract Instance Variable''' By using this on a local variable, AppCode changes it into an ivar, but with the option to generate a property for the variable if the checkbox is selected. You can also select to declare the ivar in the interface (which you don’t want to do).
8. Provide some report_options to make a meaningful report


'''Extract Define''' Extracts a macro from the selected value or expression
====Scope====
Four modules related to this deployment are-


'''Extract Typedef''' As the name suggests, it creates a typdef from the selected type.
1. Health - modules/s3db/hms.py


'''Extract Block Parameter''' By using Extract Block Parameter you select a chunk of code. A block declaration based on the selected code is created, and the signature of the method is changed to take a block of this type. Finally, the existing usages of this method are changed so that the extracted block is passed as a parameter.
2. Transport - modules/s3db/transport.py


'''Extract Superclass''' To create a superclass from an existing class, the easiest way to accomplish this is to select the Extract Superclass. This refactoring does not have a default keyboard shortcut (You can create one yourself). You will be presented with a dialog where methods, properties, and ivars are shown in a list with checkboxes, and an input field where you type the name of the new superclass. You check the name of what you want to move into the new superclass. If one of the selected methods has dependencies to other methods, properties, or ivars, you get a warning, telling you about the problem.  
3. Water - modules/s3db/water.py


'''Extract Subclass''' Here you create a subclass from a superclass. You select which methods, ivars and properties you want to take with you into the new subclass.
4. School - There is no separate module for education.  


'''Extract Protocol and Category''' Similar to the two above, except you are extracting protocols and categories.
====Reference Material====


[[File:Extract.jpg]]
[http://www.humanitarianresponse.info/operations/central-african-republic/dataset/central-african-republic-health Hospital Model]


=== Inline ===
[http://geonode.wfp.org/layers/geonode:wld_poi_bcp_wfp Border Control Points], [http://www.humanitarianresponse.info/operations/central-african-republic/dataset/central-african-republic-roads Roads], [http://geonode.wfp.org/layers/geonode:wld_trs_supplyroutes_wfp Routes], [http://www.humanitarianresponse.info/operations/central-african-republic/dataset/central-african-republic-aerodromes-airports-airfields Airports]
If you want to inline a method, AppCode will move the implementation of the method into where it’s called from. If the method is called from more than one place, AppCode prompts you and asks for “Do you want to inline ‘n’ usages of method ‘methodName’? You options are: cancel the refactoring, execute the operation or view usages of the method you have selected to inline. If you select the latter, a list of usages is shown, and while navigating in this list, you can exclude the calls you don’t want to inline


[[File:Inline.jpg]]
[http://www.humanitarianresponse.info/operations/central-african-republic/dataset/central-african-republic-water-bodies Water Bodies], [http://www.humanitarianresponse.info/operations/central-african-republic/dataset/central-african-republic-water-bodies-0 Water Points], [http://www.humanitarianresponse.info/operations/central-african-republic/dataset/central-african-republic-water-courses Rivers]


=== Pull Up Method ===
[http://www.humanitarianresponse.info/operations/central-african-republic/dataset/central-african-republic-education Education]
We may end up creating methods in subclasses that essentially do the same thing. They can often be "pulled up" to their superclass. In this method of refactoring, such duplicated code across two separate classes is "pulled" into a super class so that we DRY (Don't Repeat Yourself) out the code and use it in multiple places without duplication (i.e, changes in future only have to happen in one place).


=== Push Down Method ===
==System Overview==
This is exact opposite of pull up. This is where a method is defined in superclass but not implemented in the same way in its subclasses. Then, AppCode allows us to "Push Down" such method to its subclasses & we can write different code in each.


== Comparison: Xcode vs AppCode ==
Sahana Eden Framework:
Another refactoring tool that is widely used and well known is Xcode. Xcode allows 6 types of refactoring techniques including 'create superclass', 'pull up','push down'. This is in contrast to the vast variety of techniques offered by AppCode. AppCode also provides keyboard shortcuts for faster refactoring. With each release, AppCode keeps getting better to suit the needs of programmers.


=References=
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.
<references/>
 
#[http://en.wikipedia.org/wiki/AppCode en.wikipedia.org/wiki/AppCode]
The Sahana Eden Framework has flexible authorization policies which can be configured to grant permissions for different modules, tables as well as the ability to have multiple Organizations control their own data on a single Sahana Eden installation.
#[http://www.integralist.co.uk/posts/refactoring-techniques www.integralist.co.uk/posts/refactoring-techniques ]
 
#[http://blog.bonkowski.net/blog/2013/02/10/refactoring-in-appcode blog.bonkowski.net/blog/2013/02/10/refactoring-in-appcode]
Sahana Eden can be downloaded and run locally from a flash drive. Synchronization functionality allows data to be entered then keep up to date between different installations, including online servers and local flash drive installations. The Sahana Eden Framework also includes a scheduler for running tasks at a specific time, in regular intervals or as asynchronous tasks which are triggered by users.
#[http://books.google.com/books?id=HmrDHwgkbPsC&printsec=frontcover#v=onepage&q&f=false Refactoring: Improving The Design of Existing Code- Martin Fowler]
 
#[http://codesheriff.blogspot.com/2012/02/xcode-vs-appcode.html Appcode vs Xcode]
Sahana Eden is mainly implemented using Python, web2py, CSS and foundation. When you open the code in Eclipse, you can see that web2py is very much like Ruby on Rails. Analyze the screenshots below-
 
 
[[File: workspace.png]][[File: workspace2.png]]
 
 
Our focus is on Controllers, Models, Modules and views. For every action on various pages on Sahana Humanitarian website, there are set of controllers defined. As mentioned above, we want to focus on 4 models- health, transport, water and school.
 
==System Architecture==
The basic Sahana Eden architecture is as follows:
 
<table style="width: 100%; border: 1px dotted rgb(0, 0, 0); border-collapse: collapse;" cellpadding="5"><tr><td style="border: 1px dotted rgb(0, 0, 0);"><strong>Web Server</strong></td>
<td style="border: 1px dotted rgb(0, 0, 0);">Apache</td>
<td style="border: 1px dotted rgb(0, 0, 0);">Other web servers can also be used, such as Cherokee.</td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);"><strong>Application</strong></td>
<td style="border: 1px dotted rgb(0, 0, 0);">Sahana Eden</td>
<td style="border: 1px dotted rgb(0, 0, 0);"></td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);"><strong>Web Application Framework</strong></td>
<td style="border: 1px dotted rgb(0, 0, 0);">Web2Py</td>
<td style="border: 1px dotted rgb(0, 0, 0);"></td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);"><strong>Programming Language</strong></td>
<td style="border: 1px dotted rgb(0, 0, 0);">Python &amp; Java Script</td>
<td style="border: 1px dotted rgb(0, 0, 0);"></td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);"><strong>Database</strong></td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, or SQLite</td>
<td style="border: 1px dotted rgb(0, 0, 0);"><p>MySQL, PostgreSQL, and SQLite are supported.</p><p>Other databases should be usable without major additional work since Web2Py supplies many connectors.</p></td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);"><strong>Operating System</strong></td>
<td style="border: 1px dotted rgb(0, 0, 0);">Linux (Debian recommended)</td>
<td style="border: 1px dotted rgb(0, 0, 0);">Windows and Mac OS X are possible, but only recommended for single-user environments.</td>
</tr></table>
 
==Requirement Analysis==
 
The requirements state that some of the data needs new models. Also, the school database states that there is no module for education. Even on the [http://www.humanitarianresponse.info/operations/central-african-republic/dataset/central-african-republic-education education website] of Central African Republic, it says that the data is incomplete. Addition of new module, say edu.py in s3db module, will solve this problem.
 
For the purpose of this project, we will need to follow these steps-
 
1. Installation and setup- Follow the installation guidlines provided by Sahana to build the system on individual machines. Then, do the setup for Git repository, i.e. forking Sahana eden repo and adding the original as remote branch.
 
2. Identify properties for "edu.py" and define the basic data model in the models/ folder.
 
3. Add corresponding controller which provides access to this resource. Create another new file, this time in the controllers/ folder.
 
4. Define Field Types- By default fields are created with type string, however we may wish to use other data types. All fields have both client-side widgets & server-side validation automatically added based on their data type.
 
5. Customize & Internationalize Field labels- Field labels are automatically generated from the field names, however we are able to customize these by adding a 'label' attribute.
 
6. Add Links to other Resources.
 
7. Override default CRUD Strings.
 
8. Update the Menus- There are two levels of menu within the system: The top-level 'Modules Menu' is visible in all modules. Underneath that, each module has its own menu for for module-specific navigation.
 
9. Test the changes.
 
==Design Principles==
 
For our project, the best design principle applicable is "Open Close Principle". Since we are introducing a new module, there will definitely be extensions to it, but very few modifications.
 
==Proposed Test Cases==
 
For end-user performance gains, Sahana Eden minimizes and compresses the CSS and JavaScript. While this approach works well for optimized end-user performance, to debug the CSS and JavaScript we shall enable debug mode in models/000_config.py  in our Sahana Eden server with the following setting:
 
  settings.base.debug = True
 
Once any changes to the CSS and JavaScript are working, then we can minimizes and compresses the CSS and JavaScript using:
 
  static/scripts/tools/build.sahana.py
 
Although this uses a web service, you get better results by downloading a local version of the Closure Compiler (a tool for making JavaScript download and run faster) to static/scripts/tools. It is also possible to quickly view a single page in debug mode by adding the ?debug=1 variable to the end of a URL.
 
==Further Reading==
[https://groups.google.com/forum/#!forum/sahana-eden Public Google Forum to discuss any development issues]
 
[http://sahanafoundation.org/sahana-launches-eurosha-humanitarian-data-site/ Sahana Launches EUROSHA Humanitarian Data Site]
 
[http://sahanafoundation.org/eurosha-volunteer-diary/ A EUROSHA Volunteer Diary]
 
[http://en.flossmanuals.net/sahana-eden/user-stories/ User stories]
 
[http://www.un.org/apps/news/story.asp?NewsID=49300#.VGLHHo_wbK8 Central African Republic: UN urges support to meet basic needs in hard-hit province]
 
[https://en.wikipedia.org/wiki/Central_African_Republic Wiki Page]
 
[https://www.youtube.com/watch?v=VoQAxQgevEA War in the Central African Republic (Full Length Documentary)]

Latest revision as of 03:55, 12 November 2014

This wiki page contains design details for the project for Sahana Eden Humanitarian Platform, on their Central African Republic deployment.

Background Information

About Sahana Eden

Sahana Eden is an Open Source Humanitarian Platform, which can be used to provide solutions for Disaster Management, Development, and Environmental Management sectors. It is supported by the Sahana Software Foundation, Used in many Deployments, such as Ebola, Kashmir Floods, Hurricane Sandy, just to name a few. It is highly configurable so that it can be used in a wide variety of different contexts and is easy to modify to build custom solutions. Different levels of support are available from both the voluntary Sahana Eden community and professional companies. Sahana focuses on Community and Professional Support.

Getting to know the domain

Their domain page elaborately describes various major management projects and deployments that are done in the past or are ongoing. Spending some time to understand goals and purposes of Sahana before starting with actual development might help making the code better and more sensible from Sahana's perspective.

Installation & tutorials

Anyone who wishes to contribute their development skill to Sahana, can do so with the help of an elaborate guide they have provided, that covers everything from installation to tutorials on Python. Once the installations are complete, you can simply identify a task you are interested in, and start working on it. You may also want to sign their Contributor's License Agreement before making any pull request.

Below is a high level overview to begin contributing to Sahana-

The code is in the folder: web2py/applications/eden

Inside that folder are folders for Models (define the data structure), Controllers (provide URLs to enable access to the data) & Views (HTML templates).

Each module within Sahana Eden will normally consist of one of each of these files: 

   Model: modules/s3db/modulename.py
   Controller: controllers/modulename.py
   View: views/modulename/index.html

In order to know which file to edit in order to change a particular function, you need to look at the URL. The Web2Py web framework maps URLs as follows: 

   http://host/application/controller/function

So, if you want to edit the Home page with the URL: 

   http://host/eden/default/index

This implies that you should look at the file eden/controllers/default.py and the index function within it which can be found by searching for the function title "def index():"

Tip: Sahana Eden makes heavy use of integrated resource controllers so the typical mapping is: 

   http://host/eden/module/resource

The resource refers to a table with the name module_resource in the file modules/s3db/<module>.py

Introduction to project

Overview

In the Central African Republic page, some data needs new models, and some models need tweaking. The purpose of this project is to identify any such requirement and make necessary changes. The general steps to follow in Sahana development are mentioned below-

1. Add/modify the core models in modules/s3db

2. Add REST controllers for new models

3. Check basic operations using automatic CRUD interface- tweak list_fields to the most-relevant fields perhaps

4. Add menu entries (modules/s3menus.py)

5. Develop XSLT & CSV templates (static/formats/s3csv) to bulk import the data

6. Convert the data to these CSV templates- use ogr2ogr for this

7. Add layers to the map (private/templates/<TEMPLATE>/gis_layer_feature.csv. Look at default for now) including Markers and tooltips (popup_format)

8. Provide some report_options to make a meaningful report

Scope

Four modules related to this deployment are-

1. Health - modules/s3db/hms.py

2. Transport - modules/s3db/transport.py

3. Water - modules/s3db/water.py

4. School - There is no separate module for education.

Reference Material

Hospital Model

Border Control Points, Roads, Routes, Airports

Water Bodies, Water Points, Rivers

Education

System Overview

Sahana Eden Framework:

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 Sahana Eden Framework has flexible authorization policies which can be configured to grant permissions for different modules, tables as well as the ability to have multiple Organizations control their own data on a single Sahana Eden installation.

Sahana Eden can be downloaded and run locally from a flash drive. Synchronization functionality allows data to be entered then keep up to date between different installations, including online servers and local flash drive installations. The Sahana Eden Framework also includes a scheduler for running tasks at a specific time, in regular intervals or as asynchronous tasks which are triggered by users.

Sahana Eden is mainly implemented using Python, web2py, CSS and foundation. When you open the code in Eclipse, you can see that web2py is very much like Ruby on Rails. Analyze the screenshots below-



Our focus is on Controllers, Models, Modules and views. For every action on various pages on Sahana Humanitarian website, there are set of controllers defined. As mentioned above, we want to focus on 4 models- health, transport, water and school.

System Architecture

The basic Sahana Eden architecture is as follows:

Sahana
Sahana
Web Server Apache Other web servers can also be used, such as Cherokee.
Application Sahana Eden
Web Application Framework Web2Py
Programming Language Python & Java Script
Database MySQL, PostgreSQL, or SQLite

MySQL, PostgreSQL, and SQLite are supported.

Other databases should be usable without major additional work since Web2Py supplies many connectors.
Operating System Linux (Debian recommended) Windows and Mac OS X are possible, but only recommended for single-user environments.

Requirement Analysis

The requirements state that some of the data needs new models. Also, the school database states that there is no module for education. Even on the education website of Central African Republic, it says that the data is incomplete. Addition of new module, say edu.py in s3db module, will solve this problem.

For the purpose of this project, we will need to follow these steps-

1. Installation and setup- Follow the installation guidlines provided by Sahana to build the system on individual machines. Then, do the setup for Git repository, i.e. forking Sahana eden repo and adding the original as remote branch.

2. Identify properties for "edu.py" and define the basic data model in the models/ folder.

3. Add corresponding controller which provides access to this resource. Create another new file, this time in the controllers/ folder.

4. Define Field Types- By default fields are created with type string, however we may wish to use other data types. All fields have both client-side widgets & server-side validation automatically added based on their data type.

5. Customize & Internationalize Field labels- Field labels are automatically generated from the field names, however we are able to customize these by adding a 'label' attribute.

6. Add Links to other Resources.

7. Override default CRUD Strings.

8. Update the Menus- There are two levels of menu within the system: The top-level 'Modules Menu' is visible in all modules. Underneath that, each module has its own menu for for module-specific navigation.

9. Test the changes.

Design Principles

For our project, the best design principle applicable is "Open Close Principle". Since we are introducing a new module, there will definitely be extensions to it, but very few modifications.

Proposed Test Cases

For end-user performance gains, Sahana Eden minimizes and compresses the CSS and JavaScript. While this approach works well for optimized end-user performance, to debug the CSS and JavaScript we shall enable debug mode in models/000_config.py in our Sahana Eden server with the following setting: 

 settings.base.debug = True

Once any changes to the CSS and JavaScript are working, then we can minimizes and compresses the CSS and JavaScript using: 

 static/scripts/tools/build.sahana.py

Although this uses a web service, you get better results by downloading a local version of the Closure Compiler (a tool for making JavaScript download and run faster) to static/scripts/tools. It is also possible to quickly view a single page in debug mode by adding the ?debug=1 variable to the end of a URL.

Further Reading

Public Google Forum to discuss any development issues

Sahana Launches EUROSHA Humanitarian Data Site

A EUROSHA Volunteer Diary

User stories

Central African Republic: UN urges support to meet basic needs in hard-hit province

Wiki Page

War in the Central African Republic (Full Length Documentary)

Retrieved from "https://wiki.expertiza.ncsu.edu/index.php?title=User:Psdeo&oldid=92019"