Expertiza_Wiki - User contributions [en]

CSC/ECE 517 Spring 2015 S1503 LWJZ

2015-04-24T03:44:29Z

Hwang40: /* Synchronization between server and local mobile application */

<big>S1503. Sahana Eden Mobile Client</big>

{| border="1" class="wikitable" style="float:{{{align|right}}}"
|colspan="2" align="center" |[[File:SahanaLogo.png|center|Sahana]]
|-

=Introduction=
==Purpose==
This project aims at adding new functions to the EdenMobile client app to serve users better.These functions will allow mobile users to add new shelters and hospitals, get information of hospitals and shelters offline/online, get GPS location of device, and provide multilingual support.

==Background==
===What’s 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 the latest evolution of Sahana Software which was initially developed by members of the information technology (IT) community in Sri Lanka to provide solutions for the relief effort following the 2004 Indian Ocean Tsunami.
<ref>[http://eden.sahanafoundation.org/ Sahana Eden Instroduction]</ref> 

===What does Sahana Eden do?===
Sahana Eden provides various of functions which are sorted in several different modules. 

'''Organization Registry''' 
*Sahana Eden’s Organization Registry can track what organizations do and organizations also could record their Offices, Warehouse and Field Sites including their locations so they can be mapped as well as links to other modules such as Human Resources, Assets and Inventory. 
'''Project Tracking''' 
*Sahana Eden provides a valuable tool which could tell people what are going on about the project to help organizations responding to disasters know where the greatest needs are and coordinate with others who are engaged in similar work. 
'''Human Resources''' 
*There are contact lists in Sahana Eden which can be access by users to ensure that the right people can be contacted at the right time. 
'''Inventory''' 
*Sahana Eden can be used to manage inventories of items and match requests for items with warehouses and other facilities which have them available. Sahana Eden can support multiple Catalogs of Items as well as providing alternative items to ensure more effective use of supplies. 
'''Assets''' 
*Sahana Eden is able to manage assets which are needed to respond to disasters, track where they are, who they have been assigned to, and what condition they are in. This ensures that assets are used effectively and efficiently. 
'''Assessments''' 
*Sahana Eden can be used to collect and analyze information from assessments to help organizations more effectively plan their disaster management activities. 
'''Scenarios & Events''' 
*To help organizations better plan for disasters, Sahana Eden can be used to plan for different scenarios, including recording what human resources, assets, facilities and tasks will be needed to effectively respond. 
'''Map''' 
*Sahana Eden has fully integrated mapping functionality which allows any location-based data to be visualized on a map. Maps provide situational awareness which is essential when either planning to prepare for or respond to a disaster. 
'''Shelter Management''' 
*When disasters are widespread and result in population displacement, understanding and tracking the landscape of shelters - and the people in them - is a critical activity. The Shelter Registry provides functionality to list and track information on shelters and on the people arriving and departing. 
'''Messaging''' 
*Sahana Eden provides support for messages to be sent to one or Distribution Groups by Email, SMS, Twitter and Google Talk. Interactive messages can also be set up to allow people to send short message queries to Sahana Eden and receive automatic responses. 

===Sahana Eden 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);">Web Server</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);">Application</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);">Web Application Framework</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);">Programming Language</td>
<td style="border: 1px dotted rgb(0, 0, 0);">Python & Java Script</td>
<td style="border: 1px dotted rgb(0, 0, 0);"></td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Database</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, or SQLite</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, and SQLite are supported.Other databases should be usable without major additional work since Web2Py supplies many connectors.</td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Operating System</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>

==Scope==
We will realize the signup, secure login and logout function, which would add new module into the following files:
*communication.js
*controller.js
*model.js
*view.js
We will make it available in multiple languages environment which will implement the languages fold.
We will add some new items including:“ hospital”, “vehicles” which will be added into the folder named “plugins”. The following file will be added into their corrsponding folders: 
Hospitals:
*mHospital.js (model)
*hospital.js, editHospital.js, hospital.html, hospital.css, editHospital.html (views)
*hospitalController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Vehicles:
*mVehicles.js (model)
*vehicles.js, editVehicles.js, vehicles.html, vehicles.css, editVehicles.html (views)
*vehiclesController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Also, we find some bugs and eliminate them. These could be any possible file in this project.

==Documentation==
former developer discussion about Sahana Oden
*An [https://docs.google.com/a/ncsu.edu/document/d/11bblC7klisYjN7Gjw6hDcs5TZ8uesJD3o2xnM2gI914/edit# overview of all the Sahana Eden projects]
*An [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework basic introduction] about the framework of Edenmobile including application design, source<ref>[http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework Edenmobile Introduction]</ref>
*An [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile#J2ME list] of all the requirements need to be done in this project.
*An [https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!forum/sahana-eden google discussion], explaining former problems developers met and corresponding solutions
*[https://github.com/szhao8/eden Open source code about Sahana Eden]<ref>[https://github.com/szhao8/eden Sahana Eden Github]</ref>
*[https://github.com/szhao8/EdenMobile Open source code about Eden Mobile]<ref>[https://github.com/szhao8/EdenMobile EdenMobile Github]</ref>

=Design=
==Overview==
In this design, we add several modules to the EdenMobile client app to allow mobile users to add new shelters and hospitals. Also, users can see the list of hospitals and shelters both offline and online and we can pass users' location to the nearest medical facilities. At last, a multilingual environment is also supported.
==Requirements==
The major requirements are that:
*Secure login;
*Multiple languages;
*users are able to work offline, and update forms and content when online;
*The initial forms that will be implemented are Hospitals, and Shelters;

==Architecture==

Below is the overview of the Eden Mobile Platform. It uses a Model-View-Controller design pattern as the foundation of the project. And it also introduces a "plugin" mechanism, from which developers can add new modules (pages) to the main menu by adding them to "plugins" folder.

[[File:S1503_Architecture.png |frame‎|center|Use Case Diagram]]

==Use Cases==

* '''1. Security Log in'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills login form, which includes username, password and Captcha code.
*** Submit form to Sahana Server. 
* '''2. Submit forms to server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to Sahana Server. 
* '''3. Submit forms to local storage'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to local database. 
* '''4. Download new forms from server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Download new forms from server 
* '''5. Synchronize local data with server '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Synchronize local data with server 
* '''6. Multi-Language Support '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Choose a language from settings page 
* The UML use case diagram is shown below:

[[File:S1503_Usecase.png‎ |frame|center|Use Case Diagram]]

=Implementation=
==Login==

The Sahana Eden website already has a login page, so our initial thought is to find the web service URL for login function, and use it in our log in page on Sahana Mobile. After scrutinize the python code of Sahana Eden, we found the login url, which is "localhost:8000/eden/default/user/login?_next=%2Feden%2Fdefault%2Findex", then we use this URL as the post destination and created the login page as follows:

[[File:S1503_Login.png]]

However, if we input the correct login information and then click "login" to post our login request, we will be redirected to the Sahana Eden's original login page, rather than log into the system, as the following picture shows. Unfortunately, we have found a solution to this problem.

[[File:S1503_LoginAfter.png]]

==Hospital plugin==
===Customize hospital form===
According to the [http://pastebin.com/Gj6nEnSu create.s3json file] in the hospital module on the official website, we create the hospital form in the Eden mobile application.
<pre>
var editHospitalForm = [
{
name: "name",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: "",
required: true
},
///*
{
name: "aka1",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "code",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "facility_type",
control: "integer",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "organisation_id",
control: "select"
},
{
name: "L0",
control: "select",
form_path: "$_gis_location/field",
data_path: "$_gis_location/field",
reference: "$k_location_id",
form: "gis-location-form",
common_name: "Country",
label: ""
},
{
name: "addr_street",
control: "string",
form_path: "$_gis_location/field",
data_path: "$_gis_location/field",
reference: "$k_location_id",
form: "gis-location-form",
label: ""
},
{
name: "addr_postcode",
control: "string",
form_path: "$_gis_location/field",
data_path: "$_gis_location/field",
reference: "$k_location_id",
form: "gis-location-form",
label: ""
},
{
name: "location",
control: "gis_button"
},
{
name: "address",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "postcode",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "city",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "phone_exchange",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "phone_business",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "phone_emergency",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "website",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "email",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "fax",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "obsolete",
control: "checkbox"
},
{
name: "footer",
control: "text"
}
];
</pre>
===Synchronization between server and local mobile application===
Utilizing the framework provided by the developer, we realized to synchronize hospital data from server to the local mobile application. You can see what we did in the following image. We create a new hospital name Hospital in the Sahana, after clicking the "save" button, the new hospital is saved in the server. Then if we click the "refresh list" the button in the mobile application, the new hospital will show in the view of our mobile application.

[[File:synchronization.gif]]

Another synchronization work is to submit forms from Mobile Client to Eden Server, as the picture below shows. Here we created a new shelter on Mobile Client and then clickec "Save", from the GIF we can see that the Mobile Client displayed the newly created shelter, then after refreshing the Eden Server, the shelter is showed int the server side too.

==Add Multilanguage Support==
===Development-before preparation===
This program is hosted by a very experienced software engineering, who set the blueprint of this whole program. So we communicated with him serval times to get a better understanding of the project need and expectation. Also, he introduced the framework he used and showed some little tricky to us on google group discussion. Then we understand a mapping relationship and the implementation details about how to build a multilanguage support.

[[File:mapping.png]]

===Code Changes===
The html button changes in languages.js:

<pre>
events: {
"click #Chinese-button": "onChinese",
"click #Bosnian-button": "onBosnian",
"click #French-button": "onFrench",
"click #English-button": "onEnglish"
},
</pre>
<pre>
onChinese: function (event) {
console.log("onChinese ");
var controller = app.controller.getControllerByModel("languages");
if (controller) {
controller.onChinese();
}
},
onEnglish: function (event) {
console.log("onEnglish ");
var controller = app.controller.getControllerByModel("languages");
if (controller) {
controller.onEnglish();
}
},
onBosnian: function (event) {
console.log("onBosnian ");
var controller = app.controller.getControllerByModel("languages");
if (controller) {
controller.onBosnian();
}
},
onFrench: function (event) {
console.log("onBosnian ");
var controller = app.controller.getControllerByModel("languages");
if (controller) {
controller.onFrench();
}
}
</pre>

The html button changes in languagesController.js:

<pre>
controller.prototype.init = function (options) {
$("#Chinese-button").on("click",this.onChinese.bind(this));
$("#Bosnian-button").on("click",this.onBosnian.bind(this));
$("#French-button").on("click",this.onFrench.bind(this));
$("#English-button").on("click",this.onEnglish.bind(this));
app.controller.setControllerByModel("languages", this);
};
</pre>
<pre>
controller.prototype.onChinese = function(evt) {
app.onChinese();
};
controller.prototype.onBosnian = function(evt) {
app.onBosnian();
};
controller.prototype.onFrench = function(evt) {
app.onFrench();
};
controller.prototype.onEnglish = function(evt) {
app.onEnglish();
};
app.pluginManager.addObject(controller);
</pre>

Code changes in index.js:

<pre>
onChinese: function(){
this.controller.translate();
},
onBosnian: function(){
this.controller.translateToBosnian();
},
onFrench: function(){
this.controller.translateToFrench();
},
onEnglish: function(){
this.controller.translateToEnglish();
},
</pre>

Our basic implementation translation in controller.js function goes like this:
<pre>
controller.prototype.translate = function(){
var language = 'Chinese';
//alert("asd");
$.ajax({
url: 'languages.xml',
success: function(xml) {
$(xml).find('translation').each(function(){
var id = $(this).attr('id');

var text = $(this).find(language).text();
$("." + id).html(text);
});
}
});
}
The rest omitted //
</pre>

languages.xml mapping information:
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<translations>
<translation id="translation">
<english>Hello there, how are you?</english>
<Chinese>你好</Chinese>
<Bosnian>Zdravo</Bosnian>
<French>Bonjour</French>
</translation>
<translation id="Shelter">
<english>Shelter Name</english>
<Chinese>避难所名称</Chinese>
<Bosnian>sklonište</Bosnian>
<French>nom de l'abri</French>
</translation>
<translation id="Address">
<english>Street Address</english>
<Chinese>地址</Chinese>
<Bosnian>adresa</Bosnian>
<French>adresse</French>
</translation>
<translation id="Postcode">
<english>Postcode</english>
<Chinese>邮编</Chinese>
<Bosnian>poštanski broj</Bosnian>
<French>code postal</French>
</translation>
<translation id="Phone">
<english>Phone</english>
<Chinese>电话</Chinese>
<Bosnian>telefon</Bosnian>
<French>téléphone</French>
</translation>
<translation id="Email">
<english>Email</english>
<Chinese>邮箱</Chinese>
<Bosnian>E-mail</Bosnian>
<French>E-mail</French>
</translation>
<translation id="Population">
<english>Estimated Population</english>
<Chinese>受灾人口</Chinese>
<Bosnian>pogođene populacije</Bosnian>
<French>la population touchée</French>
</translation>
<translation id="Day">
<english>Evacuees Capacity (Day and Night)</english>
<Chinese>容纳能力（全天）</Chinese>
<Bosnian>pogođene populacije (Dan i noć)</Bosnian>
<French>Capacité évacués(Jour et nuit)</French>
</translation>
<translation id="Night"><english>Evacuees Capacity (Night only)</english>
<Chinese>容纳能力（夜晚）</Chinese>
<Bosnian>pogođene populacije(noć)</Bosnian>
<French>Capacité évacués(nuit)</French>
</translation>
<translation id="Comments">
<english>Comments</english>
<Chinese>备注</Chinese>
<Bosnian>primjedba</Bosnian>
<French>commentaire</French>
</translation>

<translation id="Shelter1">
<english>Raleigh Rescue Mission</english>
<Chinese>罗利市救援中心</Chinese>
<Bosnian>Raleigh Grad U pomoć centar</Bosnian>
<French>Raliegh ville Aidez-Moi centre</French>
</translation>
<translation id="Address1">
<english>314 E Hargett St
Raleigh, NC</english>
<Chinese>北卡州罗利市东哈格特街314号</Chinese>
<Bosnian>314 istok hargett ulica Raleigh Grad,sjever Karolina</Bosnian>
<French>314 est hargett rue Raleigh ville, nord caroline</French>
</translation>
s
<translation id="Comments1">
<english>No Comments</english>
<Chinese>无备注</Chinese>
<Bosnian>Bez Napomene</Bosnian>
<French>aucun commentaire</French>
</translation>
</translations>
</pre>

===Multilanguage UI===
After serval times of discussion and communication, we finally realize the following UI. You can click the language you need to change to it. It's very easy-using and user comfortable. The following screenshot is what it looks like.

After clicking the English button, the English UI shows as following:

[[File:English.png]]

After clicking the Chinese button, the Chinese UI shows as following:

[[File:Chinese.png]]

After clicking the French button, the French UI shows as following:

[[File:French.png]]

After clicking the Bosnian button, the Bosnian UI shows as following:

[[File:Bosnian.png]]

=Troubleshooting=

1. When loading Sahana Eden Mobile's main page, browser console will print the following error message:

[[File:S1503_Error1.png‎ |frame|center|underscore-min.map not found error]]

The problem can be solved by downloading the file [https://github.com/jashkenas/underscore/blob/master/underscore-min.map underscore-min.map] and put it in the directory where underscore-min.js is stored. More information about this error can be found [http://stackoverflow.com/questions/18429625/missing-javascript-map-file-for-underscore-js-when-loading-asp-net-web-page here].

2. When adding multi-language module to Sahana Eden Mobile's main page, browser console will print the following error message:
After adding a language plugin module, users can see a new button called "Language", but it cannot be clicked and what makes worse is that the module affect other modules, for example, we cannot new a shelter. The framework is super complex and we are new here. After discussion, we write a email describing our problems to Tom Baker, the host developer, for help.

[[File:problem.png]]

After we received his short reply, we tried to follow his instruction to check some files but still get no idea what's our problem.

[[File:reply.png]]

Finally, we set breakpoints and used chrome's developer tool to help us debug. Fortunately, we found the an object is NULL, which affect the initiation. Then we found that in our controller there is a little error which leaded to this problem. After revised that, it run well now.

=References=
<references/>

CSC/ECE 517 Spring 2015 S1503 LWJZ

2015-04-24T03:18:07Z

Hwang40: /* Synchronization between server and local mobile application */

<big>S1503. Sahana Eden Mobile Client</big>

{| border="1" class="wikitable" style="float:{{{align|right}}}"
|colspan="2" align="center" |[[File:SahanaLogo.png|center|Sahana]]
|-

=Introduction=
==Purpose==
This project aims at adding new functions to the EdenMobile client app to serve users better.These functions will allow mobile users to add new shelters and hospitals, get information of hospitals and shelters offline/online, get GPS location of device, and provide multilingual support.

==Background==
===What’s 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 the latest evolution of Sahana Software which was initially developed by members of the information technology (IT) community in Sri Lanka to provide solutions for the relief effort following the 2004 Indian Ocean Tsunami.
<ref>[http://eden.sahanafoundation.org/ Sahana Eden Instroduction]</ref> 

===What does Sahana Eden do?===
Sahana Eden provides various of functions which are sorted in several different modules. 

'''Organization Registry''' 
*Sahana Eden’s Organization Registry can track what organizations do and organizations also could record their Offices, Warehouse and Field Sites including their locations so they can be mapped as well as links to other modules such as Human Resources, Assets and Inventory. 
'''Project Tracking''' 
*Sahana Eden provides a valuable tool which could tell people what are going on about the project to help organizations responding to disasters know where the greatest needs are and coordinate with others who are engaged in similar work. 
'''Human Resources''' 
*There are contact lists in Sahana Eden which can be access by users to ensure that the right people can be contacted at the right time. 
'''Inventory''' 
*Sahana Eden can be used to manage inventories of items and match requests for items with warehouses and other facilities which have them available. Sahana Eden can support multiple Catalogs of Items as well as providing alternative items to ensure more effective use of supplies. 
'''Assets''' 
*Sahana Eden is able to manage assets which are needed to respond to disasters, track where they are, who they have been assigned to, and what condition they are in. This ensures that assets are used effectively and efficiently. 
'''Assessments''' 
*Sahana Eden can be used to collect and analyze information from assessments to help organizations more effectively plan their disaster management activities. 
'''Scenarios & Events''' 
*To help organizations better plan for disasters, Sahana Eden can be used to plan for different scenarios, including recording what human resources, assets, facilities and tasks will be needed to effectively respond. 
'''Map''' 
*Sahana Eden has fully integrated mapping functionality which allows any location-based data to be visualized on a map. Maps provide situational awareness which is essential when either planning to prepare for or respond to a disaster. 
'''Shelter Management''' 
*When disasters are widespread and result in population displacement, understanding and tracking the landscape of shelters - and the people in them - is a critical activity. The Shelter Registry provides functionality to list and track information on shelters and on the people arriving and departing. 
'''Messaging''' 
*Sahana Eden provides support for messages to be sent to one or Distribution Groups by Email, SMS, Twitter and Google Talk. Interactive messages can also be set up to allow people to send short message queries to Sahana Eden and receive automatic responses. 

===Sahana Eden 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);">Web Server</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);">Application</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);">Web Application Framework</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);">Programming Language</td>
<td style="border: 1px dotted rgb(0, 0, 0);">Python & Java Script</td>
<td style="border: 1px dotted rgb(0, 0, 0);"></td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Database</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, or SQLite</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, and SQLite are supported.Other databases should be usable without major additional work since Web2Py supplies many connectors.</td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Operating System</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>

==Scope==
We will realize the signup, secure login and logout function, which would add new module into the following files:
*communication.js
*controller.js
*model.js
*view.js
We will make it available in multiple languages environment which will implement the languages fold.
We will add some new items including:“ hospital”, “vehicles” which will be added into the folder named “plugins”. The following file will be added into their corrsponding folders: 
Hospitals:
*mHospital.js (model)
*hospital.js, editHospital.js, hospital.html, hospital.css, editHospital.html (views)
*hospitalController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Vehicles:
*mVehicles.js (model)
*vehicles.js, editVehicles.js, vehicles.html, vehicles.css, editVehicles.html (views)
*vehiclesController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Also, we find some bugs and eliminate them. These could be any possible file in this project.

==Documentation==
former developer discussion about Sahana Oden
*An [https://docs.google.com/a/ncsu.edu/document/d/11bblC7klisYjN7Gjw6hDcs5TZ8uesJD3o2xnM2gI914/edit# overview of all the Sahana Eden projects]
*An [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework basic introduction] about the framework of Edenmobile including application design, source<ref>[http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework Edenmobile Introduction]</ref>
*An [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile#J2ME list] of all the requirements need to be done in this project.
*An [https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!forum/sahana-eden google discussion], explaining former problems developers met and corresponding solutions
*[https://github.com/szhao8/eden Open source code about Sahana Eden]<ref>[https://github.com/szhao8/eden Sahana Eden Github]</ref>
*[https://github.com/szhao8/EdenMobile Open source code about Eden Mobile]<ref>[https://github.com/szhao8/EdenMobile EdenMobile Github]</ref>

=Design=
==Overview==
In this design, we add several modules to the EdenMobile client app to allow mobile users to add new shelters and hospitals. Also, users can see the list of hospitals and shelters both offline and online and we can pass users' location to the nearest medical facilities. At last, a multilingual environment is also supported.
==Requirements==
The major requirements are that:
*Secure login;
*Multiple languages;
*users are able to work offline, and update forms and content when online;
*The initial forms that will be implemented are Hospitals, and Shelters;

==Architecture==

Below is the overview of the Eden Mobile Platform. It uses a Model-View-Controller design pattern as the foundation of the project. And it also introduces a "plugin" mechanism, from which developers can add new modules (pages) to the main menu by adding them to "plugins" folder.

[[File:S1503_Architecture.png |frame‎|center|Use Case Diagram]]

==Use Cases==

* '''1. Security Log in'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills login form, which includes username, password and Captcha code.
*** Submit form to Sahana Server. 
* '''2. Submit forms to server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to Sahana Server. 
* '''3. Submit forms to local storage'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to local database. 
* '''4. Download new forms from server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Download new forms from server 
* '''5. Synchronize local data with server '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Synchronize local data with server 
* '''6. Multi-Language Support '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Choose a language from settings page 
* The UML use case diagram is shown below:

[[File:S1503_Usecase.png‎ |frame|center|Use Case Diagram]]

=Implementation=
==Login==

The Sahana Eden website already has a login page, so our initial thought is to find the web service URL for login function, and use it in our log in page on Sahana Mobile. After scrutinize the python code of Sahana Eden, we found the login url, which is "localhost:8000/eden/default/user/login?_next=%2Feden%2Fdefault%2Findex", then we use this URL as the post destination and created the login page as follows:

[[File:S1503_Login.png]]

However, if we input the correct login information and then click "login" to post our login request, we will be redirected to the Sahana Eden's original login page, rather than log into the system, as the following picture shows. Unfortunately, we have found a solution to this problem.

[[File:S1503_LoginAfter.png]]

==Hospital plugin==
===Customize hospital form===
According to the [http://pastebin.com/Gj6nEnSu create.s3json file] in the hospital module on the official website, we create the hospital form in the Eden mobile application.
<pre>
var editHospitalForm = [
{
name: "name",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: "",
required: true
},
///*
{
name: "aka1",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "code",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "facility_type",
control: "integer",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "organisation_id",
control: "select"
},
{
name: "L0",
control: "select",
form_path: "$_gis_location/field",
data_path: "$_gis_location/field",
reference: "$k_location_id",
form: "gis-location-form",
common_name: "Country",
label: ""
},
{
name: "addr_street",
control: "string",
form_path: "$_gis_location/field",
data_path: "$_gis_location/field",
reference: "$k_location_id",
form: "gis-location-form",
label: ""
},
{
name: "addr_postcode",
control: "string",
form_path: "$_gis_location/field",
data_path: "$_gis_location/field",
reference: "$k_location_id",
form: "gis-location-form",
label: ""
},
{
name: "location",
control: "gis_button"
},
{
name: "address",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "postcode",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "city",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "phone_exchange",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "phone_business",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "phone_emergency",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "website",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "email",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "fax",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "obsolete",
control: "checkbox"
},
{
name: "footer",
control: "text"
}
];
</pre>
===Synchronization between server and local mobile application===
Utilizing the framework provided by the developer, we realized to synchronize hospital data from server to the local mobile application. You can see what we did in the following image. We create a new hospital name Hospital in the Sahana, after clicking the "save" button, the new hospital is saved in the server. Then if we click the "refresh list" the button in the mobile application, the new hospital will show in the view of our mobile application.

[[File:synchronization.gif]]

==Add Multilanguage Support==
===Development-before preparation===
This program is hosted by a very experienced software engineering, who set the blueprint of this whole program. So we communicated with him serval times to get a better understanding of the project need and expectation. Also, he introduced the framework he used and showed some little tricky to us on google group discussion. Then we understand a mapping relationship and the implementation details about how to build a multilanguage support.

[[File:mapping.png]]

===Code Changes===
The html button changes in languages.js:

<pre>
events: {
"click #Chinese-button": "onChinese",
"click #Bosnian-button": "onBosnian",
"click #French-button": "onFrench",
"click #English-button": "onEnglish"
},
</pre>
<pre>
onChinese: function (event) {
console.log("onChinese ");
var controller = app.controller.getControllerByModel("languages");
if (controller) {
controller.onChinese();
}
},
onEnglish: function (event) {
console.log("onEnglish ");
var controller = app.controller.getControllerByModel("languages");
if (controller) {
controller.onEnglish();
}
},
onBosnian: function (event) {
console.log("onBosnian ");
var controller = app.controller.getControllerByModel("languages");
if (controller) {
controller.onBosnian();
}
},
onFrench: function (event) {
console.log("onBosnian ");
var controller = app.controller.getControllerByModel("languages");
if (controller) {
controller.onFrench();
}
}
</pre>

The html button changes in languagesController.js:

<pre>
controller.prototype.init = function (options) {
$("#Chinese-button").on("click",this.onChinese.bind(this));
$("#Bosnian-button").on("click",this.onBosnian.bind(this));
$("#French-button").on("click",this.onFrench.bind(this));
$("#English-button").on("click",this.onEnglish.bind(this));
app.controller.setControllerByModel("languages", this);
};
</pre>
<pre>
controller.prototype.onChinese = function(evt) {
app.onChinese();
};
controller.prototype.onBosnian = function(evt) {
app.onBosnian();
};
controller.prototype.onFrench = function(evt) {
app.onFrench();
};
controller.prototype.onEnglish = function(evt) {
app.onEnglish();
};
app.pluginManager.addObject(controller);
</pre>

Code changes in index.js:

<pre>
onChinese: function(){
this.controller.translate();
},
onBosnian: function(){
this.controller.translateToBosnian();
},
onFrench: function(){
this.controller.translateToFrench();
},
onEnglish: function(){
this.controller.translateToEnglish();
},
</pre>

Our basic implementation translation in controller.js function goes like this:
<pre>
controller.prototype.translate = function(){
var language = 'Chinese';
//alert("asd");
$.ajax({
url: 'languages.xml',
success: function(xml) {
$(xml).find('translation').each(function(){
var id = $(this).attr('id');

var text = $(this).find(language).text();
$("." + id).html(text);
});
}
});
}
The rest omitted //
</pre>

languages.xml mapping information:
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<translations>
<translation id="translation">
<english>Hello there, how are you?</english>
<Chinese>你好</Chinese>
<Bosnian>Zdravo</Bosnian>
<French>Bonjour</French>
</translation>
<translation id="Shelter">
<english>Shelter Name</english>
<Chinese>避难所名称</Chinese>
<Bosnian>sklonište</Bosnian>
<French>nom de l'abri</French>
</translation>
<translation id="Address">
<english>Street Address</english>
<Chinese>地址</Chinese>
<Bosnian>adresa</Bosnian>
<French>adresse</French>
</translation>
<translation id="Postcode">
<english>Postcode</english>
<Chinese>邮编</Chinese>
<Bosnian>poštanski broj</Bosnian>
<French>code postal</French>
</translation>
<translation id="Phone">
<english>Phone</english>
<Chinese>电话</Chinese>
<Bosnian>telefon</Bosnian>
<French>téléphone</French>
</translation>
<translation id="Email">
<english>Email</english>
<Chinese>邮箱</Chinese>
<Bosnian>E-mail</Bosnian>
<French>E-mail</French>
</translation>
<translation id="Population">
<english>Estimated Population</english>
<Chinese>受灾人口</Chinese>
<Bosnian>pogođene populacije</Bosnian>
<French>la population touchée</French>
</translation>
<translation id="Day">
<english>Evacuees Capacity (Day and Night)</english>
<Chinese>容纳能力（全天）</Chinese>
<Bosnian>pogođene populacije (Dan i noć)</Bosnian>
<French>Capacité évacués(Jour et nuit)</French>
</translation>
<translation id="Night"><english>Evacuees Capacity (Night only)</english>
<Chinese>容纳能力（夜晚）</Chinese>
<Bosnian>pogođene populacije(noć)</Bosnian>
<French>Capacité évacués(nuit)</French>
</translation>
<translation id="Comments">
<english>Comments</english>
<Chinese>备注</Chinese>
<Bosnian>primjedba</Bosnian>
<French>commentaire</French>
</translation>

<translation id="Shelter1">
<english>Raleigh Rescue Mission</english>
<Chinese>罗利市救援中心</Chinese>
<Bosnian>Raleigh Grad U pomoć centar</Bosnian>
<French>Raliegh ville Aidez-Moi centre</French>
</translation>
<translation id="Address1">
<english>314 E Hargett St
Raleigh, NC</english>
<Chinese>北卡州罗利市东哈格特街314号</Chinese>
<Bosnian>314 istok hargett ulica Raleigh Grad,sjever Karolina</Bosnian>
<French>314 est hargett rue Raleigh ville, nord caroline</French>
</translation>
s
<translation id="Comments1">
<english>No Comments</english>
<Chinese>无备注</Chinese>
<Bosnian>Bez Napomene</Bosnian>
<French>aucun commentaire</French>
</translation>
</translations>
</pre>

===Multilanguage UI===
After serval times of discussion and communication, we finally realize the following UI. You can click the language you need to change to it. It's very easy-using and user comfortable. The following screenshot is what it looks like.

After clicking the English button, the English UI shows as following:

[[File:English.png]]

After clicking the Chinese button, the Chinese UI shows as following:

[[File:Chinese.png]]

After clicking the French button, the French UI shows as following:

[[File:French.png]]

After clicking the Bosnian button, the Bosnian UI shows as following:

[[File:Bosnian.png]]

=Troubleshooting=

1. When loading Sahana Eden Mobile's main page, browser console will print the following error message:

[[File:S1503_Error1.png‎ |frame|center|underscore-min.map not found error]]

The problem can be solved by downloading the file [https://github.com/jashkenas/underscore/blob/master/underscore-min.map underscore-min.map] and put it in the directory where underscore-min.js is stored. More information about this error can be found [http://stackoverflow.com/questions/18429625/missing-javascript-map-file-for-underscore-js-when-loading-asp-net-web-page here].

2. When adding multi-language module to Sahana Eden Mobile's main page, browser console will print the following error message:
After adding a language plugin module, users can see a new button called "Language", but it cannot be clicked and what makes worse is that the module affect other modules, for example, we cannot new a shelter. The framework is super complex and we are new here. After discussion, we write a email describing our problems to Tom Baker, the host developer, for help.

[[File:problem.png]]

After we received his short reply, we tried to follow his instruction to check some files but still get no idea what's our problem.

[[File:reply.png]]

Finally, we set breakpoints and used chrome's developer tool to help us debug. Fortunately, we found the an object is NULL, which affect the initiation. Then we found that in our controller there is a little error which leaded to this problem. After revised that, it run well now.

=References=
<references/>

CSC/ECE 517 Spring 2015 S1503 LWJZ

2015-04-24T02:57:57Z

Hwang40: /* Login */

<big>S1503. Sahana Eden Mobile Client</big>

{| border="1" class="wikitable" style="float:{{{align|right}}}"
|colspan="2" align="center" |[[File:SahanaLogo.png|center|Sahana]]
|-

=Introduction=
==Purpose==
This project aims at adding new functions to the EdenMobile client app to serve users better.These functions will allow mobile users to add new shelters and hospitals, get information of hospitals and shelters offline/online, get GPS location of device, and provide multilingual support.

==Background==
===What’s 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 the latest evolution of Sahana Software which was initially developed by members of the information technology (IT) community in Sri Lanka to provide solutions for the relief effort following the 2004 Indian Ocean Tsunami.
<ref>[http://eden.sahanafoundation.org/ Sahana Eden Instroduction]</ref> 

===What does Sahana Eden do?===
Sahana Eden provides various of functions which are sorted in several different modules. 

'''Organization Registry''' 
*Sahana Eden’s Organization Registry can track what organizations do and organizations also could record their Offices, Warehouse and Field Sites including their locations so they can be mapped as well as links to other modules such as Human Resources, Assets and Inventory. 
'''Project Tracking''' 
*Sahana Eden provides a valuable tool which could tell people what are going on about the project to help organizations responding to disasters know where the greatest needs are and coordinate with others who are engaged in similar work. 
'''Human Resources''' 
*There are contact lists in Sahana Eden which can be access by users to ensure that the right people can be contacted at the right time. 
'''Inventory''' 
*Sahana Eden can be used to manage inventories of items and match requests for items with warehouses and other facilities which have them available. Sahana Eden can support multiple Catalogs of Items as well as providing alternative items to ensure more effective use of supplies. 
'''Assets''' 
*Sahana Eden is able to manage assets which are needed to respond to disasters, track where they are, who they have been assigned to, and what condition they are in. This ensures that assets are used effectively and efficiently. 
'''Assessments''' 
*Sahana Eden can be used to collect and analyze information from assessments to help organizations more effectively plan their disaster management activities. 
'''Scenarios & Events''' 
*To help organizations better plan for disasters, Sahana Eden can be used to plan for different scenarios, including recording what human resources, assets, facilities and tasks will be needed to effectively respond. 
'''Map''' 
*Sahana Eden has fully integrated mapping functionality which allows any location-based data to be visualized on a map. Maps provide situational awareness which is essential when either planning to prepare for or respond to a disaster. 
'''Shelter Management''' 
*When disasters are widespread and result in population displacement, understanding and tracking the landscape of shelters - and the people in them - is a critical activity. The Shelter Registry provides functionality to list and track information on shelters and on the people arriving and departing. 
'''Messaging''' 
*Sahana Eden provides support for messages to be sent to one or Distribution Groups by Email, SMS, Twitter and Google Talk. Interactive messages can also be set up to allow people to send short message queries to Sahana Eden and receive automatic responses. 

===Sahana Eden 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);">Web Server</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);">Application</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);">Web Application Framework</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);">Programming Language</td>
<td style="border: 1px dotted rgb(0, 0, 0);">Python & Java Script</td>
<td style="border: 1px dotted rgb(0, 0, 0);"></td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Database</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, or SQLite</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, and SQLite are supported.Other databases should be usable without major additional work since Web2Py supplies many connectors.</td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Operating System</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>

==Scope==
We will realize the signup, secure login and logout function, which would add new module into the following files:
*communication.js
*controller.js
*model.js
*view.js
We will make it available in multiple languages environment which will implement the languages fold.
We will add some new items including:“ hospital”, “vehicles” which will be added into the folder named “plugins”. The following file will be added into their corrsponding folders: 
Hospitals:
*mHospital.js (model)
*hospital.js, editHospital.js, hospital.html, hospital.css, editHospital.html (views)
*hospitalController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Vehicles:
*mVehicles.js (model)
*vehicles.js, editVehicles.js, vehicles.html, vehicles.css, editVehicles.html (views)
*vehiclesController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Also, we find some bugs and eliminate them. These could be any possible file in this project.

==Documentation==
former developer discussion about Sahana Oden
*An [https://docs.google.com/a/ncsu.edu/document/d/11bblC7klisYjN7Gjw6hDcs5TZ8uesJD3o2xnM2gI914/edit# overview of all the Sahana Eden projects]
*An [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework basic introduction] about the framework of Edenmobile including application design, source<ref>[http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework Edenmobile Introduction]</ref>
*An [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile#J2ME list] of all the requirements need to be done in this project.
*An [https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!forum/sahana-eden google discussion], explaining former problems developers met and corresponding solutions
*[https://github.com/szhao8/eden Open source code about Sahana Eden]<ref>[https://github.com/szhao8/eden Sahana Eden Github]</ref>
*[https://github.com/szhao8/EdenMobile Open source code about Eden Mobile]<ref>[https://github.com/szhao8/EdenMobile EdenMobile Github]</ref>

=Design=
==Overview==
In this design, we add several modules to the EdenMobile client app to allow mobile users to add new shelters and hospitals. Also, users can see the list of hospitals and shelters both offline and online and we can pass users' location to the nearest medical facilities. At last, a multilingual environment is also supported.
==Requirements==
The major requirements are that:
*Secure login;
*Multiple languages;
*users are able to work offline, and update forms and content when online;
*The initial forms that will be implemented are Hospitals, and Shelters;

==Architecture==

Below is the overview of the Eden Mobile Platform. It uses a Model-View-Controller design pattern as the foundation of the project. And it also introduces a "plugin" mechanism, from which developers can add new modules (pages) to the main menu by adding them to "plugins" folder.

[[File:S1503_Architecture.png |frame‎|center|Use Case Diagram]]

==Use Cases==

* '''1. Security Log in'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills login form, which includes username, password and Captcha code.
*** Submit form to Sahana Server. 
* '''2. Submit forms to server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to Sahana Server. 
* '''3. Submit forms to local storage'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to local database. 
* '''4. Download new forms from server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Download new forms from server 
* '''5. Synchronize local data with server '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Synchronize local data with server 
* '''6. Multi-Language Support '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Choose a language from settings page 
* The UML use case diagram is shown below:

[[File:S1503_Usecase.png‎ |frame|center|Use Case Diagram]]

=Implementation=
==Login==

The Sahana Eden website already has a login page, so our initial thought is to find the web service URL for login function, and use it in our log in page on Sahana Mobile. After scrutinize the python code of Sahana Eden, we found the login url, which is "localhost:8000/eden/default/user/login?_next=%2Feden%2Fdefault%2Findex", then we use this URL as the post destination and created the login page as follows:

[[File:S1503_Login.jpg]]

However, if we input the correct login information and then click "login" to post our login request, we will be redirected to the Sahana Eden's original login page, rather than log into the system, as the following picture shows. Unfortunately, we have found a solution to this problem.

[[File:S1503_LoginAfter.jpg]]

==Hospital plugin==
===Customize hospital form===
According to the [http://pastebin.com/Gj6nEnSu create.s3json file] in the hospital module on the official website, we create the hospital form in the Eden mobile application.
<pre>
var editHospitalForm = [
{
name: "name",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: "",
required: true
},
///*
{
name: "aka1",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "code",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "facility_type",
control: "integer",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "organisation_id",
control: "select"
},
{
name: "L0",
control: "select",
form_path: "$_gis_location/field",
data_path: "$_gis_location/field",
reference: "$k_location_id",
form: "gis-location-form",
common_name: "Country",
label: ""
},
{
name: "addr_street",
control: "string",
form_path: "$_gis_location/field",
data_path: "$_gis_location/field",
reference: "$k_location_id",
form: "gis-location-form",
label: ""
},
{
name: "addr_postcode",
control: "string",
form_path: "$_gis_location/field",
data_path: "$_gis_location/field",
reference: "$k_location_id",
form: "gis-location-form",
label: ""
},
{
name: "location",
control: "gis_button"
},
{
name: "address",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "postcode",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "city",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "phone_exchange",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "phone_business",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "phone_emergency",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "website",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "email",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "fax",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "obsolete",
control: "checkbox"
},
{
name: "footer",
control: "text"
}
];
</pre>
===Synchronization between server and local mobile application===
Utilizing the framework provided by the developer, we realized to synchronize hospital data from server to the local mobile application. You can see what we did in the following image. We create a new hospital name Hospital in the Sahana, after clicking the "save" button, the new hospital is saved in the server. Then if we click the "refresh list" the button in the mobile application, the new hospital will show in the view of our mobile application.

[[File:synchronization.gif]]

==Add Multilanguage Support==
===Development-before preparation===
This program is hosted by a very experienced software engineering, who set the blueprint of this whole program. So we communicated with him serval times to get a better understanding of the project need and expectation. Also, he introduced the framework he used and showed some little tricky to us on google group discussion. Then we understand a mapping relationship and the implementation details about how to build a multilanguage support.

[[File:mapping.png]]

===Code Changes===
The html button changes in languages.js:

<pre>
events: {
"click #Chinese-button": "onChinese",
"click #Bosnian-button": "onBosnian",
"click #French-button": "onFrench",
"click #English-button": "onEnglish"
},
</pre>
<pre>
onChinese: function (event) {
console.log("onChinese ");
var controller = app.controller.getControllerByModel("languages");
if (controller) {
controller.onChinese();
}
},
onEnglish: function (event) {
console.log("onEnglish ");
var controller = app.controller.getControllerByModel("languages");
if (controller) {
controller.onEnglish();
}
},
onBosnian: function (event) {
console.log("onBosnian ");
var controller = app.controller.getControllerByModel("languages");
if (controller) {
controller.onBosnian();
}
},
onFrench: function (event) {
console.log("onBosnian ");
var controller = app.controller.getControllerByModel("languages");
if (controller) {
controller.onFrench();
}
}
</pre>

The html button changes in languagesController.js:

<pre>
controller.prototype.init = function (options) {
$("#Chinese-button").on("click",this.onChinese.bind(this));
$("#Bosnian-button").on("click",this.onBosnian.bind(this));
$("#French-button").on("click",this.onFrench.bind(this));
$("#English-button").on("click",this.onEnglish.bind(this));
app.controller.setControllerByModel("languages", this);
};
</pre>
<pre>
controller.prototype.onChinese = function(evt) {
app.onChinese();
};
controller.prototype.onBosnian = function(evt) {
app.onBosnian();
};
controller.prototype.onFrench = function(evt) {
app.onFrench();
};
controller.prototype.onEnglish = function(evt) {
app.onEnglish();
};
app.pluginManager.addObject(controller);
</pre>

Code changes in index.js:

<pre>
onChinese: function(){
this.controller.translate();
},
onBosnian: function(){
this.controller.translateToBosnian();
},
onFrench: function(){
this.controller.translateToFrench();
},
onEnglish: function(){
this.controller.translateToEnglish();
},
</pre>

Our basic implementation translation in controller.js function goes like this:
<pre>
controller.prototype.translate = function(){
var language = 'Chinese';
//alert("asd");
$.ajax({
url: 'languages.xml',
success: function(xml) {
$(xml).find('translation').each(function(){
var id = $(this).attr('id');

var text = $(this).find(language).text();
$("." + id).html(text);
});
}
});
}
The rest omitted //
</pre>

languages.xml mapping information:
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<translations>
<translation id="translation">
<english>Hello there, how are you?</english>
<Chinese>你好</Chinese>
<Bosnian>Zdravo</Bosnian>
<French>Bonjour</French>
</translation>
<translation id="Shelter">
<english>Shelter Name</english>
<Chinese>避难所名称</Chinese>
<Bosnian>sklonište</Bosnian>
<French>nom de l'abri</French>
</translation>
<translation id="Address">
<english>Street Address</english>
<Chinese>地址</Chinese>
<Bosnian>adresa</Bosnian>
<French>adresse</French>
</translation>
<translation id="Postcode">
<english>Postcode</english>
<Chinese>邮编</Chinese>
<Bosnian>poštanski broj</Bosnian>
<French>code postal</French>
</translation>
<translation id="Phone">
<english>Phone</english>
<Chinese>电话</Chinese>
<Bosnian>telefon</Bosnian>
<French>téléphone</French>
</translation>
<translation id="Email">
<english>Email</english>
<Chinese>邮箱</Chinese>
<Bosnian>E-mail</Bosnian>
<French>E-mail</French>
</translation>
<translation id="Population">
<english>Estimated Population</english>
<Chinese>受灾人口</Chinese>
<Bosnian>pogođene populacije</Bosnian>
<French>la population touchée</French>
</translation>
<translation id="Day">
<english>Evacuees Capacity (Day and Night)</english>
<Chinese>容纳能力（全天）</Chinese>
<Bosnian>pogođene populacije (Dan i noć)</Bosnian>
<French>Capacité évacués(Jour et nuit)</French>
</translation>
<translation id="Night"><english>Evacuees Capacity (Night only)</english>
<Chinese>容纳能力（夜晚）</Chinese>
<Bosnian>pogođene populacije(noć)</Bosnian>
<French>Capacité évacués(nuit)</French>
</translation>
<translation id="Comments">
<english>Comments</english>
<Chinese>备注</Chinese>
<Bosnian>primjedba</Bosnian>
<French>commentaire</French>
</translation>

<translation id="Shelter1">
<english>Raleigh Rescue Mission</english>
<Chinese>罗利市救援中心</Chinese>
<Bosnian>Raleigh Grad U pomoć centar</Bosnian>
<French>Raliegh ville Aidez-Moi centre</French>
</translation>
<translation id="Address1">
<english>314 E Hargett St
Raleigh, NC</english>
<Chinese>北卡州罗利市东哈格特街314号</Chinese>
<Bosnian>314 istok hargett ulica Raleigh Grad,sjever Karolina</Bosnian>
<French>314 est hargett rue Raleigh ville, nord caroline</French>
</translation>
s
<translation id="Comments1">
<english>No Comments</english>
<Chinese>无备注</Chinese>
<Bosnian>Bez Napomene</Bosnian>
<French>aucun commentaire</French>
</translation>
</translations>
</pre>

===Multilanguage UI===
After serval times of discussion and communication, we finally realize the following UI. You can click the language you need to change to it. It's very easy-using and user comfortable. The following screenshot is what it looks like.

After clicking the English button, the English UI shows as following:

[[File:English.png]]

After clicking the Chinese button, the Chinese UI shows as following:

[[File:Chinese.png]]

After clicking the French button, the French UI shows as following:

[[File:French.png]]

After clicking the Bosnian button, the Bosnian UI shows as following:

[[File:Bosnian.png]]

=Troubleshooting=

1. When loading Sahana Eden Mobile's main page, browser console will print the following error message:

[[File:S1503_Error1.png‎ |frame|center|underscore-min.map not found error]]

The problem can be solved by downloading the file [https://github.com/jashkenas/underscore/blob/master/underscore-min.map underscore-min.map] and put it in the directory where underscore-min.js is stored. More information about this error can be found [http://stackoverflow.com/questions/18429625/missing-javascript-map-file-for-underscore-js-when-loading-asp-net-web-page here].

2. When adding multi-language module to Sahana Eden Mobile's main page, browser console will print the following error message:
After adding a language plugin module, users can see a new button called "Language", but it cannot be clicked and what makes worse is that the module affect other modules, for example, we cannot new a shelter. The framework is super complex and we are new here. After discussion, we write a email describing our problems to Tom Baker, the host developer, for help.

[[File:problem.png]]

After we received his short reply, we tried to follow his instruction to check some files but still get no idea what's our problem.

[[File:reply.png]]

Finally, we set breakpoints and used chrome's developer tool to help us debug. Fortunately, we found the an object is NULL, which affect the initiation. Then we found that in our controller there is a little error which leaded to this problem. After revised that, it run well now.

=References=
<references/>

CSC/ECE 517 Spring 2015 S1503 LWJZ

2015-04-24T02:47:47Z

Hwang40: /* Login */

<big>S1503. Sahana Eden Mobile Client</big>

{| border="1" class="wikitable" style="float:{{{align|right}}}"
|colspan="2" align="center" |[[File:SahanaLogo.png|center|Sahana]]
|-

=Introduction=
==Purpose==
This project aims at adding new functions to the EdenMobile client app to serve users better.These functions will allow mobile users to add new shelters and hospitals, get information of hospitals and shelters offline/online, get GPS location of device, and provide multilingual support.

==Background==
===What’s 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 the latest evolution of Sahana Software which was initially developed by members of the information technology (IT) community in Sri Lanka to provide solutions for the relief effort following the 2004 Indian Ocean Tsunami.
<ref>[http://eden.sahanafoundation.org/ Sahana Eden Instroduction]</ref> 

===What does Sahana Eden do?===
Sahana Eden provides various of functions which are sorted in several different modules. 

'''Organization Registry''' 
*Sahana Eden’s Organization Registry can track what organizations do and organizations also could record their Offices, Warehouse and Field Sites including their locations so they can be mapped as well as links to other modules such as Human Resources, Assets and Inventory. 
'''Project Tracking''' 
*Sahana Eden provides a valuable tool which could tell people what are going on about the project to help organizations responding to disasters know where the greatest needs are and coordinate with others who are engaged in similar work. 
'''Human Resources''' 
*There are contact lists in Sahana Eden which can be access by users to ensure that the right people can be contacted at the right time. 
'''Inventory''' 
*Sahana Eden can be used to manage inventories of items and match requests for items with warehouses and other facilities which have them available. Sahana Eden can support multiple Catalogs of Items as well as providing alternative items to ensure more effective use of supplies. 
'''Assets''' 
*Sahana Eden is able to manage assets which are needed to respond to disasters, track where they are, who they have been assigned to, and what condition they are in. This ensures that assets are used effectively and efficiently. 
'''Assessments''' 
*Sahana Eden can be used to collect and analyze information from assessments to help organizations more effectively plan their disaster management activities. 
'''Scenarios & Events''' 
*To help organizations better plan for disasters, Sahana Eden can be used to plan for different scenarios, including recording what human resources, assets, facilities and tasks will be needed to effectively respond. 
'''Map''' 
*Sahana Eden has fully integrated mapping functionality which allows any location-based data to be visualized on a map. Maps provide situational awareness which is essential when either planning to prepare for or respond to a disaster. 
'''Shelter Management''' 
*When disasters are widespread and result in population displacement, understanding and tracking the landscape of shelters - and the people in them - is a critical activity. The Shelter Registry provides functionality to list and track information on shelters and on the people arriving and departing. 
'''Messaging''' 
*Sahana Eden provides support for messages to be sent to one or Distribution Groups by Email, SMS, Twitter and Google Talk. Interactive messages can also be set up to allow people to send short message queries to Sahana Eden and receive automatic responses. 

===Sahana Eden 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);">Web Server</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);">Application</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);">Web Application Framework</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);">Programming Language</td>
<td style="border: 1px dotted rgb(0, 0, 0);">Python & Java Script</td>
<td style="border: 1px dotted rgb(0, 0, 0);"></td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Database</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, or SQLite</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, and SQLite are supported.Other databases should be usable without major additional work since Web2Py supplies many connectors.</td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Operating System</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>

==Scope==
We will realize the signup, secure login and logout function, which would add new module into the following files:
*communication.js
*controller.js
*model.js
*view.js
We will make it available in multiple languages environment which will implement the languages fold.
We will add some new items including:“ hospital”, “vehicles” which will be added into the folder named “plugins”. The following file will be added into their corrsponding folders: 
Hospitals:
*mHospital.js (model)
*hospital.js, editHospital.js, hospital.html, hospital.css, editHospital.html (views)
*hospitalController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Vehicles:
*mVehicles.js (model)
*vehicles.js, editVehicles.js, vehicles.html, vehicles.css, editVehicles.html (views)
*vehiclesController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Also, we find some bugs and eliminate them. These could be any possible file in this project.

==Documentation==
former developer discussion about Sahana Oden
*An [https://docs.google.com/a/ncsu.edu/document/d/11bblC7klisYjN7Gjw6hDcs5TZ8uesJD3o2xnM2gI914/edit# overview of all the Sahana Eden projects]
*An [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework basic introduction] about the framework of Edenmobile including application design, source<ref>[http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework Edenmobile Introduction]</ref>
*An [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile#J2ME list] of all the requirements need to be done in this project.
*An [https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!forum/sahana-eden google discussion], explaining former problems developers met and corresponding solutions
*[https://github.com/szhao8/eden Open source code about Sahana Eden]<ref>[https://github.com/szhao8/eden Sahana Eden Github]</ref>
*[https://github.com/szhao8/EdenMobile Open source code about Eden Mobile]<ref>[https://github.com/szhao8/EdenMobile EdenMobile Github]</ref>

=Design=
==Overview==
In this design, we add several modules to the EdenMobile client app to allow mobile users to add new shelters and hospitals. Also, users can see the list of hospitals and shelters both offline and online and we can pass users' location to the nearest medical facilities. At last, a multilingual environment is also supported.
==Requirements==
The major requirements are that:
*Secure login;
*Multiple languages;
*users are able to work offline, and update forms and content when online;
*The initial forms that will be implemented are Hospitals, and Shelters;

==Architecture==

Below is the overview of the Eden Mobile Platform. It uses a Model-View-Controller design pattern as the foundation of the project. And it also introduces a "plugin" mechanism, from which developers can add new modules (pages) to the main menu by adding them to "plugins" folder.

[[File:S1503_Architecture.png |frame‎|center|Use Case Diagram]]

==Use Cases==

* '''1. Security Log in'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills login form, which includes username, password and Captcha code.
*** Submit form to Sahana Server. 
* '''2. Submit forms to server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to Sahana Server. 
* '''3. Submit forms to local storage'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to local database. 
* '''4. Download new forms from server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Download new forms from server 
* '''5. Synchronize local data with server '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Synchronize local data with server 
* '''6. Multi-Language Support '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Choose a language from settings page 
* The UML use case diagram is shown below:

[[File:S1503_Usecase.png‎ |frame|center|Use Case Diagram]]

=Implementation=
==Login==

The Sahana Eden website already has a login page, so our initial thought is to find the web service URL for login function, and use it in our log in page on Sahana Mobile. After scrutinize the python code of Sahana Eden, we found the login url, which is "localhost:8000/eden/default/user/login?_next=%2Feden%2Fdefault%2Findex", then we use this URL as the post destination and created the login page as follows:

==Hospital plugin==
===Customize hospital form===
According to the [http://pastebin.com/Gj6nEnSu create.s3json file] in the hospital module on the official website, we create the hospital form in the Eden mobile application.
<pre>
var editHospitalForm = [
{
name: "name",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: "",
required: true
},
///*
{
name: "aka1",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "code",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "facility_type",
control: "integer",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "organisation_id",
control: "select"
},
{
name: "L0",
control: "select",
form_path: "$_gis_location/field",
data_path: "$_gis_location/field",
reference: "$k_location_id",
form: "gis-location-form",
common_name: "Country",
label: ""
},
{
name: "addr_street",
control: "string",
form_path: "$_gis_location/field",
data_path: "$_gis_location/field",
reference: "$k_location_id",
form: "gis-location-form",
label: ""
},
{
name: "addr_postcode",
control: "string",
form_path: "$_gis_location/field",
data_path: "$_gis_location/field",
reference: "$k_location_id",
form: "gis-location-form",
label: ""
},
{
name: "location",
control: "gis_button"
},
{
name: "address",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "postcode",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "city",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "phone_exchange",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "phone_business",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "phone_emergency",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "website",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "email",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "fax",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "obsolete",
control: "checkbox"
},
{
name: "footer",
control: "text"
}
];
</pre>
===Synchronization between server and local mobile application===
Utilizing the framework provided by the developer, we realized to synchronize hospital data from server to the local mobile application. You can see what we did in the following image. We create a new hospital name Hospital in the Sahana, after clicking the "save" button, the new hospital is saved in the server. Then if we click the "refresh list" the button in the mobile application, the new hospital will show in the view of our mobile application.

[[File:synchronization.gif]]

==Add Multilanguage Support==
===Development-before preparation===
This program is hosted by a very experienced software engineering, who set the blueprint of this whole program. So we communicated with him serval times to get a better understanding of the project need and expectation. Also, he introduced the framework he used and showed some little tricky to us on google group discussion. Then we understand a mapping relationship and the implementation details about how to build a multilanguage support.

[[File:mapping.png]]

===Code Changes===
The html button changes in languages.js:

<pre>
events: {
"click #Chinese-button": "onChinese",
"click #Bosnian-button": "onBosnian",
"click #French-button": "onFrench",
"click #English-button": "onEnglish"
},
</pre>
<pre>
onChinese: function (event) {
console.log("onChinese ");
var controller = app.controller.getControllerByModel("languages");
if (controller) {
controller.onChinese();
}
},
onEnglish: function (event) {
console.log("onEnglish ");
var controller = app.controller.getControllerByModel("languages");
if (controller) {
controller.onEnglish();
}
},
onBosnian: function (event) {
console.log("onBosnian ");
var controller = app.controller.getControllerByModel("languages");
if (controller) {
controller.onBosnian();
}
},
onFrench: function (event) {
console.log("onBosnian ");
var controller = app.controller.getControllerByModel("languages");
if (controller) {
controller.onFrench();
}
}
</pre>

The html button changes in languagesController.js:

<pre>
controller.prototype.init = function (options) {
$("#Chinese-button").on("click",this.onChinese.bind(this));
$("#Bosnian-button").on("click",this.onBosnian.bind(this));
$("#French-button").on("click",this.onFrench.bind(this));
$("#English-button").on("click",this.onEnglish.bind(this));
app.controller.setControllerByModel("languages", this);
};
</pre>
<pre>
controller.prototype.onChinese = function(evt) {
app.onChinese();
};
controller.prototype.onBosnian = function(evt) {
app.onBosnian();
};
controller.prototype.onFrench = function(evt) {
app.onFrench();
};
controller.prototype.onEnglish = function(evt) {
app.onEnglish();
};
app.pluginManager.addObject(controller);
</pre>

Code changes in index.js:

<pre>
onChinese: function(){
this.controller.translate();
},
onBosnian: function(){
this.controller.translateToBosnian();
},
onFrench: function(){
this.controller.translateToFrench();
},
onEnglish: function(){
this.controller.translateToEnglish();
},
</pre>

Our basic implementation translation in controller.js function goes like this:
<pre>
controller.prototype.translate = function(){
var language = 'Chinese';
//alert("asd");
$.ajax({
url: 'languages.xml',
success: function(xml) {
$(xml).find('translation').each(function(){
var id = $(this).attr('id');

var text = $(this).find(language).text();
$("." + id).html(text);
});
}
});
}
The rest omitted //
</pre>

languages.xml mapping information:
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<translations>
<translation id="translation">
<english>Hello there, how are you?</english>
<Chinese>你好</Chinese>
<Bosnian>Zdravo</Bosnian>
<French>Bonjour</French>
</translation>
<translation id="Shelter">
<english>Shelter Name</english>
<Chinese>避难所名称</Chinese>
<Bosnian>sklonište</Bosnian>
<French>nom de l'abri</French>
</translation>
<translation id="Address">
<english>Street Address</english>
<Chinese>地址</Chinese>
<Bosnian>adresa</Bosnian>
<French>adresse</French>
</translation>
<translation id="Postcode">
<english>Postcode</english>
<Chinese>邮编</Chinese>
<Bosnian>poštanski broj</Bosnian>
<French>code postal</French>
</translation>
<translation id="Phone">
<english>Phone</english>
<Chinese>电话</Chinese>
<Bosnian>telefon</Bosnian>
<French>téléphone</French>
</translation>
<translation id="Email">
<english>Email</english>
<Chinese>邮箱</Chinese>
<Bosnian>E-mail</Bosnian>
<French>E-mail</French>
</translation>
<translation id="Population">
<english>Estimated Population</english>
<Chinese>受灾人口</Chinese>
<Bosnian>pogođene populacije</Bosnian>
<French>la population touchée</French>
</translation>
<translation id="Day">
<english>Evacuees Capacity (Day and Night)</english>
<Chinese>容纳能力（全天）</Chinese>
<Bosnian>pogođene populacije (Dan i noć)</Bosnian>
<French>Capacité évacués(Jour et nuit)</French>
</translation>
<translation id="Night"><english>Evacuees Capacity (Night only)</english>
<Chinese>容纳能力（夜晚）</Chinese>
<Bosnian>pogođene populacije(noć)</Bosnian>
<French>Capacité évacués(nuit)</French>
</translation>
<translation id="Comments">
<english>Comments</english>
<Chinese>备注</Chinese>
<Bosnian>primjedba</Bosnian>
<French>commentaire</French>
</translation>

<translation id="Shelter1">
<english>Raleigh Rescue Mission</english>
<Chinese>罗利市救援中心</Chinese>
<Bosnian>Raleigh Grad U pomoć centar</Bosnian>
<French>Raliegh ville Aidez-Moi centre</French>
</translation>
<translation id="Address1">
<english>314 E Hargett St
Raleigh, NC</english>
<Chinese>北卡州罗利市东哈格特街314号</Chinese>
<Bosnian>314 istok hargett ulica Raleigh Grad,sjever Karolina</Bosnian>
<French>314 est hargett rue Raleigh ville, nord caroline</French>
</translation>
s
<translation id="Comments1">
<english>No Comments</english>
<Chinese>无备注</Chinese>
<Bosnian>Bez Napomene</Bosnian>
<French>aucun commentaire</French>
</translation>
</translations>
</pre>

===Multilanguage UI===
After serval times of discussion and communication, we finally realize the following UI. You can click the language you need to change to it. It's very easy-using and user comfortable. The following screenshot is what it looks like.

After clicking the English button, the English UI shows as following:

[[File:English.png]]

After clicking the Chinese button, the Chinese UI shows as following:

[[File:Chinese.png]]

After clicking the French button, the French UI shows as following:

[[File:French.png]]

After clicking the Bosnian button, the Bosnian UI shows as following:

[[File:Bosnian.png]]

=Troubleshooting=

1. When loading Sahana Eden Mobile's main page, browser console will print the following error message:

[[File:S1503_Error1.png‎ |frame|center|underscore-min.map not found error]]

The problem can be solved by downloading the file [https://github.com/jashkenas/underscore/blob/master/underscore-min.map underscore-min.map] and put it in the directory where underscore-min.js is stored. More information about this error can be found [http://stackoverflow.com/questions/18429625/missing-javascript-map-file-for-underscore-js-when-loading-asp-net-web-page here].

2. When adding multi-language module to Sahana Eden Mobile's main page, browser console will print the following error message:
After adding a language plugin module, users can see a new button called "Language", but it cannot be clicked and what makes worse is that the module affect other modules, for example, we cannot new a shelter. The framework is super complex and we are new here. After discussion, we write a email describing our problems to Tom Baker, the host developer, for help.

[[File:problem.png]]

After we received his short reply, we tried to follow his instruction to check some files but still get no idea what's our problem.

[[File:reply.png]]

Finally, we set breakpoints and used chrome's developer tool to help us debug. Fortunately, we found the an object is NULL, which affect the initiation. Then we found that in our controller there is a little error which leaded to this problem. After revised that, it run well now.

=References=
<references/>

CSC/ECE 517 Spring 2015 S1503 LWJZ

2015-04-24T02:35:55Z

Hwang40: /* Implementation */

<big>S1503. Sahana Eden Mobile Client</big>

{| border="1" class="wikitable" style="float:{{{align|right}}}"
|colspan="2" align="center" |[[File:SahanaLogo.png|center|Sahana]]
|-

=Introduction=
==Purpose==
This project aims at adding new functions to the EdenMobile client app to serve users better.These functions will allow mobile users to add new shelters and hospitals, get information of hospitals and shelters offline/online, get GPS location of device, and provide multilingual support.

==Background==
===What’s 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 the latest evolution of Sahana Software which was initially developed by members of the information technology (IT) community in Sri Lanka to provide solutions for the relief effort following the 2004 Indian Ocean Tsunami.
<ref>[http://eden.sahanafoundation.org/ Sahana Eden Instroduction]</ref> 

===What does Sahana Eden do?===
Sahana Eden provides various of functions which are sorted in several different modules. 

'''Organization Registry''' 
*Sahana Eden’s Organization Registry can track what organizations do and organizations also could record their Offices, Warehouse and Field Sites including their locations so they can be mapped as well as links to other modules such as Human Resources, Assets and Inventory. 
'''Project Tracking''' 
*Sahana Eden provides a valuable tool which could tell people what are going on about the project to help organizations responding to disasters know where the greatest needs are and coordinate with others who are engaged in similar work. 
'''Human Resources''' 
*There are contact lists in Sahana Eden which can be access by users to ensure that the right people can be contacted at the right time. 
'''Inventory''' 
*Sahana Eden can be used to manage inventories of items and match requests for items with warehouses and other facilities which have them available. Sahana Eden can support multiple Catalogs of Items as well as providing alternative items to ensure more effective use of supplies. 
'''Assets''' 
*Sahana Eden is able to manage assets which are needed to respond to disasters, track where they are, who they have been assigned to, and what condition they are in. This ensures that assets are used effectively and efficiently. 
'''Assessments''' 
*Sahana Eden can be used to collect and analyze information from assessments to help organizations more effectively plan their disaster management activities. 
'''Scenarios & Events''' 
*To help organizations better plan for disasters, Sahana Eden can be used to plan for different scenarios, including recording what human resources, assets, facilities and tasks will be needed to effectively respond. 
'''Map''' 
*Sahana Eden has fully integrated mapping functionality which allows any location-based data to be visualized on a map. Maps provide situational awareness which is essential when either planning to prepare for or respond to a disaster. 
'''Shelter Management''' 
*When disasters are widespread and result in population displacement, understanding and tracking the landscape of shelters - and the people in them - is a critical activity. The Shelter Registry provides functionality to list and track information on shelters and on the people arriving and departing. 
'''Messaging''' 
*Sahana Eden provides support for messages to be sent to one or Distribution Groups by Email, SMS, Twitter and Google Talk. Interactive messages can also be set up to allow people to send short message queries to Sahana Eden and receive automatic responses. 

===Sahana Eden 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);">Web Server</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);">Application</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);">Web Application Framework</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);">Programming Language</td>
<td style="border: 1px dotted rgb(0, 0, 0);">Python & Java Script</td>
<td style="border: 1px dotted rgb(0, 0, 0);"></td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Database</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, or SQLite</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, and SQLite are supported.Other databases should be usable without major additional work since Web2Py supplies many connectors.</td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Operating System</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>

==Scope==
We will realize the signup, secure login and logout function, which would add new module into the following files:
*communication.js
*controller.js
*model.js
*view.js
We will make it available in multiple languages environment which will implement the languages fold.
We will add some new items including:“ hospital”, “vehicles” which will be added into the folder named “plugins”. The following file will be added into their corrsponding folders: 
Hospitals:
*mHospital.js (model)
*hospital.js, editHospital.js, hospital.html, hospital.css, editHospital.html (views)
*hospitalController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Vehicles:
*mVehicles.js (model)
*vehicles.js, editVehicles.js, vehicles.html, vehicles.css, editVehicles.html (views)
*vehiclesController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Also, we find some bugs and eliminate them. These could be any possible file in this project.

==Documentation==
former developer discussion about Sahana Oden
*An [https://docs.google.com/a/ncsu.edu/document/d/11bblC7klisYjN7Gjw6hDcs5TZ8uesJD3o2xnM2gI914/edit# overview of all the Sahana Eden projects]
*An [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework basic introduction] about the framework of Edenmobile including application design, source<ref>[http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework Edenmobile Introduction]</ref>
*An [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile#J2ME list] of all the requirements need to be done in this project.
*An [https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!forum/sahana-eden google discussion], explaining former problems developers met and corresponding solutions
*[https://github.com/szhao8/eden Open source code about Sahana Eden]<ref>[https://github.com/szhao8/eden Sahana Eden Github]</ref>
*[https://github.com/szhao8/EdenMobile Open source code about Eden Mobile]<ref>[https://github.com/szhao8/EdenMobile EdenMobile Github]</ref>

=Design=
==Overview==
In this design, we add several modules to the EdenMobile client app to allow mobile users to add new shelters and hospitals. Also, users can see the list of hospitals and shelters both offline and online and we can pass users' location to the nearest medical facilities. At last, a multilingual environment is also supported.
==Requirements==
The major requirements are that:
*Secure login;
*Multiple languages;
*users are able to work offline, and update forms and content when online;
*The initial forms that will be implemented are Hospitals, and Shelters;

==Architecture==

Below is the overview of the Eden Mobile Platform. It uses a Model-View-Controller design pattern as the foundation of the project. And it also introduces a "plugin" mechanism, from which developers can add new modules (pages) to the main menu by adding them to "plugins" folder.

[[File:S1503_Architecture.png |frame‎|center|Use Case Diagram]]

==Use Cases==

* '''1. Security Log in'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills login form, which includes username, password and Captcha code.
*** Submit form to Sahana Server. 
* '''2. Submit forms to server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to Sahana Server. 
* '''3. Submit forms to local storage'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to local database. 
* '''4. Download new forms from server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Download new forms from server 
* '''5. Synchronize local data with server '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Synchronize local data with server 
* '''6. Multi-Language Support '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Choose a language from settings page 
* The UML use case diagram is shown below:

[[File:S1503_Usecase.png‎ |frame|center|Use Case Diagram]]

=Implementation=
==Login==
==Hospital plugin==
===Customize hospital form===
According to the [http://pastebin.com/Gj6nEnSu create.s3json file] in the hospital module on the official website, we create the hospital form in the Eden mobile application.
<pre>
var editHospitalForm = [
{
name: "name",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: "",
required: true
},
///*
{
name: "aka1",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "code",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "facility_type",
control: "integer",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "organisation_id",
control: "select"
},
{
name: "L0",
control: "select",
form_path: "$_gis_location/field",
data_path: "$_gis_location/field",
reference: "$k_location_id",
form: "gis-location-form",
common_name: "Country",
label: ""
},
{
name: "addr_street",
control: "string",
form_path: "$_gis_location/field",
data_path: "$_gis_location/field",
reference: "$k_location_id",
form: "gis-location-form",
label: ""
},
{
name: "addr_postcode",
control: "string",
form_path: "$_gis_location/field",
data_path: "$_gis_location/field",
reference: "$k_location_id",
form: "gis-location-form",
label: ""
},
{
name: "location",
control: "gis_button"
},
{
name: "address",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "postcode",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "city",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "phone_exchange",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "phone_business",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "phone_emergency",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "website",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "email",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "fax",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "obsolete",
control: "checkbox"
},
{
name: "footer",
control: "text"
}
];
</pre>
[[Media:[[Media:Example.ogg]][[Media:Example.ogg]]]]

==Add Multilanguage Support==
===Development-before preparation===
This program is hosted by a very experienced software engineering, who set the blueprint of this whole program. So we communicated with him serval times to get a better understanding of the project need and expectation. Also, he introduced the framework he used and showed some little tricky to us on google group discussion. Then we understand a mapping relationship and the implementation details about how to build a multilanguage support.

[[File:mapping.png]]

===Code Changes===
The html button changes in languages.js:

<pre>
events: {
"click #Chinese-button": "onChinese",
"click #Bosnian-button": "onBosnian",
"click #French-button": "onFrench",
"click #English-button": "onEnglish"
},
</pre>
<pre>
onChinese: function (event) {
console.log("onChinese ");
var controller = app.controller.getControllerByModel("languages");
if (controller) {
controller.onChinese();
}
},
onEnglish: function (event) {
console.log("onEnglish ");
var controller = app.controller.getControllerByModel("languages");
if (controller) {
controller.onEnglish();
}
},
onBosnian: function (event) {
console.log("onBosnian ");
var controller = app.controller.getControllerByModel("languages");
if (controller) {
controller.onBosnian();
}
},
onFrench: function (event) {
console.log("onBosnian ");
var controller = app.controller.getControllerByModel("languages");
if (controller) {
controller.onFrench();
}
}
</pre>

The html button changes in languagesController.js:

<pre>
controller.prototype.init = function (options) {
$("#Chinese-button").on("click",this.onChinese.bind(this));
$("#Bosnian-button").on("click",this.onBosnian.bind(this));
$("#French-button").on("click",this.onFrench.bind(this));
$("#English-button").on("click",this.onEnglish.bind(this));
app.controller.setControllerByModel("languages", this);
};
</pre>
<pre>
controller.prototype.onChinese = function(evt) {
app.onChinese();
};
controller.prototype.onBosnian = function(evt) {
app.onBosnian();
};
controller.prototype.onFrench = function(evt) {
app.onFrench();
};
controller.prototype.onEnglish = function(evt) {
app.onEnglish();
};
app.pluginManager.addObject(controller);
</pre>

Code changes in index.js:

<pre>
onChinese: function(){
this.controller.translate();
},
onBosnian: function(){
this.controller.translateToBosnian();
},
onFrench: function(){
this.controller.translateToFrench();
},
onEnglish: function(){
this.controller.translateToEnglish();
},
</pre>

Our basic implementation translation in controller.js function goes like this:
<pre>
controller.prototype.translate = function(){
var language = 'Chinese';
//alert("asd");
$.ajax({
url: 'languages.xml',
success: function(xml) {
$(xml).find('translation').each(function(){
var id = $(this).attr('id');

var text = $(this).find(language).text();
$("." + id).html(text);
});
}
});
}
The rest omitted //
</pre>

languages.xml mapping information:
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<translations>
<translation id="translation">
<english>Hello there, how are you?</english>
<Chinese>你好</Chinese>
<Bosnian>Zdravo</Bosnian>
<French>Bonjour</French>
</translation>
<translation id="Shelter">
<english>Shelter Name</english>
<Chinese>避难所名称</Chinese>
<Bosnian>sklonište</Bosnian>
<French>nom de l'abri</French>
</translation>
<translation id="Address">
<english>Street Address</english>
<Chinese>地址</Chinese>
<Bosnian>adresa</Bosnian>
<French>adresse</French>
</translation>
<translation id="Postcode">
<english>Postcode</english>
<Chinese>邮编</Chinese>
<Bosnian>poštanski broj</Bosnian>
<French>code postal</French>
</translation>
<translation id="Phone">
<english>Phone</english>
<Chinese>电话</Chinese>
<Bosnian>telefon</Bosnian>
<French>téléphone</French>
</translation>
<translation id="Email">
<english>Email</english>
<Chinese>邮箱</Chinese>
<Bosnian>E-mail</Bosnian>
<French>E-mail</French>
</translation>
<translation id="Population">
<english>Estimated Population</english>
<Chinese>受灾人口</Chinese>
<Bosnian>pogođene populacije</Bosnian>
<French>la population touchée</French>
</translation>
<translation id="Day">
<english>Evacuees Capacity (Day and Night)</english>
<Chinese>容纳能力（全天）</Chinese>
<Bosnian>pogođene populacije (Dan i noć)</Bosnian>
<French>Capacité évacués(Jour et nuit)</French>
</translation>
<translation id="Night"><english>Evacuees Capacity (Night only)</english>
<Chinese>容纳能力（夜晚）</Chinese>
<Bosnian>pogođene populacije(noć)</Bosnian>
<French>Capacité évacués(nuit)</French>
</translation>
<translation id="Comments">
<english>Comments</english>
<Chinese>备注</Chinese>
<Bosnian>primjedba</Bosnian>
<French>commentaire</French>
</translation>

<translation id="Shelter1">
<english>Raleigh Rescue Mission</english>
<Chinese>罗利市救援中心</Chinese>
<Bosnian>Raleigh Grad U pomoć centar</Bosnian>
<French>Raliegh ville Aidez-Moi centre</French>
</translation>
<translation id="Address1">
<english>314 E Hargett St
Raleigh, NC</english>
<Chinese>北卡州罗利市东哈格特街314号</Chinese>
<Bosnian>314 istok hargett ulica Raleigh Grad,sjever Karolina</Bosnian>
<French>314 est hargett rue Raleigh ville, nord caroline</French>
</translation>
s
<translation id="Comments1">
<english>No Comments</english>
<Chinese>无备注</Chinese>
<Bosnian>Bez Napomene</Bosnian>
<French>aucun commentaire</French>
</translation>
</translations>
</pre>

===Multilanguage UI===
After serval times of discussion and communication, we finally realize the following UI. You can click the language you need to change to it. It's very easy-using and user comfortable. The following screenshot is what it looks like.

After clicking the English button, the English UI shows as following:

[[File:English.png]]

After clicking the Chinese button, the Chinese UI shows as following:

[[File:Chinese.png]]

After clicking the French button, the French UI shows as following:

[[File:French.png]]

After clicking the Bosnian button, the Bosnian UI shows as following:

[[File:Bosnian.png]]

=Troubleshooting=

1. When loading Sahana Eden Mobile's main page, browser console will print the following error message:

[[File:S1503_Error1.png‎ |frame|center|underscore-min.map not found error]]

The problem can be solved by downloading the file [https://github.com/jashkenas/underscore/blob/master/underscore-min.map underscore-min.map] and put it in the directory where underscore-min.js is stored. More information about this error can be found [http://stackoverflow.com/questions/18429625/missing-javascript-map-file-for-underscore-js-when-loading-asp-net-web-page here].

2. When adding multi-language module to Sahana Eden Mobile's main page, browser console will print the following error message:
After adding a language plugin module, users can see a new button called "Language", but it cannot be clicked and what makes worse is that the module affect other modules, for example, we cannot new a shelter. The framework is super complex and we are new here. After discussion, we write a email describing our problems to Tom Baker, the host developer, for help.

[[File:problem.png]]

After we received his short reply, we tried to follow his instruction to check some files but still get no idea what's our problem.

[[File:reply.png]]

Finally, we set breakpoints and used chrome's developer tool to help us debug. Fortunately, we found the an object is NULL, which affect the initiation. Then we found that in our controller there is a little error which leaded to this problem. After revised that, it run well now.

=References=
<references/>

CSC/ECE 517 Spring 2015 S1503 LWJZ

2015-04-24T02:04:49Z

Hwang40:

<big>S1503. Sahana Eden Mobile Client</big>

{| border="1" class="wikitable" style="float:{{{align|right}}}"
|colspan="2" align="center" |[[File:SahanaLogo.png|center|Sahana]]
|-

=Introduction=
==Purpose==
This project aims at adding new functions to the EdenMobile client app to serve users better.These functions will allow mobile users to add new shelters and hospitals, get information of hospitals and shelters offline/online, get GPS location of device, and provide multilingual support.

==Background==
===What’s 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 the latest evolution of Sahana Software which was initially developed by members of the information technology (IT) community in Sri Lanka to provide solutions for the relief effort following the 2004 Indian Ocean Tsunami.
<ref>[http://eden.sahanafoundation.org/ Sahana Eden Instroduction]</ref> 

===What does Sahana Eden do?===
Sahana Eden provides various of functions which are sorted in several different modules. 

'''Organization Registry''' 
*Sahana Eden’s Organization Registry can track what organizations do and organizations also could record their Offices, Warehouse and Field Sites including their locations so they can be mapped as well as links to other modules such as Human Resources, Assets and Inventory. 
'''Project Tracking''' 
*Sahana Eden provides a valuable tool which could tell people what are going on about the project to help organizations responding to disasters know where the greatest needs are and coordinate with others who are engaged in similar work. 
'''Human Resources''' 
*There are contact lists in Sahana Eden which can be access by users to ensure that the right people can be contacted at the right time. 
'''Inventory''' 
*Sahana Eden can be used to manage inventories of items and match requests for items with warehouses and other facilities which have them available. Sahana Eden can support multiple Catalogs of Items as well as providing alternative items to ensure more effective use of supplies. 
'''Assets''' 
*Sahana Eden is able to manage assets which are needed to respond to disasters, track where they are, who they have been assigned to, and what condition they are in. This ensures that assets are used effectively and efficiently. 
'''Assessments''' 
*Sahana Eden can be used to collect and analyze information from assessments to help organizations more effectively plan their disaster management activities. 
'''Scenarios & Events''' 
*To help organizations better plan for disasters, Sahana Eden can be used to plan for different scenarios, including recording what human resources, assets, facilities and tasks will be needed to effectively respond. 
'''Map''' 
*Sahana Eden has fully integrated mapping functionality which allows any location-based data to be visualized on a map. Maps provide situational awareness which is essential when either planning to prepare for or respond to a disaster. 
'''Shelter Management''' 
*When disasters are widespread and result in population displacement, understanding and tracking the landscape of shelters - and the people in them - is a critical activity. The Shelter Registry provides functionality to list and track information on shelters and on the people arriving and departing. 
'''Messaging''' 
*Sahana Eden provides support for messages to be sent to one or Distribution Groups by Email, SMS, Twitter and Google Talk. Interactive messages can also be set up to allow people to send short message queries to Sahana Eden and receive automatic responses. 

===Sahana Eden 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);">Web Server</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);">Application</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);">Web Application Framework</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);">Programming Language</td>
<td style="border: 1px dotted rgb(0, 0, 0);">Python & Java Script</td>
<td style="border: 1px dotted rgb(0, 0, 0);"></td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Database</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, or SQLite</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, and SQLite are supported.Other databases should be usable without major additional work since Web2Py supplies many connectors.</td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Operating System</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>

==Scope==
We will realize the signup, secure login and logout function, which would add new module into the following files:
*communication.js
*controller.js
*model.js
*view.js
We will make it available in multiple languages environment which will implement the languages fold.
We will add some new items including:“ hospital”, “vehicles” which will be added into the folder named “plugins”. The following file will be added into their corrsponding folders: 
Hospitals:
*mHospital.js (model)
*hospital.js, editHospital.js, hospital.html, hospital.css, editHospital.html (views)
*hospitalController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Vehicles:
*mVehicles.js (model)
*vehicles.js, editVehicles.js, vehicles.html, vehicles.css, editVehicles.html (views)
*vehiclesController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Also, we find some bugs and eliminate them. These could be any possible file in this project.

==Documentation==
former developer discussion about Sahana Oden
*An [https://docs.google.com/a/ncsu.edu/document/d/11bblC7klisYjN7Gjw6hDcs5TZ8uesJD3o2xnM2gI914/edit# overview of all the Sahana Eden projects]
*An [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework basic introduction] about the framework of Edenmobile including application design, source<ref>[http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework Edenmobile Introduction]</ref>
*An [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile#J2ME list] of all the requirements need to be done in this project.
*An [https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!forum/sahana-eden google discussion], explaining former problems developers met and corresponding solutions
*[https://github.com/szhao8/eden Open source code about Sahana Eden]<ref>[https://github.com/szhao8/eden Sahana Eden Github]</ref>
*[https://github.com/szhao8/EdenMobile Open source code about Eden Mobile]<ref>[https://github.com/szhao8/EdenMobile EdenMobile Github]</ref>

=Design=
==Overview==
In this design, we add several modules to the EdenMobile client app to allow mobile users to add new shelters and hospitals. Also, users can see the list of hospitals and shelters both offline and online and we can pass users' location to the nearest medical facilities. At last, a multilingual environment is also supported.
==Requirements==
The major requirements are that:
*Secure login;
*Multiple languages;
*users are able to work offline, and update forms and content when online;
*The initial forms that will be implemented are Hospitals, and Shelters;

==Architecture==

Below is the overview of the Eden Mobile Platform. It uses a Model-View-Controller design pattern as the foundation of the project. And it also introduces a "plugin" mechanism, from which developers can add new modules (pages) to the main menu by adding them to "plugins" folder.

[[File:S1503_Architecture.png |frame‎|center|Use Case Diagram]]

==Use Cases==

* '''1. Security Log in'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills login form, which includes username, password and Captcha code.
*** Submit form to Sahana Server. 
* '''2. Submit forms to server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to Sahana Server. 
* '''3. Submit forms to local storage'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to local database. 
* '''4. Download new forms from server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Download new forms from server 
* '''5. Synchronize local data with server '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Synchronize local data with server 
* '''6. Multi-Language Support '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Choose a language from settings page 
* The UML use case diagram is shown below:

[[File:S1503_Usecase.png‎ |frame|center|Use Case Diagram]]

=Implementation=
==Hospital plugin==
===Customize hospital form===
<pre>
var editHospitalForm = [
{
name: "name",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: "",
required: true
},
///*
{
name: "aka1",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "code",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "facility_type",
control: "integer",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "organisation_id",
control: "select"
},
{
name: "L0",
control: "select",
form_path: "$_gis_location/field",
data_path: "$_gis_location/field",
reference: "$k_location_id",
form: "gis-location-form",
common_name: "Country",
label: ""
},
{
name: "addr_street",
control: "string",
form_path: "$_gis_location/field",
data_path: "$_gis_location/field",
reference: "$k_location_id",
form: "gis-location-form",
label: ""
},
{
name: "addr_postcode",
control: "string",
form_path: "$_gis_location/field",
data_path: "$_gis_location/field",
reference: "$k_location_id",
form: "gis-location-form",
label: ""
},
{
name: "location",
control: "gis_button"
},
{
name: "address",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "postcode",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "city",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "phone_exchange",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "phone_business",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "phone_emergency",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "website",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "email",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "fax",
control: "string",
form_path: "$_hms_hospital/field",
form: "hospital-form",
label: ""
},
{
name: "obsolete",
control: "checkbox"
},
{
name: "footer",
control: "text"
}
];
</pre>

==Add Multilanguage Support==
===Development-before preparation===
This program is hosted by a very experienced software engineering, who set the blueprint of this whole program. So we communicated with him serval times to get a better understanding of the project need and expectation. Also, he introduced the framework he used and showed some little tricky to us on google group discussion. Then we understand a mapping relationship and the implementation details about how to build a multilanguage support.

[[File:mapping.png]]

===Code Changes===
The html button changes in languages.js:

<pre>
events: {
"click #Chinese-button": "onChinese",
"click #Bosnian-button": "onBosnian",
"click #French-button": "onFrench",
"click #English-button": "onEnglish"
},
</pre>
<pre>
onChinese: function (event) {
console.log("onChinese ");
var controller = app.controller.getControllerByModel("languages");
if (controller) {
controller.onChinese();
}
},
onEnglish: function (event) {
console.log("onEnglish ");
var controller = app.controller.getControllerByModel("languages");
if (controller) {
controller.onEnglish();
}
},
onBosnian: function (event) {
console.log("onBosnian ");
var controller = app.controller.getControllerByModel("languages");
if (controller) {
controller.onBosnian();
}
},
onFrench: function (event) {
console.log("onBosnian ");
var controller = app.controller.getControllerByModel("languages");
if (controller) {
controller.onFrench();
}
}
</pre>

The html button changes in languagesController.js:

<pre>
controller.prototype.init = function (options) {
$("#Chinese-button").on("click",this.onChinese.bind(this));
$("#Bosnian-button").on("click",this.onBosnian.bind(this));
$("#French-button").on("click",this.onFrench.bind(this));
$("#English-button").on("click",this.onEnglish.bind(this));
app.controller.setControllerByModel("languages", this);
};
</pre>
<pre>
controller.prototype.onChinese = function(evt) {
app.onChinese();
};
controller.prototype.onBosnian = function(evt) {
app.onBosnian();
};
controller.prototype.onFrench = function(evt) {
app.onFrench();
};
controller.prototype.onEnglish = function(evt) {
app.onEnglish();
};
app.pluginManager.addObject(controller);
</pre>

Code changes in index.js:

<pre>
onChinese: function(){
this.controller.translate();
},
onBosnian: function(){
this.controller.translateToBosnian();
},
onFrench: function(){
this.controller.translateToFrench();
},
onEnglish: function(){
this.controller.translateToEnglish();
},
</pre>

Our basic implementation translation in controller.js function goes like this:
<pre>
controller.prototype.translate = function(){
var language = 'Chinese';
//alert("asd");
$.ajax({
url: 'languages.xml',
success: function(xml) {
$(xml).find('translation').each(function(){
var id = $(this).attr('id');

var text = $(this).find(language).text();
$("." + id).html(text);
});
}
});
}
The rest omitted //
</pre>

languages.xml mapping information:
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<translations>
<translation id="translation">
<english>Hello there, how are you?</english>
<Chinese>你好</Chinese>
<Bosnian>Zdravo</Bosnian>
<French>Bonjour</French>
</translation>
<translation id="Shelter">
<english>Shelter Name</english>
<Chinese>避难所名称</Chinese>
<Bosnian>sklonište</Bosnian>
<French>nom de l'abri</French>
</translation>
<translation id="Address">
<english>Street Address</english>
<Chinese>地址</Chinese>
<Bosnian>adresa</Bosnian>
<French>adresse</French>
</translation>
<translation id="Postcode">
<english>Postcode</english>
<Chinese>邮编</Chinese>
<Bosnian>poštanski broj</Bosnian>
<French>code postal</French>
</translation>
<translation id="Phone">
<english>Phone</english>
<Chinese>电话</Chinese>
<Bosnian>telefon</Bosnian>
<French>téléphone</French>
</translation>
<translation id="Email">
<english>Email</english>
<Chinese>邮箱</Chinese>
<Bosnian>E-mail</Bosnian>
<French>E-mail</French>
</translation>
<translation id="Population">
<english>Estimated Population</english>
<Chinese>受灾人口</Chinese>
<Bosnian>pogođene populacije</Bosnian>
<French>la population touchée</French>
</translation>
<translation id="Day">
<english>Evacuees Capacity (Day and Night)</english>
<Chinese>容纳能力（全天）</Chinese>
<Bosnian>pogođene populacije (Dan i noć)</Bosnian>
<French>Capacité évacués(Jour et nuit)</French>
</translation>
<translation id="Night"><english>Evacuees Capacity (Night only)</english>
<Chinese>容纳能力（夜晚）</Chinese>
<Bosnian>pogođene populacije(noć)</Bosnian>
<French>Capacité évacués(nuit)</French>
</translation>
<translation id="Comments">
<english>Comments</english>
<Chinese>备注</Chinese>
<Bosnian>primjedba</Bosnian>
<French>commentaire</French>
</translation>

<translation id="Shelter1">
<english>Raleigh Rescue Mission</english>
<Chinese>罗利市救援中心</Chinese>
<Bosnian>Raleigh Grad U pomoć centar</Bosnian>
<French>Raliegh ville Aidez-Moi centre</French>
</translation>
<translation id="Address1">
<english>314 E Hargett St
Raleigh, NC</english>
<Chinese>北卡州罗利市东哈格特街314号</Chinese>
<Bosnian>314 istok hargett ulica Raleigh Grad,sjever Karolina</Bosnian>
<French>314 est hargett rue Raleigh ville, nord caroline</French>
</translation>
s
<translation id="Comments1">
<english>No Comments</english>
<Chinese>无备注</Chinese>
<Bosnian>Bez Napomene</Bosnian>
<French>aucun commentaire</French>
</translation>
</translations>
</pre>

===Multilanguage UI===
After serval times of discussion and communication, we finally realize the following UI. You can click the language you need to change to it. It's very easy-using and user comfortable. The following screenshot is what it looks like.

After clicking the English button, the English UI shows as following:

[[File:English.png]]

After clicking the Chinese button, the Chinese UI shows as following:

[[File:Chinese.png]]

After clicking the French button, the French UI shows as following:

[[File:French.png]]

After clicking the Bosnian button, the Bosnian UI shows as following:

[[File:Bosnian.png]]

=Troubleshooting=

1. When loading Sahana Eden Mobile's main page, browser console will print the following error message:

[[File:S1503_Error1.png‎ |frame|center|underscore-min.map not found error]]

The problem can be solved by downloading the file [https://github.com/jashkenas/underscore/blob/master/underscore-min.map underscore-min.map] and put it in the directory where underscore-min.js is stored. More information about this error can be found [http://stackoverflow.com/questions/18429625/missing-javascript-map-file-for-underscore-js-when-loading-asp-net-web-page here].

2. When adding multi-language module to Sahana Eden Mobile's main page, browser console will print the following error message:
After adding a language plugin module, users can see a new button called "Language", but it cannot be clicked and what makes worse is that the module affect other modules, for example, we cannot new a shelter. The framework is super complex and we are new here. After discussion, we write a email describing our problems to Tom Baker, the host developer, for help.

[[File:problem.png]]

After we received his short reply, we tried to follow his instruction to check some files but still get no idea what's our problem.

[[File:reply.png]]

Finally, we set breakpoints and used chrome's developer tool to help us debug. Fortunately, we found the an object is NULL, which affect the initiation. Then we found that in our controller there is a little error which leaded to this problem. After revised that, it run well now.

=References=
<references/>

CSC/ECE 517 Spring 2015 S1503 LWJZ

2015-04-24T00:41:24Z

Hwang40: /* Architecture */

<big>S1503. Sahana Eden Mobile Client</big>

=Introduction=
==Purpose==
This project aims at adding new functions to the EdenMobile client app to serve users better.These functions will allow mobile users to add new shelters and hospitals, get information of hospitals and shelters offline/online, get GPS location of device, and provide multilingual support.

==Background==
===What’s 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 the latest evolution of Sahana Software which was initially developed by members of the information technology (IT) community in Sri Lanka to provide solutions for the relief effort following the 2004 Indian Ocean Tsunami.
<ref>[http://eden.sahanafoundation.org/ Sahana Eden Instroduction]</ref> 

===What does Sahana Eden do?===
Sahana Eden provides various of functions which are sorted in several different modules. 

'''Organization Registry''' 
*Sahana Eden’s Organization Registry can track what organizations do and organizations also could record their Offices, Warehouse and Field Sites including their locations so they can be mapped as well as links to other modules such as Human Resources, Assets and Inventory. 
'''Project Tracking''' 
*Sahana Eden provides a valuable tool which could tell people what are going on about the project to help organizations responding to disasters know where the greatest needs are and coordinate with others who are engaged in similar work. 
'''Human Resources''' 
*There are contact lists in Sahana Eden which can be access by users to ensure that the right people can be contacted at the right time. 
'''Inventory''' 
*Sahana Eden can be used to manage inventories of items and match requests for items with warehouses and other facilities which have them available. Sahana Eden can support multiple Catalogs of Items as well as providing alternative items to ensure more effective use of supplies. 
'''Assets''' 
*Sahana Eden is able to manage assets which are needed to respond to disasters, track where they are, who they have been assigned to, and what condition they are in. This ensures that assets are used effectively and efficiently. 
'''Assessments''' 
*Sahana Eden can be used to collect and analyze information from assessments to help organizations more effectively plan their disaster management activities. 
'''Scenarios & Events''' 
*To help organizations better plan for disasters, Sahana Eden can be used to plan for different scenarios, including recording what human resources, assets, facilities and tasks will be needed to effectively respond. 
'''Map''' 
*Sahana Eden has fully integrated mapping functionality which allows any location-based data to be visualized on a map. Maps provide situational awareness which is essential when either planning to prepare for or respond to a disaster. 
'''Shelter Management''' 
*When disasters are widespread and result in population displacement, understanding and tracking the landscape of shelters - and the people in them - is a critical activity. The Shelter Registry provides functionality to list and track information on shelters and on the people arriving and departing. 
'''Messaging''' 
*Sahana Eden provides support for messages to be sent to one or Distribution Groups by Email, SMS, Twitter and Google Talk. Interactive messages can also be set up to allow people to send short message queries to Sahana Eden and receive automatic responses. 

===Sahana Eden 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);">Web Server</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);">Application</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);">Web Application Framework</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);">Programming Language</td>
<td style="border: 1px dotted rgb(0, 0, 0);">Python & Java Script</td>
<td style="border: 1px dotted rgb(0, 0, 0);"></td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Database</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, or SQLite</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, and SQLite are supported.Other databases should be usable without major additional work since Web2Py supplies many connectors.</td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Operating System</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>

==Scope==
We will realize the signup, secure login and logout function, which would add new module into the following files:
*communication.js
*controller.js
*model.js
*view.js
We will make it available in multiple languages environment which will implement the languages fold.
We will add some new items including:“ hospital”, “vehicles” which will be added into the folder named “plugins”. The following file will be added into their corrsponding folders: 
Hospitals:
*mHospital.js (model)
*hospital.js, editHospital.js, hospital.html, hospital.css, editHospital.html (views)
*hospitalController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Vehicles:
*mVehicles.js (model)
*vehicles.js, editVehicles.js, vehicles.html, vehicles.css, editVehicles.html (views)
*vehiclesController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Also, we find some bugs and eliminate them. These could be any possible file in this project.

==Documentation==
former developer discussion about Sahana Oden
*An [https://docs.google.com/a/ncsu.edu/document/d/11bblC7klisYjN7Gjw6hDcs5TZ8uesJD3o2xnM2gI914/edit# overview of all the Sahana Eden projects]
*An [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework basic introduction] about the framework of Edenmobile including application design, source<ref>[http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework Edenmobile Introduction]</ref>
*An [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile#J2ME list] of all the requirements need to be done in this project.
*An [https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!forum/sahana-eden google discussion], explaining former problems developers met and corresponding solutions
*[https://github.com/szhao8/eden Open source code about Sahana Eden]<ref>[https://github.com/szhao8/eden Sahana Eden Github]</ref>
*[https://github.com/szhao8/EdenMobile Open source code about Eden Mobile]<ref>[https://github.com/szhao8/EdenMobile EdenMobile Github]</ref>

=Design=
==Overview==
In this design, we add several modules to the EdenMobile client app to allow mobile users to add new shelters and hospitals. Also, users can see the list of hospitals and shelters both offline and online and we can pass users' location to the nearest medical facilities. At last, a multilingual environment is also supported.
==Requirements==
The major requirements are that:
*Secure login;
*Multiple languages;
*users are able to work offline, and update forms and content when online;
*The initial forms that will be implemented are Hospitals, and Shelters;

==Architecture==

Below is the overview of the Eden Mobile Platform. It uses a Model-View-Controller design pattern as the foundation of the project. And it also introduces a "plugin" mechanism, from which developers can add new modules (pages) to the main menu by adding them to "plugins" folder.

[[File:S1503_Architecture.png |frame‎|center|Use Case Diagram]]

==Use Cases==

* '''1. Security Log in'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills login form, which includes username, password and Captcha code.
*** Submit form to Sahana Server. 
* '''2. Submit forms to server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to Sahana Server. 
* '''3. Submit forms to local storage'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to local database. 
* '''4. Download new forms from server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Download new forms from server 
* '''5. Synchronize local data with server '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Synchronize local data with server 
* '''6. Multi-Language Support '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Choose a language from settings page 
* The UML use case diagram is shown below:

[[File:S1503_Usecase.png‎ |frame|center|Use Case Diagram]]

=Implementation=
==Add Multilanguage Support==
===Development-before preparation===
This program is hosted by a very experienced software engineering, who set the blueprint of this whole program. So we communicated with him serval times to get a better understanding of the project need and expectation. Also, he introduced the framework he used and showed some little tricky to us on google group discussion. Then we understand a mapping relationship and the implementation details about how to build a multilanguage support.

[[File:mapping.png]]

===Code Changes===
The html button changes in languages.js:

<pre>
events: {
"click #Chinese-button": "onChinese",
"click #Bosnian-button": "onBosnian",
"click #French-button": "onFrench",
"click #English-button": "onEnglish"
},
</pre>
<pre>
onChinese: function (event) {
console.log("onChinese ");
var controller = app.controller.getControllerByModel("languages");
if (controller) {
controller.onChinese();
}
},
onEnglish: function (event) {
console.log("onEnglish ");
var controller = app.controller.getControllerByModel("languages");
if (controller) {
controller.onEnglish();
}
},
onBosnian: function (event) {
console.log("onBosnian ");
var controller = app.controller.getControllerByModel("languages");
if (controller) {
controller.onBosnian();
}
},
onFrench: function (event) {
console.log("onBosnian ");
var controller = app.controller.getControllerByModel("languages");
if (controller) {
controller.onFrench();
}
}
</pre>

The html button changes in languagesController.js:

[[File:languagecontroller.png]]

Code changes in index.js:

[[File:index.png]]

Our basic implementation translation in controller.js function goes like this:

[[File:basic.png]]

languages.xml mapping information:

[[File:xml.png]]

===Multilanguage UI===
After serval times of discussion and communication, we finally realize the following UI. You can click the language you need to change to it. It's very easy-using and user comfortable. The following screenshot is what it looks like.

After clicking the English button, the English UI shows as following:

[[File:English.png]]

After clicking the Chinese button, the Chinese UI shows as following:

[[File:Chinese.png]]

After clicking the French button, the French UI shows as following:

[[File:French.png]]

After clicking the Bosnian button, the Bosnian UI shows as following:

[[File:Bosnian.png]]

=Troubleshooting=

1. When loading Sahana Eden Mobile's main page, browser console will print the following error message:

[[File:S1503_Error1.png‎ |frame|center|underscore-min.map not found error]]

The problem can be solved by downloading the file [https://github.com/jashkenas/underscore/blob/master/underscore-min.map underscore-min.map] and put it in the directory where underscore-min.js is stored. More information about this error can be found [http://stackoverflow.com/questions/18429625/missing-javascript-map-file-for-underscore-js-when-loading-asp-net-web-page here].

2. When adding multi-language module to Sahana Eden Mobile's main page, browser console will print the following error message:
After adding a language plugin module, users can see a new button called "Language", but it cannot be clicked and what makes worse is that the module affect other modules, for example, we cannot new a shelter. The framework is super complex and we are new here. After discussion, we write a email describing our problems to Tom Baker, the host developer, for help.

[[File:problem.png]]

After we received his short reply, we tried to follow his instruction to check some files but still get no idea what's our problem.

[[File:reply.png]]

Finally, we set breakpoints and used chrome's developer tool to help us debug. Fortunately, we found the an object is NULL, which affect the initiation. Then we found that in our controller there is a little error which leaded to this problem. After revised that, it run well now.

=References=
<references/>

CSC/ECE 517 Spring 2015 S1503 LWJZ

2015-04-01T02:26:31Z

Hwang40: /* Sahana Eden Architecture */

<big>S1503. JavaRosa Mobile Client</big>
=Introduction=
==Purpose==
This project is aimed at adding new functions to the EdenMobile client app to serve users better.These functions will allow mobile users to realize functions like
adding new shelters and hospitals, observing the list of hospitals and shelters both offline and online ,passing users' location to the nearest medical facilities and realizing a multilingual environment.

==Background==
===What’s 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 the latest evolution of Sahana Software which was initially developed by members of the information technology (IT) community in Sri Lanka to provide solutions for the relief effort following the 2004 Indian Ocean Tsunami. 

===What does Sahana Eden do?===
Sahana Eden provides various of functions which are sorted in several different modules. 

'''Organization Registry''' 
*Sahana Eden’s Organization Registry can track what organizations do and organizations also could record their Offices, Warehouse and Field Sites including their locations so they can be mapped as well as links to other modules such as Human Resources, Assets and Inventory. 
'''Project Tracking''' 
*Sahana Eden provides a valuable tool which could tell people what are going on about the project to help organizations responding to disasters know where the greatest needs are and coordinate with others who are engaged in similar work. 
'''Human Resources''' 
*There are contact lists in Sahana Eden which can be access by users to ensure that the right people can be contacted at the right time. 
'''Inventory''' 
*Sahana Eden can be used to manage inventories of items and match requests for items with warehouses and other facilities which have them available. Sahana Eden can support multiple Catalogs of Items as well as providing alternative items to ensure more effective use of supplies. 
'''Assets''' 
*Sahana Eden is able to manage assets which are needed to respond to disasters, track where they are, who they have been assigned to, and what condition they are in. This ensures that assets are used effectively and efficiently. 
'''Assessments''' 
*Sahana Eden can be used to collect and analyze information from assessments to help organizations more effectively plan their disaster management activities. 
'''Scenarios & Events''' 
*To help organizations better plan for disasters, Sahana Eden can be used to plan for different scenarios, including recording what human resources, assets, facilities and tasks will be needed to effectively respond. 
'''Map''' 
*Sahana Eden has fully integrated mapping functionality which allows any location-based data to be visualized on a map. Maps provide situational awareness which is essential when either planning to prepare for or respond to a disaster. 
'''Shelter Management''' 
*When disasters are widespread and result in population displacement, understanding and tracking the landscape of shelters - and the people in them - is a critical activity. The Shelter Registry provides functionality to list and track information on shelters and on the people arriving and departing. 
'''Messaging''' 
*Sahana Eden provides support for messages to be sent to one or Distribution Groups by Email, SMS, Twitter and Google Talk. Interactive messages can also be set up to allow people to send short message queries to Sahana Eden and receive automatic responses. 

===Sahana Eden 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);">Web Server</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);">Application</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);">Web Application Framework</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);">Programming Language</td>
<td style="border: 1px dotted rgb(0, 0, 0);">Python & Java Script</td>
<td style="border: 1px dotted rgb(0, 0, 0);"></td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Database</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, or SQLite</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, and SQLite are supported.Other databases should be usable without major additional work since Web2Py supplies many connectors.</td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Operating System</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>

==Scope==
We will realize the signup, secure login and logout function, which would add new module into the following files
*communication.js
*controller.js
*model.js
*view.js
We will make it available in multiple languages environment which will implement the languages fold.
We will add some new items including:“ hospital”, “vehicles” which will be added into the folder named “plugins”. The following file will be added into their corrsponding folders: 
Hospitals:
*mHospital.js (model)
*hospital.js, editHospital.js, hospital.html, hospital.css, editHospital.html (views)
*hospitalController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Vehicles:
*mVehicles.js (model)
*vehicles.js, editVehicles.js, vehicles.html, vehicles.css, editVehicles.html (views)
*vehiclesController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Also, we find some bugs and eliminate them. These could be any possible file in this project.
==Documentation==
former developer discussion about Sahana Oden
*An [https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!forum/sahana-eden google discussion], explaining former problems developers met and corresponding solutions
*An [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework basic introduction] about the framework of Edenmobile including application design, source
* [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework Source code]

=Design=
==Overview==
In this design, we add several modules to the EdenMobile client app to allow mobile users to add new shelters and hospitals. Also, users can see the list of hospitals and shelters both offline and online and we can pass users' location to the nearest medical facilities. At last, a multilingual environment is also supported.
==Requirements==
The major requirements are that:
*Secure login;
*Multiple languages;
*users are able to work offline, and update forms and content when online;
*The initial forms that will be implemented are Hospitals, and Shelters;

==Architecture==
==Use Case==

* '''Use Case #1: Security Log in'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills login form, which includes username, password and Captcha code.
*** Submit form to Sahana Server.

* '''Use Case #2: Submit forms to server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to Sahana Server.

* '''Use Case #3: Submit forms to local storage'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to local database.

* '''Use Case #4: Download new forms from server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Download new forms from server

* '''Use Case #5: Synchronize local data with server '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Synchronize local data with server

* '''Use Case #6: Multi-Language Support '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Choose a language from settings page

* The UML use case diagram is shown below:

[[File:S1503_Usecase.png‎ |frame|center|Use Case Diagram]]

=Troubleshoots=
=References=

CSC/ECE 517 Spring 2015 S1503 LWJZ

2015-04-01T02:26:02Z

Hwang40: /* Sahana Eden Architecture */

<big>S1503. JavaRosa Mobile Client</big>
=Introduction=
==Purpose==
This project is aimed at adding new functions to the EdenMobile client app to serve users better.These functions will allow mobile users to realize functions like
adding new shelters and hospitals, observing the list of hospitals and shelters both offline and online ,passing users' location to the nearest medical facilities and realizing a multilingual environment.

==Background==
===What’s 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 the latest evolution of Sahana Software which was initially developed by members of the information technology (IT) community in Sri Lanka to provide solutions for the relief effort following the 2004 Indian Ocean Tsunami. 

===What does Sahana Eden do?===
Sahana Eden provides various of functions which are sorted in several different modules. 

'''Organization Registry''' 
*Sahana Eden’s Organization Registry can track what organizations do and organizations also could record their Offices, Warehouse and Field Sites including their locations so they can be mapped as well as links to other modules such as Human Resources, Assets and Inventory. 
'''Project Tracking''' 
*Sahana Eden provides a valuable tool which could tell people what are going on about the project to help organizations responding to disasters know where the greatest needs are and coordinate with others who are engaged in similar work. 
'''Human Resources''' 
*There are contact lists in Sahana Eden which can be access by users to ensure that the right people can be contacted at the right time. 
'''Inventory''' 
*Sahana Eden can be used to manage inventories of items and match requests for items with warehouses and other facilities which have them available. Sahana Eden can support multiple Catalogs of Items as well as providing alternative items to ensure more effective use of supplies. 
'''Assets''' 
*Sahana Eden is able to manage assets which are needed to respond to disasters, track where they are, who they have been assigned to, and what condition they are in. This ensures that assets are used effectively and efficiently. 
'''Assessments''' 
*Sahana Eden can be used to collect and analyze information from assessments to help organizations more effectively plan their disaster management activities. 
'''Scenarios & Events''' 
*To help organizations better plan for disasters, Sahana Eden can be used to plan for different scenarios, including recording what human resources, assets, facilities and tasks will be needed to effectively respond. 
'''Map''' 
*Sahana Eden has fully integrated mapping functionality which allows any location-based data to be visualized on a map. Maps provide situational awareness which is essential when either planning to prepare for or respond to a disaster. 
'''Shelter Management''' 
*When disasters are widespread and result in population displacement, understanding and tracking the landscape of shelters - and the people in them - is a critical activity. The Shelter Registry provides functionality to list and track information on shelters and on the people arriving and departing. 
'''Messaging''' 
*Sahana Eden provides support for messages to be sent to one or Distribution Groups by Email, SMS, Twitter and Google Talk. Interactive messages can also be set up to allow people to send short message queries to Sahana Eden and receive automatic responses. 

===Sahana Eden Architecture===
The basic Sahana Eden architecture is as follows<ref></ref>:

<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);">Web Server</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);">Application</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);">Web Application Framework</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);">Programming Language</td>
<td style="border: 1px dotted rgb(0, 0, 0);">Python & Java Script</td>
<td style="border: 1px dotted rgb(0, 0, 0);"></td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Database</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, or SQLite</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, and SQLite are supported.Other databases should be usable without major additional work since Web2Py supplies many connectors.</td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Operating System</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>

==Scope==
We will realize the signup, secure login and logout function, which would add new module into the following files
*communication.js
*controller.js
*model.js
*view.js
We will make it available in multiple languages environment which will implement the languages fold.
We will add some new items including:“ hospital”, “vehicles” which will be added into the folder named “plugins”. The following file will be added into their corrsponding folders: 
Hospitals:
*mHospital.js (model)
*hospital.js, editHospital.js, hospital.html, hospital.css, editHospital.html (views)
*hospitalController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Vehicles:
*mVehicles.js (model)
*vehicles.js, editVehicles.js, vehicles.html, vehicles.css, editVehicles.html (views)
*vehiclesController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Also, we find some bugs and eliminate them. These could be any possible file in this project.
==Documentation==
former developer discussion about Sahana Oden
*An [https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!forum/sahana-eden google discussion], explaining former problems developers met and corresponding solutions
*An [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework basic introduction] about the framework of Edenmobile including application design, source
* [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework Source code]

=Design=
==Overview==
In this design, we add several modules to the EdenMobile client app to allow mobile users to add new shelters and hospitals. Also, users can see the list of hospitals and shelters both offline and online and we can pass users' location to the nearest medical facilities. At last, a multilingual environment is also supported.
==Requirements==
The major requirements are that:
*Secure login;
*Multiple languages;
*users are able to work offline, and update forms and content when online;
*The initial forms that will be implemented are Hospitals, and Shelters;

==Architecture==
==Use Case==

* '''Use Case #1: Security Log in'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills login form, which includes username, password and Captcha code.
*** Submit form to Sahana Server.

* '''Use Case #2: Submit forms to server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to Sahana Server.

* '''Use Case #3: Submit forms to local storage'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to local database.

* '''Use Case #4: Download new forms from server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Download new forms from server

* '''Use Case #5: Synchronize local data with server '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Synchronize local data with server

* '''Use Case #6: Multi-Language Support '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Choose a language from settings page

* The UML use case diagram is shown below:

[[File:S1503_Usecase.png‎ |frame|center|Use Case Diagram]]

=Troubleshoots=
=References=

CSC/ECE 517 Spring 2015 S1503 LWJZ

2015-04-01T02:21:17Z

Hwang40: /* What does Sahana Eden do? */

<big>S1503. JavaRosa Mobile Client</big>
=Introduction=
==Purpose==
This project is aimed at adding new functions to the EdenMobile client app to serve users better.These functions will allow mobile users to realize functions like
adding new shelters and hospitals, observing the list of hospitals and shelters both offline and online ,passing users' location to the nearest medical facilities and realizing a multilingual environment.
==Scope==
We will realize the signup, secure login and logout function, which would add new module into the following files
*communication.js
*controller.js
*model.js
*view.js
We will make it available in multiple languages environment which will implement the languages fold.
We will add some new items including:“ hospital”, “vehicles” which will be added into the folder named “plugins”. The following file will be added into their corrsponding folders: 
Hospitals:
*mHospital.js (model)
*hospital.js, editHospital.js, hospital.html, hospital.css, editHospital.html (views)
*hospitalController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Vehicles:
*mVehicles.js (model)
*vehicles.js, editVehicles.js, vehicles.html, vehicles.css, editVehicles.html (views)
*vehiclesController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Also, we find some bugs and eliminate them. These could be any possible file in this project.

==Background==
===What’s 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 the latest evolution of Sahana Software which was initially developed by members of the information technology (IT) community in Sri Lanka to provide solutions for the relief effort following the 2004 Indian Ocean Tsunami. 

===What does Sahana Eden do?===
Sahana Eden provides various of functions which are sorted in several different modules. 

'''Organization Registry''' 
*Sahana Eden’s Organization Registry can track what organizations do and organizations also could record their Offices, Warehouse and Field Sites including their locations so they can be mapped as well as links to other modules such as Human Resources, Assets and Inventory. 
'''Project Tracking''' 
*Sahana Eden provides a valuable tool which could tell people what are going on about the project to help organizations responding to disasters know where the greatest needs are and coordinate with others who are engaged in similar work. 
'''Human Resources''' 
*There are contact lists in Sahana Eden which can be access by users to ensure that the right people can be contacted at the right time. 
'''Inventory''' 
*Sahana Eden can be used to manage inventories of items and match requests for items with warehouses and other facilities which have them available. Sahana Eden can support multiple Catalogs of Items as well as providing alternative items to ensure more effective use of supplies. 
'''Assets''' 
*Sahana Eden is able to manage assets which are needed to respond to disasters, track where they are, who they have been assigned to, and what condition they are in. This ensures that assets are used effectively and efficiently. 
'''Assessments''' 
*Sahana Eden can be used to collect and analyze information from assessments to help organizations more effectively plan their disaster management activities. 
'''Scenarios & Events''' 
*To help organizations better plan for disasters, Sahana Eden can be used to plan for different scenarios, including recording what human resources, assets, facilities and tasks will be needed to effectively respond. 
'''Map''' 
*Sahana Eden has fully integrated mapping functionality which allows any location-based data to be visualized on a map. Maps provide situational awareness which is essential when either planning to prepare for or respond to a disaster. 
'''Shelter Management''' 
*When disasters are widespread and result in population displacement, understanding and tracking the landscape of shelters - and the people in them - is a critical activity. The Shelter Registry provides functionality to list and track information on shelters and on the people arriving and departing. 
'''Messaging''' 
*Sahana Eden provides support for messages to be sent to one or Distribution Groups by Email, SMS, Twitter and Google Talk. Interactive messages can also be set up to allow people to send short message queries to Sahana Eden and receive automatic responses. 

===Sahana Eden 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);">Web Server</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);">Application</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);">Web Application Framework</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);">Programming Language</td>
<td style="border: 1px dotted rgb(0, 0, 0);">Python & Java Script</td>
<td style="border: 1px dotted rgb(0, 0, 0);"></td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Database</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, or SQLite</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, and SQLite are supported.Other databases should be usable without major additional work since Web2Py supplies many connectors.</td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Operating System</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>

==Documentation==
former developer discussion about Sahana Oden
*An [https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!forum/sahana-eden google discussion], explaining former problems developers met and corresponding solutions
*An [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework basic introduction] about the framework of Edenmobile including application design, source
* [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework Source code]

=Design=
==Overview==
In this design, we add several modules to the EdenMobile client app to allow mobile users to add new shelters and hospitals. Also, users can see the list of hospitals and shelters both offline and online and we can pass users' location to the nearest medical facilities. At last, a multilingual environment is also supported.
==Requirements==
The major requirements are that:
*Secure login;
*Multiple languages;
*users are able to work offline, and update forms and content when online;
*The initial forms that will be implemented are Hospitals, and Shelters;

==Architecture==
==Use Case==

* '''Use Case #1: Security Log in'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills login form, which includes username, password and Captcha code.
*** Submit form to Sahana Server.

* '''Use Case #2: Submit forms to server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to Sahana Server.

* '''Use Case #3: Submit forms to local storage'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to local database.

* '''Use Case #4: Download new forms from server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Download new forms from server

* '''Use Case #5: Synchronize local data with server '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Synchronize local data with server

* '''Use Case #6: Multi-Language Support '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Choose a language from settings page

* The UML use case diagram is shown below:

[[File:S1503_Usecase.png‎ |frame|center|Use Case Diagram]]

=Troubleshoots=
=References=

CSC/ECE 517 Spring 2015 S1503 LWJZ

2015-04-01T02:20:38Z

Hwang40: /* Background */

<big>S1503. JavaRosa Mobile Client</big>
=Introduction=
==Purpose==
This project is aimed at adding new functions to the EdenMobile client app to serve users better.These functions will allow mobile users to realize functions like
adding new shelters and hospitals, observing the list of hospitals and shelters both offline and online ,passing users' location to the nearest medical facilities and realizing a multilingual environment.
==Scope==
We will realize the signup, secure login and logout function, which would add new module into the following files
*communication.js
*controller.js
*model.js
*view.js
We will make it available in multiple languages environment which will implement the languages fold.
We will add some new items including:“ hospital”, “vehicles” which will be added into the folder named “plugins”. The following file will be added into their corrsponding folders: 
Hospitals:
*mHospital.js (model)
*hospital.js, editHospital.js, hospital.html, hospital.css, editHospital.html (views)
*hospitalController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Vehicles:
*mVehicles.js (model)
*vehicles.js, editVehicles.js, vehicles.html, vehicles.css, editVehicles.html (views)
*vehiclesController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Also, we find some bugs and eliminate them. These could be any possible file in this project.

==Background==
===What’s 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 the latest evolution of Sahana Software which was initially developed by members of the information technology (IT) community in Sri Lanka to provide solutions for the relief effort following the 2004 Indian Ocean Tsunami. 

===What does Sahana Eden do?===
Sahana Eden provides various of functions which are sorted in several different modules. 

'''Organization Registry''' 
*Sahana Eden’s Organization Registry can track what organizations do and organizations also could record their Offices, Warehouse and Field Sites including their locations so they can be mapped as well as links to other modules such as Human Resources, Assets and Inventory. 
'''Project Tracking''' 
*Sahana Eden provides a valuable tool which could tell people what are going on about the project to help organizations responding to disasters know where the greatest needs are and coordinate with others who are engaged in similar work. 
'''Human Resources''' 
     There are contact lists in Sahana Eden which can be access by users to ensure that the right people can be contacted at the right time. 
'''Inventory''' 
     Sahana Eden can be used to manage inventories of items and match requests for items with warehouses and other facilities which have them available. Sahana Eden can support multiple Catalogs of Items as well as providing alternative items to ensure more effective use of supplies. 
'''Assets''' 
     Sahana Eden is able to manage assets which are needed to respond to disasters, track where they are, who they have been assigned to, and what condition they are in. This ensures that assets are used effectively and efficiently. 
'''Assessments''' 
     Sahana Eden can be used to collect and analyze information from assessments to help organizations more effectively plan their disaster management activities. 
'''Scenarios & Events''' 
    To help organizations better plan for disasters, Sahana Eden can be used to plan for different scenarios, including recording what human resources, assets, facilities and tasks will be needed to effectively respond. 
'''Map''' 
     Sahana Eden has fully integrated mapping functionality which allows any location-based data to be visualized on a map. Maps provide situational awareness which is essential when either planning to prepare for or respond to a disaster. 
'''Shelter Management''' 
     When disasters are widespread and result in population displacement, understanding and tracking the landscape of shelters - and the people in them - is a critical activity. The Shelter Registry provides functionality to list and track information on shelters and on the people arriving and departing. 
'''Messaging''' 
     Sahana Eden provides support for messages to be sent to one or Distribution Groups by Email, SMS, Twitter and Google Talk. Interactive messages can also be set up to allow people to send short message queries to Sahana Eden and receive automatic responses. 

===Sahana Eden 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);">Web Server</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);">Application</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);">Web Application Framework</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);">Programming Language</td>
<td style="border: 1px dotted rgb(0, 0, 0);">Python & Java Script</td>
<td style="border: 1px dotted rgb(0, 0, 0);"></td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Database</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, or SQLite</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, and SQLite are supported.Other databases should be usable without major additional work since Web2Py supplies many connectors.</td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Operating System</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>

==Documentation==
former developer discussion about Sahana Oden
*An [https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!forum/sahana-eden google discussion], explaining former problems developers met and corresponding solutions
*An [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework basic introduction] about the framework of Edenmobile including application design, source
* [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework Source code]

=Design=
==Overview==
In this design, we add several modules to the EdenMobile client app to allow mobile users to add new shelters and hospitals. Also, users can see the list of hospitals and shelters both offline and online and we can pass users' location to the nearest medical facilities. At last, a multilingual environment is also supported.
==Requirements==
The major requirements are that:
*Secure login;
*Multiple languages;
*users are able to work offline, and update forms and content when online;
*The initial forms that will be implemented are Hospitals, and Shelters;

==Architecture==
==Use Case==

* '''Use Case #1: Security Log in'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills login form, which includes username, password and Captcha code.
*** Submit form to Sahana Server.

* '''Use Case #2: Submit forms to server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to Sahana Server.

* '''Use Case #3: Submit forms to local storage'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to local database.

* '''Use Case #4: Download new forms from server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Download new forms from server

* '''Use Case #5: Synchronize local data with server '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Synchronize local data with server

* '''Use Case #6: Multi-Language Support '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Choose a language from settings page

* The UML use case diagram is shown below:

[[File:S1503_Usecase.png‎ |frame|center|Use Case Diagram]]

=Troubleshoots=
=References=

CSC/ECE 517 Spring 2015 S1503 LWJZ

2015-04-01T02:16:22Z

Hwang40:

<big>S1503. JavaRosa Mobile Client</big>
=Introduction=
==Purpose==
This project is aimed at adding new functions to the EdenMobile client app to serve users better.These functions will allow mobile users to realize functions like
adding new shelters and hospitals, observing the list of hospitals and shelters both offline and online ,passing users' location to the nearest medical facilities and realizing a multilingual environment.
==Scope==
We will realize the signup, secure login and logout function, which would add new module into the following files
*communication.js
*controller.js
*model.js
*view.js
We will make it available in multiple languages environment which will implement the languages fold.
We will add some new items including:“ hospital”, “vehicles” which will be added into the folder named “plugins”. The following file will be added into their corrsponding folders: 
Hospitals:
*mHospital.js (model)
*hospital.js, editHospital.js, hospital.html, hospital.css, editHospital.html (views)
*hospitalController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Vehicles:
*mVehicles.js (model)
*vehicles.js, editVehicles.js, vehicles.html, vehicles.css, editVehicles.html (views)
*vehiclesController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Also, we find some bugs and eliminate them. These could be any possible file in this project.

==Background==
===What’s 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 the latest evolution of Sahana Software which was initially developed by members of the information technology (IT) community in Sri Lanka to provide solutions for the relief effort following the 2004 Indian Ocean Tsunami. 

===What does Sahana Eden do?===
Sahana Eden provides various of functions which are sorted in several different modules. 

'''Organization Registry''' 
     Sahana Eden’s Organization Registry can track what organizations do and organizations also could record their Offices, Warehouse and Field Sites including their locations so they can be mapped as well as links to other modules such as Human Resources, Assets and Inventory. 
'''Project Tracking''' 
     Sahana Eden provides a valuable tool which could tell people what are going on about the project to help organizations responding to disasters know where the greatest needs are and coordinate with others who are engaged in similar work. 
'''Human Resources''' 
     There are contact lists in Sahana Eden which can be access by users to ensure that the right people can be contacted at the right time. 
'''Inventory''' 
     Sahana Eden can be used to manage inventories of items and match requests for items with warehouses and other facilities which have them available. Sahana Eden can support multiple Catalogs of Items as well as providing alternative items to ensure more effective use of supplies. 
'''Assets''' 
     Sahana Eden is able to manage assets which are needed to respond to disasters, track where they are, who they have been assigned to, and what condition they are in. This ensures that assets are used effectively and efficiently. 
'''Assessments''' 
     Sahana Eden can be used to collect and analyze information from assessments to help organizations more effectively plan their disaster management activities. 
'''Scenarios & Events''' 
    To help organizations better plan for disasters, Sahana Eden can be used to plan for different scenarios, including recording what human resources, assets, facilities and tasks will be needed to effectively respond. 
'''Map''' 
     Sahana Eden has fully integrated mapping functionality which allows any location-based data to be visualized on a map. Maps provide situational awareness which is essential when either planning to prepare for or respond to a disaster. 
'''Shelter Management''' 
     When disasters are widespread and result in population displacement, understanding and tracking the landscape of shelters - and the people in them - is a critical activity. The Shelter Registry provides functionality to list and track information on shelters and on the people arriving and departing. 
'''Messaging''' 
     Sahana Eden provides support for messages to be sent to one or Distribution Groups by Email, SMS, Twitter and Google Talk. Interactive messages can also be set up to allow people to send short message queries to Sahana Eden and receive automatic responses. 

===Sahana Eden 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);">Web Server</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);">Application</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);">Web Application Framework</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);">Programming Language</td>
<td style="border: 1px dotted rgb(0, 0, 0);">Python & Java Script</td>
<td style="border: 1px dotted rgb(0, 0, 0);"></td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Database</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, or SQLite</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, and SQLite are supported.Other databases should be usable without major additional work since Web2Py supplies many connectors.</td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Operating System</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>

==Documentation==
former developer discussion about Sahana Oden
*An [https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!forum/sahana-eden google discussion], explaining former problems developers met and corresponding solutions
*An [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework basic introduction] about the framework of Edenmobile including application design, source
* [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework Source code]

=Design=
==Overview==
In this design, we add several modules to the EdenMobile client app to allow mobile users to add new shelters and hospitals. Also, users can see the list of hospitals and shelters both offline and online and we can pass users' location to the nearest medical facilities. At last, a multilingual environment is also supported.
==Requirements==
The major requirements are that:
*Secure login;
*Multiple languages;
*users are able to work offline, and update forms and content when online;
*The initial forms that will be implemented are Hospitals, and Shelters;

==Architecture==
=='''Use Case'''==

* '''Use Case #1: Security Log in'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills login form, which includes username, password and Captcha code.
*** Submit form to Sahana Server.

* '''Use Case #2: Submit forms to server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to Sahana Server.

* '''Use Case #3: Submit forms to local storage'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to local database.

* '''Use Case #4: Download new forms from server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Download new forms from server

* '''Use Case #5: Synchronize local data with server '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Synchronize local data with server

* '''Use Case #6: Multi-Language Support '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Choose a language from settings page

* The UML use case diagram is shown below:

[[File:S1503_Usecase.png‎ |frame|center|Use Case Diagram]]

=Troubleshoots=
=References=

CSC/ECE 517 Spring 2015 S1503 LWJZ

2015-04-01T02:15:25Z

Hwang40: /* What does Sahana Eden do? */

<big>S1503. JavaRosa Mobile Client</big>
=Introduction=
==Purpose==
This project is aimed at adding new functions to the EdenMobile client app to serve users better.These functions will allow mobile users to realize functions like
adding new shelters and hospitals, observing the list of hospitals and shelters both offline and online ,passing users' location to the nearest medical facilities and realizing a multilingual environment.
==Scope==
We will realize the signup, secure login and logout function, which would add new module into the following files
*communication.js
*controller.js
*model.js
*view.js
We will make it available in multiple languages environment which will implement the languages fold.
We will add some new items including:“ hospital”, “vehicles” which will be added into the folder named “plugins”. The following file will be added into their corrsponding folders: 
Hospitals:
*mHospital.js (model)
*hospital.js, editHospital.js, hospital.html, hospital.css, editHospital.html (views)
*hospitalController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Vehicles:
*mVehicles.js (model)
*vehicles.js, editVehicles.js, vehicles.html, vehicles.css, editVehicles.html (views)
*vehiclesController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Also, we find some bugs and eliminate them. These could be any possible file in this project.

==Background==
===What’s 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 the latest evolution of Sahana Software which was initially developed by members of the information technology (IT) community in Sri Lanka to provide solutions for the relief effort following the 2004 Indian Ocean Tsunami. 

===What does Sahana Eden do?===
Sahana Eden provides various of functions which are sorted in several different modules. 

'''Organization Registry''' 
     Sahana Eden’s Organization Registry can track what organizations do and organizations also could record their Offices, Warehouse and Field Sites including their locations so they can be mapped as well as links to other modules such as Human Resources, Assets and Inventory. 
'''Project Tracking''' 
     Sahana Eden provides a valuable tool which could tell people what are going on about the project to help organizations responding to disasters know where the greatest needs are and coordinate with others who are engaged in similar work. 
'''Human Resources''' 
     There are contact lists in Sahana Eden which can be access by users to ensure that the right people can be contacted at the right time. 
'''Inventory''' 
     Sahana Eden can be used to manage inventories of items and match requests for items with warehouses and other facilities which have them available. Sahana Eden can support multiple Catalogs of Items as well as providing alternative items to ensure more effective use of supplies. 
'''Assets''' 
     Sahana Eden is able to manage assets which are needed to respond to disasters, track where they are, who they have been assigned to, and what condition they are in. This ensures that assets are used effectively and efficiently. 
'''Assessments''' 
     Sahana Eden can be used to collect and analyze information from assessments to help organizations more effectively plan their disaster management activities. 
'''Scenarios & Events''' 
    To help organizations better plan for disasters, Sahana Eden can be used to plan for different scenarios, including recording what human resources, assets, facilities and tasks will be needed to effectively respond. 
'''Map''' 
     Sahana Eden has fully integrated mapping functionality which allows any location-based data to be visualized on a map. Maps provide situational awareness which is essential when either planning to prepare for or respond to a disaster. 
'''Shelter Management''' 
     When disasters are widespread and result in population displacement, understanding and tracking the landscape of shelters - and the people in them - is a critical activity. The Shelter Registry provides functionality to list and track information on shelters and on the people arriving and departing. 
'''Messaging''' 
     Sahana Eden provides support for messages to be sent to one or Distribution Groups by Email, SMS, Twitter and Google Talk. Interactive messages can also be set up to allow people to send short message queries to Sahana Eden and receive automatic responses. 

===Sahana Eden 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);">Web Server</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);">Application</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);">Web Application Framework</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);">Programming Language</td>
<td style="border: 1px dotted rgb(0, 0, 0);">Python & Java Script</td>
<td style="border: 1px dotted rgb(0, 0, 0);"></td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Database</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, or SQLite</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, and SQLite are supported.Other databases should be usable without major additional work since Web2Py supplies many connectors.</td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Operating System</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>

===Documentation===
former developer discussion about Sahana Oden
*An [https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!forum/sahana-eden google discussion], explaining former problems developers met and corresponding solutions
*An [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework basic introduction] about the framework of Edenmobile including application design, source
* [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework Source code]

=Design=
==Overview==
In this design, we add several modules to the EdenMobile client app to allow mobile users to add new shelters and hospitals. Also, users can see the list of hospitals and shelters both offline and online and we can pass users' location to the nearest medical facilities. At last, a multilingual environment is also supported.
==Requirements==
The major requirements are that:
*Secure login;
*Multiple languages;
*users are able to work offline, and update forms and content when online;
*The initial forms that will be implemented are Hospitals, and Shelters;

==Architecture==
=='''Use Case'''==

* '''Use Case #1: Security Log in'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills login form, which includes username, password and Captcha code.
*** Submit form to Sahana Server.

* '''Use Case #2: Submit forms to server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to Sahana Server.

* '''Use Case #3: Submit forms to local storage'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to local database.

* '''Use Case #4: Download new forms from server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Download new forms from server

* '''Use Case #5: Synchronize local data with server '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Synchronize local data with server

* '''Use Case #6: Multi-Language Support '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Choose a language from settings page

* The UML use case diagram is shown below:

[[File:S1503_Usecase.png‎ |frame|center|Use Case Diagram]]

=Troubleshoots=
=References=

CSC/ECE 517 Spring 2015 S1503 LWJZ

2015-04-01T02:07:06Z

Hwang40: /* What does Sahana Eden do? */

<big>S1503. JavaRosa Mobile Client</big>
=Introduction=
==Purpose==
This project is aimed at adding new functions to the EdenMobile client app to serve users better.These functions will allow mobile users to realize functions like
adding new shelters and hospitals, observing the list of hospitals and shelters both offline and online ,passing users' location to the nearest medical facilities and realizing a multilingual environment.
==Scope==
We will realize the signup, secure login and logout function, which would add new module into the following files
*communication.js
*controller.js
*model.js
*view.js
We will make it available in multiple languages environment which will implement the languages fold.
We will add some new items including:“ hospital”, “vehicles” which will be added into the folder named “plugins”. The following file will be added into their corrsponding folders: 
Hospitals:
*mHospital.js (model)
*hospital.js, editHospital.js, hospital.html, hospital.css, editHospital.html (views)
*hospitalController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Vehicles:
*mVehicles.js (model)
*vehicles.js, editVehicles.js, vehicles.html, vehicles.css, editVehicles.html (views)
*vehiclesController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Also, we find some bugs and eliminate them. These could be any possible file in this project.

==Background==
===What’s 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 the latest evolution of Sahana Software which was initially developed by members of the information technology (IT) community in Sri Lanka to provide solutions for the relief effort following the 2004 Indian Ocean Tsunami. 

===What does Sahana Eden do?===
Sahana Eden provides various of functions which are sorted in several different modules. 

'''Organization Registry''' 
Sahana Eden’s Organization Registry can track what organizations do and organizations also could record their Offices, Warehouse and Field Sites including their locations so they can be mapped as well as links to other modules such as Human Resources, Assets and Inventory. 
'''Project Tracking''' 
Sahana Eden provides a valuable tool which could tell people what are going on about the project to help organizations responding to disasters know where the greatest needs are and coordinate with others who are engaged in similar work. 
'''Human Resources''' 
There are contact lists in Sahana Eden which can be access by users to ensure that the right people can be contacted at the right time. 
'''Inventory''' 
Sahana Eden can be used to manage inventories of items and match requests for items with warehouses and other facilities which have them available. Sahana Eden can support multiple Catalogs of Items as well as providing alternative items to ensure more effective use of supplies. 
'''Assets''' 
Sahana Eden is able to manage assets which are needed to respond to disasters, track where they are, who they have been assigned to, and what condition they are in. This ensures that assets are used effectively and efficiently. 
'''Assessments''' 
Sahana Eden can be used to collect and analyze information from assessments to help organizations more effectively plan their disaster management activities. 
'''Scenarios & Events''' 
To help organizations better plan for disasters, Sahana Eden can be used to plan for different scenarios, including recording what human resources, assets, facilities and tasks will be needed to effectively respond. 
'''Map''' 
Sahana Eden has fully integrated mapping functionality which allows any location-based data to be visualized on a map. Maps provide situational awareness which is essential when either planning to prepare for or respond to a disaster. 
'''Shelter Management''' 
When disasters are widespread and result in population displacement, understanding and tracking the landscape of shelters - and the people in them - is a critical activity. The Shelter Registry provides functionality to list and track information on shelters and on the people arriving and departing. 
'''Messaging''' 
Sahana Eden provides support for messages to be sent to one or Distribution Groups by Email, SMS, Twitter and Google Talk. Interactive messages can also be set up to allow people to send short message queries to Sahana Eden and receive automatic responses. 

===Sahana Eden 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);">Web Server</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);">Application</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);">Web Application Framework</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);">Programming Language</td>
<td style="border: 1px dotted rgb(0, 0, 0);">Python & Java Script</td>
<td style="border: 1px dotted rgb(0, 0, 0);"></td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Database</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, or SQLite</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, and SQLite are supported.Other databases should be usable without major additional work since Web2Py supplies many connectors.</td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Operating System</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>

===Documentation===
former developer discussion about Sahana Oden
*An [https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!forum/sahana-eden google discussion], explaining former problems developers met and corresponding solutions
*An [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework basic introduction] about the framework of Edenmobile including application design, source
* [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework Source code]

=Design=
==Overview==
In this design, we add several modules to the EdenMobile client app to allow mobile users to add new shelters and hospitals. Also, users can see the list of hospitals and shelters both offline and online and we can pass users' location to the nearest medical facilities. At last, a multilingual environment is also supported.
==Requirements==
The major requirements are that:
*Secure login;
*Multiple languages;
*users are able to work offline, and update forms and content when online;
*The initial forms that will be implemented are Hospitals, and Shelters;

==Architecture==
=='''Use Case'''==

* '''Use Case #1: Security Log in'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills login form, which includes username, password and Captcha code.
*** Submit form to Sahana Server.

* '''Use Case #2: Submit forms to server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to Sahana Server.

* '''Use Case #3: Submit forms to local storage'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to local database.

* '''Use Case #4: Download new forms from server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Download new forms from server

* '''Use Case #5: Synchronize local data with server '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Synchronize local data with server

* '''Use Case #6: Multi-Language Support '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Choose a language from settings page

* The UML use case diagram is shown below:

[[File:S1503_Usecase.png‎ |frame|center|Use Case Diagram]]

=Troubleshoots=

CSC/ECE 517 Spring 2015 S1503 LWJZ

2015-04-01T02:05:57Z

Hwang40: /* What does Sahana Eden do? */

<big>S1503. JavaRosa Mobile Client</big>
=Introduction=
==Purpose==
This project is aimed at adding new functions to the EdenMobile client app to serve users better.These functions will allow mobile users to realize functions like
adding new shelters and hospitals, observing the list of hospitals and shelters both offline and online ,passing users' location to the nearest medical facilities and realizing a multilingual environment.
==Scope==
We will realize the signup, secure login and logout function, which would add new module into the following files
*communication.js
*controller.js
*model.js
*view.js
We will make it available in multiple languages environment which will implement the languages fold.
We will add some new items including:“ hospital”, “vehicles” which will be added into the folder named “plugins”. The following file will be added into their corrsponding folders: 
Hospitals:
*mHospital.js (model)
*hospital.js, editHospital.js, hospital.html, hospital.css, editHospital.html (views)
*hospitalController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Vehicles:
*mVehicles.js (model)
*vehicles.js, editVehicles.js, vehicles.html, vehicles.css, editVehicles.html (views)
*vehiclesController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Also, we find some bugs and eliminate them. These could be any possible file in this project.

==Background==
===What’s 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 the latest evolution of Sahana Software which was initially developed by members of the information technology (IT) community in Sri Lanka to provide solutions for the relief effort following the 2004 Indian Ocean Tsunami. 

===What does Sahana Eden do?===
Sahana Eden provides various of functions which are sorted in several different modules. 

'''Organization Registry''' 
Sahana Eden’s Organization Registry can track what organizations do and organizations also could record their Offices, Warehouse and Field Sites including their locations so they can be mapped as well as links to other modules such as Human Resources, Assets and Inventory. 
'''Project Tracking''' 
Sahana Eden provides a valuable tool which could tell people what are going on about the project to help organizations responding to disasters know where the greatest needs are and coordinate with others who are engaged in similar work. 
'''Human Resources''' 
There are contact lists in Sahana Eden which can be access by users to ensure that the right people can be contacted at the right time. 
'''Inventory''' 
Sahana Eden can be used to manage inventories of items and match requests for items with warehouses and other facilities which have them available. Sahana Eden can support multiple Catalogs of Items as well as providing alternative items to ensure more effective use of supplies. 
'''Assets''' 
Sahana Eden is able to manage assets which are needed to respond to disasters, track where they are, who they have been assigned to, and what condition they are in. This ensures that assets are used effectively and efficiently. 
'''Assessments''' 
Sahana Eden can be used to collect and analyze information from assessments to help organizations more effectively plan their disaster management activities. 
'''Scenarios & Events''' 
To help organizations better plan for disasters, Sahana Eden can be used to plan for different scenarios, including recording what human resources, assets, facilities and tasks will be needed to effectively respond. 
'''Map''' 
Sahana Eden has fully integrated mapping functionality which allows any location-based data to be visualized on a map. Maps provide situational awareness which is essential when either planning to prepare for or respond to a disaster. 
'''Shelter Management''' 
When disasters are widespread and result in population displacement, understanding and tracking the landscape of shelters - and the people in them - is a critical activity. The Shelter Registry provides functionality to list and track information on shelters and on the people arriving and departing. 
'''Messaging''' 
Sahana Eden provides support for messages to be sent to one or Distribution Groups by Email, SMS, Twitter and Google Talk. Interactive messages can also be set up to allow people to send short message queries to Sahana Eden and receive automatic responses. 

===Sahana Eden 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);">Web Server</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);">Application</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);">Web Application Framework</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);">Programming Language</td>
<td style="border: 1px dotted rgb(0, 0, 0);">Python & Java Script</td>
<td style="border: 1px dotted rgb(0, 0, 0);"></td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Database</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, or SQLite</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, and SQLite are supported.Other databases should be usable without major additional work since Web2Py supplies many connectors.</td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Operating System</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>

===Documentation===
former developer discussion about Sahana Oden
*An [https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!forum/sahana-eden google discussion], explaining former problems developers met and corresponding solutions
*An [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework basic introduction] about the framework of Edenmobile including application design, source
* [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework Source code]

=Design=
==Overview==
In this design, we add several modules to the EdenMobile client app to allow mobile users to add new shelters and hospitals. Also, users can see the list of hospitals and shelters both offline and online and we can pass users' location to the nearest medical facilities. At last, a multilingual environment is also supported.
==Requirements==
The major requirements are that:
*Secure login;
*Multiple languages;
*users are able to work offline, and update forms and content when online;
*The initial forms that will be implemented are Hospitals, and Shelters;

==Architecture==
=='''Use Case'''==

* '''Use Case #1: Security Log in'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills login form, which includes username, password and Captcha code.
*** Submit form to Sahana Server.

* '''Use Case #2: Submit forms to server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to Sahana Server.

* '''Use Case #3: Submit forms to local storage'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to local database.

* '''Use Case #4: Download new forms from server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Download new forms from server

* '''Use Case #5: Synchronize local data with server '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Synchronize local data with server

* '''Use Case #6: Multi-Language Support '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Choose a language from settings page

* The UML use case diagram is shown below:

[[File:S1503_Usecase.png‎ |frame|center|Use Case Diagram]]

=Troubleshoots=

CSC/ECE 517 Spring 2015 S1503 LWJZ

2015-04-01T01:58:15Z

Hwang40: /* Background */

<big>S1503. JavaRosa Mobile Client</big>
==Introduction==
===Purpose===
This project is aimed at adding new functions to the EdenMobile client app to serve users better.These functions will allow mobile users to realize functions like
adding new shelters and hospitals, observing the list of hospitals and shelters both offline and online ,passing users' location to the nearest medical facilities and realizing a multilingual environment.
===Scope===
We will realize the signup, secure login and logout function, which would add new module into the following files
*communication.js
*controller.js
*model.js
*view.js
We will make it available in multiple languages environment which will implement the languages fold.
We will add some new items including:“ hospital”, “vehicles” which will be added into the folder named “plugins”. The following file will be added into their corrsponding folders: 
Hospitals:
*mHospital.js (model)
*hospital.js, editHospital.js, hospital.html, hospital.css, editHospital.html (views)
*hospitalController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Vehicles:
*mVehicles.js (model)
*vehicles.js, editVehicles.js, vehicles.html, vehicles.css, editVehicles.html (views)
*vehiclesController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Also, we find some bugs and eliminate them. These could be any possible file in this project.

===Background===
====What’s 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 the latest evolution of Sahana Software which was initially developed by members of the information technology (IT) community in Sri Lanka to provide solutions for the relief effort following the 2004 Indian Ocean Tsunami. 

====What does Sahana Eden do?====
Sahana Eden provides various of functions which are sorted in several different modules. 

'''Organization Registry''' 
Sahana Eden’s Organization Registry can track what organizations do and organizations also could record their Offices, Warehouse and Field Sites including their locations so they can be mapped as well as links to other modules such as Human Resources, Assets and Inventory. 
'''Project Tracking''' 
Sahana Eden provides a valuable tool which could tell people what are going on about the project to help organizations responding to disasters know where the greatest needs are and coordinate with others who are engaged in similar work. 
'''Human Resources''' 
There are contact lists in Sahana Eden which can be access by users to ensure that the right people can be contacted at the right time. 
'''Inventory''' 
Sahana Eden can be used to manage inventories of items and match requests for items with warehouses and other facilities which have them available. Sahana Eden can support multiple Catalogs of Items as well as providing alternative items to ensure more effective use of supplies. 
'''Assets''' 
Sahana Eden is able to manage assets which are needed to respond to disasters, track where they are, who they have been assigned to, and what condition they are in. This ensures that assets are used effectively and efficiently. 
'''Assessments''' 
Sahana Eden can be used to collect and analyze information from assessments to help organizations more effectively plan their disaster management activities. 
'''Scenarios & Events''' 
To help organizations better plan for disasters, Sahana Eden can be used to plan for different scenarios, including recording what human resources, assets, facilities and tasks will be needed to effectively respond. 
'''Map''' 
Sahana Eden has fully integrated mapping functionality which allows any location-based data to be visualized on a map. Maps provide situational awareness which is essential when either planning to prepare for or respond to a disaster. 
'''Shelter Management''' 
When disasters are widespread and result in population displacement, understanding and tracking the landscape of shelters - and the people in them - is a critical activity. The Shelter Registry provides functionality to list and track information on shelters and on the people arriving and departing. 
'''Messaging''' 
Sahana Eden provides support for messages to be sent to one or Distribution Groups by Email, SMS, Twitter and Google Talk. Interactive messages can also be set up to allow people to send short message queries to Sahana Eden and receive automatic responses. 
====Sahana Eden 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);">Web Server</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);">Application</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);">Web Application Framework</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);">Programming Language</td>
<td style="border: 1px dotted rgb(0, 0, 0);">Python & Java Script</td>
<td style="border: 1px dotted rgb(0, 0, 0);"></td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Database</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, or SQLite</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, and SQLite are supported.Other databases should be usable without major additional work since Web2Py supplies many connectors.</td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Operating System</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>

====Documentation====
former developer discussion about Sahana Oden
*An [https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!forum/sahana-eden google discussion], explaining former problems developers met and corresponding solutions
*An [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework basic introduction] about the framework of Edenmobile including application design, source
* [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework Source code]

===Design===
=====Overview=====
In this design, we add several modules to the EdenMobile client app to allow mobile users to add new shelters and hospitals. Also, users can see the list of hospitals and shelters both offline and online and we can pass users' location to the nearest medical facilities. At last, a multilingual environment is also supported.
=====Requirements=====
The major requirements are that:
*Secure login;
*Multiple languages;
*users are able to work offline, and update forms and content when online;
*The initial forms that will be implemented are Hospitals, and Shelters;

===Architecture===
=='''Use Case'''==

* '''Use Case #1: Security Log in'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills login form, which includes username, password and Captcha code.
*** Submit form to Sahana Server.

* '''Use Case #2: Submit forms to server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to Sahana Server.

* '''Use Case #3: Submit forms to local storage'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to local database.

* '''Use Case #4: Download new forms from server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Download new forms from server

* '''Use Case #5: Synchronize local data with server '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Synchronize local data with server

* '''Use Case #6: Multi-Language Support '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Choose a language from settings page

* The UML use case diagram is shown below:

[[File:S1503_Usecase.png‎ |frame|center|Use Case Diagram]]

=Troubleshoots=

CSC/ECE 517 Spring 2015 S1503 LWJZ

2015-04-01T01:55:37Z

Hwang40: /* Background */

<big>S1503. JavaRosa Mobile Client</big>
==Introduction==
===Purpose===
This project is aimed at adding new functions to the EdenMobile client app to serve users better.These functions will allow mobile users to realize functions like
adding new shelters and hospitals, observing the list of hospitals and shelters both offline and online ,passing users' location to the nearest medical facilities and realizing a multilingual environment.
===Scope===
We will realize the signup, secure login and logout function, which would add new module into the following files
*communication.js
*controller.js
*model.js
*view.js
We will make it available in multiple languages environment which will implement the languages fold.
We will add some new items including:“ hospital”, “vehicles” which will be added into the folder named “plugins”. The following file will be added into their corrsponding folders: 
Hospitals:
*mHospital.js (model)
*hospital.js, editHospital.js, hospital.html, hospital.css, editHospital.html (views)
*hospitalController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Vehicles:
*mVehicles.js (model)
*vehicles.js, editVehicles.js, vehicles.html, vehicles.css, editVehicles.html (views)
*vehiclesController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Also, we find some bugs and eliminate them. These could be any possible file in this project.

===Background===
====What’s 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 the latest evolution of Sahana Software which was initially developed by members of the information technology (IT) community in Sri Lanka to provide solutions for the relief effort following the 2004 Indian Ocean Tsunami. 

====What does Sahana Eden do?====
Sahana Eden provides various of functions which are sorted in several different modules. 

'''Organization Registry'''
Sahana Eden’s Organization Registry can track what organizations do and organizations also could record their Offices, Warehouse and Field Sites including their locations so they can be mapped as well as links to other modules such as Human Resources, Assets and Inventory. 
'''Project Tracking'''
Sahana Eden provides a valuable tool which could tell people what are going on about the project to help organizations responding to disasters know where the greatest needs are and coordinate with others who are engaged in similar work. 
=====Human Resources=====
There are contact lists in Sahana Eden which can be access by users to ensure that the right people can be contacted at the right time. 
=====Inventory=====
Sahana Eden can be used to manage inventories of items and match requests for items with warehouses and other facilities which have them available. Sahana Eden can support multiple Catalogs of Items as well as providing alternative items to ensure more effective use of supplies. 
=====Assets=====
Sahana Eden is able to manage assets which are needed to respond to disasters, track where they are, who they have been assigned to, and what condition they are in. This ensures that assets are used effectively and efficiently. 
=====Assessments=====
Sahana Eden can be used to collect and analyze information from assessments to help organizations more effectively plan their disaster management activities. 
=====Scenarios & Events=====
To help organizations better plan for disasters, Sahana Eden can be used to plan for different scenarios, including recording what human resources, assets, facilities and tasks will be needed to effectively respond. 
=====Map=====
Sahana Eden has fully integrated mapping functionality which allows any location-based data to be visualized on a map. Maps provide situational awareness which is essential when either planning to prepare for or respond to a disaster. 
=====Shelter Management=====
When disasters are widespread and result in population displacement, understanding and tracking the landscape of shelters - and the people in them - is a critical activity. The Shelter Registry provides functionality to list and track information on shelters and on the people arriving and departing. 
=====Messaging=====
Sahana Eden provides support for messages to be sent to one or Distribution Groups by Email, SMS, Twitter and Google Talk. Interactive messages can also be set up to allow people to send short message queries to Sahana Eden and receive automatic responses. 
=====Sahana Eden 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);">Web Server</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);">Application</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);">Web Application Framework</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);">Programming Language</td>
<td style="border: 1px dotted rgb(0, 0, 0);">Python & Java Script</td>
<td style="border: 1px dotted rgb(0, 0, 0);"></td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Database</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, or SQLite</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, and SQLite are supported.Other databases should be usable without major additional work since Web2Py supplies many connectors.</td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Operating System</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>

====Documentation====
former developer discussion about Sahana Oden
*An [https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!forum/sahana-eden google discussion], explaining former problems developers met and corresponding solutions
*An [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework basic introduction] about the framework of Edenmobile including application design, source
* [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework Source code]

===Design===
=====Overview=====
In this design, we add several modules to the EdenMobile client app to allow mobile users to add new shelters and hospitals. Also, users can see the list of hospitals and shelters both offline and online and we can pass users' location to the nearest medical facilities. At last, a multilingual environment is also supported.
=====Requirements=====
The major requirements are that:
*Secure login;
*Multiple languages;
*users are able to work offline, and update forms and content when online;
*The initial forms that will be implemented are Hospitals, and Shelters;

===Architecture===
=='''Use Case'''==

* '''Use Case #1: Security Log in'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills login form, which includes username, password and Captcha code.
*** Submit form to Sahana Server.

* '''Use Case #2: Submit forms to server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to Sahana Server.

* '''Use Case #3: Submit forms to local storage'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to local database.

* '''Use Case #4: Download new forms from server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Download new forms from server

* '''Use Case #5: Synchronize local data with server '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Synchronize local data with server

* '''Use Case #6: Multi-Language Support '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Choose a language from settings page

* The UML use case diagram is shown below:

[[File:S1503_Usecase.png‎ |frame|center|Use Case Diagram]]

=Troubleshoots=

CSC/ECE 517 Spring 2015 S1503 LWJZ

2015-04-01T01:54:51Z

Hwang40: /* Background */

<big>S1503. JavaRosa Mobile Client</big>
==Introduction==
===Purpose===
This project is aimed at adding new functions to the EdenMobile client app to serve users better.These functions will allow mobile users to realize functions like
adding new shelters and hospitals, observing the list of hospitals and shelters both offline and online ,passing users' location to the nearest medical facilities and realizing a multilingual environment.
===Scope===
We will realize the signup, secure login and logout function, which would add new module into the following files
*communication.js
*controller.js
*model.js
*view.js
We will make it available in multiple languages environment which will implement the languages fold.
We will add some new items including:“ hospital”, “vehicles” which will be added into the folder named “plugins”. The following file will be added into their corrsponding folders: 
Hospitals:
*mHospital.js (model)
*hospital.js, editHospital.js, hospital.html, hospital.css, editHospital.html (views)
*hospitalController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Vehicles:
*mVehicles.js (model)
*vehicles.js, editVehicles.js, vehicles.html, vehicles.css, editVehicles.html (views)
*vehiclesController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Also, we find some bugs and eliminate them. These could be any possible file in this project.

===Background===
====What’s 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 the latest evolution of Sahana Software which was initially developed by members of the information technology (IT) community in Sri Lanka to provide solutions for the relief effort following the 2004 Indian Ocean Tsunami. 

====What does Sahana Eden do?====
Sahana Eden provides various of functions which are sorted in several different modules. 

*Organization Registry
Sahana Eden’s Organization Registry can track what organizations do and organizations also could record their Offices, Warehouse and Field Sites including their locations so they can be mapped as well as links to other modules such as Human Resources, Assets and Inventory. 
*Project Tracking
Sahana Eden provides a valuable tool which could tell people what are going on about the project to help organizations responding to disasters know where the greatest needs are and coordinate with others who are engaged in similar work. 
=====Human Resources=====
There are contact lists in Sahana Eden which can be access by users to ensure that the right people can be contacted at the right time. 
=====Inventory=====
Sahana Eden can be used to manage inventories of items and match requests for items with warehouses and other facilities which have them available. Sahana Eden can support multiple Catalogs of Items as well as providing alternative items to ensure more effective use of supplies. 
=====Assets=====
Sahana Eden is able to manage assets which are needed to respond to disasters, track where they are, who they have been assigned to, and what condition they are in. This ensures that assets are used effectively and efficiently. 
=====Assessments=====
Sahana Eden can be used to collect and analyze information from assessments to help organizations more effectively plan their disaster management activities. 
=====Scenarios & Events=====
To help organizations better plan for disasters, Sahana Eden can be used to plan for different scenarios, including recording what human resources, assets, facilities and tasks will be needed to effectively respond. 
=====Map=====
Sahana Eden has fully integrated mapping functionality which allows any location-based data to be visualized on a map. Maps provide situational awareness which is essential when either planning to prepare for or respond to a disaster. 
=====Shelter Management=====
When disasters are widespread and result in population displacement, understanding and tracking the landscape of shelters - and the people in them - is a critical activity. The Shelter Registry provides functionality to list and track information on shelters and on the people arriving and departing. 
=====Messaging=====
Sahana Eden provides support for messages to be sent to one or Distribution Groups by Email, SMS, Twitter and Google Talk. Interactive messages can also be set up to allow people to send short message queries to Sahana Eden and receive automatic responses. 
====Sahana Eden 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);">Web Server</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);">Application</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);">Web Application Framework</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);">Programming Language</td>
<td style="border: 1px dotted rgb(0, 0, 0);">Python & Java Script</td>
<td style="border: 1px dotted rgb(0, 0, 0);"></td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Database</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, or SQLite</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, and SQLite are supported.Other databases should be usable without major additional work since Web2Py supplies many connectors.</td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Operating System</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>

===Documentation===
former developer discussion about Sahana Oden
*An [https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!forum/sahana-eden google discussion], explaining former problems developers met and corresponding solutions
*An [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework basic introduction] about the framework of Edenmobile including application design, source
* [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework Source code]

==Design==
====Overview====
In this design, we add several modules to the EdenMobile client app to allow mobile users to add new shelters and hospitals. Also, users can see the list of hospitals and shelters both offline and online and we can pass users' location to the nearest medical facilities. At last, a multilingual environment is also supported.
====Requirements===
The major requirements are that:
*Secure login;
*Multiple languages;
*users are able to work offline, and update forms and content when online;
*The initial forms that will be implemented are Hospitals, and Shelters;

===Architecture===
=='''Use Case'''==

* '''Use Case #1: Security Log in'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills login form, which includes username, password and Captcha code.
*** Submit form to Sahana Server.

* '''Use Case #2: Submit forms to server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to Sahana Server.

* '''Use Case #3: Submit forms to local storage'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to local database.

* '''Use Case #4: Download new forms from server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Download new forms from server

* '''Use Case #5: Synchronize local data with server '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Synchronize local data with server

* '''Use Case #6: Multi-Language Support '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Choose a language from settings page

* The UML use case diagram is shown below:

[[File:S1503_Usecase.png‎ |frame|center|Use Case Diagram]]

=Troubleshoots=

CSC/ECE 517 Spring 2015 S1503 LWJZ

2015-04-01T01:35:07Z

Hwang40: /* Background */

<big>E1526. JavaRosa Mobile Client</big>
=Introduction=
==Purpose==
This project is aimed at adding new functions to the EdenMobile client app to serve users better.These functions will allow mobile users to realize functions like
adding new shelters and hospitals, observing the list of hospitals and shelters both offline and online ,passing users' location to the nearest medical facilities and realizing a multilingual environment.
==Scope==
We will realize the signup, secure login and logout function, which would add new module into the following files
*communication.js
*controller.js
*model.js
*view.js
We will make it available in multiple languages environment which will implement the languages fold.
We will add some new items including:“ hospital”, “vehicles” which will be added into the folder named “plugins”. The following file will be added into their corrsponding folders: 
Hospitals:
*mHospital.js (model)
*hospital.js, editHospital.js, hospital.html, hospital.css, editHospital.html (views)
*hospitalController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Vehicles:
*mVehicles.js (model)
*vehicles.js, editVehicles.js, vehicles.html, vehicles.css, editVehicles.html (views)
*vehiclesController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Also, we find some bugs and eliminate them. These could be any possible file in this project.

==Background==
===What’s 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 the latest evolution of Sahana Software which was initially developed by members of the information technology (IT) community in Sri Lanka to provide solutions for the relief effort following the 2004 Indian Ocean Tsunami. 

===What does Sahana Eden do?===
Sahana Eden provides various of functions which are sorted in several different modules. 

===Organization Registry===
Sahana Eden’s Organization Registry can track what organizations do and organizations also could record their Offices, Warehouse and Field Sites including their locations so they can be mapped as well as links to other modules such as Human Resources, Assets and Inventory. 
====Project Tracking====
Sahana Eden provides a valuable tool which could tell people what are going on about the project to help organizations responding to disasters know where the greatest needs are and coordinate with others who are engaged in similar work. 
====Human Resources====
There are contact lists in Sahana Eden which can be access by users to ensure that the right people can be contacted at the right time. 
====Inventory====
Sahana Eden can be used to manage inventories of items and match requests for items with warehouses and other facilities which have them available. Sahana Eden can support multiple Catalogs of Items as well as providing alternative items to ensure more effective use of supplies. 
====Assets====
Sahana Eden is able to manage assets which are needed to respond to disasters, track where they are, who they have been assigned to, and what condition they are in. This ensures that assets are used effectively and efficiently. 
====Assessments====
Sahana Eden can be used to collect and analyze information from assessments to help organizations more effectively plan their disaster management activities. 
====Scenarios & Events====
To help organizations better plan for disasters, Sahana Eden can be used to plan for different scenarios, including recording what human resources, assets, facilities and tasks will be needed to effectively respond. 
====Map ====
Sahana Eden has fully integrated mapping functionality which allows any location-based data to be visualized on a map. Maps provide situational awareness which is essential when either planning to prepare for or respond to a disaster. 
====Shelter Management====
When disasters are widespread and result in population displacement, understanding and tracking the landscape of shelters - and the people in them - is a critical activity. The Shelter Registry provides functionality to list and track information on shelters and on the people arriving and departing. 
====Messaging====
Sahana Eden provides support for messages to be sent to one or Distribution Groups by Email, SMS, Twitter and Google Talk. Interactive messages can also be set up to allow people to send short message queries to Sahana Eden and receive automatic responses. 
===Sahana Eden 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);">Web Server</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);">Application</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);">Web Application Framework</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);">Programming Language</td>
<td style="border: 1px dotted rgb(0, 0, 0);">Python & Java Script</td>
<td style="border: 1px dotted rgb(0, 0, 0);"></td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Database</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, or SQLite</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, and SQLite are supported.Other databases should be usable without major additional work since Web2Py supplies many connectors.</td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Operating System</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>

==Documentation==
former developer discussion about Sahana Oden
*An [https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!forum/sahana-eden google discussion], explaining former problems developers met and corresponding solutions
*An [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework basic introduction] about the framework of Edenmobile including application design, source
* [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework Source code]

=Design=
===Overview===
In this design, we add several modules to the EdenMobile client app to allow mobile users to add new shelters and hospitals. Also, users can see the list of hospitals and shelters both offline and online and we can pass users' location to the nearest medical facilities. At last, a multilingual environment is also supported.
===Requirements===

===Architecture===
=='''Use Case'''==

* '''Use Case #1: Security Log in'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills login form, which includes username, password and Captcha code.
*** Submit form to Sahana Server.

* '''Use Case #2: Submit forms to server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to Sahana Server.

* '''Use Case #3: Submit forms to local storage'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User fills forms of shelter/warehouse/disaster etc.
*** Submit form to local database.

* '''Use Case #4: Download new forms from server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Download new forms from server

* '''Use Case #5: Synchronize local data with server '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Synchronize local data with server

* '''Use Case #6: Multi-Language Support '''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** Choose a language from settings page

[[File:TO_BE_ADDED.png‎ |frame|center|Use Case Diagram]]

=Troubleshoots=

CSC/ECE 517 Spring 2015 S1503 LWJZ

2015-04-01T00:54:37Z

Hwang40: /* Sahana Eden Architecture */

<big>E1526. JavaRosa Mobile Client</big>
=Introduction=
==Purpose==
To add several modules to the EdenMobile client app based on the web2py framework to allow mobile users to add new shelters and hospitals, to see the list of hospitals and shelters both offline and online and pass their location to the nearest medical facilities.
==Scope==
We will realize the signup, secure login and logout function, which would add new module into the following files
*communication.js
*controller.js
*model.js
*view.js
We will make it available in multiple languages environment which will implement the languages fold.
We will add some new items including:“ hospital”, “vehicles” which will be added into the folder named “plugins”. The following file will be added into their corrsponding folders: 
Hospitals:
*mHospital.js (model)
*hospital.js, editHospital.js, hospital.html, hospital.css, editHospital.html (views)
*hospitalController.js (controller)
*config.js(Giving details on the configuration of the plugin
Vehicles:
*mVehicles.js (model)
*vehicles.js, editVehicles.js, vehicles.html, vehicles.css, editVehicles.html (views)
*vehiclesController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Also, we find some bugs and eliminate them. These could be any possible file in this project.

==Background==
===What’s 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 the latest evolution of Sahana Software which was initially developed by members of the information technology (IT) community in Sri Lanka to provide solutions for the relief effort following the 2004 Indian Ocean Tsunami. 

===What does Sahana Eden do?===
Sahana Eden provides various of functions which are sorted in several different modules. 

===Organization Registry===
Sahana Eden’s Organization Registry can track what organizations do and organizations also could record their Offices, Warehouse and Field Sites including their locations so they can be mapped as well as links to other modules such as Human Resources, Assets and Inventory. 
====Project Tracking====
By telling you Who’s Doing What, Where, and When, Sahana Eden provides a valuable tool to help organizations responding to disasters know where the greatest needs are and coordinate with others who are engaged in similar work. 
====Human Resources====
Sahana Eden can also be used to provide a contact list to ensure that the right people can be contacted at the right time. 
====Inventory====
Sahana Eden can be used to manage inventories of items and match requests for items with warehouses and other facilities which have them available. Sahana Eden can support multiple Catalogs of Items as well as providing alternative items to ensure more effective use of supplies. 
====Assets====
Sahana Eden is able to manage assets which are needed to respond to disasters, track where they are, who they have been assigned to, and what condition they are in. This ensures that assets are used effectively and efficiently. 
====Assessments====
Sahana Eden can be used to collect and analyze information from assessments to help organizations more effectively plan their disaster management activities. 
====Scenarios & Events====
To help organizations better plan for disasters, Sahana Eden can be used to plan for different scenarios, including recording what human resources, assets, facilities and tasks will be needed to effectively respond. 
====Map ====
Sahana Eden has fully integrated mapping functionality which allows any location-based data to be visualized on a map. Maps provide situational awareness which is essential when either planning to prepare for or respond to a disaster. 
====Shelter Management====
When disasters are widespread and result in population displacement, understanding and tracking the landscape of shelters - and the people in them - is a critical activity. The Shelter Registry provides functionality to list and track information on shelters and on the people arriving and departing. 
====Messaging====
Sahana Eden provides support for messages to be sent to one or Distribution Groups by Email, SMS, Twitter and Google Talk. Interactive messages can also be set up to allow people to send short message queries to Sahana Eden and receive automatic responses. 
===Sahana Eden 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);">Web Server</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);">Application</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);">Web Application Framework</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);">Programming Language</td>
<td style="border: 1px dotted rgb(0, 0, 0);">Python & Java Script</td>
<td style="border: 1px dotted rgb(0, 0, 0);"></td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Database</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, or SQLite</td>
<td style="border: 1px dotted rgb(0, 0, 0);">MySQL, PostgreSQL, and SQLite are supported.Other databases should be usable without major additional work since Web2Py supplies many connectors.</td>
</tr><tr><td style="border: 1px dotted rgb(0, 0, 0);">Operating System</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>

==Documentation==
former developer discussion about Sahana Oden
* An [https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!forum/sahana-eden google discussion], explaining former problems developers met and corresponding solutions
*An [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework basic introduction about the framework of Edenmobile including application design, source ]
Source code
http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework

=Design=
=='''Use Case'''==

* '''Use Case #1: Submit forms to server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** User fills .

* '''Use Case #2: Submit forms to local storage'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** A.
*** B.
*** C.
*** D.

* '''Use Case #3: Download new forms from server'''
** '''Actor:''' Student finish work for first round
** '''Actions:'''
*** A.
*** B.
*** C.
*** D.

* '''Use Case #4: Synchronize local data with server '''
** '''Actor:''' Student not finish work for first round
** '''Actions:'''
*** A.
*** B.
*** C.
*** D.

[[File:TO_BE_ADDED.png‎ |frame|center|Use Case Diagram]]

=Troubleshoots=

CSC/ECE 517 Spring 2015 S1503 LWJZ

2015-04-01T00:51:23Z

Hwang40: /* What’s Sahana Eden? */

<big>E1526. JavaRosa Mobile Client</big>
=Introduction=
==Purpose==
To add several modules to the EdenMobile client app based on the web2py framework to allow mobile users to add new shelters and hospitals, to see the list of hospitals and shelters both offline and online and pass their location to the nearest medical facilities.
==Scope==
We will realize the signup, secure login and logout function, which would add new module into the following files
*communication.js
*controller.js
*model.js
*view.js
We will make it available in multiple languages environment which will implement the languages fold.
We will add some new items including:“ hospital”, “vehicles” which will be added into the folder named “plugins”. The following file will be added into their corrsponding folders: 
Hospitals:
*mHospital.js (model)
*hospital.js, editHospital.js, hospital.html, hospital.css, editHospital.html (views)
*hospitalController.js (controller)
*config.js(Giving details on the configuration of the plugin
Vehicles:
*mVehicles.js (model)
*vehicles.js, editVehicles.js, vehicles.html, vehicles.css, editVehicles.html (views)
*vehiclesController.js (controller)
*config.js(Giving details on the configuration of the plugin)
Also, we find some bugs and eliminate them. These could be any possible file in this project.

==Background==
===What’s 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 the latest evolution of Sahana Software which was initially developed by members of the information technology (IT) community in Sri Lanka to provide solutions for the relief effort following the 2004 Indian Ocean Tsunami. 

===What does Sahana Eden do?===
Sahana Eden provides various of functions which are sorted in several different modules. 

===Organization Registry===
Sahana Eden’s Organization Registry can track what organizations do and organizations also could record their Offices, Warehouse and Field Sites including their locations so they can be mapped as well as links to other modules such as Human Resources, Assets and Inventory. 
====Project Tracking====
By telling you Who’s Doing What, Where, and When, Sahana Eden provides a valuable tool to help organizations responding to disasters know where the greatest needs are and coordinate with others who are engaged in similar work. 
====Human Resources====
Sahana Eden can also be used to provide a contact list to ensure that the right people can be contacted at the right time. 
====Inventory====
Sahana Eden can be used to manage inventories of items and match requests for items with warehouses and other facilities which have them available. Sahana Eden can support multiple Catalogs of Items as well as providing alternative items to ensure more effective use of supplies. 
====Assets====
Sahana Eden is able to manage assets which are needed to respond to disasters, track where they are, who they have been assigned to, and what condition they are in. This ensures that assets are used effectively and efficiently. 
====Assessments====
Sahana Eden can be used to collect and analyze information from assessments to help organizations more effectively plan their disaster management activities. 
====Scenarios & Events====
To help organizations better plan for disasters, Sahana Eden can be used to plan for different scenarios, including recording what human resources, assets, facilities and tasks will be needed to effectively respond. 
====Map ====
Sahana Eden has fully integrated mapping functionality which allows any location-based data to be visualized on a map. Maps provide situational awareness which is essential when either planning to prepare for or respond to a disaster. 
====Shelter Management====
When disasters are widespread and result in population displacement, understanding and tracking the landscape of shelters - and the people in them - is a critical activity. The Shelter Registry provides functionality to list and track information on shelters and on the people arriving and departing. 
====Messaging====
Sahana Eden provides support for messages to be sent to one or Distribution Groups by Email, SMS, Twitter and Google Talk. Interactive messages can also be set up to allow people to send short message queries to Sahana Eden and receive automatic responses. 
===Sahana Eden Architecture===

==Documentation==
former developer discussion about Sahana Oden
* An [https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!forum/sahana-eden google discussion], explaining former problems developers met and corresponding solutions
*An [http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework basic introduction about the framework of Edenmobile including application design, source ]
Source code
http://eden.sahanafoundation.org/wiki/BluePrint/Mobile/EdenMobileFramework

=Design=
=='''Use Case'''==

* '''Use Case #1: Submit forms to server'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** User logs in to Sahana Server.
*** User fills .

* '''Use Case #2: Submit forms to local storage'''
** '''Actor:''' Mobile App User
** '''Actions:'''
*** A.
*** B.
*** C.
*** D.

* '''Use Case #3: Download new forms from server'''
** '''Actor:''' Student finish work for first round
** '''Actions:'''
*** A.
*** B.
*** C.
*** D.

* '''Use Case #4: Synchronize local data with server '''
** '''Actor:''' Student not finish work for first round
** '''Actions:'''
*** A.
*** B.
*** C.
*** D.

[[File:TO_BE_ADDED.png‎ |frame|center|Use Case Diagram]]

=Troubleshoots=

CSC/ECE 517 Spring 2015 S1503 LWJZ

2015-04-01T00:40:39Z

Hwang40: /* Background */

CSC/ECE 517 Spring 2015/oss E1502 wwj

2015-03-22T18:15:21Z

Hwang40: /* What needs to be done: */

E1502: Questionnaire Controller Refactoring 
In this project, we have done some refactoring on the questionnaires_controller. We moved some methods to where we thought suited them, and changed the format of language into ruby style, deleted debugging statement. Details are displayed in the following sections.

=Introduction to Expertiza=
The Expertiza project is system for using peer review to create reusable learning objects. Students do different assignments; then peer review selects the best work in each category, and assembles it to create a single unit.<ref>[http://expertiza.ncsu.edu/ Expertiza]</ref>

=Project Description=
==What it does:==
Used on the admin side of Expertiza for creating/ editing questionnaires (rubrics, surveys and quizzes). It helps in add/removing questions, options, etc for a questionnaire.
<li>Very big controller that handles a lot more than the name suggests. Functionalities need to be moved to appropriate controllers.
<li>Quiz methods are should be treated the same as any other type of questionnaire; differences between quiz questionnaires and other questionnaires should be implemented in the model class, quiz_questionnaire
<li>Turn the questionnaire into a “form object.” The ..._questions methods: save_new_questions, delete_questions, save_questions should be in a separate class.
==Other classes involved:==
<li>questionnaire.rb
<li>quiz_questionnaire.rb
<li>questions_controller.rb

==What needs to be done:==
<li>Move quiz related functions to quiz_questionnaire.rb.
<li>copy, update_quiz, valid_quiz methods, clone_questionnaire_details is too long.
<li>Debug output (print statements) should be removed.
<li>Understand the functions in the controller and comment them. Ensure that the code is understandable to the next programmer who works on it.

=What We Have Done=
==Method Refactoring==
{| class="wikitable"
|-
! style="width:13%;"|Method Name
! style="width:33%;"|Changes Made
! style="width:43%;"|Reason For Change
|- style="vertical-align:top;"
| copy
| Extracted the content of this method as copy_questionnaires method and put it in questionnaire.rb
| The content of this method is about operations on the database (coping a questionnaire), it is better to be put in the model
|-
| valid_quiz
| Moved this method to quiz_questionnaire.rb
| This method is about validation of the quiz, it shouldn't appear in the controller
|-
| export
| Moved this method to questionnaire.rb
| This method exports the questionnaires as csv file, it should't appear in the controller
|-
| import
| Moved this method to questionnaire.rb
| This method imports the questionnaires from csv file, it should't appear in the controller
|-
| clone_questionnaire_details
| Deleted this method due to the duplication
| Substituted by copy_questionnaires method in questionnaire.rb
|-
|}

==Format Refactoring==
===Case 1: Loop Condition===
Change all the looping conditions into one format 
Before
<pre>
# Remove a given questionnaire
def delete
.
.
.
for question in @questionnaire.questions
.
.
.
end
</pre>
After
<pre>
# Remove a given questionnaire
def delete
.
.
.
@questionnaire.assignments.each
.
.
.
end
</pre>

===Case 2: If Condition===
Change all the if conditions into ruby format 
Before
<pre>
.
.
if @successful_create == true
.
.
unless this_q.nil?
.
.
</pre>
After
<pre>
.
.
if @successful_create
.
.
if this_q
.
.
</pre>

===Case 3: Name===
Change all the name from "JAVA name" to "Ruby name" 
Before
<pre>
#save an updated quiz questionnaire to the database
def update_quiz
.
.
.
questionnum=1
.
.
.
end
</pre>
After
<pre>
#save an updated quiz questionnaire to the database
def update_quiz
.
.
.
question_num=1
.
.
.
end
</pre>
==Refactoring Example==
In models/questionnaires.rb, we add copy_questionnaires method, as shown below:
<pre>
def self.copy_questionnaires(id,user)
@orig_questionnaire = Questionnaire.find(id)
questions = Question.where(questionnaire_id: id)
@questionnaire = @orig_questionnaire.clone
@questionnaire.instructor_id = user.instructor_id ## Why was TA-specific code removed here? See Project E713.
@questionnaire.name = 'Copy of ' + @orig_questionnaire.name

if user.role.name != "Teaching Assistant"
@questionnaire.instructor_id = user.id
else # for TA we need to get his instructor id and by default add it to his course for which he is the TA
@questionnaire.instructor_id = Ta.get_my_instructor(user.id)
end
@questionnaire.name = 'Copy of '+@orig_questionnaire.name

@questionnaire.created_at = Time.now
@questionnaire.save!

questions.each{ | question |

new_question = question.clone
new_question.questionnaire_id = @questionnaire.id
new_question.save

advice = QuestionAdvice.find_by_question_id(question.id)
if advice
new_advice = advice.clone
new_advice.question_id = newquestion.id
new_advice.save
end

if (@questionnaire.section == "Custom")
old_question_type = QuestionType.find_by_question_id(question.id)
if old_question_type
new_question_type = old_question_type.clone
new_question_type.question_id = newquestion.id
new_question_type.save
end
end
}
pFolder = TreeFolder.find_by_name(@questionnaire.display_type)
parent = FolderNode.find_by_node_object_id(pFolder.id)
unless QuestionnaireNode.where(parent_id: parent.id, node_object_id: @questionnaire.id)
QuestionnaireNode.create(:parent_id => parent.id, :node_object_id => @questionnaire.id)
end
end
</pre>

=References=
<references/>

CSC/ECE 517 Spring 2015/oss E1502 wwj

2015-03-22T18:14:12Z

Hwang40: /* Refactoring Example */

E1502: Questionnaire Controller Refactoring 
In this project, we have done some refactoring on the questionnaires_controller. We moved some methods to where we thought suited them, and changed the format of language into ruby style, deleted debugging statement. Details are displayed in the following sections.

=Introduction to Expertiza=
The Expertiza project is system for using peer review to create reusable learning objects. Students do different assignments; then peer review selects the best work in each category, and assembles it to create a single unit.<ref>[http://expertiza.ncsu.edu/ Expertiza]</ref>

=Project Description=
==What it does:==
Used on the admin side of Expertiza for creating/ editing questionnaires (rubrics, surveys and quizzes). It helps in add/removing questions, options, etc for a questionnaire.
<li>Very big controller that handles a lot more than the name suggests. Functionalities need to be moved to appropriate controllers.
<li>Quiz methods are should be treated the same as any other type of questionnaire; differences between quiz questionnaires and other questionnaires should be implemented in the model class, quiz_questionnaire
<li>Turn the questionnaire into a “form object.” The ..._questions methods: save_new_questions, delete_questions, save_questions should be in a separate class.
==Other classes involved:==
<li>questionnaire.rb
<li>quiz_questionnaire.rb
<li>questions_controller.rb

==What needs to be done:==
<li>Move quiz related functions to quiz_questionnaire.rb.
<li>copy, update_quiz, valid_quiz methods, clone_questionnaire_details is too long.
<li>Debug output (print statements) should be removed.
<li>Understand the functions in the controller and comment them. Ensure that the code is understandable to the next programmer who works on it.

=What We Have Done=
==Method Refactoring==
{| class="wikitable"
|-
! style="width:13%;"|Method Name
! style="width:33%;"|Changes Made
! style="width:43%;"|Reason For Change
|- style="vertical-align:top;"
| copy
| Extracted the content of this method as copy_questionnaires method and put it in questionnaire.rb
| The content of this method is about operations on the database (coping a questionnaire), it is better to be put in the model
|-
| valid_quiz
| Moved this method to quiz_questionnaire.rb
| This method is about validation of the quiz, it shouldn't appear in the controller
|-
| export
| Moved this method to questionnaire.rb
| This method exports the questionnaires as csv file, it should't appear in the controller
|-
| import
| Moved this method to questionnaire.rb
| This method imports the questionnaires from csv file, it should't appear in the controller
|-
| clone_questionnaire_details
| Deleted this method due to the duplication
| Substituted by copy_questionnaires method in questionnaire.rb
|-
|}

==Format Refactoring==
===Case 1: Loop Condition===
Change all the looping conditions into one format 
Before
<pre>
# Remove a given questionnaire
def delete
.
.
.
for question in @questionnaire.questions
.
.
.
end
</pre>
After
<pre>
# Remove a given questionnaire
def delete
.
.
.
@questionnaire.assignments.each
.
.
.
end
</pre>

===Case 2: If Condition===
Change all the if conditions into ruby format 
Before
<pre>
.
.
if @successful_create == true
.
.
unless this_q.nil?
.
.
</pre>
After
<pre>
.
.
if @successful_create
.
.
if this_q
.
.
</pre>

===Case 3: Name===
Change all the name from "JAVA name" to "Ruby name" 
Before
<pre>
#save an updated quiz questionnaire to the database
def update_quiz
.
.
.
questionnum=1
.
.
.
end
</pre>
After
<pre>
#save an updated quiz questionnaire to the database
def update_quiz
.
.
.
question_num=1
.
.
.
end
</pre>
==Refactoring Example==
In models/questionnaires.rb, we add copy_questionnaires method, as shown below:
<pre>
def self.copy_questionnaires(id,user)
@orig_questionnaire = Questionnaire.find(id)
questions = Question.where(questionnaire_id: id)
@questionnaire = @orig_questionnaire.clone
@questionnaire.instructor_id = user.instructor_id ## Why was TA-specific code removed here? See Project E713.
@questionnaire.name = 'Copy of ' + @orig_questionnaire.name

if user.role.name != "Teaching Assistant"
@questionnaire.instructor_id = user.id
else # for TA we need to get his instructor id and by default add it to his course for which he is the TA
@questionnaire.instructor_id = Ta.get_my_instructor(user.id)
end
@questionnaire.name = 'Copy of '+@orig_questionnaire.name

@questionnaire.created_at = Time.now
@questionnaire.save!

questions.each{ | question |

new_question = question.clone
new_question.questionnaire_id = @questionnaire.id
new_question.save

advice = QuestionAdvice.find_by_question_id(question.id)
if advice
new_advice = advice.clone
new_advice.question_id = newquestion.id
new_advice.save
end

if (@questionnaire.section == "Custom")
old_question_type = QuestionType.find_by_question_id(question.id)
if old_question_type
new_question_type = old_question_type.clone
new_question_type.question_id = newquestion.id
new_question_type.save
end
end
}
pFolder = TreeFolder.find_by_name(@questionnaire.display_type)
parent = FolderNode.find_by_node_object_id(pFolder.id)
unless QuestionnaireNode.where(parent_id: parent.id, node_object_id: @questionnaire.id)
QuestionnaireNode.create(:parent_id => parent.id, :node_object_id => @questionnaire.id)
end
end
</pre>

=References=
<references/>

CSC/ECE 517 Spring 2015/oss E1502 wwj

2015-03-22T18:04:37Z

Hwang40:

E1502: Questionnaire Controller Refactoring 
In this project, we have done some refactoring on the questionnaires_controller. We moved some methods to where we thought suited them, and changed the format of language into ruby style, deleted debugging statement. Details are displayed in the following sections.

=Introduction to Expertiza=
The Expertiza project is system for using peer review to create reusable learning objects. Students do different assignments; then peer review selects the best work in each category, and assembles it to create a single unit.<ref>[http://expertiza.ncsu.edu/ Expertiza]</ref>

=Project Description=
==What it does:==
Used on the admin side of Expertiza for creating/ editing questionnaires (rubrics, surveys and quizzes). It helps in add/removing questions, options, etc for a questionnaire.
<li>Very big controller that handles a lot more than the name suggests. Functionalities need to be moved to appropriate controllers.
<li>Quiz methods are should be treated the same as any other type of questionnaire; differences between quiz questionnaires and other questionnaires should be implemented in the model class, quiz_questionnaire
<li>Turn the questionnaire into a “form object.” The ..._questions methods: save_new_questions, delete_questions, save_questions should be in a separate class.
==Other classes involved:==
<li>questionnaire.rb
<li>quiz_questionnaire.rb
<li>questions_controller.rb

==What needs to be done:==
<li>Move quiz related functions to quiz_questionnaire.rb.
<li>copy, update_quiz, valid_quiz methods, clone_questionnaire_details is too long.
<li>Debug output (print statements) should be removed.
<li>Understand the functions in the controller and comment them. Ensure that the code is understandable to the next programmer who works on it.

=What We Have Done=
==Method Refactoring==
{| class="wikitable"
|-
! style="width:13%;"|Method Name
! style="width:33%;"|Changes Made
! style="width:43%;"|Reason For Change
|- style="vertical-align:top;"
| copy
| Extracted the content of this method as copy_questionnaires method and put it in questionnaire.rb
| The content of this method is about operations on the database (coping a questionnaire), it is better to be put in the model
|-
| valid_quiz
| Moved this method to quiz_questionnaire.rb
| This method is about validation of the quiz, it shouldn't appear in the controller
|-
| export
| Moved this method to questionnaire.rb
| This method exports the questionnaires as csv file, it should't appear in the controller
|-
| import
| Moved this method to questionnaire.rb
| This method imports the questionnaires from csv file, it should't appear in the controller
|-
| clone_questionnaire_details
| Deleted this method due to the duplication
| Substituted by copy_questionnaires method in questionnaire.rb
|-
|}

==Format Refactoring==
===Case 1: Loop Condition===
Change all the looping conditions into one format 
Before
<pre>
# Remove a given questionnaire
def delete
.
.
.
for question in @questionnaire.questions
.
.
.
end
</pre>
After
<pre>
# Remove a given questionnaire
def delete
.
.
.
@questionnaire.assignments.each
.
.
.
end
</pre>

===Case 2: If Condition===
Change all the if conditions into ruby format 
Before
<pre>
.
.
if @successful_create == true
.
.
unless this_q.nil?
.
.
</pre>
After
<pre>
.
.
if @successful_create
.
.
if this_q
.
.
</pre>

===Case 3: Name===
Change all the name from "JAVA name" to "Ruby name" 
Before
<pre>
#save an updated quiz questionnaire to the database
def update_quiz
.
.
.
questionnum=1
.
.
.
end
</pre>
After
<pre>
#save an updated quiz questionnaire to the database
def update_quiz
.
.
.
question_num=1
.
.
.
end
</pre>
==Refactoring Example==
In models/questionnaires.rb, we add copy_questionnaires method, as shown below:
<pre>
def self.copy_questionnaires(id,user)
@orig_questionnaire = Questionnaire.find(id)
questions = Question.where(questionnaire_id: id)
@questionnaire = @orig_questionnaire.clone
@questionnaire.instructor_id = user.instructor_id ## Why was TA-specific code removed here? See Project E713.
@questionnaire.name = 'Copy of ' + @orig_questionnaire.name

if user.role.name != "Teaching Assistant"
@questionnaire.instructor_id = user.id
else # for TA we need to get his instructor id and by default add it to his course for which he is the TA
@questionnaire.instructor_id = Ta.get_my_instructor(user.id)
end
@questionnaire.name = 'Copy of '+@orig_questionnaire.name

@questionnaire.created_at = Time.now
@questionnaire.save!

questions.each{ | question |

new_question = question.clone
new_question.questionnaire_id = @questionnaire.id
new_question.save

advice = QuestionAdvice.find_by_question_id(question.id)
if advice
new_advice = advice.clone
new_advice.question_id = newquestion.id
new_advice.save
end

if (@questionnaire.section == "Custom")
old_question_type = QuestionType.find_by_question_id(question.id)
if old_question_type
new_question_type = old_question_type.clone
new_question_type.question_id = newquestion.id
new_question_type.save
end
end
}
pFolder = TreeFolder.find_by_name(@questionnaire.display_type)
parent = FolderNode.find_by_node_object_id(pFolder.id)
unless QuestionnaireNode.where(parent_id: parent.id, node_object_id: @questionnaire.id)
QuestionnaireNode.create(:parent_id => parent.id, :node_object_id => @questionnaire.id)
end
end
</pre>

=References=
<references/>

CSC/ECE 517 Spring 2015/oss E1502 wwj

2015-03-22T17:50:57Z

Hwang40:

E1502: Questionnaire Controller Refactoring

In this project, we have done some refactoring on the questionnaires_controller. We moved some methods to where we thought suited them, and changed the format of language into ruby style, deleted debugging statement. Details are displayed in the following sections.

=Introduction to Expertiza=
The Expertiza project is system for using peer review to create reusable learning objects. Students do different assignments; then peer review selects the best work in each category, and assembles it to create a single unit.<ref>[http://expertiza.ncsu.edu/ Expertiza]</ref>

=Project Description=
==What it does:==
Used on the admin side of Expertiza for creating/ editing questionnaires (rubrics, surveys and quizzes). It helps in add/removing questions, options, etc for a questionnaire.
<li>Very big controller that handles a lot more than the name suggests. Functionalities need to be moved to appropriate controllers.
<li>Quiz methods are should be treated the same as any other type of questionnaire; differences between quiz questionnaires and other questionnaires should be implemented in the model class, quiz_questionnaire
<li>Turn the questionnaire into a “form object.” The ..._questions methods: save_new_questions, delete_questions, save_questions should be in a separate class.
==Other classes involved:==
<li>questionnaire.rb
<li>quiz_questionnaire.rb
<li>questions_controller.rb

==What needs to be done:==
<li>Move quiz related functions to quiz_questionnaire.rb.
<li>copy, update_quiz, valid_quiz methods, clone_questionnaire_details is too long.
<li>Debug output (print statements) should be removed.
<li>Understand the functions in the controller and comment them. Ensure that the code is understandable to the next programmer who works on it.

=What We Have Done=
==Method Refactoring==
{| class="wikitable"
|-
! style="width:13%;"|Method Name
! style="width:33%;"|Changes Made
! style="width:43%;"|Reason For Change
|- style="vertical-align:top;"
| copy
| Extracted the content of this method as copy_questionnaires method and put it in questionnaire.rb
| The content of this method is about operations on the database (coping a questionnaire), it is better to be put in the model
|-
| valid_quiz
| Moved this method to quiz_questionnaire.rb
| This method is about validation of the quiz, it shouldn't appear in the controller
|-
| export
| Moved this method to questionnaire.rb
| This method exports the questionnaires as csv file, it should't appear in the controller
|-
| import
| Moved this method to questionnaire.rb
| This method imports the questionnaires from csv file, it should't appear in the controller
|-
| clone_questionnaire_details
| Deleted this method due to the duplication
| Substituted by copy_questionnaires method in questionnaire.rb
|-
|}

==Format Refactoring==
===Case 1: Loop Condition===
Change all the looping conditions into one format 
Before
<pre>
# Remove a given questionnaire
def delete
.
.
.
for question in @questionnaire.questions
.
.
.
end
</pre>
After
<pre>
# Remove a given questionnaire
def delete
.
.
.
@questionnaire.assignments.each
.
.
.
end
</pre>

===Case 2: If Condition===
Change all the if conditions into ruby format 
Before
<pre>
.
.
if @successful_create == true
.
.
unless this_q.nil?
.
.
</pre>
After
<pre>
.
.
if @successful_create
.
.
if this_q
.
.
</pre>

===Case 3: Name===
Change all the name from "JAVA name" to "Ruby name" 
Before
<pre>
#save an updated quiz questionnaire to the database
def update_quiz
.
.
.
questionnum=1
.
.
.
end
</pre>
After
<pre>
#save an updated quiz questionnaire to the database
def update_quiz
.
.
.
question_num=1
.
.
.
end
</pre>
==Refactoring Example==
In models/questionnaires.rb, we add copy_questionnaires method, as shown below:
<pre>
def self.copy_questionnaires(id,user)
@orig_questionnaire = Questionnaire.find(id)
questions = Question.where(questionnaire_id: id)
@questionnaire = @orig_questionnaire.clone
@questionnaire.instructor_id = user.instructor_id ## Why was TA-specific code removed here? See Project E713.
@questionnaire.name = 'Copy of ' + @orig_questionnaire.name

if user.role.name != "Teaching Assistant"
@questionnaire.instructor_id = user.id
else # for TA we need to get his instructor id and by default add it to his course for which he is the TA
@questionnaire.instructor_id = Ta.get_my_instructor(user.id)
end
@questionnaire.name = 'Copy of '+@orig_questionnaire.name

@questionnaire.created_at = Time.now
@questionnaire.save!

questions.each{ | question |

new_question = question.clone
new_question.questionnaire_id = @questionnaire.id
new_question.save

advice = QuestionAdvice.find_by_question_id(question.id)
if advice
new_advice = advice.clone
new_advice.question_id = newquestion.id
new_advice.save
end

if (@questionnaire.section == "Custom")
old_question_type = QuestionType.find_by_question_id(question.id)
if old_question_type
new_question_type = old_question_type.clone
new_question_type.question_id = newquestion.id
new_question_type.save
end
end
}
pFolder = TreeFolder.find_by_name(@questionnaire.display_type)
parent = FolderNode.find_by_node_object_id(pFolder.id)
unless QuestionnaireNode.where(parent_id: parent.id, node_object_id: @questionnaire.id)
QuestionnaireNode.create(:parent_id => parent.id, :node_object_id => @questionnaire.id)
end
end
</pre>

=References=
<references/>

CSC/ECE 517 Spring 2015/oss E1502 wwj

2015-03-22T17:49:29Z

Hwang40:

E1502: Questionnaire Controller Refactoring

In this project, we have done some refactoring on the questionnaires_controller. We moved some methods to where we thought suited them, and changed the format of language into ruby style, deleted debugging statement. Details are displayed in the following sections.

==Introduction to Expertiza==
The Expertiza project is system for using peer review to create reusable learning objects. Students do different assignments; then peer review selects the best work in each category, and assembles it to create a single unit.<ref>[http://expertiza.ncsu.edu/ Expertiza]</ref>

==Project Description==
===What it does:===
Used on the admin side of Expertiza for creating/ editing questionnaires (rubrics, surveys and quizzes). It helps in add/removing questions, options, etc for a questionnaire.
<li>Very big controller that handles a lot more than the name suggests. Functionalities need to be moved to appropriate controllers.
<li>Quiz methods are should be treated the same as any other type of questionnaire; differences between quiz questionnaires and other questionnaires should be implemented in the model class, quiz_questionnaire
<li>Turn the questionnaire into a “form object.” The ..._questions methods: save_new_questions, delete_questions, save_questions should be in a separate class.
===Other classes involved:===
<li>questionnaire.rb
<li>quiz_questionnaire.rb
<li>questions_controller.rb

===What needs to be done:===
<li>Move quiz related functions to quiz_questionnaire.rb.
<li>copy, update_quiz, valid_quiz methods, clone_questionnaire_details is too long.
<li>Debug output (print statements) should be removed.
<li>Understand the functions in the controller and comment them. Ensure that the code is understandable to the next programmer who works on it.

==What We Have Done==
===Method Refactoring===
{| class="wikitable"
|-
! style="width:13%;"|Method Name
! style="width:33%;"|Changes Made
! style="width:43%;"|Reason For Change
|- style="vertical-align:top;"
| copy
| Extracted the content of this method as copy_questionnaires method and put it in questionnaire.rb
| The content of this method is about operations on the database (coping a questionnaire), it is better to be put in the model
|-
| valid_quiz
| Moved this method to quiz_questionnaire.rb
| This method is about validation of the quiz, it shouldn't appear in the controller
|-
| export
| Moved this method to questionnaire.rb
| This method exports the questionnaires as csv file, it should't appear in the controller
|-
| import
| Moved this method to questionnaire.rb
| This method imports the questionnaires from csv file, it should't appear in the controller
|-
| clone_questionnaire_details
| Deleted this method due to the duplication
| Substituted by copy_questionnaires method in questionnaire.rb
|-
|}

===Format Refactoring===
====Case 1: Loop Condition====
Change all the looping conditions into one format 
Before
<pre>
# Remove a given questionnaire
def delete
.
.
.
for question in @questionnaire.questions
.
.
.
end
</pre>
After
<pre>
# Remove a given questionnaire
def delete
.
.
.
@questionnaire.assignments.each
.
.
.
end
</pre>

====Case 2: If Condition====
Change all the if conditions into ruby format 
Before
<pre>
.
.
if @successful_create == true
.
.
unless this_q.nil?
.
.
</pre>
After
<pre>
.
.
if @successful_create
.
.
if this_q
.
.
</pre>

====Case 3: Name====
Change all the name from "JAVA name" to "Ruby name" 
Before
<pre>
#save an updated quiz questionnaire to the database
def update_quiz
.
.
.
questionnum=1
.
.
.
end
</pre>
After
<pre>
#save an updated quiz questionnaire to the database
def update_quiz
.
.
.
question_num=1
.
.
.
end
</pre>
===Refactoring Example===
In models/questionnaires.rb, we add copy_questionnaires method, as shown below:
<pre>
def self.copy_questionnaires(id,user)
@orig_questionnaire = Questionnaire.find(id)
questions = Question.where(questionnaire_id: id)
@questionnaire = @orig_questionnaire.clone
@questionnaire.instructor_id = user.instructor_id ## Why was TA-specific code removed here? See Project E713.
@questionnaire.name = 'Copy of ' + @orig_questionnaire.name

if user.role.name != "Teaching Assistant"
@questionnaire.instructor_id = user.id
else # for TA we need to get his instructor id and by default add it to his course for which he is the TA
@questionnaire.instructor_id = Ta.get_my_instructor(user.id)
end
@questionnaire.name = 'Copy of '+@orig_questionnaire.name

@questionnaire.created_at = Time.now
@questionnaire.save!

questions.each{ | question |

new_question = question.clone
new_question.questionnaire_id = @questionnaire.id
new_question.save

advice = QuestionAdvice.find_by_question_id(question.id)
if advice
new_advice = advice.clone
new_advice.question_id = newquestion.id
new_advice.save
end

if (@questionnaire.section == "Custom")
old_question_type = QuestionType.find_by_question_id(question.id)
if old_question_type
new_question_type = old_question_type.clone
new_question_type.question_id = newquestion.id
new_question_type.save
end
end
}
pFolder = TreeFolder.find_by_name(@questionnaire.display_type)
parent = FolderNode.find_by_node_object_id(pFolder.id)
unless QuestionnaireNode.where(parent_id: parent.id, node_object_id: @questionnaire.id)
QuestionnaireNode.create(:parent_id => parent.id, :node_object_id => @questionnaire.id)
end
end
</pre>

==References==
<references/>

CSC/ECE 517 Spring 2015/oss E1502 wwj

2015-03-22T17:48:39Z

Hwang40:

E1502: Questionnaire Controller Refactoring
In this project, we have done some refactoring on the questionnaires_controller. We moved some methods to where we thought suited them, and changed the format of language into ruby style, deleted debugging statement. Details are displayed in the following sections.

==Introduction to Expertiza==
The Expertiza project is system for using peer review to create reusable learning objects. Students do different assignments; then peer review selects the best work in each category, and assembles it to create a single unit.<ref>[http://expertiza.ncsu.edu/ Expertiza]</ref>

==Project Description==
===What it does:===
Used on the admin side of Expertiza for creating/ editing questionnaires (rubrics, surveys and quizzes). It helps in add/removing questions, options, etc for a questionnaire.
<li>Very big controller that handles a lot more than the name suggests. Functionalities need to be moved to appropriate controllers.
<li>Quiz methods are should be treated the same as any other type of questionnaire; differences between quiz questionnaires and other questionnaires should be implemented in the model class, quiz_questionnaire
<li>Turn the questionnaire into a “form object.” The ..._questions methods: save_new_questions, delete_questions, save_questions should be in a separate class.
===Other classes involved:===
<li>questionnaire.rb
<li>quiz_questionnaire.rb
<li>questions_controller.rb

===What needs to be done:===
<li>Move quiz related functions to quiz_questionnaire.rb.
<li>copy, update_quiz, valid_quiz methods, clone_questionnaire_details is too long.
<li>Debug output (print statements) should be removed.
<li>Understand the functions in the controller and comment them. Ensure that the code is understandable to the next programmer who works on it.

==What We Have Done==
===Method Refactoring===
{| class="wikitable"
|-
! style="width:13%;"|Method Name
! style="width:33%;"|Changes Made
! style="width:43%;"|Reason For Change
|- style="vertical-align:top;"
| copy
| Extracted the content of this method as copy_questionnaires method and put it in questionnaire.rb
| The content of this method is about operations on the database (coping a questionnaire), it is better to be put in the model
|-
| valid_quiz
| Moved this method to quiz_questionnaire.rb
| This method is about validation of the quiz, it shouldn't appear in the controller
|-
| export
| Moved this method to questionnaire.rb
| This method exports the questionnaires as csv file, it should't appear in the controller
|-
| import
| Moved this method to questionnaire.rb
| This method imports the questionnaires from csv file, it should't appear in the controller
|-
| clone_questionnaire_details
| Deleted this method due to the duplication
| Substituted by copy_questionnaires method in questionnaire.rb
|-
|}

===Format Refactoring===
====Case 1: Loop Condition====
Change all the looping conditions into one format 
Before
<pre>
# Remove a given questionnaire
def delete
.
.
.
for question in @questionnaire.questions
.
.
.
end
</pre>
After
<pre>
# Remove a given questionnaire
def delete
.
.
.
@questionnaire.assignments.each
.
.
.
end
</pre>

====Case 2: If Condition====
Change all the if conditions into ruby format 
Before
<pre>
.
.
if @successful_create == true
.
.
unless this_q.nil?
.
.
</pre>
After
<pre>
.
.
if @successful_create
.
.
if this_q
.
.
</pre>

====Case 3: Name====
Change all the name from "JAVA name" to "Ruby name" 
Before
<pre>
#save an updated quiz questionnaire to the database
def update_quiz
.
.
.
questionnum=1
.
.
.
end
</pre>
After
<pre>
#save an updated quiz questionnaire to the database
def update_quiz
.
.
.
question_num=1
.
.
.
end
</pre>
===Refactoring Example===
In models/questionnaires.rb, we add copy_questionnaires method, as shown below:
<pre>
def self.copy_questionnaires(id,user)
@orig_questionnaire = Questionnaire.find(id)
questions = Question.where(questionnaire_id: id)
@questionnaire = @orig_questionnaire.clone
@questionnaire.instructor_id = user.instructor_id ## Why was TA-specific code removed here? See Project E713.
@questionnaire.name = 'Copy of ' + @orig_questionnaire.name

if user.role.name != "Teaching Assistant"
@questionnaire.instructor_id = user.id
else # for TA we need to get his instructor id and by default add it to his course for which he is the TA
@questionnaire.instructor_id = Ta.get_my_instructor(user.id)
end
@questionnaire.name = 'Copy of '+@orig_questionnaire.name

@questionnaire.created_at = Time.now
@questionnaire.save!

questions.each{ | question |

new_question = question.clone
new_question.questionnaire_id = @questionnaire.id
new_question.save

advice = QuestionAdvice.find_by_question_id(question.id)
if advice
new_advice = advice.clone
new_advice.question_id = newquestion.id
new_advice.save
end

if (@questionnaire.section == "Custom")
old_question_type = QuestionType.find_by_question_id(question.id)
if old_question_type
new_question_type = old_question_type.clone
new_question_type.question_id = newquestion.id
new_question_type.save
end
end
}
pFolder = TreeFolder.find_by_name(@questionnaire.display_type)
parent = FolderNode.find_by_node_object_id(pFolder.id)
unless QuestionnaireNode.where(parent_id: parent.id, node_object_id: @questionnaire.id)
QuestionnaireNode.create(:parent_id => parent.id, :node_object_id => @questionnaire.id)
end
end
</pre>

==References==
<references/>

CSC/ECE 517 Spring 2015/oss E1502 wwj

2015-03-22T17:46:36Z

Hwang40: Created page with "==E1502: Questionnaire Controller Refactoring== In this project, we have done some refactoring on the questionnaires_controller. We moved some methods to where we thought suited ..."

==E1502: Questionnaire Controller Refactoring==
In this project, we have done some refactoring on the questionnaires_controller. We moved some methods to where we thought suited them, and changed the format of language into ruby style, deleted debugging statement. Details are displayed in the following sections.

==Introduction to Expertiza==
The Expertiza project is system for using peer review to create reusable learning objects. Students do different assignments; then peer review selects the best work in each category, and assembles it to create a single unit.<ref>[http://expertiza.ncsu.edu/ Expertiza]</ref>

==Project Description==
===What it does:===
Used on the admin side of Expertiza for creating/ editing questionnaires (rubrics, surveys and quizzes). It helps in add/removing questions, options, etc for a questionnaire.
<li>Very big controller that handles a lot more than the name suggests. Functionalities need to be moved to appropriate controllers.
<li>Quiz methods are should be treated the same as any other type of questionnaire; differences between quiz questionnaires and other questionnaires should be implemented in the model class, quiz_questionnaire
<li>Turn the questionnaire into a “form object.” The ..._questions methods: save_new_questions, delete_questions, save_questions should be in a separate class.
===Other classes involved:===
<li>questionnaire.rb
<li>quiz_questionnaire.rb
<li>questions_controller.rb

===What needs to be done:===
<li>Move quiz related functions to quiz_questionnaire.rb.
<li>copy, update_quiz, valid_quiz methods, clone_questionnaire_details is too long.
<li>Debug output (print statements) should be removed.
<li>Understand the functions in the controller and comment them. Ensure that the code is understandable to the next programmer who works on it.

==What We Have Done==
===Method Refactoring===
{| class="wikitable"
|-
! style="width:13%;"|Method Name
! style="width:33%;"|Changes Made
! style="width:43%;"|Reason For Change
|- style="vertical-align:top;"
| copy
| Extracted the content of this method as copy_questionnaires method and put it in questionnaire.rb
| The content of this method is about operations on the database (coping a questionnaire), it is better to be put in the model
|-
| valid_quiz
| Moved this method to quiz_questionnaire.rb
| This method is about validation of the quiz, it shouldn't appear in the controller
|-
| export
| Moved this method to questionnaire.rb
| This method exports the questionnaires as csv file, it should't appear in the controller
|-
| import
| Moved this method to questionnaire.rb
| This method imports the questionnaires from csv file, it should't appear in the controller
|-
| clone_questionnaire_details
| Deleted this method due to the duplication
| Substituted by copy_questionnaires method in questionnaire.rb
|-
|}

===Format Refactoring===
====Case 1: Loop Condition====
Change all the looping conditions into one format 
Before
<pre>
# Remove a given questionnaire
def delete
.
.
.
for question in @questionnaire.questions
.
.
.
end
</pre>
After
<pre>
# Remove a given questionnaire
def delete
.
.
.
@questionnaire.assignments.each
.
.
.
end
</pre>

====Case 2: If Condition====
Change all the if conditions into ruby format 
Before
<pre>
.
.
if @successful_create == true
.
.
unless this_q.nil?
.
.
</pre>
After
<pre>
.
.
if @successful_create
.
.
if this_q
.
.
</pre>

====Case 3: Name====
Change all the name from "JAVA name" to "Ruby name" 
Before
<pre>
#save an updated quiz questionnaire to the database
def update_quiz
.
.
.
questionnum=1
.
.
.
end
</pre>
After
<pre>
#save an updated quiz questionnaire to the database
def update_quiz
.
.
.
question_num=1
.
.
.
end
</pre>
===Refactoring Example===
In models/questionnaires.rb, we add copy_questionnaires method, as shown below:
<pre>
def self.copy_questionnaires(id,user)
@orig_questionnaire = Questionnaire.find(id)
questions = Question.where(questionnaire_id: id)
@questionnaire = @orig_questionnaire.clone
@questionnaire.instructor_id = user.instructor_id ## Why was TA-specific code removed here? See Project E713.
@questionnaire.name = 'Copy of ' + @orig_questionnaire.name

if user.role.name != "Teaching Assistant"
@questionnaire.instructor_id = user.id
else # for TA we need to get his instructor id and by default add it to his course for which he is the TA
@questionnaire.instructor_id = Ta.get_my_instructor(user.id)
end
@questionnaire.name = 'Copy of '+@orig_questionnaire.name

@questionnaire.created_at = Time.now
@questionnaire.save!

questions.each{ | question |

new_question = question.clone
new_question.questionnaire_id = @questionnaire.id
new_question.save

advice = QuestionAdvice.find_by_question_id(question.id)
if advice
new_advice = advice.clone
new_advice.question_id = newquestion.id
new_advice.save
end

if (@questionnaire.section == "Custom")
old_question_type = QuestionType.find_by_question_id(question.id)
if old_question_type
new_question_type = old_question_type.clone
new_question_type.question_id = newquestion.id
new_question_type.save
end
end
}
pFolder = TreeFolder.find_by_name(@questionnaire.display_type)
parent = FolderNode.find_by_node_object_id(pFolder.id)
unless QuestionnaireNode.where(parent_id: parent.id, node_object_id: @questionnaire.id)
QuestionnaireNode.create(:parent_id => parent.id, :node_object_id => @questionnaire.id)
end
end
</pre>

==References==
<references/>

CSC/ECE 517 Spring 2015

2015-03-22T17:43:45Z

Hwang40: /* Writing Assignment 2 */

==Writing Assignment 1==
*[[CSC/ECE 517 Spring 2015/ch1a 17 WL]]
*[[CSC/ECE 517 Spring 2015/ch1a 5 ZX]]
*[[CSC/ECE 517 Spring 2015/ch1a 6 TZ]]
*[[CSC/ECE 517 Spring 2015/ch1a 4 RW]]
*[[CSC/ECE 517 Spring 2015/ch1a 7 SA]]
*[[CSC/ECE 517 Spring 2015/ch1a 9 RA]]
*[[CSC/ECE 517 Spring 2015/ch1a 14 RI]]
*[[CSC/ECE 517 Spring 2015/ch1a 1 DZ]]
*[[CSC/ECE 517 Spring 2015/ch1a 20 HA]]
*[[CSC/ECE 517 Spring 2015/ch1a 3 RF]]
*[[CSC/ECE 517 Spring 2015/ch1a 12 LS]]
*[[CSC/ECE 517 Spring 2015/ch1a 13 MA]]
*[[CSC/ECE 517 Spring 2015/ch1a 2 WA]]
*[[CSC/ECE 517 Spring 2015/ch1b 21 QW]]
*[[CSC/ECE 517 Spring 2015/ch1b 23 MS]]
*[[CSC/ECE 517 Spring 2015/ch1b 10 GL]]
*[[CSC/ECE 517 Spring 2015/ch1b 27 VC]]
*[[CSC/ECE 517 Spring 2015/ch1b 22 SF]]
*[[CSC/ECE 517 Spring 2015/ch1b 15 SH]]
*[[CSC/ECE 517 Spring 2015/ch1b 18 AS]]

==Writing Assignment 2==
*[[CSC/ECE 517 Spring 2015/oss E1502 wwj]]
*[[CSC/ECE 517 Fall 2014/oss E1508 MRS]]
*[[CSC/ECE 517 Spring 2015/oss E1504 IMV]]
*[[CSC/ECE 517 Spring 2015/oss E1505 xzl]]
*[[CSC/ECE 517 Spring 2015/oss E1509 lds]]
*[[CSC/ECE 517 Spring 2015/oss E1510 FLP]]
*[[CSC/ECE 517 Spring 2015/oss E1506 SYZ]]
*[[CSC/ECE 517 Spring 2015/oss S1504 AAC]]
*[[CSC/ECE 517 Spring 2015/oss E1507 DGO]]
*[[CSC/ECE 517 Spring 2015/oss M1502 GVJ]]
*[[CSC/ECE 517 Spring 2015/oss M1503 EDT]]

CSC/ECE 517 Spring 2015/ch1a 12 LS

2015-02-16T04:08:01Z

Hwang40: /* Template streaming */

Live Streaming

='''Introduction'''=
The purpose of live streaming is to send data over the Internet in real-time. This requires a data source, a data encoder, a media publisher and a proper network.

In Rails, the concept of streaming first appeared in [http://weblog.rubyonrails.org/releases/ version 3.1], and is further optimized in Rails 4. Now Rails 4 supports live streaming, which uses handling I/O object and can send data from server to client in real-time.

__TOC__

='''Examples'''=
==Template Streaming==
Some basic knowledge about how web pages are rendered can be found [http://friendlybit.com/css/rendering-a-web-page-step-by-step/ here] and also [http://www.pathinteractive.com/blog/2014/07/rendering-a-webpage-with-google-webmaster-tools/ here]. 
Since Rail 3.1, [http://api.rubyonrails.org/classes/ActionController/Streaming.html ''::Streaming''] module has been added to ActionController. For example, the loading progress in a traditional Rails client-side may look like this<ref>Template Streaming, George Ogata https://github.com/oggy/template_streaming</ref>:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:slow-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 1 progress without streaming</div>
This is because that layouts are rendered before the content, thus causing control flow to be altered to render the page in the order that the client needs (layout first).But for some resources which are static, if they could be loaded while waiting for the server response, a lot of time can be saved.
 
 
The module ''::Streaming'' inverts the regular Rails process of rendering the layout and template. Using ''::Streaming'', Rails will render template first and then layout. It will first run method ''yield'' and load up the template, and then renders the assets and layouts. In this way, the progress with streaming looks like this:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:fast-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 2 progress with streaming</div>

===When to use streaming===
For actions like ''new'' or ''edit'', it may not be that necessary to use streaming. But for expensive actions like database query and generation of large amount of data, streaming can be extremely important and effective. Take the following action as an example:
<pre>
def storyboard
@stories = Story.all
@developers = Page.all
@comments = Comment.all
end
</pre>

Since most of the queries here are executing in the controller, it might take a while before them to finish, thus causing the front end (user) to wait for long. We can solve this problem and enhance user experience, the above code can be rewrite as follows,
<pre>
def storyboard
# Allow lazy execution of the queries
@stories = Story.all
@developers = Page.all
@comments = Comment.all
render :stream => true
end
</pre>
(Note: '':Streaming'' only works with templates. It doesn’t work with :json or :xml)<ref>ActionController::Streaming http://apidock.com/rails/ActionController/Streaming</ref>
 
 

===Tweaking views===
When using streaming, instance variables that are set in the template and are used in the layout won't need some tweak to work well. This is done by using content_for, provide and yield.
Here’s a simple example where the layout expects the template to tell which title to use<ref>ActionController::Streaming http://apidock.com/rails/ActionController/Streaming</ref>:
<pre>
<html>
<head><title><%= yield :title %></title></head>
<body><%= yield %></body>
</html>
</pre>

Instead of yield, we can also use content_for to specify the title:
<pre>
<%= content_for :title, "Main" %>
Hello
</pre>

And the final result would be:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>

However, if content_for is called several times, the final result would have all calls concatenated.
For instance, if we have the following template:
<pre>
<%= content_for :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>

The final result would be:
<pre>
<html>
<head><title>Main page</title></head>
<body>Hello</body>
</html>
</pre>
This means that, if you have yield '':title'' in your layout and you want to use streaming, you would have to render the whole template (and eventually trigger all queries) before streaming the title and all assets, which kills the purpose of streaming. For this reason Rails 3.1 introduces a new helper called provide that does the same as content_for but tells the layout to stop searching for other entries and continue rendering.

For instance, the template above using provide would be:
<pre>
<%= provide :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>
Giving:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>
That said, when streaming, you need to properly check your templates and choose when to use provide and content_for.
 
 

==Live Streaming==
The module [http://api.rubyonrails.org/classes/ActionController/Live.html ''::Live''] was then added to ActionController at Rail 4. The difference between Streaming and Live is that Streaming is implicitly included whenever you create a new controller class, while ''::Live'' requires explicit include.

===Traditional Response===
In this type of communication between server and client, data will be buffered until all render works are finished, and everything will be sent to the client at the same time. And the stream object behaves just like an IO object. Here’s the sample code:
<pre>
class MessageController < ApplicationController
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a response message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>

When we run the code above, the web page will '''keep loading and remain blank''' for 8 seconds, and shows all 8 lines of “This is a response message!” altogether, as with the following image shows: 
[[File:nostreaming.gif]]

===Live Aproach===
In order to enable live streaming, we need to include a module named ''ActionController::Live''. When this module is mixed into the controller, all actions within that controller will be able to stream data to the client in real time, like the following code:
<pre>
class MessageController < ApplicationController
#here we enabled live streaming
include ActionController::Live
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a live streaming message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>
The above code looks exactly the same as the traditional response, except the newly included module ''ActionController::Live''. Now '''data can be streamed to the client immediately whenever write method is called'''. When we run the code above, the web page will print one line “This is a response message!” for every seconds and repeats 8 times.<ref>Is it live? http://tenderlovemaking.com/2012/07/30/is-it-live.html</ref> Like the image shows below: 
[[File:streaming.gif]]
 
 

==Server-Sent Event==
[https://en.wikipedia.org/wiki/Server-sent_events Server-sent event (SSE)] is a technology where browser can automatically receive update data from a server via [https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol HTTP] connection. Whenever server sends data, the SSE method in the browser will trigger an event.The SSE EventSource API is standardized as part of [https://en.wikipedia.org/wiki/HTML5 HTML5] by the [https://en.wikipedia.org/wiki/World_Wide_Web_Consortium W3C]. It can be used together with the Live API to achieve full-duplex communication.<ref>Server-sent events https://en.wikipedia.org/wiki/Server-sent_events</ref>
 
A simple SSE looks like the following :
<pre>
require 'json'
module ServerSide
class SSE
def initialize io
@io = io
end

def write object, options = {}
options.each do |k,v|
@io.write "#{k}: #{v}n"
end
@io.write "data: #{object}nn"
end

def close
@io.close
end
end
end
</pre>
This module assigns the I/O stream object to a hash and converts it into a key-value pair so that it is easy to read, store, and send it back in [https://en.wikipedia.org/wiki/JSON JSON] format.
 
 
Now we can wrap stream object inside the SSE class. By doing this, we need to include SSE module inside the controller, so that the opening and closing of connections will be managed by SSE module. And we also add the ensure clause to make sure that the connection will always be closed after execution.
<pre>
require 'sse'
class MessagingController < ApplicationController
include ActionController::Live

def stream
response.headers['Content-Type'] = 'text/event-stream'
sse = SSE.new(response.stream)
begin
5.times {
sse.write(“Streaming using SSE!”)
sleep 1
}
ensure
sse.close
end
end
end
</pre>
The code above will print the sentence “Streaming using SSE!” once per second, until the loop ends.
 
 
Here’s another sample showing how to use SSE to stream data<ref>https://github.com/rails/rails/blob/6061c540ac7880233a6e32de85cec72c20ed8778/actionpack/lib/action_controller/metal/live.rb</ref>:

# This class provides the ability to write an SSE (Server Sent Event)
# to an IO stream. The class is initialized with a stream and can be used
# to either write a JSON string or an object which can be converted to JSON.
#
# Writing an object will convert it into standard SSE format with whatever
# options you have configured. You may choose to set the following options:
#
# 1) Event. If specified, an event with this name will be dispatched on
# the browser.
# 2) Retry. The reconnection time in milliseconds used when attempting
# to send the event.
# 3) Id. If the connection dies while sending an SSE to the browser, then
# the server will receive a +Last-Event-ID+ header with value equal to +id+.
#
# After setting an option in the constructor of the SSE object, all future
# SSEs sent across the stream will use those options unless overridden.
#
# Example Usage:
#
# class MyController < ActionController::Base
# include ActionController::Live
#
# def index
# response.headers['Content-Type'] = 'text/event-stream'
# sse = SSE.new(response.stream, retry: 300, event: "event-name")
# sse.write({ name: 'John'})
# sse.write({ name: 'John'}, id: 10)
# sse.write({ name: 'John'}, id: 10, event: "other-event")
# sse.write({ name: 'John'}, id: 10, event: "other-event", retry: 500)
# ensure
# sse.close
# end
# end
#
# Note: SSEs are not currently supported by IE. However, they are supported
# by Chrome, Firefox, Opera, and Safari.

Note: By default Rails provides a one-way communication process by writing the stream to the client when data is available. However, if we can add SSEs, we can enable events and responses, thus making it two-way.
 
 

='''Conclusion'''=
The supporting for live streaming has deep impact on Rails. It not only makes Rails more competitive with Node.js, but also opens a gate for Rails to embrace lots of new areas and applications that it does not fits well before. The main advantage of Rails can be summarized as follows: 

1.Send partial responses to the client immediately.
 
2.Using Server-sent events, the ability to create chat clients, push notifications, and real-time feeds are available within Rails itself.
 
3.Continuously inform the user about the progress.
See example below<ref>Why Rails 4 Live Streaming is a big deal, Hongli Lai http://blog.phusion.nl/2012/08/03/why-rails-4-live-streaming-is-a-big-deal/</ref>:
<pre>
def big_work
work = WorkModel.new
while !work.done?
work.do_some_calculations
response.stream.write "Progress: #{work.progress}%\n"
end
response.stream.close
end
</pre>
 

='''Troubleshooting'''=
When running streaming programs, we need to install [http://puma.io/ PUMA] to substitute the original [https://en.wikipedia.org/wiki/WEBrick WEBrick] server, because puma can handle concurrency better. In order to do this, we need to add the following line to Gemfile:
<pre>
gem 'puma'
</pre>
 
After installed puma, if we start rails server, the console will print the following output:
<pre>
"C:\Program Files (x86)\JetBrains\RubyMine 7.0.2\bin\runnerw.exe" C:\RailsInstaller\Ruby2.0.0\bin\ruby.exe -e $stdout.sync=true;$stderr.sync=true;load($0=ARGV.shift) D:/Cloud/Coding/RubymineProjects/LiveStreamingExample/bin/rails server -b 127.0.0.1 -p 3000 -e development
=> Booting Puma
=> Rails 4.1.8 application starting in development on http://127.0.0.1:3000
=> Run `rails server -h` for more startup options
=> Ctrl-C to shutdown server
Puma 2.11.0 starting...
* Min threads: 0, max threads: 16
* Environment: development
* Listening on tcp://127.0.0.1:3000
</pre>
This means that PUMA is set as our default server and successfully booted.
 
 
We encountered failure on Windows when trying to install PUMA, the console printed the following error:
<pre>
Building native extensions. This could take a while...
ERROR: Error installing rails:
ERROR: Failed to build gem native extension.

/Users/WillieTran/.rvm/rubies/ruby-2.0.0-p247/bin/ruby extconf.rb
*** extconf.rb failed ***

Could not create Makefile due to some reason, probably lack of necessary
libraries and/or headers. Check the mkmf.log file for more details. You may
need configuration options.
</pre>
 
To solve this problem, we need to install [https://www.openssl.org/ openssl] for windows. And then run the following command<ref>Installing puma on windows, Robert Kranz https://github.com/hicknhack-software/rails-disco/wiki/Installing-puma-on-windows</ref>:
<pre>
gem install puma -- --with-opt-dir=c:\openssl
</pre>
 

='''References'''=
<references>

CSC/ECE 517 Spring 2015/ch1a 12 LS

2015-02-16T04:07:34Z

Hwang40: /* Live Streaming */

Live Streaming

='''Introduction'''=
The purpose of live streaming is to send data over the Internet in real-time. This requires a data source, a data encoder, a media publisher and a proper network.

In Rails, the concept of streaming first appeared in [http://weblog.rubyonrails.org/releases/ version 3.1], and is further optimized in Rails 4. Now Rails 4 supports live streaming, which uses handling I/O object and can send data from server to client in real-time.

__TOC__

='''Examples'''=
==Template streaming==
Some basic knowledge about how web pages are rendered can be found [http://friendlybit.com/css/rendering-a-web-page-step-by-step/ here] and also [http://www.pathinteractive.com/blog/2014/07/rendering-a-webpage-with-google-webmaster-tools/ here]. 
Since Rail 3.1, [http://api.rubyonrails.org/classes/ActionController/Streaming.html ''::Streaming''] module has been added to ActionController. For example, the loading progress in a traditional Rails client-side may look like this<ref>Template Streaming, George Ogata https://github.com/oggy/template_streaming</ref>:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:slow-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 1 progress without streaming</div>
This is because that layouts are rendered before the content, thus causing control flow to be altered to render the page in the order that the client needs (layout first).But for some resources which are static, if they could be loaded while waiting for the server response, a lot of time can be saved.
 
 
The module ''::Streaming'' inverts the regular Rails process of rendering the layout and template. Using ''::Streaming'', Rails will render template first and then layout. It will first run method ''yield'' and load up the template, and then renders the assets and layouts. In this way, the progress with streaming looks like this:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:fast-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 2 progress with streaming</div>

===When to use streaming===
For actions like ''new'' or ''edit'', it may not be that necessary to use streaming. But for expensive actions like database query and generation of large amount of data, streaming can be extremely important and effective. Take the following action as an example:
<pre>
def storyboard
@stories = Story.all
@developers = Page.all
@comments = Comment.all
end
</pre>

Since most of the queries here are executing in the controller, it might take a while before them to finish, thus causing the front end (user) to wait for long. We can solve this problem and enhance user experience, the above code can be rewrite as follows,
<pre>
def storyboard
# Allow lazy execution of the queries
@stories = Story.all
@developers = Page.all
@comments = Comment.all
render :stream => true
end
</pre>
(Note: '':Streaming'' only works with templates. It doesn’t work with :json or :xml)<ref>ActionController::Streaming http://apidock.com/rails/ActionController/Streaming</ref>
 
 

===Tweaking views===
When using streaming, instance variables that are set in the template and are used in the layout won't need some tweak to work well. This is done by using content_for, provide and yield.
Here’s a simple example where the layout expects the template to tell which title to use<ref>ActionController::Streaming http://apidock.com/rails/ActionController/Streaming</ref>:
<pre>
<html>
<head><title><%= yield :title %></title></head>
<body><%= yield %></body>
</html>
</pre>

Instead of yield, we can also use content_for to specify the title:
<pre>
<%= content_for :title, "Main" %>
Hello
</pre>

And the final result would be:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>

However, if content_for is called several times, the final result would have all calls concatenated.
For instance, if we have the following template:
<pre>
<%= content_for :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>

The final result would be:
<pre>
<html>
<head><title>Main page</title></head>
<body>Hello</body>
</html>
</pre>
This means that, if you have yield '':title'' in your layout and you want to use streaming, you would have to render the whole template (and eventually trigger all queries) before streaming the title and all assets, which kills the purpose of streaming. For this reason Rails 3.1 introduces a new helper called provide that does the same as content_for but tells the layout to stop searching for other entries and continue rendering.

For instance, the template above using provide would be:
<pre>
<%= provide :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>
Giving:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>
That said, when streaming, you need to properly check your templates and choose when to use provide and content_for.
 
 

==Live Streaming==
The module [http://api.rubyonrails.org/classes/ActionController/Live.html ''::Live''] was then added to ActionController at Rail 4. The difference between Streaming and Live is that Streaming is implicitly included whenever you create a new controller class, while ''::Live'' requires explicit include.

===Traditional Response===
In this type of communication between server and client, data will be buffered until all render works are finished, and everything will be sent to the client at the same time. And the stream object behaves just like an IO object. Here’s the sample code:
<pre>
class MessageController < ApplicationController
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a response message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>

When we run the code above, the web page will '''keep loading and remain blank''' for 8 seconds, and shows all 8 lines of “This is a response message!” altogether, as with the following image shows: 
[[File:nostreaming.gif]]

===Live Aproach===
In order to enable live streaming, we need to include a module named ''ActionController::Live''. When this module is mixed into the controller, all actions within that controller will be able to stream data to the client in real time, like the following code:
<pre>
class MessageController < ApplicationController
#here we enabled live streaming
include ActionController::Live
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a live streaming message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>
The above code looks exactly the same as the traditional response, except the newly included module ''ActionController::Live''. Now '''data can be streamed to the client immediately whenever write method is called'''. When we run the code above, the web page will print one line “This is a response message!” for every seconds and repeats 8 times.<ref>Is it live? http://tenderlovemaking.com/2012/07/30/is-it-live.html</ref> Like the image shows below: 
[[File:streaming.gif]]
 
 

==Server-Sent Event==
[https://en.wikipedia.org/wiki/Server-sent_events Server-sent event (SSE)] is a technology where browser can automatically receive update data from a server via [https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol HTTP] connection. Whenever server sends data, the SSE method in the browser will trigger an event.The SSE EventSource API is standardized as part of [https://en.wikipedia.org/wiki/HTML5 HTML5] by the [https://en.wikipedia.org/wiki/World_Wide_Web_Consortium W3C]. It can be used together with the Live API to achieve full-duplex communication.<ref>Server-sent events https://en.wikipedia.org/wiki/Server-sent_events</ref>
 
A simple SSE looks like the following :
<pre>
require 'json'
module ServerSide
class SSE
def initialize io
@io = io
end

def write object, options = {}
options.each do |k,v|
@io.write "#{k}: #{v}n"
end
@io.write "data: #{object}nn"
end

def close
@io.close
end
end
end
</pre>
This module assigns the I/O stream object to a hash and converts it into a key-value pair so that it is easy to read, store, and send it back in [https://en.wikipedia.org/wiki/JSON JSON] format.
 
 
Now we can wrap stream object inside the SSE class. By doing this, we need to include SSE module inside the controller, so that the opening and closing of connections will be managed by SSE module. And we also add the ensure clause to make sure that the connection will always be closed after execution.
<pre>
require 'sse'
class MessagingController < ApplicationController
include ActionController::Live

def stream
response.headers['Content-Type'] = 'text/event-stream'
sse = SSE.new(response.stream)
begin
5.times {
sse.write(“Streaming using SSE!”)
sleep 1
}
ensure
sse.close
end
end
end
</pre>
The code above will print the sentence “Streaming using SSE!” once per second, until the loop ends.
 
 
Here’s another sample showing how to use SSE to stream data<ref>https://github.com/rails/rails/blob/6061c540ac7880233a6e32de85cec72c20ed8778/actionpack/lib/action_controller/metal/live.rb</ref>:

# This class provides the ability to write an SSE (Server Sent Event)
# to an IO stream. The class is initialized with a stream and can be used
# to either write a JSON string or an object which can be converted to JSON.
#
# Writing an object will convert it into standard SSE format with whatever
# options you have configured. You may choose to set the following options:
#
# 1) Event. If specified, an event with this name will be dispatched on
# the browser.
# 2) Retry. The reconnection time in milliseconds used when attempting
# to send the event.
# 3) Id. If the connection dies while sending an SSE to the browser, then
# the server will receive a +Last-Event-ID+ header with value equal to +id+.
#
# After setting an option in the constructor of the SSE object, all future
# SSEs sent across the stream will use those options unless overridden.
#
# Example Usage:
#
# class MyController < ActionController::Base
# include ActionController::Live
#
# def index
# response.headers['Content-Type'] = 'text/event-stream'
# sse = SSE.new(response.stream, retry: 300, event: "event-name")
# sse.write({ name: 'John'})
# sse.write({ name: 'John'}, id: 10)
# sse.write({ name: 'John'}, id: 10, event: "other-event")
# sse.write({ name: 'John'}, id: 10, event: "other-event", retry: 500)
# ensure
# sse.close
# end
# end
#
# Note: SSEs are not currently supported by IE. However, they are supported
# by Chrome, Firefox, Opera, and Safari.

Note: By default Rails provides a one-way communication process by writing the stream to the client when data is available. However, if we can add SSEs, we can enable events and responses, thus making it two-way.
 
 

='''Conclusion'''=
The supporting for live streaming has deep impact on Rails. It not only makes Rails more competitive with Node.js, but also opens a gate for Rails to embrace lots of new areas and applications that it does not fits well before. The main advantage of Rails can be summarized as follows: 

1.Send partial responses to the client immediately.
 
2.Using Server-sent events, the ability to create chat clients, push notifications, and real-time feeds are available within Rails itself.
 
3.Continuously inform the user about the progress.
See example below<ref>Why Rails 4 Live Streaming is a big deal, Hongli Lai http://blog.phusion.nl/2012/08/03/why-rails-4-live-streaming-is-a-big-deal/</ref>:
<pre>
def big_work
work = WorkModel.new
while !work.done?
work.do_some_calculations
response.stream.write "Progress: #{work.progress}%\n"
end
response.stream.close
end
</pre>
 

='''Troubleshooting'''=
When running streaming programs, we need to install [http://puma.io/ PUMA] to substitute the original [https://en.wikipedia.org/wiki/WEBrick WEBrick] server, because puma can handle concurrency better. In order to do this, we need to add the following line to Gemfile:
<pre>
gem 'puma'
</pre>
 
After installed puma, if we start rails server, the console will print the following output:
<pre>
"C:\Program Files (x86)\JetBrains\RubyMine 7.0.2\bin\runnerw.exe" C:\RailsInstaller\Ruby2.0.0\bin\ruby.exe -e $stdout.sync=true;$stderr.sync=true;load($0=ARGV.shift) D:/Cloud/Coding/RubymineProjects/LiveStreamingExample/bin/rails server -b 127.0.0.1 -p 3000 -e development
=> Booting Puma
=> Rails 4.1.8 application starting in development on http://127.0.0.1:3000
=> Run `rails server -h` for more startup options
=> Ctrl-C to shutdown server
Puma 2.11.0 starting...
* Min threads: 0, max threads: 16
* Environment: development
* Listening on tcp://127.0.0.1:3000
</pre>
This means that PUMA is set as our default server and successfully booted.
 
 
We encountered failure on Windows when trying to install PUMA, the console printed the following error:
<pre>
Building native extensions. This could take a while...
ERROR: Error installing rails:
ERROR: Failed to build gem native extension.

/Users/WillieTran/.rvm/rubies/ruby-2.0.0-p247/bin/ruby extconf.rb
*** extconf.rb failed ***

Could not create Makefile due to some reason, probably lack of necessary
libraries and/or headers. Check the mkmf.log file for more details. You may
need configuration options.
</pre>
 
To solve this problem, we need to install [https://www.openssl.org/ openssl] for windows. And then run the following command<ref>Installing puma on windows, Robert Kranz https://github.com/hicknhack-software/rails-disco/wiki/Installing-puma-on-windows</ref>:
<pre>
gem install puma -- --with-opt-dir=c:\openssl
</pre>
 

='''References'''=
<references>

CSC/ECE 517 Spring 2015/ch1a 12 LS

2015-02-16T03:38:06Z

Hwang40:

Live Streaming

='''Introduction'''=
The purpose of live streaming is to send data over the Internet in real-time. This requires a data source, a data encoder, a media publisher and a proper network.

In Rails, the concept of streaming first appeared in [http://weblog.rubyonrails.org/releases/ version 3.1], and is further optimized in Rails 4. Now Rails 4 supports live streaming, which uses handling I/O object and can send data from server to client in real-time.

__TOC__

='''Examples'''=
==Template streaming==
Some basic knowledge about how web pages are rendered can be found [http://friendlybit.com/css/rendering-a-web-page-step-by-step/ here] and [http://www.pathinteractive.com/blog/2014/07/rendering-a-webpage-with-google-webmaster-tools/ here]. 
Since Rail 3.1, [http://api.rubyonrails.org/classes/ActionController/Streaming.html ''::Streaming''] module has been added to ActionController. For example, the loading progress in a traditional Rails client-side may look like this<ref>Template Streaming, George Ogata https://github.com/oggy/template_streaming</ref>:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:slow-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 1 progress without streaming</div>
This is because that layouts are rendered before the content, thus causing control flow to be altered to render the page in the order that the client needs (layout first).But for some resources which are static, if they could be loaded while waiting for the server response, a lot of time can be saved.
 
 
The module ''::Streaming'' inverts the regular Rails process of rendering the layout and template. Using ''::Streaming'', Rails will render template first and then layout. It will first run method ''yield'' and load up the template, and then renders the assets and layouts. In this way, the progress with streaming looks like this:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:fast-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 2 progress with streaming</div>

===When to use streaming===
For actions like ''new'' or ''edit'', it may not be that necessary to use streaming. But for expensive actions like database query and generation of large amount of data, streaming can be extremely important and effective. Take the following action as an example:
<pre>
def storyboard
@stories = Story.all
@developers = Page.all
@comments = Comment.all
end
</pre>

Since most of the queries here are executing in the controller, it might take a while before them to finish, thus causing the front end (user) to wait for long. We can solve this problem and enhance user experience, the above code can be rewrite as follows,
<pre>
def storyboard
# Allow lazy execution of the queries
@stories = Story.all
@developers = Page.all
@comments = Comment.all
render :stream => true
end
</pre>
(Note: '':Streaming'' only works with templates. It doesn’t work with :json or :xml)<ref>ActionController::Streaming http://apidock.com/rails/ActionController/Streaming</ref>
 
 

===Tweaking views===
When using streaming, instance variables that are set in the template and are used in the layout won't need some tweak to work well. This is done by using content_for, provide and yield.
Here’s a simple example where the layout expects the template to tell which title to use<ref>ActionController::Streaming http://apidock.com/rails/ActionController/Streaming</ref>:
<pre>
<html>
<head><title><%= yield :title %></title></head>
<body><%= yield %></body>
</html>
</pre>

Instead of yield, we can also use content_for to specify the title:
<pre>
<%= content_for :title, "Main" %>
Hello
</pre>

And the final result would be:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>

However, if content_for is called several times, the final result would have all calls concatenated.
For instance, if we have the following template:
<pre>
<%= content_for :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>

The final result would be:
<pre>
<html>
<head><title>Main page</title></head>
<body>Hello</body>
</html>
</pre>
This means that, if you have yield '':title'' in your layout and you want to use streaming, you would have to render the whole template (and eventually trigger all queries) before streaming the title and all assets, which kills the purpose of streaming. For this reason Rails 3.1 introduces a new helper called provide that does the same as content_for but tells the layout to stop searching for other entries and continue rendering.

For instance, the template above using provide would be:
<pre>
<%= provide :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>
Giving:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>
That said, when streaming, you need to properly check your templates and choose when to use provide and content_for.
 
 

==Live Streaming==
The module [http://api.rubyonrails.org/classes/ActionController/Live.html ''::Live''] was then added to ActionController at Rail 4. The difference between Streaming and Live is that Streaming is implicitly included whenever you create a new controller class, while ''::Live'' requires explicit include.

===Traditional Response===
In this type of communication between server and client, data will be buffered until all render works are finished, and everything will be sent to the client at the same time. And the stream object behaves just like an IO object. Here’s the sample code:
<pre>
class MessageController < ApplicationController
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a response message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>

When we run the code above, the web page will '''keep loading and remain blank''' for 8 seconds, and shows all 8 lines of “This is a response message!” altogether, as with the following image shows: 
[[File:nostreaming.gif]]

===Live Streaming===
In order to enable live streaming, we need to include a module named ''ActionController::Live''. When this module is mixed into the controller, all actions within that controller will be able to stream data to the client in real time, like the following code:
<pre>
class MessageController < ApplicationController
#here we enabled live streaming
include ActionController::Live
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a live streaming message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>
The above code looks exactly the same as the traditional response, except the newly included module ''ActionController::Live''. Now '''data can be streamed to the client immediately whenever write method is called'''. When we run the code above, the web page will print one line “This is a response message!” for every seconds and repeats 8 times.<ref>Is it live? http://tenderlovemaking.com/2012/07/30/is-it-live.html</ref> Like the image shows below: 
[[File:streaming.gif]]
 
 

==Server-Sent Event==
[https://en.wikipedia.org/wiki/Server-sent_events Server-sent event (SSE)] is a technology where browser can automatically receive update data from a server via [https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol HTTP] connection. Whenever server sends data, the SSE method in the browser will trigger an event.The SSE EventSource API is standardized as part of [https://en.wikipedia.org/wiki/HTML5 HTML5] by the [https://en.wikipedia.org/wiki/World_Wide_Web_Consortium W3C]. It can be used together with the Live API to achieve full-duplex communication.<ref>Server-sent events https://en.wikipedia.org/wiki/Server-sent_events</ref>
 
A simple SSE looks like the following :
<pre>
require 'json'
module ServerSide
class SSE
def initialize io
@io = io
end

def write object, options = {}
options.each do |k,v|
@io.write "#{k}: #{v}n"
end
@io.write "data: #{object}nn"
end

def close
@io.close
end
end
end
</pre>
This module assigns the I/O stream object to a hash and converts it into a key-value pair so that it is easy to read, store, and send it back in [https://en.wikipedia.org/wiki/JSON JSON] format.
 
 
Now we can wrap stream object inside the SSE class. By doing this, we need to include SSE module inside the controller, so that the opening and closing of connections will be managed by SSE module. And we also add the ensure clause to make sure that the connection will always be closed after execution.
<pre>
require 'sse'
class MessagingController < ApplicationController
include ActionController::Live

def stream
response.headers['Content-Type'] = 'text/event-stream'
sse = SSE.new(response.stream)
begin
5.times {
sse.write(“Streaming using SSE!”)
sleep 1
}
ensure
sse.close
end
end
end
</pre>
The code above will print the sentence “Streaming using SSE!” once per second, until the loop ends.
 
 
Here’s another sample showing how to use SSE to stream data<ref>https://github.com/rails/rails/blob/6061c540ac7880233a6e32de85cec72c20ed8778/actionpack/lib/action_controller/metal/live.rb</ref>:

# This class provides the ability to write an SSE (Server Sent Event)
# to an IO stream. The class is initialized with a stream and can be used
# to either write a JSON string or an object which can be converted to JSON.
#
# Writing an object will convert it into standard SSE format with whatever
# options you have configured. You may choose to set the following options:
#
# 1) Event. If specified, an event with this name will be dispatched on
# the browser.
# 2) Retry. The reconnection time in milliseconds used when attempting
# to send the event.
# 3) Id. If the connection dies while sending an SSE to the browser, then
# the server will receive a +Last-Event-ID+ header with value equal to +id+.
#
# After setting an option in the constructor of the SSE object, all future
# SSEs sent across the stream will use those options unless overridden.
#
# Example Usage:
#
# class MyController < ActionController::Base
# include ActionController::Live
#
# def index
# response.headers['Content-Type'] = 'text/event-stream'
# sse = SSE.new(response.stream, retry: 300, event: "event-name")
# sse.write({ name: 'John'})
# sse.write({ name: 'John'}, id: 10)
# sse.write({ name: 'John'}, id: 10, event: "other-event")
# sse.write({ name: 'John'}, id: 10, event: "other-event", retry: 500)
# ensure
# sse.close
# end
# end
#
# Note: SSEs are not currently supported by IE. However, they are supported
# by Chrome, Firefox, Opera, and Safari.

Note: By default Rails provides a one-way communication process by writing the stream to the client when data is available. However, if we can add SSEs, we can enable events and responses, thus making it two-way.
 
 

='''Conclusion'''=
1.Send partial responses to the client immediately.
 
2.Using Server-sent events, the ability to create chat clients, push notifications, and real-time feeds are available within Rails itself
 
3.Continuously inform the user about the progress.
See example below<ref>Why Rails 4 Live Streaming is a big deal, Hongli Lai http://blog.phusion.nl/2012/08/03/why-rails-4-live-streaming-is-a-big-deal/</ref>:
<pre>
def big_work
work = WorkModel.new
while !work.done?
work.do_some_calculations
response.stream.write "Progress: #{work.progress}%\n"
end
response.stream.close
end
</pre>
 

='''Troubleshooting'''=
When running streaming programs, we need to install [http://puma.io/ PUMA] to substitute the original [https://en.wikipedia.org/wiki/WEBrick WEBrick] server, because puma can handle concurrency better. In order to do this, we need to add the following line to Gemfile:
<pre>
gem 'puma'
</pre>
 
After installed puma, if we start rails server, the console will print the following output:
<pre>
"C:\Program Files (x86)\JetBrains\RubyMine 7.0.2\bin\runnerw.exe" C:\RailsInstaller\Ruby2.0.0\bin\ruby.exe -e $stdout.sync=true;$stderr.sync=true;load($0=ARGV.shift) D:/Cloud/Coding/RubymineProjects/LiveStreamingExample/bin/rails server -b 127.0.0.1 -p 3000 -e development
=> Booting Puma
=> Rails 4.1.8 application starting in development on http://127.0.0.1:3000
=> Run `rails server -h` for more startup options
=> Ctrl-C to shutdown server
Puma 2.11.0 starting...
* Min threads: 0, max threads: 16
* Environment: development
* Listening on tcp://127.0.0.1:3000
</pre>
This means that PUMA is set as our default server and successfully booted.
 
 
We encountered failure on Windows when trying to install PUMA, the console printed the following error:
<pre>
Building native extensions. This could take a while...
ERROR: Error installing rails:
ERROR: Failed to build gem native extension.

/Users/WillieTran/.rvm/rubies/ruby-2.0.0-p247/bin/ruby extconf.rb
*** extconf.rb failed ***

Could not create Makefile due to some reason, probably lack of necessary
libraries and/or headers. Check the mkmf.log file for more details. You may
need configuration options.
</pre>
 
To solve this problem, we need to install [https://www.openssl.org/ openssl] for windows. And then run the following command<ref>Installing puma on windows, Robert Kranz https://github.com/hicknhack-software/rails-disco/wiki/Installing-puma-on-windows</ref>:
<pre>
gem install puma -- --with-opt-dir=c:\openssl
</pre>
 

='''References'''=
<references>

CSC/ECE 517 Spring 2015/ch1a 12 LS

2015-02-16T03:37:40Z

Hwang40:

Live Streaming

='''Introduction'''=
The purpose of live streaming is to send data over the Internet in real-time. This requires a data source, a data encoder, a media publisher and a proper network.

In Rails, the concept of streaming first appeared in [http://weblog.rubyonrails.org/releases/ version 3.1], and is further optimized in Rails 4. Now Rails 4 supports live streaming, which uses handling I/O object and can send data from server to client in real-time.

__TOC__

='''Examples'''=
==Template streaming==
Some basic knowledge about how web pages are rendered can be found [http://friendlybit.com/css/rendering-a-web-page-step-by-step/ here] and [http://www.pathinteractive.com/blog/2014/07/rendering-a-webpage-with-google-webmaster-tools/ here]. 
Since Rail 3.1, [http://api.rubyonrails.org/classes/ActionController/Streaming.html ''::Streaming''] module has been added to ActionController. For example, the loading progress in a traditional Rails client-side may look like this<ref>Template Streaming, George Ogata https://github.com/oggy/template_streaming</ref>:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:slow-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 1 progress without streaming</div>
This is because that layouts are rendered before the content, thus causing control flow to be altered to render the page in the order that the client needs (layout first).But for some resources which are static, if they could be loaded while waiting for the server response, a lot of time can be saved.
 
 
The module ''::Streaming'' inverts the regular Rails process of rendering the layout and template. Using ''::Streaming'', Rails will render template first and then layout. It will first run method ''yield'' and load up the template, and then renders the assets and layouts. In this way, the progress with streaming looks like this:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:fast-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 2 progress with streaming</div>

===When to use streaming===
For actions like ''new'' or ''edit'', it may not be that necessary to use streaming. But for expensive actions like database query and generation of large amount of data, streaming can be extremely important and effective. Take the following action as an example:
<pre>
def storyboard
@stories = Story.all
@developers = Page.all
@comments = Comment.all
end
</pre>

Since most of the queries here are executing in the controller, it might take a while before them to finish, thus causing the front end (user) to wait for long. We can solve this problem and enhance user experience, the above code can be rewrite as follows,
<pre>
def storyboard
# Allow lazy execution of the queries
@stories = Story.all
@developers = Page.all
@comments = Comment.all
render :stream => true
end
</pre>
(Note: '':Streaming'' only works with templates. It doesn’t work with :json or :xml)<ref>ActionController::Streaming http://apidock.com/rails/ActionController/Streaming</ref>
 
 

===Tweaking views===
When using streaming, instance variables that are set in the template and are used in the layout won't need some tweak to work well. This is done by using content_for, provide and yield.
Here’s a simple example where the layout expects the template to tell which title to use<ref>ActionController::Streaming http://apidock.com/rails/ActionController/Streaming</ref>:
<pre>
<html>
<head><title><%= yield :title %></title></head>
<body><%= yield %></body>
</html>
</pre>

Instead of yield, we can also use content_for to specify the title:
<pre>
<%= content_for :title, "Main" %>
Hello
</pre>

And the final result would be:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>

However, if content_for is called several times, the final result would have all calls concatenated.
For instance, if we have the following template:
<pre>
<%= content_for :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>

The final result would be:
<pre>
<html>
<head><title>Main page</title></head>
<body>Hello</body>
</html>
</pre>
This means that, if you have yield '':title'' in your layout and you want to use streaming, you would have to render the whole template (and eventually trigger all queries) before streaming the title and all assets, which kills the purpose of streaming. For this reason Rails 3.1 introduces a new helper called provide that does the same as content_for but tells the layout to stop searching for other entries and continue rendering.

For instance, the template above using provide would be:
<pre>
<%= provide :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>
Giving:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>
That said, when streaming, you need to properly check your templates and choose when to use provide and content_for.
 
 

==Live Streaming==
The module [http://api.rubyonrails.org/classes/ActionController/Live.html ''::Live''] was then added to ActionController at Rail 4. The difference between Streaming and Live is that Streaming is implicitly included whenever you create a new controller class, while ''::Live'' requires explicit include.

===Traditional Response===
In this type of communication between server and client, data will be buffered until all render works are finished, and everything will be sent to the client at the same time. And the stream object behaves just like an IO object. Here’s the sample code:
<pre>
class MessageController < ApplicationController
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a response message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>

When we run the code above, the web page will '''keep loading and remain blank''' for 8 seconds, and shows all 8 lines of “This is a response message!” altogether, as with the following image shows: 
[[File:nostreaming.gif]]

===Live Streaming===
In order to enable live streaming, we need to include a module named ''ActionController::Live''. When this module is mixed into the controller, all actions within that controller will be able to stream data to the client in real time, like the following code:
<pre>
class MessageController < ApplicationController
#here we enabled live streaming
include ActionController::Live
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a live streaming message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>
The above code looks exactly the same as the traditional response, except the newly included module ''ActionController::Live''. Now '''data can be streamed to the client immediately whenever write method is called'''. When we run the code above, the web page will print one line “This is a response message!” for every seconds and repeats 8 times.<ref>Is it live? http://tenderlovemaking.com/2012/07/30/is-it-live.html</ref> Like the image shows below: 
[[File:streaming.gif]]
 
 

==Server-Sent Event==
[https://en.wikipedia.org/wiki/Server-sent_events Server-sent event (SSE)] is a technology where browser can automatically receive update data from a server via [https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol HTTP] connection. Whenever server sends data, the SSE method in the browser will trigger an event.The SSE EventSource API is standardized as part of [https://en.wikipedia.org/wiki/HTML5 HTML5] by the [https://en.wikipedia.org/wiki/World_Wide_Web_Consortium W3C]. It can be used together with the Live API to achieve full-duplex communication.<ref>Server-sent events https://en.wikipedia.org/wiki/Server-sent_events</ref>
 
A simple SSE looks like the following :
<pre>
require 'json'
module ServerSide
class SSE
def initialize io
@io = io
end

def write object, options = {}
options.each do |k,v|
@io.write "#{k}: #{v}n"
end
@io.write "data: #{object}nn"
end

def close
@io.close
end
end
end
</pre>
This module assigns the I/O stream object to a hash and converts it into a key-value pair so that it is easy to read, store, and send it back in [https://en.wikipedia.org/wiki/JSON JSON] format.
 
 
Now we can wrap stream object inside the SSE class. By doing this, we need to include SSE module inside the controller, so that the opening and closing of connections will be managed by SSE module. And we also add the ensure clause to make sure that the connection will always be closed after execution.
<pre>
require 'sse'
class MessagingController < ApplicationController
include ActionController::Live

def stream
response.headers['Content-Type'] = 'text/event-stream'
sse = SSE.new(response.stream)
begin
5.times {
sse.write(“Streaming using SSE!”)
sleep 1
}
ensure
sse.close
end
end
end
</pre>
The code above will print the sentence “Streaming using SSE!” once per second, until the loop ends.
 
 
Here’s another sample showing how to use SSE to stream data<ref>https://github.com/rails/rails/blob/6061c540ac7880233a6e32de85cec72c20ed8778/actionpack/lib/action_controller/metal/live.rb</ref>:

# This class provides the ability to write an SSE (Server Sent Event)
# to an IO stream. The class is initialized with a stream and can be used
# to either write a JSON string or an object which can be converted to JSON.
#
# Writing an object will convert it into standard SSE format with whatever
# options you have configured. You may choose to set the following options:
#
# 1) Event. If specified, an event with this name will be dispatched on
# the browser.
# 2) Retry. The reconnection time in milliseconds used when attempting
# to send the event.
# 3) Id. If the connection dies while sending an SSE to the browser, then
# the server will receive a +Last-Event-ID+ header with value equal to +id+.
#
# After setting an option in the constructor of the SSE object, all future
# SSEs sent across the stream will use those options unless overridden.
#
# Example Usage:
#
# class MyController < ActionController::Base
# include ActionController::Live
#
# def index
# response.headers['Content-Type'] = 'text/event-stream'
# sse = SSE.new(response.stream, retry: 300, event: "event-name")
# sse.write({ name: 'John'})
# sse.write({ name: 'John'}, id: 10)
# sse.write({ name: 'John'}, id: 10, event: "other-event")
# sse.write({ name: 'John'}, id: 10, event: "other-event", retry: 500)
# ensure
# sse.close
# end
# end
#
# Note: SSEs are not currently supported by IE. However, they are supported
# by Chrome, Firefox, Opera, and Safari.

Note: By default Rails provides a one-way communication process by writing the stream to the client when data is available. However, if we can add SSEs, we can enable events and responses, thus making it two-way.
 
 

='''Benefit of live streaming'''=
1.Send partial responses to the client immediately.
 
2.Using Server-sent events, the ability to create chat clients, push notifications, and real-time feeds are available within Rails itself
 
3.Continuously inform the user about the progress.
See example below<ref>Why Rails 4 Live Streaming is a big deal, Hongli Lai http://blog.phusion.nl/2012/08/03/why-rails-4-live-streaming-is-a-big-deal/</ref>:
<pre>
def big_work
work = WorkModel.new
while !work.done?
work.do_some_calculations
response.stream.write "Progress: #{work.progress}%\n"
end
response.stream.close
end
</pre>
 

='''Troubleshooting'''=
When running streaming programs, we need to install [http://puma.io/ PUMA] to substitute the original [https://en.wikipedia.org/wiki/WEBrick WEBrick] server, because puma can handle concurrency better. In order to do this, we need to add the following line to Gemfile:
<pre>
gem 'puma'
</pre>
 
After installed puma, if we start rails server, the console will print the following output:
<pre>
"C:\Program Files (x86)\JetBrains\RubyMine 7.0.2\bin\runnerw.exe" C:\RailsInstaller\Ruby2.0.0\bin\ruby.exe -e $stdout.sync=true;$stderr.sync=true;load($0=ARGV.shift) D:/Cloud/Coding/RubymineProjects/LiveStreamingExample/bin/rails server -b 127.0.0.1 -p 3000 -e development
=> Booting Puma
=> Rails 4.1.8 application starting in development on http://127.0.0.1:3000
=> Run `rails server -h` for more startup options
=> Ctrl-C to shutdown server
Puma 2.11.0 starting...
* Min threads: 0, max threads: 16
* Environment: development
* Listening on tcp://127.0.0.1:3000
</pre>
This means that PUMA is set as our default server and successfully booted.
 
 
We encountered failure on Windows when trying to install PUMA, the console printed the following error:
<pre>
Building native extensions. This could take a while...
ERROR: Error installing rails:
ERROR: Failed to build gem native extension.

/Users/WillieTran/.rvm/rubies/ruby-2.0.0-p247/bin/ruby extconf.rb
*** extconf.rb failed ***

Could not create Makefile due to some reason, probably lack of necessary
libraries and/or headers. Check the mkmf.log file for more details. You may
need configuration options.
</pre>
 
To solve this problem, we need to install [https://www.openssl.org/ openssl] for windows. And then run the following command<ref>Installing puma on windows, Robert Kranz https://github.com/hicknhack-software/rails-disco/wiki/Installing-puma-on-windows</ref>:
<pre>
gem install puma -- --with-opt-dir=c:\openssl
</pre>
 

='''References'''=
<references>

CSC/ECE 517 Spring 2015/ch1a 12 LS

2015-02-16T03:22:06Z

Hwang40: /* Troubleshooting */

Live Streaming

='''Introduction'''=
The purpose of live streaming is to send data over the Internet in real-time. This requires a data source, a data encoder, a media publisher and a proper network.

In Rails, the concept of streaming first appeared in [http://weblog.rubyonrails.org/releases/ version 3.1], and is further optimized in Rails 4. Now Rails 4 supports live streaming, which uses handling I/O object and can send data from server to client in real-time.

__TOC__

='''Details'''=
==Template streaming==
Since Rail 3.1, [http://api.rubyonrails.org/classes/ActionController/Streaming.html ''::Streaming''] module has been added to ActionController. For example, the loading progress in a traditional Rails client-side may look like this<ref>Template Streaming, George Ogata https://github.com/oggy/template_streaming</ref>:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:slow-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 1 progress without streaming</div>
This is because that layouts are rendered before the content, thus causing control flow to be altered to render the page in the order that the client needs (layout first).But for some resources which are static, if they could be loaded while waiting for the server response, a lot of time can be saved.
 
 
The module ''::Streaming'' inverts the regular Rails process of rendering the layout and template. Using ''::Streaming'', Rails will render template first and then layout. It will first run method yield and load up the template, and then renders the assets and layouts. In this way, the progress with streaming looks like this:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:fast-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 2 progress with streaming</div>

===When to use streaming===
For actions like new or edit, it may not be that necessary to use streaming. But for expensive actions like database query and generation of large amount of data, streaming can be extremely important and effective. Take the following action as an example:
<pre>
def storyboard
@stories = Story.all
@developers = Page.all
@comments = Comment.all
end
</pre>

Since most of the queries here are executing in the controller, it might take a while before them to finish, thus causing the front end (user) to wait for long. We can solve this problem and enhance user experience, the above code can be rewrite as follows,
<pre>
def storyboard
# Allow lazy execution of the queries
@stories = Story.all
@developers = Page.all
@comments = Comment.all
render :stream => true
end
</pre>
(Note: '':Streaming'' only works with templates. It doesn’t work with :json or :xml)<ref>ActionController::Streaming http://apidock.com/rails/ActionController/Streaming</ref>
 
 

===Tweaking views===
When using streaming, instance variables that are set in the template and are used in the layout won't need some tweak to work well. This is done by using content_for, provide and yield.
Here’s a simple example where the layout expects the template to tell which title to use<ref>ActionController::Streaming http://apidock.com/rails/ActionController/Streaming</ref>:
<pre>
<html>
<head><title><%= yield :title %></title></head>
<body><%= yield %></body>
</html>
</pre>

Instead of yield, we can also use content_for to specify the title:
<pre>
<%= content_for :title, "Main" %>
Hello
</pre>

And the final result would be:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>

However, if content_for is called several times, the final result would have all calls concatenated.
For instance, if we have the following template:
<pre>
<%= content_for :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>

The final result would be:
<pre>
<html>
<head><title>Main page</title></head>
<body>Hello</body>
</html>
</pre>
This means that, if you have yield '':title'' in your layout and you want to use streaming, you would have to render the whole template (and eventually trigger all queries) before streaming the title and all assets, which kills the purpose of streaming. For this reason Rails 3.1 introduces a new helper called provide that does the same as content_for but tells the layout to stop searching for other entries and continue rendering.

For instance, the template above using provide would be:
<pre>
<%= provide :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>
Giving:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>
That said, when streaming, you need to properly check your templates and choose when to use provide and content_for.
 
 

==Live Streaming==
The module [http://api.rubyonrails.org/classes/ActionController/Live.html ''::Live''] was then added to ActionController at Rail 4. The difference between Streaming and Live is that Streaming is implicitly included whenever you create a new controller class, while ''::Live'' requires explicit include.

===Traditional Response===
In this type of communication between server and client, data will be buffered until all render works are finished, and everything will be sent to the client at the same time. And the stream object behaves just like an IO object. Here’s the sample code:
<pre>
class MessageController < ApplicationController
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a response message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>

When we run the code above, the web page will '''keep loading and remain blank''' for 8 seconds, and shows all 8 lines of “This is a response message!” altogether, as with the following image shows: 
[[File:nostreaming.gif]]

===Live Streaming===
In order to enable live streaming, we need to include a module named ''ActionController::Live''. When this module is mixed into the controller, all actions within that controller will be able to stream data to the client in real time, like the following code:
<pre>
class MessageController < ApplicationController
#here we enabled live streaming
include ActionController::Live
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a live streaming message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>
The above code looks exactly the same as the traditional response, except the newly included module ''ActionController::Live''. Now '''data can be streamed to the client immediately whenever write method is called'''. When we run the code above, the web page will print one line “This is a response message!” for every seconds and repeats 8 times.<ref>Is it live? http://tenderlovemaking.com/2012/07/30/is-it-live.html</ref> Like the image shows below: 
[[File:streaming.gif]]
 
 

==Server-Sent Event==
[https://en.wikipedia.org/wiki/Server-sent_events Server-sent event (SSE)] is a technology where browser can automatically receive update data from a server via [https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol HTTP] connection. Whenever server sends data, the SSE method in the browser will trigger an event.The SSE EventSource API is standardized as part of [https://en.wikipedia.org/wiki/HTML5 HTML5] by the [https://en.wikipedia.org/wiki/World_Wide_Web_Consortium W3C]. It can be used together with the Live API to achieve full-duplex communication.<ref>Server-sent events https://en.wikipedia.org/wiki/Server-sent_events</ref>
 
A simple SSE looks like the following :
<pre>
require 'json'
module ServerSide
class SSE
def initialize io
@io = io
end

def write object, options = {}
options.each do |k,v|
@io.write "#{k}: #{v}n"
end
@io.write "data: #{object}nn"
end

def close
@io.close
end
end
end
</pre>
This module assigns the I/O stream object to a hash and converts it into a key-value pair so that it is easy to read, store, and send it back in [https://en.wikipedia.org/wiki/JSON JSON] format.
 
 
Now we can wrap stream object inside the SSE class. By doing this, we need to include SSE module inside the controller, so that the opening and closing of connections will be managed by SSE module. And we also add the ensure clause to make sure that the connection will always be closed after execution.
<pre>
require 'sse'
class MessagingController < ApplicationController
include ActionController::Live

def stream
response.headers['Content-Type'] = 'text/event-stream'
sse = SSE.new(response.stream)
begin
5.times {
sse.write(“Streaming using SSE!”)
sleep 1
}
ensure
sse.close
end
end
end
</pre>
The code above will print the sentence “Streaming using SSE!” once per second, until the loop ends.
 
 
Here’s another sample showing how to use SSE to stream data<ref>https://github.com/rails/rails/blob/6061c540ac7880233a6e32de85cec72c20ed8778/actionpack/lib/action_controller/metal/live.rb</ref>:

# This class provides the ability to write an SSE (Server Sent Event)
# to an IO stream. The class is initialized with a stream and can be used
# to either write a JSON string or an object which can be converted to JSON.
#
# Writing an object will convert it into standard SSE format with whatever
# options you have configured. You may choose to set the following options:
#
# 1) Event. If specified, an event with this name will be dispatched on
# the browser.
# 2) Retry. The reconnection time in milliseconds used when attempting
# to send the event.
# 3) Id. If the connection dies while sending an SSE to the browser, then
# the server will receive a +Last-Event-ID+ header with value equal to +id+.
#
# After setting an option in the constructor of the SSE object, all future
# SSEs sent across the stream will use those options unless overridden.
#
# Example Usage:
#
# class MyController < ActionController::Base
# include ActionController::Live
#
# def index
# response.headers['Content-Type'] = 'text/event-stream'
# sse = SSE.new(response.stream, retry: 300, event: "event-name")
# sse.write({ name: 'John'})
# sse.write({ name: 'John'}, id: 10)
# sse.write({ name: 'John'}, id: 10, event: "other-event")
# sse.write({ name: 'John'}, id: 10, event: "other-event", retry: 500)
# ensure
# sse.close
# end
# end
#
# Note: SSEs are not currently supported by IE. However, they are supported
# by Chrome, Firefox, Opera, and Safari.

Note: By default Rails provides a one-way communication process by writing the stream to the client when data is available. However, if we can add SSEs, we can enable events and responses, thus making it two-way.
 
 

==Benefit of live streaming==
1.Send partial responses to the client immediately.
 
2.Using Server-sent events, the ability to create chat clients, push notifications, and real-time feeds are available within Rails itself
 
3.Continuously inform the user about the progress.
See example below<ref>Why Rails 4 Live Streaming is a big deal, Hongli Lai http://blog.phusion.nl/2012/08/03/why-rails-4-live-streaming-is-a-big-deal/</ref>:
<pre>
def big_work
work = WorkModel.new
while !work.done?
work.do_some_calculations
response.stream.write "Progress: #{work.progress}%\n"
end
response.stream.close
end
</pre>
 

='''Troubleshooting'''=
When running streaming programs, we need to install [http://puma.io/ PUMA] to substitute the original [https://en.wikipedia.org/wiki/WEBrick WEBrick] server, because puma can handle concurrency better. In order to do this, we need to add the following line to Gemfile:
<pre>
gem 'puma'
</pre>
 
After installed puma, if we start rails server, the console will print the following output:
<pre>
"C:\Program Files (x86)\JetBrains\RubyMine 7.0.2\bin\runnerw.exe" C:\RailsInstaller\Ruby2.0.0\bin\ruby.exe -e $stdout.sync=true;$stderr.sync=true;load($0=ARGV.shift) D:/Cloud/Coding/RubymineProjects/LiveStreamingExample/bin/rails server -b 127.0.0.1 -p 3000 -e development
=> Booting Puma
=> Rails 4.1.8 application starting in development on http://127.0.0.1:3000
=> Run `rails server -h` for more startup options
=> Ctrl-C to shutdown server
Puma 2.11.0 starting...
* Min threads: 0, max threads: 16
* Environment: development
* Listening on tcp://127.0.0.1:3000
</pre>
This means that PUMA is set as our default server and successfully booted.
 
 
We encountered failure on Windows when trying to install PUMA, the console printed the following error:
<pre>
Building native extensions. This could take a while...
ERROR: Error installing rails:
ERROR: Failed to build gem native extension.

/Users/WillieTran/.rvm/rubies/ruby-2.0.0-p247/bin/ruby extconf.rb
*** extconf.rb failed ***

Could not create Makefile due to some reason, probably lack of necessary
libraries and/or headers. Check the mkmf.log file for more details. You may
need configuration options.
</pre>
 
To solve this problem, we need to install [https://www.openssl.org/ openssl] for windows. And then run the following command<ref>Installing puma on windows, Robert Kranz https://github.com/hicknhack-software/rails-disco/wiki/Installing-puma-on-windows</ref>:
<pre>
gem install puma -- --with-opt-dir=c:\openssl
</pre>
 

='''References'''=
<references>

CSC/ECE 517 Spring 2015/ch1a 12 LS

2015-02-16T03:20:49Z

Hwang40: /* Server-Sent Event */

Live Streaming

='''Introduction'''=
The purpose of live streaming is to send data over the Internet in real-time. This requires a data source, a data encoder, a media publisher and a proper network.

In Rails, the concept of streaming first appeared in [http://weblog.rubyonrails.org/releases/ version 3.1], and is further optimized in Rails 4. Now Rails 4 supports live streaming, which uses handling I/O object and can send data from server to client in real-time.

__TOC__

='''Details'''=
==Template streaming==
Since Rail 3.1, [http://api.rubyonrails.org/classes/ActionController/Streaming.html ''::Streaming''] module has been added to ActionController. For example, the loading progress in a traditional Rails client-side may look like this<ref>Template Streaming, George Ogata https://github.com/oggy/template_streaming</ref>:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:slow-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 1 progress without streaming</div>
This is because that layouts are rendered before the content, thus causing control flow to be altered to render the page in the order that the client needs (layout first).But for some resources which are static, if they could be loaded while waiting for the server response, a lot of time can be saved.
 
 
The module ''::Streaming'' inverts the regular Rails process of rendering the layout and template. Using ''::Streaming'', Rails will render template first and then layout. It will first run method yield and load up the template, and then renders the assets and layouts. In this way, the progress with streaming looks like this:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:fast-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 2 progress with streaming</div>

===When to use streaming===
For actions like new or edit, it may not be that necessary to use streaming. But for expensive actions like database query and generation of large amount of data, streaming can be extremely important and effective. Take the following action as an example:
<pre>
def storyboard
@stories = Story.all
@developers = Page.all
@comments = Comment.all
end
</pre>

Since most of the queries here are executing in the controller, it might take a while before them to finish, thus causing the front end (user) to wait for long. We can solve this problem and enhance user experience, the above code can be rewrite as follows,
<pre>
def storyboard
# Allow lazy execution of the queries
@stories = Story.all
@developers = Page.all
@comments = Comment.all
render :stream => true
end
</pre>
(Note: '':Streaming'' only works with templates. It doesn’t work with :json or :xml)<ref>ActionController::Streaming http://apidock.com/rails/ActionController/Streaming</ref>
 
 

===Tweaking views===
When using streaming, instance variables that are set in the template and are used in the layout won't need some tweak to work well. This is done by using content_for, provide and yield.
Here’s a simple example where the layout expects the template to tell which title to use<ref>ActionController::Streaming http://apidock.com/rails/ActionController/Streaming</ref>:
<pre>
<html>
<head><title><%= yield :title %></title></head>
<body><%= yield %></body>
</html>
</pre>

Instead of yield, we can also use content_for to specify the title:
<pre>
<%= content_for :title, "Main" %>
Hello
</pre>

And the final result would be:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>

However, if content_for is called several times, the final result would have all calls concatenated.
For instance, if we have the following template:
<pre>
<%= content_for :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>

The final result would be:
<pre>
<html>
<head><title>Main page</title></head>
<body>Hello</body>
</html>
</pre>
This means that, if you have yield '':title'' in your layout and you want to use streaming, you would have to render the whole template (and eventually trigger all queries) before streaming the title and all assets, which kills the purpose of streaming. For this reason Rails 3.1 introduces a new helper called provide that does the same as content_for but tells the layout to stop searching for other entries and continue rendering.

For instance, the template above using provide would be:
<pre>
<%= provide :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>
Giving:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>
That said, when streaming, you need to properly check your templates and choose when to use provide and content_for.
 
 

==Live Streaming==
The module [http://api.rubyonrails.org/classes/ActionController/Live.html ''::Live''] was then added to ActionController at Rail 4. The difference between Streaming and Live is that Streaming is implicitly included whenever you create a new controller class, while ''::Live'' requires explicit include.

===Traditional Response===
In this type of communication between server and client, data will be buffered until all render works are finished, and everything will be sent to the client at the same time. And the stream object behaves just like an IO object. Here’s the sample code:
<pre>
class MessageController < ApplicationController
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a response message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>

When we run the code above, the web page will '''keep loading and remain blank''' for 8 seconds, and shows all 8 lines of “This is a response message!” altogether, as with the following image shows: 
[[File:nostreaming.gif]]

===Live Streaming===
In order to enable live streaming, we need to include a module named ''ActionController::Live''. When this module is mixed into the controller, all actions within that controller will be able to stream data to the client in real time, like the following code:
<pre>
class MessageController < ApplicationController
#here we enabled live streaming
include ActionController::Live
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a live streaming message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>
The above code looks exactly the same as the traditional response, except the newly included module ''ActionController::Live''. Now '''data can be streamed to the client immediately whenever write method is called'''. When we run the code above, the web page will print one line “This is a response message!” for every seconds and repeats 8 times.<ref>Is it live? http://tenderlovemaking.com/2012/07/30/is-it-live.html</ref> Like the image shows below: 
[[File:streaming.gif]]
 
 

==Server-Sent Event==
[https://en.wikipedia.org/wiki/Server-sent_events Server-sent event (SSE)] is a technology where browser can automatically receive update data from a server via [https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol HTTP] connection. Whenever server sends data, the SSE method in the browser will trigger an event.The SSE EventSource API is standardized as part of [https://en.wikipedia.org/wiki/HTML5 HTML5] by the [https://en.wikipedia.org/wiki/World_Wide_Web_Consortium W3C]. It can be used together with the Live API to achieve full-duplex communication.<ref>Server-sent events https://en.wikipedia.org/wiki/Server-sent_events</ref>
 
A simple SSE looks like the following :
<pre>
require 'json'
module ServerSide
class SSE
def initialize io
@io = io
end

def write object, options = {}
options.each do |k,v|
@io.write "#{k}: #{v}n"
end
@io.write "data: #{object}nn"
end

def close
@io.close
end
end
end
</pre>
This module assigns the I/O stream object to a hash and converts it into a key-value pair so that it is easy to read, store, and send it back in [https://en.wikipedia.org/wiki/JSON JSON] format.
 
 
Now we can wrap stream object inside the SSE class. By doing this, we need to include SSE module inside the controller, so that the opening and closing of connections will be managed by SSE module. And we also add the ensure clause to make sure that the connection will always be closed after execution.
<pre>
require 'sse'
class MessagingController < ApplicationController
include ActionController::Live

def stream
response.headers['Content-Type'] = 'text/event-stream'
sse = SSE.new(response.stream)
begin
5.times {
sse.write(“Streaming using SSE!”)
sleep 1
}
ensure
sse.close
end
end
end
</pre>
The code above will print the sentence “Streaming using SSE!” once per second, until the loop ends.
 
 
Here’s another sample showing how to use SSE to stream data<ref>https://github.com/rails/rails/blob/6061c540ac7880233a6e32de85cec72c20ed8778/actionpack/lib/action_controller/metal/live.rb</ref>:

# This class provides the ability to write an SSE (Server Sent Event)
# to an IO stream. The class is initialized with a stream and can be used
# to either write a JSON string or an object which can be converted to JSON.
#
# Writing an object will convert it into standard SSE format with whatever
# options you have configured. You may choose to set the following options:
#
# 1) Event. If specified, an event with this name will be dispatched on
# the browser.
# 2) Retry. The reconnection time in milliseconds used when attempting
# to send the event.
# 3) Id. If the connection dies while sending an SSE to the browser, then
# the server will receive a +Last-Event-ID+ header with value equal to +id+.
#
# After setting an option in the constructor of the SSE object, all future
# SSEs sent across the stream will use those options unless overridden.
#
# Example Usage:
#
# class MyController < ActionController::Base
# include ActionController::Live
#
# def index
# response.headers['Content-Type'] = 'text/event-stream'
# sse = SSE.new(response.stream, retry: 300, event: "event-name")
# sse.write({ name: 'John'})
# sse.write({ name: 'John'}, id: 10)
# sse.write({ name: 'John'}, id: 10, event: "other-event")
# sse.write({ name: 'John'}, id: 10, event: "other-event", retry: 500)
# ensure
# sse.close
# end
# end
#
# Note: SSEs are not currently supported by IE. However, they are supported
# by Chrome, Firefox, Opera, and Safari.

Note: By default Rails provides a one-way communication process by writing the stream to the client when data is available. However, if we can add SSEs, we can enable events and responses, thus making it two-way.
 
 

==Benefit of live streaming==
1.Send partial responses to the client immediately.
 
2.Using Server-sent events, the ability to create chat clients, push notifications, and real-time feeds are available within Rails itself
 
3.Continuously inform the user about the progress.
See example below<ref>Why Rails 4 Live Streaming is a big deal, Hongli Lai http://blog.phusion.nl/2012/08/03/why-rails-4-live-streaming-is-a-big-deal/</ref>:
<pre>
def big_work
work = WorkModel.new
while !work.done?
work.do_some_calculations
response.stream.write "Progress: #{work.progress}%\n"
end
response.stream.close
end
</pre>
 

='''Troubleshooting'''=
When running streaming programs, we need to install [http://puma.io/ PUMA] to substitute the original [https://en.wikipedia.org/wiki/WEBrick WEBrick] server, because puma can handle concurrency better. In order to do this, we need to add the following line to Gemfile:
<pre>
gem 'puma'
</pre>
 
After installed puma, if we start rails server, the console will print the following output:
<pre>
"C:\Program Files (x86)\JetBrains\RubyMine 7.0.2\bin\runnerw.exe" C:\RailsInstaller\Ruby2.0.0\bin\ruby.exe -e $stdout.sync=true;$stderr.sync=true;load($0=ARGV.shift) D:/Cloud/Coding/RubymineProjects/LiveStreamingExample/bin/rails server -b 127.0.0.1 -p 3000 -e development
=> Booting Puma
=> Rails 4.1.8 application starting in development on http://127.0.0.1:3000
=> Run `rails server -h` for more startup options
=> Ctrl-C to shutdown server
Puma 2.11.0 starting...
* Min threads: 0, max threads: 16
* Environment: development
* Listening on tcp://127.0.0.1:3000
</pre>
This means that PUMA is set as our default server and successfully booted.
 
 
We encountered failure on Windows when trying to install PUMA, the console printed the following error:
<pre>
Building native extensions. This could take a while...
ERROR: Error installing rails:
ERROR: Failed to build gem native extension.

/Users/WillieTran/.rvm/rubies/ruby-2.0.0-p247/bin/ruby extconf.rb
*** extconf.rb failed ***

Could not create Makefile due to some reason, probably lack of necessary
libraries and/or headers. Check the mkmf.log file for more details. You may
need configuration options.
</pre>
 
To solve this problem, we need to install [https://www.openssl.org/ openssl] for windows. And then run the following command<ref>https://github.com/hicknhack-software/rails-disco/wiki/Installing-puma-on-windows</ref>:
<pre>
gem install puma -- --with-opt-dir=c:\openssl
</pre>
 

='''References'''=
<references>

CSC/ECE 517 Spring 2015/ch1a 12 LS

2015-02-16T03:19:55Z

Hwang40: /* Live Streaming */

Live Streaming

='''Introduction'''=
The purpose of live streaming is to send data over the Internet in real-time. This requires a data source, a data encoder, a media publisher and a proper network.

In Rails, the concept of streaming first appeared in [http://weblog.rubyonrails.org/releases/ version 3.1], and is further optimized in Rails 4. Now Rails 4 supports live streaming, which uses handling I/O object and can send data from server to client in real-time.

__TOC__

='''Details'''=
==Template streaming==
Since Rail 3.1, [http://api.rubyonrails.org/classes/ActionController/Streaming.html ''::Streaming''] module has been added to ActionController. For example, the loading progress in a traditional Rails client-side may look like this<ref>Template Streaming, George Ogata https://github.com/oggy/template_streaming</ref>:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:slow-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 1 progress without streaming</div>
This is because that layouts are rendered before the content, thus causing control flow to be altered to render the page in the order that the client needs (layout first).But for some resources which are static, if they could be loaded while waiting for the server response, a lot of time can be saved.
 
 
The module ''::Streaming'' inverts the regular Rails process of rendering the layout and template. Using ''::Streaming'', Rails will render template first and then layout. It will first run method yield and load up the template, and then renders the assets and layouts. In this way, the progress with streaming looks like this:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:fast-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 2 progress with streaming</div>

===When to use streaming===
For actions like new or edit, it may not be that necessary to use streaming. But for expensive actions like database query and generation of large amount of data, streaming can be extremely important and effective. Take the following action as an example:
<pre>
def storyboard
@stories = Story.all
@developers = Page.all
@comments = Comment.all
end
</pre>

Since most of the queries here are executing in the controller, it might take a while before them to finish, thus causing the front end (user) to wait for long. We can solve this problem and enhance user experience, the above code can be rewrite as follows,
<pre>
def storyboard
# Allow lazy execution of the queries
@stories = Story.all
@developers = Page.all
@comments = Comment.all
render :stream => true
end
</pre>
(Note: '':Streaming'' only works with templates. It doesn’t work with :json or :xml)<ref>ActionController::Streaming http://apidock.com/rails/ActionController/Streaming</ref>
 
 

===Tweaking views===
When using streaming, instance variables that are set in the template and are used in the layout won't need some tweak to work well. This is done by using content_for, provide and yield.
Here’s a simple example where the layout expects the template to tell which title to use<ref>ActionController::Streaming http://apidock.com/rails/ActionController/Streaming</ref>:
<pre>
<html>
<head><title><%= yield :title %></title></head>
<body><%= yield %></body>
</html>
</pre>

Instead of yield, we can also use content_for to specify the title:
<pre>
<%= content_for :title, "Main" %>
Hello
</pre>

And the final result would be:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>

However, if content_for is called several times, the final result would have all calls concatenated.
For instance, if we have the following template:
<pre>
<%= content_for :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>

The final result would be:
<pre>
<html>
<head><title>Main page</title></head>
<body>Hello</body>
</html>
</pre>
This means that, if you have yield '':title'' in your layout and you want to use streaming, you would have to render the whole template (and eventually trigger all queries) before streaming the title and all assets, which kills the purpose of streaming. For this reason Rails 3.1 introduces a new helper called provide that does the same as content_for but tells the layout to stop searching for other entries and continue rendering.

For instance, the template above using provide would be:
<pre>
<%= provide :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>
Giving:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>
That said, when streaming, you need to properly check your templates and choose when to use provide and content_for.
 
 

==Live Streaming==
The module [http://api.rubyonrails.org/classes/ActionController/Live.html ''::Live''] was then added to ActionController at Rail 4. The difference between Streaming and Live is that Streaming is implicitly included whenever you create a new controller class, while ''::Live'' requires explicit include.

===Traditional Response===
In this type of communication between server and client, data will be buffered until all render works are finished, and everything will be sent to the client at the same time. And the stream object behaves just like an IO object. Here’s the sample code:
<pre>
class MessageController < ApplicationController
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a response message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>

When we run the code above, the web page will '''keep loading and remain blank''' for 8 seconds, and shows all 8 lines of “This is a response message!” altogether, as with the following image shows: 
[[File:nostreaming.gif]]

===Live Streaming===
In order to enable live streaming, we need to include a module named ''ActionController::Live''. When this module is mixed into the controller, all actions within that controller will be able to stream data to the client in real time, like the following code:
<pre>
class MessageController < ApplicationController
#here we enabled live streaming
include ActionController::Live
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a live streaming message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>
The above code looks exactly the same as the traditional response, except the newly included module ''ActionController::Live''. Now '''data can be streamed to the client immediately whenever write method is called'''. When we run the code above, the web page will print one line “This is a response message!” for every seconds and repeats 8 times.<ref>Is it live? http://tenderlovemaking.com/2012/07/30/is-it-live.html</ref> Like the image shows below: 
[[File:streaming.gif]]
 
 

==Server-Sent Event==
[https://en.wikipedia.org/wiki/Server-sent_events Server-sent event (SSE)] is a technology where browser can automatically receive update data from a server via [https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol HTTP] connection. Whenever server sends data, the SSE method in the browser will trigger an event.The SSE EventSource API is standardized as part of [https://en.wikipedia.org/wiki/HTML5 HTML5] by the [https://en.wikipedia.org/wiki/World_Wide_Web_Consortium W3C]. It can be used together with the Live API to achieve full-duplex communication.<ref>https://en.wikipedia.org/wiki/Server-sent_events</ref>
 
A simple SSE looks like the following :
<pre>
require 'json'
module ServerSide
class SSE
def initialize io
@io = io
end

def write object, options = {}
options.each do |k,v|
@io.write "#{k}: #{v}n"
end
@io.write "data: #{object}nn"
end

def close
@io.close
end
end
end
</pre>
This module assigns the I/O stream object to a hash and converts it into a key-value pair so that it is easy to read, store, and send it back in [https://en.wikipedia.org/wiki/JSON JSON] format.
 
 
Now we can wrap stream object inside the SSE class. By doing this, we need to include SSE module inside the controller, so that the opening and closing of connections will be managed by SSE module. And we also add the ensure clause to make sure that the connection will always be closed after execution.
<pre>
require 'sse'
class MessagingController < ApplicationController
include ActionController::Live

def stream
response.headers['Content-Type'] = 'text/event-stream'
sse = SSE.new(response.stream)
begin
5.times {
sse.write(“Streaming using SSE!”)
sleep 1
}
ensure
sse.close
end
end
end
</pre>
The code above will print the sentence “Streaming using SSE!” once per second, until the loop ends.
 
 
Here’s another sample showing how to use SSE to stream data<ref>https://github.com/rails/rails/blob/6061c540ac7880233a6e32de85cec72c20ed8778/actionpack/lib/action_controller/metal/live.rb</ref>:

# This class provides the ability to write an SSE (Server Sent Event)
# to an IO stream. The class is initialized with a stream and can be used
# to either write a JSON string or an object which can be converted to JSON.
#
# Writing an object will convert it into standard SSE format with whatever
# options you have configured. You may choose to set the following options:
#
# 1) Event. If specified, an event with this name will be dispatched on
# the browser.
# 2) Retry. The reconnection time in milliseconds used when attempting
# to send the event.
# 3) Id. If the connection dies while sending an SSE to the browser, then
# the server will receive a +Last-Event-ID+ header with value equal to +id+.
#
# After setting an option in the constructor of the SSE object, all future
# SSEs sent across the stream will use those options unless overridden.
#
# Example Usage:
#
# class MyController < ActionController::Base
# include ActionController::Live
#
# def index
# response.headers['Content-Type'] = 'text/event-stream'
# sse = SSE.new(response.stream, retry: 300, event: "event-name")
# sse.write({ name: 'John'})
# sse.write({ name: 'John'}, id: 10)
# sse.write({ name: 'John'}, id: 10, event: "other-event")
# sse.write({ name: 'John'}, id: 10, event: "other-event", retry: 500)
# ensure
# sse.close
# end
# end
#
# Note: SSEs are not currently supported by IE. However, they are supported
# by Chrome, Firefox, Opera, and Safari.

Note: By default Rails provides a one-way communication process by writing the stream to the client when data is available. However, if we can add SSEs, we can enable events and responses, thus making it two-way.
 
 

==Benefit of live streaming==
1.Send partial responses to the client immediately.
 
2.Using Server-sent events, the ability to create chat clients, push notifications, and real-time feeds are available within Rails itself
 
3.Continuously inform the user about the progress.
See example below<ref>Why Rails 4 Live Streaming is a big deal, Hongli Lai http://blog.phusion.nl/2012/08/03/why-rails-4-live-streaming-is-a-big-deal/</ref>:
<pre>
def big_work
work = WorkModel.new
while !work.done?
work.do_some_calculations
response.stream.write "Progress: #{work.progress}%\n"
end
response.stream.close
end
</pre>
 

='''Troubleshooting'''=
When running streaming programs, we need to install [http://puma.io/ PUMA] to substitute the original [https://en.wikipedia.org/wiki/WEBrick WEBrick] server, because puma can handle concurrency better. In order to do this, we need to add the following line to Gemfile:
<pre>
gem 'puma'
</pre>
 
After installed puma, if we start rails server, the console will print the following output:
<pre>
"C:\Program Files (x86)\JetBrains\RubyMine 7.0.2\bin\runnerw.exe" C:\RailsInstaller\Ruby2.0.0\bin\ruby.exe -e $stdout.sync=true;$stderr.sync=true;load($0=ARGV.shift) D:/Cloud/Coding/RubymineProjects/LiveStreamingExample/bin/rails server -b 127.0.0.1 -p 3000 -e development
=> Booting Puma
=> Rails 4.1.8 application starting in development on http://127.0.0.1:3000
=> Run `rails server -h` for more startup options
=> Ctrl-C to shutdown server
Puma 2.11.0 starting...
* Min threads: 0, max threads: 16
* Environment: development
* Listening on tcp://127.0.0.1:3000
</pre>
This means that PUMA is set as our default server and successfully booted.
 
 
We encountered failure on Windows when trying to install PUMA, the console printed the following error:
<pre>
Building native extensions. This could take a while...
ERROR: Error installing rails:
ERROR: Failed to build gem native extension.

/Users/WillieTran/.rvm/rubies/ruby-2.0.0-p247/bin/ruby extconf.rb
*** extconf.rb failed ***

Could not create Makefile due to some reason, probably lack of necessary
libraries and/or headers. Check the mkmf.log file for more details. You may
need configuration options.
</pre>
 
To solve this problem, we need to install [https://www.openssl.org/ openssl] for windows. And then run the following command<ref>https://github.com/hicknhack-software/rails-disco/wiki/Installing-puma-on-windows</ref>:
<pre>
gem install puma -- --with-opt-dir=c:\openssl
</pre>
 

='''References'''=
<references>

CSC/ECE 517 Spring 2015/ch1a 12 LS

2015-02-16T03:18:19Z

Hwang40: /* Tweaking views */

Live Streaming

='''Introduction'''=
The purpose of live streaming is to send data over the Internet in real-time. This requires a data source, a data encoder, a media publisher and a proper network.

In Rails, the concept of streaming first appeared in [http://weblog.rubyonrails.org/releases/ version 3.1], and is further optimized in Rails 4. Now Rails 4 supports live streaming, which uses handling I/O object and can send data from server to client in real-time.

__TOC__

='''Details'''=
==Template streaming==
Since Rail 3.1, [http://api.rubyonrails.org/classes/ActionController/Streaming.html ''::Streaming''] module has been added to ActionController. For example, the loading progress in a traditional Rails client-side may look like this<ref>Template Streaming, George Ogata https://github.com/oggy/template_streaming</ref>:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:slow-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 1 progress without streaming</div>
This is because that layouts are rendered before the content, thus causing control flow to be altered to render the page in the order that the client needs (layout first).But for some resources which are static, if they could be loaded while waiting for the server response, a lot of time can be saved.
 
 
The module ''::Streaming'' inverts the regular Rails process of rendering the layout and template. Using ''::Streaming'', Rails will render template first and then layout. It will first run method yield and load up the template, and then renders the assets and layouts. In this way, the progress with streaming looks like this:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:fast-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 2 progress with streaming</div>

===When to use streaming===
For actions like new or edit, it may not be that necessary to use streaming. But for expensive actions like database query and generation of large amount of data, streaming can be extremely important and effective. Take the following action as an example:
<pre>
def storyboard
@stories = Story.all
@developers = Page.all
@comments = Comment.all
end
</pre>

Since most of the queries here are executing in the controller, it might take a while before them to finish, thus causing the front end (user) to wait for long. We can solve this problem and enhance user experience, the above code can be rewrite as follows,
<pre>
def storyboard
# Allow lazy execution of the queries
@stories = Story.all
@developers = Page.all
@comments = Comment.all
render :stream => true
end
</pre>
(Note: '':Streaming'' only works with templates. It doesn’t work with :json or :xml)<ref>ActionController::Streaming http://apidock.com/rails/ActionController/Streaming</ref>
 
 

===Tweaking views===
When using streaming, instance variables that are set in the template and are used in the layout won't need some tweak to work well. This is done by using content_for, provide and yield.
Here’s a simple example where the layout expects the template to tell which title to use<ref>ActionController::Streaming http://apidock.com/rails/ActionController/Streaming</ref>:
<pre>
<html>
<head><title><%= yield :title %></title></head>
<body><%= yield %></body>
</html>
</pre>

Instead of yield, we can also use content_for to specify the title:
<pre>
<%= content_for :title, "Main" %>
Hello
</pre>

And the final result would be:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>

However, if content_for is called several times, the final result would have all calls concatenated.
For instance, if we have the following template:
<pre>
<%= content_for :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>

The final result would be:
<pre>
<html>
<head><title>Main page</title></head>
<body>Hello</body>
</html>
</pre>
This means that, if you have yield '':title'' in your layout and you want to use streaming, you would have to render the whole template (and eventually trigger all queries) before streaming the title and all assets, which kills the purpose of streaming. For this reason Rails 3.1 introduces a new helper called provide that does the same as content_for but tells the layout to stop searching for other entries and continue rendering.

For instance, the template above using provide would be:
<pre>
<%= provide :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>
Giving:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>
That said, when streaming, you need to properly check your templates and choose when to use provide and content_for.
 
 

==Live Streaming==
The module [http://api.rubyonrails.org/classes/ActionController/Live.html ''::Live''] was then added to ActionController at Rail 4. The difference between Streaming and Live is that Streaming is implicitly included whenever you create a new controller class, while ''::Live'' requires explicit include.

===Traditional Response===
In this type of communication between server and client, data will be buffered until all render works are finished, and everything will be sent to the client at the same time. And the stream object behaves just like an IO object. Here’s the sample code:
<pre>
class MessageController < ApplicationController
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a response message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>

When we run the code above, the web page will '''keep loading and remain blank''' for 8 seconds, and shows all 8 lines of “This is a response message!” altogether, as with the following image shows: 
[[File:nostreaming.gif]]

===Live Streaming===
In order to enable live streaming, we need to include a module named ''ActionController::Live''. When this module is mixed into the controller, all actions within that controller will be able to stream data to the client in real time, like the following code:
<pre>
class MessageController < ApplicationController
#here we enabled live streaming
include ActionController::Live
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a live streaming message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>
The above code looks exactly the same as the traditional response, except the newly included module ''ActionController::Live''. Now '''data can be streamed to the client immediately whenever write method is called'''. When we run the code above, the web page will print one line “This is a response message!” for every seconds and repeats 8 times.<ref>http://tenderlovemaking.com/2012/07/30/is-it-live.html</ref> Like the image shows below: 
[[File:streaming.gif]]
 
 

==Server-Sent Event==
[https://en.wikipedia.org/wiki/Server-sent_events Server-sent event (SSE)] is a technology where browser can automatically receive update data from a server via [https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol HTTP] connection. Whenever server sends data, the SSE method in the browser will trigger an event.The SSE EventSource API is standardized as part of [https://en.wikipedia.org/wiki/HTML5 HTML5] by the [https://en.wikipedia.org/wiki/World_Wide_Web_Consortium W3C]. It can be used together with the Live API to achieve full-duplex communication.<ref>https://en.wikipedia.org/wiki/Server-sent_events</ref>
 
A simple SSE looks like the following :
<pre>
require 'json'
module ServerSide
class SSE
def initialize io
@io = io
end

def write object, options = {}
options.each do |k,v|
@io.write "#{k}: #{v}n"
end
@io.write "data: #{object}nn"
end

def close
@io.close
end
end
end
</pre>
This module assigns the I/O stream object to a hash and converts it into a key-value pair so that it is easy to read, store, and send it back in [https://en.wikipedia.org/wiki/JSON JSON] format.
 
 
Now we can wrap stream object inside the SSE class. By doing this, we need to include SSE module inside the controller, so that the opening and closing of connections will be managed by SSE module. And we also add the ensure clause to make sure that the connection will always be closed after execution.
<pre>
require 'sse'
class MessagingController < ApplicationController
include ActionController::Live

def stream
response.headers['Content-Type'] = 'text/event-stream'
sse = SSE.new(response.stream)
begin
5.times {
sse.write(“Streaming using SSE!”)
sleep 1
}
ensure
sse.close
end
end
end
</pre>
The code above will print the sentence “Streaming using SSE!” once per second, until the loop ends.
 
 
Here’s another sample showing how to use SSE to stream data<ref>https://github.com/rails/rails/blob/6061c540ac7880233a6e32de85cec72c20ed8778/actionpack/lib/action_controller/metal/live.rb</ref>:

# This class provides the ability to write an SSE (Server Sent Event)
# to an IO stream. The class is initialized with a stream and can be used
# to either write a JSON string or an object which can be converted to JSON.
#
# Writing an object will convert it into standard SSE format with whatever
# options you have configured. You may choose to set the following options:
#
# 1) Event. If specified, an event with this name will be dispatched on
# the browser.
# 2) Retry. The reconnection time in milliseconds used when attempting
# to send the event.
# 3) Id. If the connection dies while sending an SSE to the browser, then
# the server will receive a +Last-Event-ID+ header with value equal to +id+.
#
# After setting an option in the constructor of the SSE object, all future
# SSEs sent across the stream will use those options unless overridden.
#
# Example Usage:
#
# class MyController < ActionController::Base
# include ActionController::Live
#
# def index
# response.headers['Content-Type'] = 'text/event-stream'
# sse = SSE.new(response.stream, retry: 300, event: "event-name")
# sse.write({ name: 'John'})
# sse.write({ name: 'John'}, id: 10)
# sse.write({ name: 'John'}, id: 10, event: "other-event")
# sse.write({ name: 'John'}, id: 10, event: "other-event", retry: 500)
# ensure
# sse.close
# end
# end
#
# Note: SSEs are not currently supported by IE. However, they are supported
# by Chrome, Firefox, Opera, and Safari.

Note: By default Rails provides a one-way communication process by writing the stream to the client when data is available. However, if we can add SSEs, we can enable events and responses, thus making it two-way.
 
 

==Benefit of live streaming==
1.Send partial responses to the client immediately.
 
2.Using Server-sent events, the ability to create chat clients, push notifications, and real-time feeds are available within Rails itself
 
3.Continuously inform the user about the progress.
See example below<ref>Why Rails 4 Live Streaming is a big deal, Hongli Lai http://blog.phusion.nl/2012/08/03/why-rails-4-live-streaming-is-a-big-deal/</ref>:
<pre>
def big_work
work = WorkModel.new
while !work.done?
work.do_some_calculations
response.stream.write "Progress: #{work.progress}%\n"
end
response.stream.close
end
</pre>
 

='''Troubleshooting'''=
When running streaming programs, we need to install [http://puma.io/ PUMA] to substitute the original [https://en.wikipedia.org/wiki/WEBrick WEBrick] server, because puma can handle concurrency better. In order to do this, we need to add the following line to Gemfile:
<pre>
gem 'puma'
</pre>
 
After installed puma, if we start rails server, the console will print the following output:
<pre>
"C:\Program Files (x86)\JetBrains\RubyMine 7.0.2\bin\runnerw.exe" C:\RailsInstaller\Ruby2.0.0\bin\ruby.exe -e $stdout.sync=true;$stderr.sync=true;load($0=ARGV.shift) D:/Cloud/Coding/RubymineProjects/LiveStreamingExample/bin/rails server -b 127.0.0.1 -p 3000 -e development
=> Booting Puma
=> Rails 4.1.8 application starting in development on http://127.0.0.1:3000
=> Run `rails server -h` for more startup options
=> Ctrl-C to shutdown server
Puma 2.11.0 starting...
* Min threads: 0, max threads: 16
* Environment: development
* Listening on tcp://127.0.0.1:3000
</pre>
This means that PUMA is set as our default server and successfully booted.
 
 
We encountered failure on Windows when trying to install PUMA, the console printed the following error:
<pre>
Building native extensions. This could take a while...
ERROR: Error installing rails:
ERROR: Failed to build gem native extension.

/Users/WillieTran/.rvm/rubies/ruby-2.0.0-p247/bin/ruby extconf.rb
*** extconf.rb failed ***

Could not create Makefile due to some reason, probably lack of necessary
libraries and/or headers. Check the mkmf.log file for more details. You may
need configuration options.
</pre>
 
To solve this problem, we need to install [https://www.openssl.org/ openssl] for windows. And then run the following command<ref>https://github.com/hicknhack-software/rails-disco/wiki/Installing-puma-on-windows</ref>:
<pre>
gem install puma -- --with-opt-dir=c:\openssl
</pre>
 

='''References'''=
<references>

CSC/ECE 517 Spring 2015/ch1a 12 LS

2015-02-16T03:18:07Z

Hwang40: /* When to use streaming */

Live Streaming

='''Introduction'''=
The purpose of live streaming is to send data over the Internet in real-time. This requires a data source, a data encoder, a media publisher and a proper network.

In Rails, the concept of streaming first appeared in [http://weblog.rubyonrails.org/releases/ version 3.1], and is further optimized in Rails 4. Now Rails 4 supports live streaming, which uses handling I/O object and can send data from server to client in real-time.

__TOC__

='''Details'''=
==Template streaming==
Since Rail 3.1, [http://api.rubyonrails.org/classes/ActionController/Streaming.html ''::Streaming''] module has been added to ActionController. For example, the loading progress in a traditional Rails client-side may look like this<ref>Template Streaming, George Ogata https://github.com/oggy/template_streaming</ref>:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:slow-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 1 progress without streaming</div>
This is because that layouts are rendered before the content, thus causing control flow to be altered to render the page in the order that the client needs (layout first).But for some resources which are static, if they could be loaded while waiting for the server response, a lot of time can be saved.
 
 
The module ''::Streaming'' inverts the regular Rails process of rendering the layout and template. Using ''::Streaming'', Rails will render template first and then layout. It will first run method yield and load up the template, and then renders the assets and layouts. In this way, the progress with streaming looks like this:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:fast-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 2 progress with streaming</div>

===When to use streaming===
For actions like new or edit, it may not be that necessary to use streaming. But for expensive actions like database query and generation of large amount of data, streaming can be extremely important and effective. Take the following action as an example:
<pre>
def storyboard
@stories = Story.all
@developers = Page.all
@comments = Comment.all
end
</pre>

Since most of the queries here are executing in the controller, it might take a while before them to finish, thus causing the front end (user) to wait for long. We can solve this problem and enhance user experience, the above code can be rewrite as follows,
<pre>
def storyboard
# Allow lazy execution of the queries
@stories = Story.all
@developers = Page.all
@comments = Comment.all
render :stream => true
end
</pre>
(Note: '':Streaming'' only works with templates. It doesn’t work with :json or :xml)<ref>ActionController::Streaming http://apidock.com/rails/ActionController/Streaming</ref>
 
 

===Tweaking views===
When using streaming, instance variables that are set in the template and are used in the layout won't need some tweak to work well. This is done by using content_for, provide and yield.
Here’s a simple example where the layout expects the template to tell which title to use<ref>http://apidock.com/rails/ActionController/Streaming</ref>:
<pre>
<html>
<head><title><%= yield :title %></title></head>
<body><%= yield %></body>
</html>
</pre>

Instead of yield, we can also use content_for to specify the title:
<pre>
<%= content_for :title, "Main" %>
Hello
</pre>

And the final result would be:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>

However, if content_for is called several times, the final result would have all calls concatenated.
For instance, if we have the following template:
<pre>
<%= content_for :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>

The final result would be:
<pre>
<html>
<head><title>Main page</title></head>
<body>Hello</body>
</html>
</pre>
This means that, if you have yield '':title'' in your layout and you want to use streaming, you would have to render the whole template (and eventually trigger all queries) before streaming the title and all assets, which kills the purpose of streaming. For this reason Rails 3.1 introduces a new helper called provide that does the same as content_for but tells the layout to stop searching for other entries and continue rendering.

For instance, the template above using provide would be:
<pre>
<%= provide :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>
Giving:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>
That said, when streaming, you need to properly check your templates and choose when to use provide and content_for.
 
 

==Live Streaming==
The module [http://api.rubyonrails.org/classes/ActionController/Live.html ''::Live''] was then added to ActionController at Rail 4. The difference between Streaming and Live is that Streaming is implicitly included whenever you create a new controller class, while ''::Live'' requires explicit include.

===Traditional Response===
In this type of communication between server and client, data will be buffered until all render works are finished, and everything will be sent to the client at the same time. And the stream object behaves just like an IO object. Here’s the sample code:
<pre>
class MessageController < ApplicationController
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a response message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>

When we run the code above, the web page will '''keep loading and remain blank''' for 8 seconds, and shows all 8 lines of “This is a response message!” altogether, as with the following image shows: 
[[File:nostreaming.gif]]

===Live Streaming===
In order to enable live streaming, we need to include a module named ''ActionController::Live''. When this module is mixed into the controller, all actions within that controller will be able to stream data to the client in real time, like the following code:
<pre>
class MessageController < ApplicationController
#here we enabled live streaming
include ActionController::Live
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a live streaming message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>
The above code looks exactly the same as the traditional response, except the newly included module ''ActionController::Live''. Now '''data can be streamed to the client immediately whenever write method is called'''. When we run the code above, the web page will print one line “This is a response message!” for every seconds and repeats 8 times.<ref>http://tenderlovemaking.com/2012/07/30/is-it-live.html</ref> Like the image shows below: 
[[File:streaming.gif]]
 
 

==Server-Sent Event==
[https://en.wikipedia.org/wiki/Server-sent_events Server-sent event (SSE)] is a technology where browser can automatically receive update data from a server via [https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol HTTP] connection. Whenever server sends data, the SSE method in the browser will trigger an event.The SSE EventSource API is standardized as part of [https://en.wikipedia.org/wiki/HTML5 HTML5] by the [https://en.wikipedia.org/wiki/World_Wide_Web_Consortium W3C]. It can be used together with the Live API to achieve full-duplex communication.<ref>https://en.wikipedia.org/wiki/Server-sent_events</ref>
 
A simple SSE looks like the following :
<pre>
require 'json'
module ServerSide
class SSE
def initialize io
@io = io
end

def write object, options = {}
options.each do |k,v|
@io.write "#{k}: #{v}n"
end
@io.write "data: #{object}nn"
end

def close
@io.close
end
end
end
</pre>
This module assigns the I/O stream object to a hash and converts it into a key-value pair so that it is easy to read, store, and send it back in [https://en.wikipedia.org/wiki/JSON JSON] format.
 
 
Now we can wrap stream object inside the SSE class. By doing this, we need to include SSE module inside the controller, so that the opening and closing of connections will be managed by SSE module. And we also add the ensure clause to make sure that the connection will always be closed after execution.
<pre>
require 'sse'
class MessagingController < ApplicationController
include ActionController::Live

def stream
response.headers['Content-Type'] = 'text/event-stream'
sse = SSE.new(response.stream)
begin
5.times {
sse.write(“Streaming using SSE!”)
sleep 1
}
ensure
sse.close
end
end
end
</pre>
The code above will print the sentence “Streaming using SSE!” once per second, until the loop ends.
 
 
Here’s another sample showing how to use SSE to stream data<ref>https://github.com/rails/rails/blob/6061c540ac7880233a6e32de85cec72c20ed8778/actionpack/lib/action_controller/metal/live.rb</ref>:

# This class provides the ability to write an SSE (Server Sent Event)
# to an IO stream. The class is initialized with a stream and can be used
# to either write a JSON string or an object which can be converted to JSON.
#
# Writing an object will convert it into standard SSE format with whatever
# options you have configured. You may choose to set the following options:
#
# 1) Event. If specified, an event with this name will be dispatched on
# the browser.
# 2) Retry. The reconnection time in milliseconds used when attempting
# to send the event.
# 3) Id. If the connection dies while sending an SSE to the browser, then
# the server will receive a +Last-Event-ID+ header with value equal to +id+.
#
# After setting an option in the constructor of the SSE object, all future
# SSEs sent across the stream will use those options unless overridden.
#
# Example Usage:
#
# class MyController < ActionController::Base
# include ActionController::Live
#
# def index
# response.headers['Content-Type'] = 'text/event-stream'
# sse = SSE.new(response.stream, retry: 300, event: "event-name")
# sse.write({ name: 'John'})
# sse.write({ name: 'John'}, id: 10)
# sse.write({ name: 'John'}, id: 10, event: "other-event")
# sse.write({ name: 'John'}, id: 10, event: "other-event", retry: 500)
# ensure
# sse.close
# end
# end
#
# Note: SSEs are not currently supported by IE. However, they are supported
# by Chrome, Firefox, Opera, and Safari.

Note: By default Rails provides a one-way communication process by writing the stream to the client when data is available. However, if we can add SSEs, we can enable events and responses, thus making it two-way.
 
 

==Benefit of live streaming==
1.Send partial responses to the client immediately.
 
2.Using Server-sent events, the ability to create chat clients, push notifications, and real-time feeds are available within Rails itself
 
3.Continuously inform the user about the progress.
See example below<ref>Why Rails 4 Live Streaming is a big deal, Hongli Lai http://blog.phusion.nl/2012/08/03/why-rails-4-live-streaming-is-a-big-deal/</ref>:
<pre>
def big_work
work = WorkModel.new
while !work.done?
work.do_some_calculations
response.stream.write "Progress: #{work.progress}%\n"
end
response.stream.close
end
</pre>
 

='''Troubleshooting'''=
When running streaming programs, we need to install [http://puma.io/ PUMA] to substitute the original [https://en.wikipedia.org/wiki/WEBrick WEBrick] server, because puma can handle concurrency better. In order to do this, we need to add the following line to Gemfile:
<pre>
gem 'puma'
</pre>
 
After installed puma, if we start rails server, the console will print the following output:
<pre>
"C:\Program Files (x86)\JetBrains\RubyMine 7.0.2\bin\runnerw.exe" C:\RailsInstaller\Ruby2.0.0\bin\ruby.exe -e $stdout.sync=true;$stderr.sync=true;load($0=ARGV.shift) D:/Cloud/Coding/RubymineProjects/LiveStreamingExample/bin/rails server -b 127.0.0.1 -p 3000 -e development
=> Booting Puma
=> Rails 4.1.8 application starting in development on http://127.0.0.1:3000
=> Run `rails server -h` for more startup options
=> Ctrl-C to shutdown server
Puma 2.11.0 starting...
* Min threads: 0, max threads: 16
* Environment: development
* Listening on tcp://127.0.0.1:3000
</pre>
This means that PUMA is set as our default server and successfully booted.
 
 
We encountered failure on Windows when trying to install PUMA, the console printed the following error:
<pre>
Building native extensions. This could take a while...
ERROR: Error installing rails:
ERROR: Failed to build gem native extension.

/Users/WillieTran/.rvm/rubies/ruby-2.0.0-p247/bin/ruby extconf.rb
*** extconf.rb failed ***

Could not create Makefile due to some reason, probably lack of necessary
libraries and/or headers. Check the mkmf.log file for more details. You may
need configuration options.
</pre>
 
To solve this problem, we need to install [https://www.openssl.org/ openssl] for windows. And then run the following command<ref>https://github.com/hicknhack-software/rails-disco/wiki/Installing-puma-on-windows</ref>:
<pre>
gem install puma -- --with-opt-dir=c:\openssl
</pre>
 

='''References'''=
<references>

CSC/ECE 517 Spring 2015/ch1a 12 LS

2015-02-16T03:17:08Z

Hwang40: /* Benefit of live streaming */

Live Streaming

='''Introduction'''=
The purpose of live streaming is to send data over the Internet in real-time. This requires a data source, a data encoder, a media publisher and a proper network.

In Rails, the concept of streaming first appeared in [http://weblog.rubyonrails.org/releases/ version 3.1], and is further optimized in Rails 4. Now Rails 4 supports live streaming, which uses handling I/O object and can send data from server to client in real-time.

__TOC__

='''Details'''=
==Template streaming==
Since Rail 3.1, [http://api.rubyonrails.org/classes/ActionController/Streaming.html ''::Streaming''] module has been added to ActionController. For example, the loading progress in a traditional Rails client-side may look like this<ref>Template Streaming, George Ogata https://github.com/oggy/template_streaming</ref>:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:slow-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 1 progress without streaming</div>
This is because that layouts are rendered before the content, thus causing control flow to be altered to render the page in the order that the client needs (layout first).But for some resources which are static, if they could be loaded while waiting for the server response, a lot of time can be saved.
 
 
The module ''::Streaming'' inverts the regular Rails process of rendering the layout and template. Using ''::Streaming'', Rails will render template first and then layout. It will first run method yield and load up the template, and then renders the assets and layouts. In this way, the progress with streaming looks like this:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:fast-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 2 progress with streaming</div>

===When to use streaming===
For actions like new or edit, it may not be that necessary to use streaming. But for expensive actions like database query and generation of large amount of data, streaming can be extremely important and effective. Take the following action as an example:
<pre>
def storyboard
@stories = Story.all
@developers = Page.all
@comments = Comment.all
end
</pre>

Since most of the queries here are executing in the controller, it might take a while before them to finish, thus causing the front end (user) to wait for long. We can solve this problem and enhance user experience, the above code can be rewrite as follows,
<pre>
def storyboard
# Allow lazy execution of the queries
@stories = Story.all
@developers = Page.all
@comments = Comment.all
render :stream => true
end
</pre>
(Note: '':Streaming'' only works with templates. It doesn’t work with :json or :xml)<ref>http://apidock.com/rails/ActionController/Streaming</ref>
 
 

===Tweaking views===
When using streaming, instance variables that are set in the template and are used in the layout won't need some tweak to work well. This is done by using content_for, provide and yield.
Here’s a simple example where the layout expects the template to tell which title to use<ref>http://apidock.com/rails/ActionController/Streaming</ref>:
<pre>
<html>
<head><title><%= yield :title %></title></head>
<body><%= yield %></body>
</html>
</pre>

Instead of yield, we can also use content_for to specify the title:
<pre>
<%= content_for :title, "Main" %>
Hello
</pre>

And the final result would be:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>

However, if content_for is called several times, the final result would have all calls concatenated.
For instance, if we have the following template:
<pre>
<%= content_for :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>

The final result would be:
<pre>
<html>
<head><title>Main page</title></head>
<body>Hello</body>
</html>
</pre>
This means that, if you have yield '':title'' in your layout and you want to use streaming, you would have to render the whole template (and eventually trigger all queries) before streaming the title and all assets, which kills the purpose of streaming. For this reason Rails 3.1 introduces a new helper called provide that does the same as content_for but tells the layout to stop searching for other entries and continue rendering.

For instance, the template above using provide would be:
<pre>
<%= provide :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>
Giving:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>
That said, when streaming, you need to properly check your templates and choose when to use provide and content_for.
 
 

==Live Streaming==
The module [http://api.rubyonrails.org/classes/ActionController/Live.html ''::Live''] was then added to ActionController at Rail 4. The difference between Streaming and Live is that Streaming is implicitly included whenever you create a new controller class, while ''::Live'' requires explicit include.

===Traditional Response===
In this type of communication between server and client, data will be buffered until all render works are finished, and everything will be sent to the client at the same time. And the stream object behaves just like an IO object. Here’s the sample code:
<pre>
class MessageController < ApplicationController
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a response message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>

When we run the code above, the web page will '''keep loading and remain blank''' for 8 seconds, and shows all 8 lines of “This is a response message!” altogether, as with the following image shows: 
[[File:nostreaming.gif]]

===Live Streaming===
In order to enable live streaming, we need to include a module named ''ActionController::Live''. When this module is mixed into the controller, all actions within that controller will be able to stream data to the client in real time, like the following code:
<pre>
class MessageController < ApplicationController
#here we enabled live streaming
include ActionController::Live
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a live streaming message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>
The above code looks exactly the same as the traditional response, except the newly included module ''ActionController::Live''. Now '''data can be streamed to the client immediately whenever write method is called'''. When we run the code above, the web page will print one line “This is a response message!” for every seconds and repeats 8 times.<ref>http://tenderlovemaking.com/2012/07/30/is-it-live.html</ref> Like the image shows below: 
[[File:streaming.gif]]
 
 

==Server-Sent Event==
[https://en.wikipedia.org/wiki/Server-sent_events Server-sent event (SSE)] is a technology where browser can automatically receive update data from a server via [https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol HTTP] connection. Whenever server sends data, the SSE method in the browser will trigger an event.The SSE EventSource API is standardized as part of [https://en.wikipedia.org/wiki/HTML5 HTML5] by the [https://en.wikipedia.org/wiki/World_Wide_Web_Consortium W3C]. It can be used together with the Live API to achieve full-duplex communication.<ref>https://en.wikipedia.org/wiki/Server-sent_events</ref>
 
A simple SSE looks like the following :
<pre>
require 'json'
module ServerSide
class SSE
def initialize io
@io = io
end

def write object, options = {}
options.each do |k,v|
@io.write "#{k}: #{v}n"
end
@io.write "data: #{object}nn"
end

def close
@io.close
end
end
end
</pre>
This module assigns the I/O stream object to a hash and converts it into a key-value pair so that it is easy to read, store, and send it back in [https://en.wikipedia.org/wiki/JSON JSON] format.
 
 
Now we can wrap stream object inside the SSE class. By doing this, we need to include SSE module inside the controller, so that the opening and closing of connections will be managed by SSE module. And we also add the ensure clause to make sure that the connection will always be closed after execution.
<pre>
require 'sse'
class MessagingController < ApplicationController
include ActionController::Live

def stream
response.headers['Content-Type'] = 'text/event-stream'
sse = SSE.new(response.stream)
begin
5.times {
sse.write(“Streaming using SSE!”)
sleep 1
}
ensure
sse.close
end
end
end
</pre>
The code above will print the sentence “Streaming using SSE!” once per second, until the loop ends.
 
 
Here’s another sample showing how to use SSE to stream data<ref>https://github.com/rails/rails/blob/6061c540ac7880233a6e32de85cec72c20ed8778/actionpack/lib/action_controller/metal/live.rb</ref>:

# This class provides the ability to write an SSE (Server Sent Event)
# to an IO stream. The class is initialized with a stream and can be used
# to either write a JSON string or an object which can be converted to JSON.
#
# Writing an object will convert it into standard SSE format with whatever
# options you have configured. You may choose to set the following options:
#
# 1) Event. If specified, an event with this name will be dispatched on
# the browser.
# 2) Retry. The reconnection time in milliseconds used when attempting
# to send the event.
# 3) Id. If the connection dies while sending an SSE to the browser, then
# the server will receive a +Last-Event-ID+ header with value equal to +id+.
#
# After setting an option in the constructor of the SSE object, all future
# SSEs sent across the stream will use those options unless overridden.
#
# Example Usage:
#
# class MyController < ActionController::Base
# include ActionController::Live
#
# def index
# response.headers['Content-Type'] = 'text/event-stream'
# sse = SSE.new(response.stream, retry: 300, event: "event-name")
# sse.write({ name: 'John'})
# sse.write({ name: 'John'}, id: 10)
# sse.write({ name: 'John'}, id: 10, event: "other-event")
# sse.write({ name: 'John'}, id: 10, event: "other-event", retry: 500)
# ensure
# sse.close
# end
# end
#
# Note: SSEs are not currently supported by IE. However, they are supported
# by Chrome, Firefox, Opera, and Safari.

Note: By default Rails provides a one-way communication process by writing the stream to the client when data is available. However, if we can add SSEs, we can enable events and responses, thus making it two-way.
 
 

==Benefit of live streaming==
1.Send partial responses to the client immediately.
 
2.Using Server-sent events, the ability to create chat clients, push notifications, and real-time feeds are available within Rails itself
 
3.Continuously inform the user about the progress.
See example below<ref>Why Rails 4 Live Streaming is a big deal, Hongli Lai http://blog.phusion.nl/2012/08/03/why-rails-4-live-streaming-is-a-big-deal/</ref>:
<pre>
def big_work
work = WorkModel.new
while !work.done?
work.do_some_calculations
response.stream.write "Progress: #{work.progress}%\n"
end
response.stream.close
end
</pre>
 

='''Troubleshooting'''=
When running streaming programs, we need to install [http://puma.io/ PUMA] to substitute the original [https://en.wikipedia.org/wiki/WEBrick WEBrick] server, because puma can handle concurrency better. In order to do this, we need to add the following line to Gemfile:
<pre>
gem 'puma'
</pre>
 
After installed puma, if we start rails server, the console will print the following output:
<pre>
"C:\Program Files (x86)\JetBrains\RubyMine 7.0.2\bin\runnerw.exe" C:\RailsInstaller\Ruby2.0.0\bin\ruby.exe -e $stdout.sync=true;$stderr.sync=true;load($0=ARGV.shift) D:/Cloud/Coding/RubymineProjects/LiveStreamingExample/bin/rails server -b 127.0.0.1 -p 3000 -e development
=> Booting Puma
=> Rails 4.1.8 application starting in development on http://127.0.0.1:3000
=> Run `rails server -h` for more startup options
=> Ctrl-C to shutdown server
Puma 2.11.0 starting...
* Min threads: 0, max threads: 16
* Environment: development
* Listening on tcp://127.0.0.1:3000
</pre>
This means that PUMA is set as our default server and successfully booted.
 
 
We encountered failure on Windows when trying to install PUMA, the console printed the following error:
<pre>
Building native extensions. This could take a while...
ERROR: Error installing rails:
ERROR: Failed to build gem native extension.

/Users/WillieTran/.rvm/rubies/ruby-2.0.0-p247/bin/ruby extconf.rb
*** extconf.rb failed ***

Could not create Makefile due to some reason, probably lack of necessary
libraries and/or headers. Check the mkmf.log file for more details. You may
need configuration options.
</pre>
 
To solve this problem, we need to install [https://www.openssl.org/ openssl] for windows. And then run the following command<ref>https://github.com/hicknhack-software/rails-disco/wiki/Installing-puma-on-windows</ref>:
<pre>
gem install puma -- --with-opt-dir=c:\openssl
</pre>
 

='''References'''=
<references>

CSC/ECE 517 Spring 2015/ch1a 12 LS

2015-02-16T03:16:01Z

Hwang40: /* Template streaming */

Live Streaming

='''Introduction'''=
The purpose of live streaming is to send data over the Internet in real-time. This requires a data source, a data encoder, a media publisher and a proper network.

In Rails, the concept of streaming first appeared in [http://weblog.rubyonrails.org/releases/ version 3.1], and is further optimized in Rails 4. Now Rails 4 supports live streaming, which uses handling I/O object and can send data from server to client in real-time.

__TOC__

='''Details'''=
==Template streaming==
Since Rail 3.1, [http://api.rubyonrails.org/classes/ActionController/Streaming.html ''::Streaming''] module has been added to ActionController. For example, the loading progress in a traditional Rails client-side may look like this<ref>Template Streaming, George Ogata https://github.com/oggy/template_streaming</ref>:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:slow-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 1 progress without streaming</div>
This is because that layouts are rendered before the content, thus causing control flow to be altered to render the page in the order that the client needs (layout first).But for some resources which are static, if they could be loaded while waiting for the server response, a lot of time can be saved.
 
 
The module ''::Streaming'' inverts the regular Rails process of rendering the layout and template. Using ''::Streaming'', Rails will render template first and then layout. It will first run method yield and load up the template, and then renders the assets and layouts. In this way, the progress with streaming looks like this:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:fast-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 2 progress with streaming</div>

===When to use streaming===
For actions like new or edit, it may not be that necessary to use streaming. But for expensive actions like database query and generation of large amount of data, streaming can be extremely important and effective. Take the following action as an example:
<pre>
def storyboard
@stories = Story.all
@developers = Page.all
@comments = Comment.all
end
</pre>

Since most of the queries here are executing in the controller, it might take a while before them to finish, thus causing the front end (user) to wait for long. We can solve this problem and enhance user experience, the above code can be rewrite as follows,
<pre>
def storyboard
# Allow lazy execution of the queries
@stories = Story.all
@developers = Page.all
@comments = Comment.all
render :stream => true
end
</pre>
(Note: '':Streaming'' only works with templates. It doesn’t work with :json or :xml)<ref>http://apidock.com/rails/ActionController/Streaming</ref>
 
 

===Tweaking views===
When using streaming, instance variables that are set in the template and are used in the layout won't need some tweak to work well. This is done by using content_for, provide and yield.
Here’s a simple example where the layout expects the template to tell which title to use<ref>http://apidock.com/rails/ActionController/Streaming</ref>:
<pre>
<html>
<head><title><%= yield :title %></title></head>
<body><%= yield %></body>
</html>
</pre>

Instead of yield, we can also use content_for to specify the title:
<pre>
<%= content_for :title, "Main" %>
Hello
</pre>

And the final result would be:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>

However, if content_for is called several times, the final result would have all calls concatenated.
For instance, if we have the following template:
<pre>
<%= content_for :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>

The final result would be:
<pre>
<html>
<head><title>Main page</title></head>
<body>Hello</body>
</html>
</pre>
This means that, if you have yield '':title'' in your layout and you want to use streaming, you would have to render the whole template (and eventually trigger all queries) before streaming the title and all assets, which kills the purpose of streaming. For this reason Rails 3.1 introduces a new helper called provide that does the same as content_for but tells the layout to stop searching for other entries and continue rendering.

For instance, the template above using provide would be:
<pre>
<%= provide :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>
Giving:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>
That said, when streaming, you need to properly check your templates and choose when to use provide and content_for.
 
 

==Live Streaming==
The module [http://api.rubyonrails.org/classes/ActionController/Live.html ''::Live''] was then added to ActionController at Rail 4. The difference between Streaming and Live is that Streaming is implicitly included whenever you create a new controller class, while ''::Live'' requires explicit include.

===Traditional Response===
In this type of communication between server and client, data will be buffered until all render works are finished, and everything will be sent to the client at the same time. And the stream object behaves just like an IO object. Here’s the sample code:
<pre>
class MessageController < ApplicationController
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a response message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>

When we run the code above, the web page will '''keep loading and remain blank''' for 8 seconds, and shows all 8 lines of “This is a response message!” altogether, as with the following image shows: 
[[File:nostreaming.gif]]

===Live Streaming===
In order to enable live streaming, we need to include a module named ''ActionController::Live''. When this module is mixed into the controller, all actions within that controller will be able to stream data to the client in real time, like the following code:
<pre>
class MessageController < ApplicationController
#here we enabled live streaming
include ActionController::Live
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a live streaming message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>
The above code looks exactly the same as the traditional response, except the newly included module ''ActionController::Live''. Now '''data can be streamed to the client immediately whenever write method is called'''. When we run the code above, the web page will print one line “This is a response message!” for every seconds and repeats 8 times.<ref>http://tenderlovemaking.com/2012/07/30/is-it-live.html</ref> Like the image shows below: 
[[File:streaming.gif]]
 
 

==Server-Sent Event==
[https://en.wikipedia.org/wiki/Server-sent_events Server-sent event (SSE)] is a technology where browser can automatically receive update data from a server via [https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol HTTP] connection. Whenever server sends data, the SSE method in the browser will trigger an event.The SSE EventSource API is standardized as part of [https://en.wikipedia.org/wiki/HTML5 HTML5] by the [https://en.wikipedia.org/wiki/World_Wide_Web_Consortium W3C]. It can be used together with the Live API to achieve full-duplex communication.<ref>https://en.wikipedia.org/wiki/Server-sent_events</ref>
 
A simple SSE looks like the following :
<pre>
require 'json'
module ServerSide
class SSE
def initialize io
@io = io
end

def write object, options = {}
options.each do |k,v|
@io.write "#{k}: #{v}n"
end
@io.write "data: #{object}nn"
end

def close
@io.close
end
end
end
</pre>
This module assigns the I/O stream object to a hash and converts it into a key-value pair so that it is easy to read, store, and send it back in [https://en.wikipedia.org/wiki/JSON JSON] format.
 
 
Now we can wrap stream object inside the SSE class. By doing this, we need to include SSE module inside the controller, so that the opening and closing of connections will be managed by SSE module. And we also add the ensure clause to make sure that the connection will always be closed after execution.
<pre>
require 'sse'
class MessagingController < ApplicationController
include ActionController::Live

def stream
response.headers['Content-Type'] = 'text/event-stream'
sse = SSE.new(response.stream)
begin
5.times {
sse.write(“Streaming using SSE!”)
sleep 1
}
ensure
sse.close
end
end
end
</pre>
The code above will print the sentence “Streaming using SSE!” once per second, until the loop ends.
 
 
Here’s another sample showing how to use SSE to stream data<ref>https://github.com/rails/rails/blob/6061c540ac7880233a6e32de85cec72c20ed8778/actionpack/lib/action_controller/metal/live.rb</ref>:

# This class provides the ability to write an SSE (Server Sent Event)
# to an IO stream. The class is initialized with a stream and can be used
# to either write a JSON string or an object which can be converted to JSON.
#
# Writing an object will convert it into standard SSE format with whatever
# options you have configured. You may choose to set the following options:
#
# 1) Event. If specified, an event with this name will be dispatched on
# the browser.
# 2) Retry. The reconnection time in milliseconds used when attempting
# to send the event.
# 3) Id. If the connection dies while sending an SSE to the browser, then
# the server will receive a +Last-Event-ID+ header with value equal to +id+.
#
# After setting an option in the constructor of the SSE object, all future
# SSEs sent across the stream will use those options unless overridden.
#
# Example Usage:
#
# class MyController < ActionController::Base
# include ActionController::Live
#
# def index
# response.headers['Content-Type'] = 'text/event-stream'
# sse = SSE.new(response.stream, retry: 300, event: "event-name")
# sse.write({ name: 'John'})
# sse.write({ name: 'John'}, id: 10)
# sse.write({ name: 'John'}, id: 10, event: "other-event")
# sse.write({ name: 'John'}, id: 10, event: "other-event", retry: 500)
# ensure
# sse.close
# end
# end
#
# Note: SSEs are not currently supported by IE. However, they are supported
# by Chrome, Firefox, Opera, and Safari.

Note: By default Rails provides a one-way communication process by writing the stream to the client when data is available. However, if we can add SSEs, we can enable events and responses, thus making it two-way.
 
 

==Benefit of live streaming==
1.Send partial responses to the client immediately.
 
2.Using Server-sent events, the ability to create chat clients, push notifications, and real-time feeds are available within Rails itself
 
3.Continuously inform the user about the progress.
See example below<ref>Why Rails 4 Live Streaming is a big deal, Hongli Lai, August 3rd, 2012 http://blog.phusion.nl/2012/08/03/why-rails-4-live-streaming-is-a-big-deal/</ref>:
<pre>
def big_work
work = WorkModel.new
while !work.done?
work.do_some_calculations
response.stream.write "Progress: #{work.progress}%\n"
end
response.stream.close
end
</pre>
 

='''Troubleshooting'''=
When running streaming programs, we need to install [http://puma.io/ PUMA] to substitute the original [https://en.wikipedia.org/wiki/WEBrick WEBrick] server, because puma can handle concurrency better. In order to do this, we need to add the following line to Gemfile:
<pre>
gem 'puma'
</pre>
 
After installed puma, if we start rails server, the console will print the following output:
<pre>
"C:\Program Files (x86)\JetBrains\RubyMine 7.0.2\bin\runnerw.exe" C:\RailsInstaller\Ruby2.0.0\bin\ruby.exe -e $stdout.sync=true;$stderr.sync=true;load($0=ARGV.shift) D:/Cloud/Coding/RubymineProjects/LiveStreamingExample/bin/rails server -b 127.0.0.1 -p 3000 -e development
=> Booting Puma
=> Rails 4.1.8 application starting in development on http://127.0.0.1:3000
=> Run `rails server -h` for more startup options
=> Ctrl-C to shutdown server
Puma 2.11.0 starting...
* Min threads: 0, max threads: 16
* Environment: development
* Listening on tcp://127.0.0.1:3000
</pre>
This means that PUMA is set as our default server and successfully booted.
 
 
We encountered failure on Windows when trying to install PUMA, the console printed the following error:
<pre>
Building native extensions. This could take a while...
ERROR: Error installing rails:
ERROR: Failed to build gem native extension.

/Users/WillieTran/.rvm/rubies/ruby-2.0.0-p247/bin/ruby extconf.rb
*** extconf.rb failed ***

Could not create Makefile due to some reason, probably lack of necessary
libraries and/or headers. Check the mkmf.log file for more details. You may
need configuration options.
</pre>
 
To solve this problem, we need to install [https://www.openssl.org/ openssl] for windows. And then run the following command<ref>https://github.com/hicknhack-software/rails-disco/wiki/Installing-puma-on-windows</ref>:
<pre>
gem install puma -- --with-opt-dir=c:\openssl
</pre>
 

='''References'''=
<references>

CSC/ECE 517 Spring 2015/ch1a 12 LS

2015-02-16T03:13:42Z

Hwang40: /* Benefit of live streaming */

Live Streaming

='''Introduction'''=
The purpose of live streaming is to send data over the Internet in real-time. This requires a data source, a data encoder, a media publisher and a proper network.

In Rails, the concept of streaming first appeared in [http://weblog.rubyonrails.org/releases/ version 3.1], and is further optimized in Rails 4. Now Rails 4 supports live streaming, which uses handling I/O object and can send data from server to client in real-time.

__TOC__

='''Details'''=
==Template streaming==
Since Rail 3.1, [http://api.rubyonrails.org/classes/ActionController/Streaming.html ''::Streaming''] module has been added to ActionController. For example, the loading progress in a traditional Rails client-side may look like this<ref> https://github.com/oggy/template_streaming</ref>:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:slow-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 1 progress without streaming</div>
This is because that layouts are rendered before the content, thus causing control flow to be altered to render the page in the order that the client needs (layout first).But for some resources which are static, if they could be loaded while waiting for the server response, a lot of time can be saved.
 
 
The module ''::Streaming'' inverts the regular Rails process of rendering the layout and template. Using ''::Streaming'', Rails will render template first and then layout. It will first run method yield and load up the template, and then renders the assets and layouts. In this way, the progress with streaming looks like this:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:fast-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 2 progress with streaming</div>

===When to use streaming===
For actions like new or edit, it may not be that necessary to use streaming. But for expensive actions like database query and generation of large amount of data, streaming can be extremely important and effective. Take the following action as an example:
<pre>
def storyboard
@stories = Story.all
@developers = Page.all
@comments = Comment.all
end
</pre>

Since most of the queries here are executing in the controller, it might take a while before them to finish, thus causing the front end (user) to wait for long. We can solve this problem and enhance user experience, the above code can be rewrite as follows,
<pre>
def storyboard
# Allow lazy execution of the queries
@stories = Story.all
@developers = Page.all
@comments = Comment.all
render :stream => true
end
</pre>
(Note: '':Streaming'' only works with templates. It doesn’t work with :json or :xml)<ref>http://apidock.com/rails/ActionController/Streaming</ref>
 
 

===Tweaking views===
When using streaming, instance variables that are set in the template and are used in the layout won't need some tweak to work well. This is done by using content_for, provide and yield.
Here’s a simple example where the layout expects the template to tell which title to use<ref>http://apidock.com/rails/ActionController/Streaming</ref>:
<pre>
<html>
<head><title><%= yield :title %></title></head>
<body><%= yield %></body>
</html>
</pre>

Instead of yield, we can also use content_for to specify the title:
<pre>
<%= content_for :title, "Main" %>
Hello
</pre>

And the final result would be:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>

However, if content_for is called several times, the final result would have all calls concatenated.
For instance, if we have the following template:
<pre>
<%= content_for :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>

The final result would be:
<pre>
<html>
<head><title>Main page</title></head>
<body>Hello</body>
</html>
</pre>
This means that, if you have yield '':title'' in your layout and you want to use streaming, you would have to render the whole template (and eventually trigger all queries) before streaming the title and all assets, which kills the purpose of streaming. For this reason Rails 3.1 introduces a new helper called provide that does the same as content_for but tells the layout to stop searching for other entries and continue rendering.

For instance, the template above using provide would be:
<pre>
<%= provide :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>
Giving:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>
That said, when streaming, you need to properly check your templates and choose when to use provide and content_for.
 
 

==Live Streaming==
The module [http://api.rubyonrails.org/classes/ActionController/Live.html ''::Live''] was then added to ActionController at Rail 4. The difference between Streaming and Live is that Streaming is implicitly included whenever you create a new controller class, while ''::Live'' requires explicit include.

===Traditional Response===
In this type of communication between server and client, data will be buffered until all render works are finished, and everything will be sent to the client at the same time. And the stream object behaves just like an IO object. Here’s the sample code:
<pre>
class MessageController < ApplicationController
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a response message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>

When we run the code above, the web page will '''keep loading and remain blank''' for 8 seconds, and shows all 8 lines of “This is a response message!” altogether, as with the following image shows: 
[[File:nostreaming.gif]]

===Live Streaming===
In order to enable live streaming, we need to include a module named ''ActionController::Live''. When this module is mixed into the controller, all actions within that controller will be able to stream data to the client in real time, like the following code:
<pre>
class MessageController < ApplicationController
#here we enabled live streaming
include ActionController::Live
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a live streaming message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>
The above code looks exactly the same as the traditional response, except the newly included module ''ActionController::Live''. Now '''data can be streamed to the client immediately whenever write method is called'''. When we run the code above, the web page will print one line “This is a response message!” for every seconds and repeats 8 times.<ref>http://tenderlovemaking.com/2012/07/30/is-it-live.html</ref> Like the image shows below: 
[[File:streaming.gif]]
 
 

==Server-Sent Event==
[https://en.wikipedia.org/wiki/Server-sent_events Server-sent event (SSE)] is a technology where browser can automatically receive update data from a server via [https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol HTTP] connection. Whenever server sends data, the SSE method in the browser will trigger an event.The SSE EventSource API is standardized as part of [https://en.wikipedia.org/wiki/HTML5 HTML5] by the [https://en.wikipedia.org/wiki/World_Wide_Web_Consortium W3C]. It can be used together with the Live API to achieve full-duplex communication.<ref>https://en.wikipedia.org/wiki/Server-sent_events</ref>
 
A simple SSE looks like the following :
<pre>
require 'json'
module ServerSide
class SSE
def initialize io
@io = io
end

def write object, options = {}
options.each do |k,v|
@io.write "#{k}: #{v}n"
end
@io.write "data: #{object}nn"
end

def close
@io.close
end
end
end
</pre>
This module assigns the I/O stream object to a hash and converts it into a key-value pair so that it is easy to read, store, and send it back in [https://en.wikipedia.org/wiki/JSON JSON] format.
 
 
Now we can wrap stream object inside the SSE class. By doing this, we need to include SSE module inside the controller, so that the opening and closing of connections will be managed by SSE module. And we also add the ensure clause to make sure that the connection will always be closed after execution.
<pre>
require 'sse'
class MessagingController < ApplicationController
include ActionController::Live

def stream
response.headers['Content-Type'] = 'text/event-stream'
sse = SSE.new(response.stream)
begin
5.times {
sse.write(“Streaming using SSE!”)
sleep 1
}
ensure
sse.close
end
end
end
</pre>
The code above will print the sentence “Streaming using SSE!” once per second, until the loop ends.
 
 
Here’s another sample showing how to use SSE to stream data<ref>https://github.com/rails/rails/blob/6061c540ac7880233a6e32de85cec72c20ed8778/actionpack/lib/action_controller/metal/live.rb</ref>:

# This class provides the ability to write an SSE (Server Sent Event)
# to an IO stream. The class is initialized with a stream and can be used
# to either write a JSON string or an object which can be converted to JSON.
#
# Writing an object will convert it into standard SSE format with whatever
# options you have configured. You may choose to set the following options:
#
# 1) Event. If specified, an event with this name will be dispatched on
# the browser.
# 2) Retry. The reconnection time in milliseconds used when attempting
# to send the event.
# 3) Id. If the connection dies while sending an SSE to the browser, then
# the server will receive a +Last-Event-ID+ header with value equal to +id+.
#
# After setting an option in the constructor of the SSE object, all future
# SSEs sent across the stream will use those options unless overridden.
#
# Example Usage:
#
# class MyController < ActionController::Base
# include ActionController::Live
#
# def index
# response.headers['Content-Type'] = 'text/event-stream'
# sse = SSE.new(response.stream, retry: 300, event: "event-name")
# sse.write({ name: 'John'})
# sse.write({ name: 'John'}, id: 10)
# sse.write({ name: 'John'}, id: 10, event: "other-event")
# sse.write({ name: 'John'}, id: 10, event: "other-event", retry: 500)
# ensure
# sse.close
# end
# end
#
# Note: SSEs are not currently supported by IE. However, they are supported
# by Chrome, Firefox, Opera, and Safari.

Note: By default Rails provides a one-way communication process by writing the stream to the client when data is available. However, if we can add SSEs, we can enable events and responses, thus making it two-way.
 
 

==Benefit of live streaming==
1.Send partial responses to the client immediately.
 
2.Using Server-sent events, the ability to create chat clients, push notifications, and real-time feeds are available within Rails itself
 
3.Continuously inform the user about the progress.
See example below<ref>Why Rails 4 Live Streaming is a big deal, Hongli Lai, August 3rd, 2012 http://blog.phusion.nl/2012/08/03/why-rails-4-live-streaming-is-a-big-deal/</ref>:
<pre>
def big_work
work = WorkModel.new
while !work.done?
work.do_some_calculations
response.stream.write "Progress: #{work.progress}%\n"
end
response.stream.close
end
</pre>
 

='''Troubleshooting'''=
When running streaming programs, we need to install [http://puma.io/ PUMA] to substitute the original [https://en.wikipedia.org/wiki/WEBrick WEBrick] server, because puma can handle concurrency better. In order to do this, we need to add the following line to Gemfile:
<pre>
gem 'puma'
</pre>
 
After installed puma, if we start rails server, the console will print the following output:
<pre>
"C:\Program Files (x86)\JetBrains\RubyMine 7.0.2\bin\runnerw.exe" C:\RailsInstaller\Ruby2.0.0\bin\ruby.exe -e $stdout.sync=true;$stderr.sync=true;load($0=ARGV.shift) D:/Cloud/Coding/RubymineProjects/LiveStreamingExample/bin/rails server -b 127.0.0.1 -p 3000 -e development
=> Booting Puma
=> Rails 4.1.8 application starting in development on http://127.0.0.1:3000
=> Run `rails server -h` for more startup options
=> Ctrl-C to shutdown server
Puma 2.11.0 starting...
* Min threads: 0, max threads: 16
* Environment: development
* Listening on tcp://127.0.0.1:3000
</pre>
This means that PUMA is set as our default server and successfully booted.
 
 
We encountered failure on Windows when trying to install PUMA, the console printed the following error:
<pre>
Building native extensions. This could take a while...
ERROR: Error installing rails:
ERROR: Failed to build gem native extension.

/Users/WillieTran/.rvm/rubies/ruby-2.0.0-p247/bin/ruby extconf.rb
*** extconf.rb failed ***

Could not create Makefile due to some reason, probably lack of necessary
libraries and/or headers. Check the mkmf.log file for more details. You may
need configuration options.
</pre>
 
To solve this problem, we need to install [https://www.openssl.org/ openssl] for windows. And then run the following command<ref>https://github.com/hicknhack-software/rails-disco/wiki/Installing-puma-on-windows</ref>:
<pre>
gem install puma -- --with-opt-dir=c:\openssl
</pre>
 

='''References'''=
<references>

CSC/ECE 517 Spring 2015/ch1a 12 LS

2015-02-16T03:13:26Z

Hwang40: /* Benefit of live streaming */

Live Streaming

='''Introduction'''=
The purpose of live streaming is to send data over the Internet in real-time. This requires a data source, a data encoder, a media publisher and a proper network.

In Rails, the concept of streaming first appeared in [http://weblog.rubyonrails.org/releases/ version 3.1], and is further optimized in Rails 4. Now Rails 4 supports live streaming, which uses handling I/O object and can send data from server to client in real-time.

__TOC__

='''Details'''=
==Template streaming==
Since Rail 3.1, [http://api.rubyonrails.org/classes/ActionController/Streaming.html ''::Streaming''] module has been added to ActionController. For example, the loading progress in a traditional Rails client-side may look like this<ref> https://github.com/oggy/template_streaming</ref>:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:slow-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 1 progress without streaming</div>
This is because that layouts are rendered before the content, thus causing control flow to be altered to render the page in the order that the client needs (layout first).But for some resources which are static, if they could be loaded while waiting for the server response, a lot of time can be saved.
 
 
The module ''::Streaming'' inverts the regular Rails process of rendering the layout and template. Using ''::Streaming'', Rails will render template first and then layout. It will first run method yield and load up the template, and then renders the assets and layouts. In this way, the progress with streaming looks like this:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:fast-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 2 progress with streaming</div>

===When to use streaming===
For actions like new or edit, it may not be that necessary to use streaming. But for expensive actions like database query and generation of large amount of data, streaming can be extremely important and effective. Take the following action as an example:
<pre>
def storyboard
@stories = Story.all
@developers = Page.all
@comments = Comment.all
end
</pre>

Since most of the queries here are executing in the controller, it might take a while before them to finish, thus causing the front end (user) to wait for long. We can solve this problem and enhance user experience, the above code can be rewrite as follows,
<pre>
def storyboard
# Allow lazy execution of the queries
@stories = Story.all
@developers = Page.all
@comments = Comment.all
render :stream => true
end
</pre>
(Note: '':Streaming'' only works with templates. It doesn’t work with :json or :xml)<ref>http://apidock.com/rails/ActionController/Streaming</ref>
 
 

===Tweaking views===
When using streaming, instance variables that are set in the template and are used in the layout won't need some tweak to work well. This is done by using content_for, provide and yield.
Here’s a simple example where the layout expects the template to tell which title to use<ref>http://apidock.com/rails/ActionController/Streaming</ref>:
<pre>
<html>
<head><title><%= yield :title %></title></head>
<body><%= yield %></body>
</html>
</pre>

Instead of yield, we can also use content_for to specify the title:
<pre>
<%= content_for :title, "Main" %>
Hello
</pre>

And the final result would be:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>

However, if content_for is called several times, the final result would have all calls concatenated.
For instance, if we have the following template:
<pre>
<%= content_for :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>

The final result would be:
<pre>
<html>
<head><title>Main page</title></head>
<body>Hello</body>
</html>
</pre>
This means that, if you have yield '':title'' in your layout and you want to use streaming, you would have to render the whole template (and eventually trigger all queries) before streaming the title and all assets, which kills the purpose of streaming. For this reason Rails 3.1 introduces a new helper called provide that does the same as content_for but tells the layout to stop searching for other entries and continue rendering.

For instance, the template above using provide would be:
<pre>
<%= provide :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>
Giving:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>
That said, when streaming, you need to properly check your templates and choose when to use provide and content_for.
 
 

==Live Streaming==
The module [http://api.rubyonrails.org/classes/ActionController/Live.html ''::Live''] was then added to ActionController at Rail 4. The difference between Streaming and Live is that Streaming is implicitly included whenever you create a new controller class, while ''::Live'' requires explicit include.

===Traditional Response===
In this type of communication between server and client, data will be buffered until all render works are finished, and everything will be sent to the client at the same time. And the stream object behaves just like an IO object. Here’s the sample code:
<pre>
class MessageController < ApplicationController
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a response message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>

When we run the code above, the web page will '''keep loading and remain blank''' for 8 seconds, and shows all 8 lines of “This is a response message!” altogether, as with the following image shows: 
[[File:nostreaming.gif]]

===Live Streaming===
In order to enable live streaming, we need to include a module named ''ActionController::Live''. When this module is mixed into the controller, all actions within that controller will be able to stream data to the client in real time, like the following code:
<pre>
class MessageController < ApplicationController
#here we enabled live streaming
include ActionController::Live
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a live streaming message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>
The above code looks exactly the same as the traditional response, except the newly included module ''ActionController::Live''. Now '''data can be streamed to the client immediately whenever write method is called'''. When we run the code above, the web page will print one line “This is a response message!” for every seconds and repeats 8 times.<ref>http://tenderlovemaking.com/2012/07/30/is-it-live.html</ref> Like the image shows below: 
[[File:streaming.gif]]
 
 

==Server-Sent Event==
[https://en.wikipedia.org/wiki/Server-sent_events Server-sent event (SSE)] is a technology where browser can automatically receive update data from a server via [https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol HTTP] connection. Whenever server sends data, the SSE method in the browser will trigger an event.The SSE EventSource API is standardized as part of [https://en.wikipedia.org/wiki/HTML5 HTML5] by the [https://en.wikipedia.org/wiki/World_Wide_Web_Consortium W3C]. It can be used together with the Live API to achieve full-duplex communication.<ref>https://en.wikipedia.org/wiki/Server-sent_events</ref>
 
A simple SSE looks like the following :
<pre>
require 'json'
module ServerSide
class SSE
def initialize io
@io = io
end

def write object, options = {}
options.each do |k,v|
@io.write "#{k}: #{v}n"
end
@io.write "data: #{object}nn"
end

def close
@io.close
end
end
end
</pre>
This module assigns the I/O stream object to a hash and converts it into a key-value pair so that it is easy to read, store, and send it back in [https://en.wikipedia.org/wiki/JSON JSON] format.
 
 
Now we can wrap stream object inside the SSE class. By doing this, we need to include SSE module inside the controller, so that the opening and closing of connections will be managed by SSE module. And we also add the ensure clause to make sure that the connection will always be closed after execution.
<pre>
require 'sse'
class MessagingController < ApplicationController
include ActionController::Live

def stream
response.headers['Content-Type'] = 'text/event-stream'
sse = SSE.new(response.stream)
begin
5.times {
sse.write(“Streaming using SSE!”)
sleep 1
}
ensure
sse.close
end
end
end
</pre>
The code above will print the sentence “Streaming using SSE!” once per second, until the loop ends.
 
 
Here’s another sample showing how to use SSE to stream data<ref>https://github.com/rails/rails/blob/6061c540ac7880233a6e32de85cec72c20ed8778/actionpack/lib/action_controller/metal/live.rb</ref>:

# This class provides the ability to write an SSE (Server Sent Event)
# to an IO stream. The class is initialized with a stream and can be used
# to either write a JSON string or an object which can be converted to JSON.
#
# Writing an object will convert it into standard SSE format with whatever
# options you have configured. You may choose to set the following options:
#
# 1) Event. If specified, an event with this name will be dispatched on
# the browser.
# 2) Retry. The reconnection time in milliseconds used when attempting
# to send the event.
# 3) Id. If the connection dies while sending an SSE to the browser, then
# the server will receive a +Last-Event-ID+ header with value equal to +id+.
#
# After setting an option in the constructor of the SSE object, all future
# SSEs sent across the stream will use those options unless overridden.
#
# Example Usage:
#
# class MyController < ActionController::Base
# include ActionController::Live
#
# def index
# response.headers['Content-Type'] = 'text/event-stream'
# sse = SSE.new(response.stream, retry: 300, event: "event-name")
# sse.write({ name: 'John'})
# sse.write({ name: 'John'}, id: 10)
# sse.write({ name: 'John'}, id: 10, event: "other-event")
# sse.write({ name: 'John'}, id: 10, event: "other-event", retry: 500)
# ensure
# sse.close
# end
# end
#
# Note: SSEs are not currently supported by IE. However, they are supported
# by Chrome, Firefox, Opera, and Safari.

Note: By default Rails provides a one-way communication process by writing the stream to the client when data is available. However, if we can add SSEs, we can enable events and responses, thus making it two-way.
 
 

==Benefit of live streaming==
1.Send partial responses to the client immediately.
 
2.Using Server-sent events, the ability to create chat clients, push notifications, and real-time feeds are available within Rails itself
 
3.Continuously inform the user about the progress.
See example below<ref>Why Rails 4 Live Streaming is a big deal, Hongli Lai, August 3rd, 2012 http://blog.phusion.nl/2012/08/03/why-rails-4-live-streaming-is-a-big-deal/ Why Rails 4 Live Streaming is a big deal By Hongli Lai on August 3rd, 2012</ref>:
<pre>
def big_work
work = WorkModel.new
while !work.done?
work.do_some_calculations
response.stream.write "Progress: #{work.progress}%\n"
end
response.stream.close
end
</pre>
 

='''Troubleshooting'''=
When running streaming programs, we need to install [http://puma.io/ PUMA] to substitute the original [https://en.wikipedia.org/wiki/WEBrick WEBrick] server, because puma can handle concurrency better. In order to do this, we need to add the following line to Gemfile:
<pre>
gem 'puma'
</pre>
 
After installed puma, if we start rails server, the console will print the following output:
<pre>
"C:\Program Files (x86)\JetBrains\RubyMine 7.0.2\bin\runnerw.exe" C:\RailsInstaller\Ruby2.0.0\bin\ruby.exe -e $stdout.sync=true;$stderr.sync=true;load($0=ARGV.shift) D:/Cloud/Coding/RubymineProjects/LiveStreamingExample/bin/rails server -b 127.0.0.1 -p 3000 -e development
=> Booting Puma
=> Rails 4.1.8 application starting in development on http://127.0.0.1:3000
=> Run `rails server -h` for more startup options
=> Ctrl-C to shutdown server
Puma 2.11.0 starting...
* Min threads: 0, max threads: 16
* Environment: development
* Listening on tcp://127.0.0.1:3000
</pre>
This means that PUMA is set as our default server and successfully booted.
 
 
We encountered failure on Windows when trying to install PUMA, the console printed the following error:
<pre>
Building native extensions. This could take a while...
ERROR: Error installing rails:
ERROR: Failed to build gem native extension.

/Users/WillieTran/.rvm/rubies/ruby-2.0.0-p247/bin/ruby extconf.rb
*** extconf.rb failed ***

Could not create Makefile due to some reason, probably lack of necessary
libraries and/or headers. Check the mkmf.log file for more details. You may
need configuration options.
</pre>
 
To solve this problem, we need to install [https://www.openssl.org/ openssl] for windows. And then run the following command<ref>https://github.com/hicknhack-software/rails-disco/wiki/Installing-puma-on-windows</ref>:
<pre>
gem install puma -- --with-opt-dir=c:\openssl
</pre>
 

='''References'''=
<references>

CSC/ECE 517 Spring 2015/ch1a 12 LS

2015-02-16T03:11:27Z

Hwang40: /* Benefit of live streaming */

Live Streaming

='''Introduction'''=
The purpose of live streaming is to send data over the Internet in real-time. This requires a data source, a data encoder, a media publisher and a proper network.

In Rails, the concept of streaming first appeared in [http://weblog.rubyonrails.org/releases/ version 3.1], and is further optimized in Rails 4. Now Rails 4 supports live streaming, which uses handling I/O object and can send data from server to client in real-time.

__TOC__

='''Details'''=
==Template streaming==
Since Rail 3.1, [http://api.rubyonrails.org/classes/ActionController/Streaming.html ''::Streaming''] module has been added to ActionController. For example, the loading progress in a traditional Rails client-side may look like this<ref> https://github.com/oggy/template_streaming</ref>:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:slow-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 1 progress without streaming</div>
This is because that layouts are rendered before the content, thus causing control flow to be altered to render the page in the order that the client needs (layout first).But for some resources which are static, if they could be loaded while waiting for the server response, a lot of time can be saved.
 
 
The module ''::Streaming'' inverts the regular Rails process of rendering the layout and template. Using ''::Streaming'', Rails will render template first and then layout. It will first run method yield and load up the template, and then renders the assets and layouts. In this way, the progress with streaming looks like this:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:fast-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 2 progress with streaming</div>

===When to use streaming===
For actions like new or edit, it may not be that necessary to use streaming. But for expensive actions like database query and generation of large amount of data, streaming can be extremely important and effective. Take the following action as an example:
<pre>
def storyboard
@stories = Story.all
@developers = Page.all
@comments = Comment.all
end
</pre>

Since most of the queries here are executing in the controller, it might take a while before them to finish, thus causing the front end (user) to wait for long. We can solve this problem and enhance user experience, the above code can be rewrite as follows,
<pre>
def storyboard
# Allow lazy execution of the queries
@stories = Story.all
@developers = Page.all
@comments = Comment.all
render :stream => true
end
</pre>
(Note: '':Streaming'' only works with templates. It doesn’t work with :json or :xml)<ref>http://apidock.com/rails/ActionController/Streaming</ref>
 
 

===Tweaking views===
When using streaming, instance variables that are set in the template and are used in the layout won't need some tweak to work well. This is done by using content_for, provide and yield.
Here’s a simple example where the layout expects the template to tell which title to use<ref>http://apidock.com/rails/ActionController/Streaming</ref>:
<pre>
<html>
<head><title><%= yield :title %></title></head>
<body><%= yield %></body>
</html>
</pre>

Instead of yield, we can also use content_for to specify the title:
<pre>
<%= content_for :title, "Main" %>
Hello
</pre>

And the final result would be:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>

However, if content_for is called several times, the final result would have all calls concatenated.
For instance, if we have the following template:
<pre>
<%= content_for :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>

The final result would be:
<pre>
<html>
<head><title>Main page</title></head>
<body>Hello</body>
</html>
</pre>
This means that, if you have yield '':title'' in your layout and you want to use streaming, you would have to render the whole template (and eventually trigger all queries) before streaming the title and all assets, which kills the purpose of streaming. For this reason Rails 3.1 introduces a new helper called provide that does the same as content_for but tells the layout to stop searching for other entries and continue rendering.

For instance, the template above using provide would be:
<pre>
<%= provide :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>
Giving:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>
That said, when streaming, you need to properly check your templates and choose when to use provide and content_for.
 
 

==Live Streaming==
The module [http://api.rubyonrails.org/classes/ActionController/Live.html ''::Live''] was then added to ActionController at Rail 4. The difference between Streaming and Live is that Streaming is implicitly included whenever you create a new controller class, while ''::Live'' requires explicit include.

===Traditional Response===
In this type of communication between server and client, data will be buffered until all render works are finished, and everything will be sent to the client at the same time. And the stream object behaves just like an IO object. Here’s the sample code:
<pre>
class MessageController < ApplicationController
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a response message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>

When we run the code above, the web page will '''keep loading and remain blank''' for 8 seconds, and shows all 8 lines of “This is a response message!” altogether, as with the following image shows: 
[[File:nostreaming.gif]]

===Live Streaming===
In order to enable live streaming, we need to include a module named ''ActionController::Live''. When this module is mixed into the controller, all actions within that controller will be able to stream data to the client in real time, like the following code:
<pre>
class MessageController < ApplicationController
#here we enabled live streaming
include ActionController::Live
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a live streaming message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>
The above code looks exactly the same as the traditional response, except the newly included module ''ActionController::Live''. Now '''data can be streamed to the client immediately whenever write method is called'''. When we run the code above, the web page will print one line “This is a response message!” for every seconds and repeats 8 times.<ref>http://tenderlovemaking.com/2012/07/30/is-it-live.html</ref> Like the image shows below: 
[[File:streaming.gif]]
 
 

==Server-Sent Event==
[https://en.wikipedia.org/wiki/Server-sent_events Server-sent event (SSE)] is a technology where browser can automatically receive update data from a server via [https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol HTTP] connection. Whenever server sends data, the SSE method in the browser will trigger an event.The SSE EventSource API is standardized as part of [https://en.wikipedia.org/wiki/HTML5 HTML5] by the [https://en.wikipedia.org/wiki/World_Wide_Web_Consortium W3C]. It can be used together with the Live API to achieve full-duplex communication.<ref>https://en.wikipedia.org/wiki/Server-sent_events</ref>
 
A simple SSE looks like the following :
<pre>
require 'json'
module ServerSide
class SSE
def initialize io
@io = io
end

def write object, options = {}
options.each do |k,v|
@io.write "#{k}: #{v}n"
end
@io.write "data: #{object}nn"
end

def close
@io.close
end
end
end
</pre>
This module assigns the I/O stream object to a hash and converts it into a key-value pair so that it is easy to read, store, and send it back in [https://en.wikipedia.org/wiki/JSON JSON] format.
 
 
Now we can wrap stream object inside the SSE class. By doing this, we need to include SSE module inside the controller, so that the opening and closing of connections will be managed by SSE module. And we also add the ensure clause to make sure that the connection will always be closed after execution.
<pre>
require 'sse'
class MessagingController < ApplicationController
include ActionController::Live

def stream
response.headers['Content-Type'] = 'text/event-stream'
sse = SSE.new(response.stream)
begin
5.times {
sse.write(“Streaming using SSE!”)
sleep 1
}
ensure
sse.close
end
end
end
</pre>
The code above will print the sentence “Streaming using SSE!” once per second, until the loop ends.
 
 
Here’s another sample showing how to use SSE to stream data<ref>https://github.com/rails/rails/blob/6061c540ac7880233a6e32de85cec72c20ed8778/actionpack/lib/action_controller/metal/live.rb</ref>:

# This class provides the ability to write an SSE (Server Sent Event)
# to an IO stream. The class is initialized with a stream and can be used
# to either write a JSON string or an object which can be converted to JSON.
#
# Writing an object will convert it into standard SSE format with whatever
# options you have configured. You may choose to set the following options:
#
# 1) Event. If specified, an event with this name will be dispatched on
# the browser.
# 2) Retry. The reconnection time in milliseconds used when attempting
# to send the event.
# 3) Id. If the connection dies while sending an SSE to the browser, then
# the server will receive a +Last-Event-ID+ header with value equal to +id+.
#
# After setting an option in the constructor of the SSE object, all future
# SSEs sent across the stream will use those options unless overridden.
#
# Example Usage:
#
# class MyController < ActionController::Base
# include ActionController::Live
#
# def index
# response.headers['Content-Type'] = 'text/event-stream'
# sse = SSE.new(response.stream, retry: 300, event: "event-name")
# sse.write({ name: 'John'})
# sse.write({ name: 'John'}, id: 10)
# sse.write({ name: 'John'}, id: 10, event: "other-event")
# sse.write({ name: 'John'}, id: 10, event: "other-event", retry: 500)
# ensure
# sse.close
# end
# end
#
# Note: SSEs are not currently supported by IE. However, they are supported
# by Chrome, Firefox, Opera, and Safari.

Note: By default Rails provides a one-way communication process by writing the stream to the client when data is available. However, if we can add SSEs, we can enable events and responses, thus making it two-way.
 
 

==Benefit of live streaming==
1.Send partial responses to the client immediately.
 
2.Using Server-sent events, the ability to create chat clients, push notifications, and real-time feeds are available within Rails itself
 
3.Continuously inform the user about the progress.
See example below<ref>http://blog.phusion.nl/2012/08/03/why-rails-4-live-streaming-is-a-big-deal/ Why Rails 4 Live Streaming is a big deal By Hongli Lai on August 3rd, 2012</ref>:
<pre>
def big_work
work = WorkModel.new
while !work.done?
work.do_some_calculations
response.stream.write "Progress: #{work.progress}%\n"
end
response.stream.close
end
</pre>
 

='''Troubleshooting'''=
When running streaming programs, we need to install [http://puma.io/ PUMA] to substitute the original [https://en.wikipedia.org/wiki/WEBrick WEBrick] server, because puma can handle concurrency better. In order to do this, we need to add the following line to Gemfile:
<pre>
gem 'puma'
</pre>
 
After installed puma, if we start rails server, the console will print the following output:
<pre>
"C:\Program Files (x86)\JetBrains\RubyMine 7.0.2\bin\runnerw.exe" C:\RailsInstaller\Ruby2.0.0\bin\ruby.exe -e $stdout.sync=true;$stderr.sync=true;load($0=ARGV.shift) D:/Cloud/Coding/RubymineProjects/LiveStreamingExample/bin/rails server -b 127.0.0.1 -p 3000 -e development
=> Booting Puma
=> Rails 4.1.8 application starting in development on http://127.0.0.1:3000
=> Run `rails server -h` for more startup options
=> Ctrl-C to shutdown server
Puma 2.11.0 starting...
* Min threads: 0, max threads: 16
* Environment: development
* Listening on tcp://127.0.0.1:3000
</pre>
This means that PUMA is set as our default server and successfully booted.
 
 
We encountered failure on Windows when trying to install PUMA, the console printed the following error:
<pre>
Building native extensions. This could take a while...
ERROR: Error installing rails:
ERROR: Failed to build gem native extension.

/Users/WillieTran/.rvm/rubies/ruby-2.0.0-p247/bin/ruby extconf.rb
*** extconf.rb failed ***

Could not create Makefile due to some reason, probably lack of necessary
libraries and/or headers. Check the mkmf.log file for more details. You may
need configuration options.
</pre>
 
To solve this problem, we need to install [https://www.openssl.org/ openssl] for windows. And then run the following command<ref>https://github.com/hicknhack-software/rails-disco/wiki/Installing-puma-on-windows</ref>:
<pre>
gem install puma -- --with-opt-dir=c:\openssl
</pre>
 

='''References'''=
<references>

CSC/ECE 517 Spring 2015/ch1a 12 LS

2015-02-16T03:05:11Z

Hwang40: /* Server-Sent Event */

Live Streaming

='''Introduction'''=
The purpose of live streaming is to send data over the Internet in real-time. This requires a data source, a data encoder, a media publisher and a proper network.

In Rails, the concept of streaming first appeared in [http://weblog.rubyonrails.org/releases/ version 3.1], and is further optimized in Rails 4. Now Rails 4 supports live streaming, which uses handling I/O object and can send data from server to client in real-time.

__TOC__

='''Details'''=
==Template streaming==
Since Rail 3.1, [http://api.rubyonrails.org/classes/ActionController/Streaming.html ''::Streaming''] module has been added to ActionController. For example, the loading progress in a traditional Rails client-side may look like this<ref> https://github.com/oggy/template_streaming</ref>:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:slow-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 1 progress without streaming</div>
This is because that layouts are rendered before the content, thus causing control flow to be altered to render the page in the order that the client needs (layout first).But for some resources which are static, if they could be loaded while waiting for the server response, a lot of time can be saved.
 
 
The module ''::Streaming'' inverts the regular Rails process of rendering the layout and template. Using ''::Streaming'', Rails will render template first and then layout. It will first run method yield and load up the template, and then renders the assets and layouts. In this way, the progress with streaming looks like this:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:fast-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 2 progress with streaming</div>

===When to use streaming===
For actions like new or edit, it may not be that necessary to use streaming. But for expensive actions like database query and generation of large amount of data, streaming can be extremely important and effective. Take the following action as an example:
<pre>
def storyboard
@stories = Story.all
@developers = Page.all
@comments = Comment.all
end
</pre>

Since most of the queries here are executing in the controller, it might take a while before them to finish, thus causing the front end (user) to wait for long. We can solve this problem and enhance user experience, the above code can be rewrite as follows,
<pre>
def storyboard
# Allow lazy execution of the queries
@stories = Story.all
@developers = Page.all
@comments = Comment.all
render :stream => true
end
</pre>
(Note: '':Streaming'' only works with templates. It doesn’t work with :json or :xml)<ref>http://apidock.com/rails/ActionController/Streaming</ref>
 
 

===Tweaking views===
When using streaming, instance variables that are set in the template and are used in the layout won't need some tweak to work well. This is done by using content_for, provide and yield.
Here’s a simple example where the layout expects the template to tell which title to use<ref>http://apidock.com/rails/ActionController/Streaming</ref>:
<pre>
<html>
<head><title><%= yield :title %></title></head>
<body><%= yield %></body>
</html>
</pre>

Instead of yield, we can also use content_for to specify the title:
<pre>
<%= content_for :title, "Main" %>
Hello
</pre>

And the final result would be:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>

However, if content_for is called several times, the final result would have all calls concatenated.
For instance, if we have the following template:
<pre>
<%= content_for :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>

The final result would be:
<pre>
<html>
<head><title>Main page</title></head>
<body>Hello</body>
</html>
</pre>
This means that, if you have yield '':title'' in your layout and you want to use streaming, you would have to render the whole template (and eventually trigger all queries) before streaming the title and all assets, which kills the purpose of streaming. For this reason Rails 3.1 introduces a new helper called provide that does the same as content_for but tells the layout to stop searching for other entries and continue rendering.

For instance, the template above using provide would be:
<pre>
<%= provide :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>
Giving:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>
That said, when streaming, you need to properly check your templates and choose when to use provide and content_for.
 
 

==Live Streaming==
The module [http://api.rubyonrails.org/classes/ActionController/Live.html ''::Live''] was then added to ActionController at Rail 4. The difference between Streaming and Live is that Streaming is implicitly included whenever you create a new controller class, while ''::Live'' requires explicit include.

===Traditional Response===
In this type of communication between server and client, data will be buffered until all render works are finished, and everything will be sent to the client at the same time. And the stream object behaves just like an IO object. Here’s the sample code:
<pre>
class MessageController < ApplicationController
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a response message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>

When we run the code above, the web page will '''keep loading and remain blank''' for 8 seconds, and shows all 8 lines of “This is a response message!” altogether, as with the following image shows: 
[[File:nostreaming.gif]]

===Live Streaming===
In order to enable live streaming, we need to include a module named ''ActionController::Live''. When this module is mixed into the controller, all actions within that controller will be able to stream data to the client in real time, like the following code:
<pre>
class MessageController < ApplicationController
#here we enabled live streaming
include ActionController::Live
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a live streaming message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>
The above code looks exactly the same as the traditional response, except the newly included module ''ActionController::Live''. Now '''data can be streamed to the client immediately whenever write method is called'''. When we run the code above, the web page will print one line “This is a response message!” for every seconds and repeats 8 times.<ref>http://tenderlovemaking.com/2012/07/30/is-it-live.html</ref> Like the image shows below: 
[[File:streaming.gif]]
 
 

==Server-Sent Event==
[https://en.wikipedia.org/wiki/Server-sent_events Server-sent event (SSE)] is a technology where browser can automatically receive update data from a server via [https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol HTTP] connection. Whenever server sends data, the SSE method in the browser will trigger an event.The SSE EventSource API is standardized as part of [https://en.wikipedia.org/wiki/HTML5 HTML5] by the [https://en.wikipedia.org/wiki/World_Wide_Web_Consortium W3C]. It can be used together with the Live API to achieve full-duplex communication.<ref>https://en.wikipedia.org/wiki/Server-sent_events</ref>
 
A simple SSE looks like the following :
<pre>
require 'json'
module ServerSide
class SSE
def initialize io
@io = io
end

def write object, options = {}
options.each do |k,v|
@io.write "#{k}: #{v}n"
end
@io.write "data: #{object}nn"
end

def close
@io.close
end
end
end
</pre>
This module assigns the I/O stream object to a hash and converts it into a key-value pair so that it is easy to read, store, and send it back in [https://en.wikipedia.org/wiki/JSON JSON] format.
 
 
Now we can wrap stream object inside the SSE class. By doing this, we need to include SSE module inside the controller, so that the opening and closing of connections will be managed by SSE module. And we also add the ensure clause to make sure that the connection will always be closed after execution.
<pre>
require 'sse'
class MessagingController < ApplicationController
include ActionController::Live

def stream
response.headers['Content-Type'] = 'text/event-stream'
sse = SSE.new(response.stream)
begin
5.times {
sse.write(“Streaming using SSE!”)
sleep 1
}
ensure
sse.close
end
end
end
</pre>
The code above will print the sentence “Streaming using SSE!” once per second, until the loop ends.
 
 
Here’s another sample showing how to use SSE to stream data<ref>https://github.com/rails/rails/blob/6061c540ac7880233a6e32de85cec72c20ed8778/actionpack/lib/action_controller/metal/live.rb</ref>:

# This class provides the ability to write an SSE (Server Sent Event)
# to an IO stream. The class is initialized with a stream and can be used
# to either write a JSON string or an object which can be converted to JSON.
#
# Writing an object will convert it into standard SSE format with whatever
# options you have configured. You may choose to set the following options:
#
# 1) Event. If specified, an event with this name will be dispatched on
# the browser.
# 2) Retry. The reconnection time in milliseconds used when attempting
# to send the event.
# 3) Id. If the connection dies while sending an SSE to the browser, then
# the server will receive a +Last-Event-ID+ header with value equal to +id+.
#
# After setting an option in the constructor of the SSE object, all future
# SSEs sent across the stream will use those options unless overridden.
#
# Example Usage:
#
# class MyController < ActionController::Base
# include ActionController::Live
#
# def index
# response.headers['Content-Type'] = 'text/event-stream'
# sse = SSE.new(response.stream, retry: 300, event: "event-name")
# sse.write({ name: 'John'})
# sse.write({ name: 'John'}, id: 10)
# sse.write({ name: 'John'}, id: 10, event: "other-event")
# sse.write({ name: 'John'}, id: 10, event: "other-event", retry: 500)
# ensure
# sse.close
# end
# end
#
# Note: SSEs are not currently supported by IE. However, they are supported
# by Chrome, Firefox, Opera, and Safari.

Note: By default Rails provides a one-way communication process by writing the stream to the client when data is available. However, if we can add SSEs, we can enable events and responses, thus making it two-way.
 
 

==Benefit of live streaming==
1.Send partial responses to the client immediately.
 
2.Using Server-sent events, the ability to create chat clients, push notifications, and real-time feeds are available within Rails itself
 
3.Continuously inform the user about the progress.
See example below<ref>http://blog.phusion.nl/2012/08/03/why-rails-4-live-streaming-is-a-big-deal/</ref>:
<pre>
def big_work
work = WorkModel.new
while !work.done?
work.do_some_calculations
response.stream.write "Progress: #{work.progress}%\n"
end
response.stream.close
end
</pre>
 

='''Troubleshooting'''=
When running streaming programs, we need to install [http://puma.io/ PUMA] to substitute the original [https://en.wikipedia.org/wiki/WEBrick WEBrick] server, because puma can handle concurrency better. In order to do this, we need to add the following line to Gemfile:
<pre>
gem 'puma'
</pre>
 
After installed puma, if we start rails server, the console will print the following output:
<pre>
"C:\Program Files (x86)\JetBrains\RubyMine 7.0.2\bin\runnerw.exe" C:\RailsInstaller\Ruby2.0.0\bin\ruby.exe -e $stdout.sync=true;$stderr.sync=true;load($0=ARGV.shift) D:/Cloud/Coding/RubymineProjects/LiveStreamingExample/bin/rails server -b 127.0.0.1 -p 3000 -e development
=> Booting Puma
=> Rails 4.1.8 application starting in development on http://127.0.0.1:3000
=> Run `rails server -h` for more startup options
=> Ctrl-C to shutdown server
Puma 2.11.0 starting...
* Min threads: 0, max threads: 16
* Environment: development
* Listening on tcp://127.0.0.1:3000
</pre>
This means that PUMA is set as our default server and successfully booted.
 
 
We encountered failure on Windows when trying to install PUMA, the console printed the following error:
<pre>
Building native extensions. This could take a while...
ERROR: Error installing rails:
ERROR: Failed to build gem native extension.

/Users/WillieTran/.rvm/rubies/ruby-2.0.0-p247/bin/ruby extconf.rb
*** extconf.rb failed ***

Could not create Makefile due to some reason, probably lack of necessary
libraries and/or headers. Check the mkmf.log file for more details. You may
need configuration options.
</pre>
 
To solve this problem, we need to install [https://www.openssl.org/ openssl] for windows. And then run the following command<ref>https://github.com/hicknhack-software/rails-disco/wiki/Installing-puma-on-windows</ref>:
<pre>
gem install puma -- --with-opt-dir=c:\openssl
</pre>
 

='''References'''=
<references>

CSC/ECE 517 Spring 2015/ch1a 12 LS

2015-02-16T03:04:11Z

Hwang40: /* Server-Sent Event */

Live Streaming

='''Introduction'''=
The purpose of live streaming is to send data over the Internet in real-time. This requires a data source, a data encoder, a media publisher and a proper network.

In Rails, the concept of streaming first appeared in [http://weblog.rubyonrails.org/releases/ version 3.1], and is further optimized in Rails 4. Now Rails 4 supports live streaming, which uses handling I/O object and can send data from server to client in real-time.

__TOC__

='''Details'''=
==Template streaming==
Since Rail 3.1, [http://api.rubyonrails.org/classes/ActionController/Streaming.html ''::Streaming''] module has been added to ActionController. For example, the loading progress in a traditional Rails client-side may look like this<ref> https://github.com/oggy/template_streaming</ref>:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:slow-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 1 progress without streaming</div>
This is because that layouts are rendered before the content, thus causing control flow to be altered to render the page in the order that the client needs (layout first).But for some resources which are static, if they could be loaded while waiting for the server response, a lot of time can be saved.
 
 
The module ''::Streaming'' inverts the regular Rails process of rendering the layout and template. Using ''::Streaming'', Rails will render template first and then layout. It will first run method yield and load up the template, and then renders the assets and layouts. In this way, the progress with streaming looks like this:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:fast-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 2 progress with streaming</div>

===When to use streaming===
For actions like new or edit, it may not be that necessary to use streaming. But for expensive actions like database query and generation of large amount of data, streaming can be extremely important and effective. Take the following action as an example:
<pre>
def storyboard
@stories = Story.all
@developers = Page.all
@comments = Comment.all
end
</pre>

Since most of the queries here are executing in the controller, it might take a while before them to finish, thus causing the front end (user) to wait for long. We can solve this problem and enhance user experience, the above code can be rewrite as follows,
<pre>
def storyboard
# Allow lazy execution of the queries
@stories = Story.all
@developers = Page.all
@comments = Comment.all
render :stream => true
end
</pre>
(Note: '':Streaming'' only works with templates. It doesn’t work with :json or :xml)<ref>http://apidock.com/rails/ActionController/Streaming</ref>
 
 

===Tweaking views===
When using streaming, instance variables that are set in the template and are used in the layout won't need some tweak to work well. This is done by using content_for, provide and yield.
Here’s a simple example where the layout expects the template to tell which title to use<ref>http://apidock.com/rails/ActionController/Streaming</ref>:
<pre>
<html>
<head><title><%= yield :title %></title></head>
<body><%= yield %></body>
</html>
</pre>

Instead of yield, we can also use content_for to specify the title:
<pre>
<%= content_for :title, "Main" %>
Hello
</pre>

And the final result would be:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>

However, if content_for is called several times, the final result would have all calls concatenated.
For instance, if we have the following template:
<pre>
<%= content_for :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>

The final result would be:
<pre>
<html>
<head><title>Main page</title></head>
<body>Hello</body>
</html>
</pre>
This means that, if you have yield '':title'' in your layout and you want to use streaming, you would have to render the whole template (and eventually trigger all queries) before streaming the title and all assets, which kills the purpose of streaming. For this reason Rails 3.1 introduces a new helper called provide that does the same as content_for but tells the layout to stop searching for other entries and continue rendering.

For instance, the template above using provide would be:
<pre>
<%= provide :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>
Giving:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>
That said, when streaming, you need to properly check your templates and choose when to use provide and content_for.
 
 

==Live Streaming==
The module [http://api.rubyonrails.org/classes/ActionController/Live.html ''::Live''] was then added to ActionController at Rail 4. The difference between Streaming and Live is that Streaming is implicitly included whenever you create a new controller class, while ''::Live'' requires explicit include.

===Traditional Response===
In this type of communication between server and client, data will be buffered until all render works are finished, and everything will be sent to the client at the same time. And the stream object behaves just like an IO object. Here’s the sample code:
<pre>
class MessageController < ApplicationController
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a response message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>

When we run the code above, the web page will '''keep loading and remain blank''' for 8 seconds, and shows all 8 lines of “This is a response message!” altogether, as with the following image shows: 
[[File:nostreaming.gif]]

===Live Streaming===
In order to enable live streaming, we need to include a module named ''ActionController::Live''. When this module is mixed into the controller, all actions within that controller will be able to stream data to the client in real time, like the following code:
<pre>
class MessageController < ApplicationController
#here we enabled live streaming
include ActionController::Live
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a live streaming message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>
The above code looks exactly the same as the traditional response, except the newly included module ''ActionController::Live''. Now '''data can be streamed to the client immediately whenever write method is called'''. When we run the code above, the web page will print one line “This is a response message!” for every seconds and repeats 8 times.<ref>http://tenderlovemaking.com/2012/07/30/is-it-live.html</ref> Like the image shows below: 
[[File:streaming.gif]]
 
 

==Server-Sent Event==
[https://en.wikipedia.org/wiki/Server-sent_events Server-sent event (SSE)] is a technology where browser can automatically receive update data from a server via [https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol HTTP] connection. Whenever server sends data, the SSE method in the browser will trigger an event.The SSE EventSource API is standardized as part of [https://en.wikipedia.org/wiki/HTML5 HTML5] by the [https://en.wikipedia.org/wiki/World_Wide_Web_Consortium W3C]. It can be used together with the Live API to achieve full-duplex communication.<ref>https://en.wikipedia.org/wiki/Server-sent_events</ref>
 
A simple SSE looks like the following :
<pre>
require 'json'
module ServerSide
class SSE
def initialize io
@io = io
end

def write object, options = {}
options.each do |k,v|
@io.write "#{k}: #{v}n"
end
@io.write "data: #{object}nn"
end

def close
@io.close
end
end
end
</pre>
This module assigns the I/O stream object to a hash and converts it into a key-value pair so that it is easy to read, store, and send it back in JSON format.
 
 
Now we can wrap stream object inside the SSE class. By doing this, we need to include SSE module inside the controller, so that the opening and closing of connections will be managed by SSE module. And we also add the ensure clause to make sure that the connection will always be closed after execution.
<pre>
require 'sse'
class MessagingController < ApplicationController
include ActionController::Live

def stream
response.headers['Content-Type'] = 'text/event-stream'
sse = SSE.new(response.stream)
begin
5.times {
sse.write(“Streaming using SSE!”)
sleep 1
}
ensure
sse.close
end
end
end
</pre>
The code above will print the sentence “Streaming using SSE!” once per second, until the loop ends.
 
 
Here’s another sample showing how to use SSE to stream data<ref>https://github.com/rails/rails/blob/6061c540ac7880233a6e32de85cec72c20ed8778/actionpack/lib/action_controller/metal/live.rb</ref>:

# This class provides the ability to write an SSE (Server Sent Event)
# to an IO stream. The class is initialized with a stream and can be used
# to either write a JSON string or an object which can be converted to JSON.
#
# Writing an object will convert it into standard SSE format with whatever
# options you have configured. You may choose to set the following options:
#
# 1) Event. If specified, an event with this name will be dispatched on
# the browser.
# 2) Retry. The reconnection time in milliseconds used when attempting
# to send the event.
# 3) Id. If the connection dies while sending an SSE to the browser, then
# the server will receive a +Last-Event-ID+ header with value equal to +id+.
#
# After setting an option in the constructor of the SSE object, all future
# SSEs sent across the stream will use those options unless overridden.
#
# Example Usage:
#
# class MyController < ActionController::Base
# include ActionController::Live
#
# def index
# response.headers['Content-Type'] = 'text/event-stream'
# sse = SSE.new(response.stream, retry: 300, event: "event-name")
# sse.write({ name: 'John'})
# sse.write({ name: 'John'}, id: 10)
# sse.write({ name: 'John'}, id: 10, event: "other-event")
# sse.write({ name: 'John'}, id: 10, event: "other-event", retry: 500)
# ensure
# sse.close
# end
# end
#
# Note: SSEs are not currently supported by IE. However, they are supported
# by Chrome, Firefox, Opera, and Safari.

Note: By default Rails provides a one-way communication process by writing the stream to the client when data is available. However, if we can add SSEs, we can enable events and responses, thus making it two-way.
 
 

==Benefit of live streaming==
1.Send partial responses to the client immediately.
 
2.Using Server-sent events, the ability to create chat clients, push notifications, and real-time feeds are available within Rails itself
 
3.Continuously inform the user about the progress.
See example below<ref>http://blog.phusion.nl/2012/08/03/why-rails-4-live-streaming-is-a-big-deal/</ref>:
<pre>
def big_work
work = WorkModel.new
while !work.done?
work.do_some_calculations
response.stream.write "Progress: #{work.progress}%\n"
end
response.stream.close
end
</pre>
 

='''Troubleshooting'''=
When running streaming programs, we need to install [http://puma.io/ PUMA] to substitute the original [https://en.wikipedia.org/wiki/WEBrick WEBrick] server, because puma can handle concurrency better. In order to do this, we need to add the following line to Gemfile:
<pre>
gem 'puma'
</pre>
 
After installed puma, if we start rails server, the console will print the following output:
<pre>
"C:\Program Files (x86)\JetBrains\RubyMine 7.0.2\bin\runnerw.exe" C:\RailsInstaller\Ruby2.0.0\bin\ruby.exe -e $stdout.sync=true;$stderr.sync=true;load($0=ARGV.shift) D:/Cloud/Coding/RubymineProjects/LiveStreamingExample/bin/rails server -b 127.0.0.1 -p 3000 -e development
=> Booting Puma
=> Rails 4.1.8 application starting in development on http://127.0.0.1:3000
=> Run `rails server -h` for more startup options
=> Ctrl-C to shutdown server
Puma 2.11.0 starting...
* Min threads: 0, max threads: 16
* Environment: development
* Listening on tcp://127.0.0.1:3000
</pre>
This means that PUMA is set as our default server and successfully booted.
 
 
We encountered failure on Windows when trying to install PUMA, the console printed the following error:
<pre>
Building native extensions. This could take a while...
ERROR: Error installing rails:
ERROR: Failed to build gem native extension.

/Users/WillieTran/.rvm/rubies/ruby-2.0.0-p247/bin/ruby extconf.rb
*** extconf.rb failed ***

Could not create Makefile due to some reason, probably lack of necessary
libraries and/or headers. Check the mkmf.log file for more details. You may
need configuration options.
</pre>
 
To solve this problem, we need to install [https://www.openssl.org/ openssl] for windows. And then run the following command<ref>https://github.com/hicknhack-software/rails-disco/wiki/Installing-puma-on-windows</ref>:
<pre>
gem install puma -- --with-opt-dir=c:\openssl
</pre>
 

='''References'''=
<references>

CSC/ECE 517 Spring 2015/ch1a 12 LS

2015-02-16T03:01:35Z

Hwang40: /* Troubleshooting */

Live Streaming

='''Introduction'''=
The purpose of live streaming is to send data over the Internet in real-time. This requires a data source, a data encoder, a media publisher and a proper network.

In Rails, the concept of streaming first appeared in [http://weblog.rubyonrails.org/releases/ version 3.1], and is further optimized in Rails 4. Now Rails 4 supports live streaming, which uses handling I/O object and can send data from server to client in real-time.

__TOC__

='''Details'''=
==Template streaming==
Since Rail 3.1, [http://api.rubyonrails.org/classes/ActionController/Streaming.html ''::Streaming''] module has been added to ActionController. For example, the loading progress in a traditional Rails client-side may look like this<ref> https://github.com/oggy/template_streaming</ref>:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:slow-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 1 progress without streaming</div>
This is because that layouts are rendered before the content, thus causing control flow to be altered to render the page in the order that the client needs (layout first).But for some resources which are static, if they could be loaded while waiting for the server response, a lot of time can be saved.
 
 
The module ''::Streaming'' inverts the regular Rails process of rendering the layout and template. Using ''::Streaming'', Rails will render template first and then layout. It will first run method yield and load up the template, and then renders the assets and layouts. In this way, the progress with streaming looks like this:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:fast-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 2 progress with streaming</div>

===When to use streaming===
For actions like new or edit, it may not be that necessary to use streaming. But for expensive actions like database query and generation of large amount of data, streaming can be extremely important and effective. Take the following action as an example:
<pre>
def storyboard
@stories = Story.all
@developers = Page.all
@comments = Comment.all
end
</pre>

Since most of the queries here are executing in the controller, it might take a while before them to finish, thus causing the front end (user) to wait for long. We can solve this problem and enhance user experience, the above code can be rewrite as follows,
<pre>
def storyboard
# Allow lazy execution of the queries
@stories = Story.all
@developers = Page.all
@comments = Comment.all
render :stream => true
end
</pre>
(Note: '':Streaming'' only works with templates. It doesn’t work with :json or :xml)<ref>http://apidock.com/rails/ActionController/Streaming</ref>
 
 

===Tweaking views===
When using streaming, instance variables that are set in the template and are used in the layout won't need some tweak to work well. This is done by using content_for, provide and yield.
Here’s a simple example where the layout expects the template to tell which title to use<ref>http://apidock.com/rails/ActionController/Streaming</ref>:
<pre>
<html>
<head><title><%= yield :title %></title></head>
<body><%= yield %></body>
</html>
</pre>

Instead of yield, we can also use content_for to specify the title:
<pre>
<%= content_for :title, "Main" %>
Hello
</pre>

And the final result would be:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>

However, if content_for is called several times, the final result would have all calls concatenated.
For instance, if we have the following template:
<pre>
<%= content_for :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>

The final result would be:
<pre>
<html>
<head><title>Main page</title></head>
<body>Hello</body>
</html>
</pre>
This means that, if you have yield '':title'' in your layout and you want to use streaming, you would have to render the whole template (and eventually trigger all queries) before streaming the title and all assets, which kills the purpose of streaming. For this reason Rails 3.1 introduces a new helper called provide that does the same as content_for but tells the layout to stop searching for other entries and continue rendering.

For instance, the template above using provide would be:
<pre>
<%= provide :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>
Giving:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>
That said, when streaming, you need to properly check your templates and choose when to use provide and content_for.
 
 

==Live Streaming==
The module [http://api.rubyonrails.org/classes/ActionController/Live.html ''::Live''] was then added to ActionController at Rail 4. The difference between Streaming and Live is that Streaming is implicitly included whenever you create a new controller class, while ''::Live'' requires explicit include.

===Traditional Response===
In this type of communication between server and client, data will be buffered until all render works are finished, and everything will be sent to the client at the same time. And the stream object behaves just like an IO object. Here’s the sample code:
<pre>
class MessageController < ApplicationController
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a response message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>

When we run the code above, the web page will '''keep loading and remain blank''' for 8 seconds, and shows all 8 lines of “This is a response message!” altogether, as with the following image shows: 
[[File:nostreaming.gif]]

===Live Streaming===
In order to enable live streaming, we need to include a module named ''ActionController::Live''. When this module is mixed into the controller, all actions within that controller will be able to stream data to the client in real time, like the following code:
<pre>
class MessageController < ApplicationController
#here we enabled live streaming
include ActionController::Live
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a live streaming message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>
The above code looks exactly the same as the traditional response, except the newly included module ''ActionController::Live''. Now '''data can be streamed to the client immediately whenever write method is called'''. When we run the code above, the web page will print one line “This is a response message!” for every seconds and repeats 8 times.<ref>http://tenderlovemaking.com/2012/07/30/is-it-live.html</ref> Like the image shows below: 
[[File:streaming.gif]]
 
 

==Server-Sent Event==
Server-sent event (SSE) is a technology where browser can automatically receive update data from a server via HTTP connection. Whenever server sends data, the SSE method in the browser will trigger an event.The SSE EventSource API is standardized as part of HTML5 by the W3C. It can be used together with the Live API to achieve full-duplex communication.<ref>https://en.wikipedia.org/wiki/Server-sent_events</ref>
 
A simple SSE looks like the following :
<pre>
require 'json'
module ServerSide
class SSE
def initialize io
@io = io
end

def write object, options = {}
options.each do |k,v|
@io.write "#{k}: #{v}n"
end
@io.write "data: #{object}nn"
end

def close
@io.close
end
end
end
</pre>
This module assigns the I/O stream object to a hash and converts it into a key-value pair so that it is easy to read, store, and send it back in JSON format.
 
 
Now we can wrap stream object inside the SSE class. By doing this, we need to include SSE module inside the controller, so that the opening and closing of connections will be managed by SSE module. And we also add the ensure clause to make sure that the connection will always be closed after execution.
<pre>
require 'sse'
class MessagingController < ApplicationController
include ActionController::Live

def stream
response.headers['Content-Type'] = 'text/event-stream'
sse = SSE.new(response.stream)
begin
5.times {
sse.write(“Streaming using SSE!”)
sleep 1
}
ensure
sse.close
end
end
end
</pre>
The code above will print the sentence “Streaming using SSE!” once per second, until the loop ends.
 
 
Here’s another sample showing how to use SSE to stream data<ref>https://github.com/rails/rails/blob/6061c540ac7880233a6e32de85cec72c20ed8778/actionpack/lib/action_controller/metal/live.rb</ref>:

# This class provides the ability to write an SSE (Server Sent Event)
# to an IO stream. The class is initialized with a stream and can be used
# to either write a JSON string or an object which can be converted to JSON.
#
# Writing an object will convert it into standard SSE format with whatever
# options you have configured. You may choose to set the following options:
#
# 1) Event. If specified, an event with this name will be dispatched on
# the browser.
# 2) Retry. The reconnection time in milliseconds used when attempting
# to send the event.
# 3) Id. If the connection dies while sending an SSE to the browser, then
# the server will receive a +Last-Event-ID+ header with value equal to +id+.
#
# After setting an option in the constructor of the SSE object, all future
# SSEs sent across the stream will use those options unless overridden.
#
# Example Usage:
#
# class MyController < ActionController::Base
# include ActionController::Live
#
# def index
# response.headers['Content-Type'] = 'text/event-stream'
# sse = SSE.new(response.stream, retry: 300, event: "event-name")
# sse.write({ name: 'John'})
# sse.write({ name: 'John'}, id: 10)
# sse.write({ name: 'John'}, id: 10, event: "other-event")
# sse.write({ name: 'John'}, id: 10, event: "other-event", retry: 500)
# ensure
# sse.close
# end
# end
#
# Note: SSEs are not currently supported by IE. However, they are supported
# by Chrome, Firefox, Opera, and Safari.

Note: By default Rails provides a one-way communication process by writing the stream to the client when data is available. However, if we can add SSEs, we can enable events and responses, thus making it two-way.
 
 

==Benefit of live streaming==
1.Send partial responses to the client immediately.
 
2.Using Server-sent events, the ability to create chat clients, push notifications, and real-time feeds are available within Rails itself
 
3.Continuously inform the user about the progress.
See example below<ref>http://blog.phusion.nl/2012/08/03/why-rails-4-live-streaming-is-a-big-deal/</ref>:
<pre>
def big_work
work = WorkModel.new
while !work.done?
work.do_some_calculations
response.stream.write "Progress: #{work.progress}%\n"
end
response.stream.close
end
</pre>
 

='''Troubleshooting'''=
When running streaming programs, we need to install [http://puma.io/ PUMA] to substitute the original [https://en.wikipedia.org/wiki/WEBrick WEBrick] server, because puma can handle concurrency better. In order to do this, we need to add the following line to Gemfile:
<pre>
gem 'puma'
</pre>
 
After installed puma, if we start rails server, the console will print the following output:
<pre>
"C:\Program Files (x86)\JetBrains\RubyMine 7.0.2\bin\runnerw.exe" C:\RailsInstaller\Ruby2.0.0\bin\ruby.exe -e $stdout.sync=true;$stderr.sync=true;load($0=ARGV.shift) D:/Cloud/Coding/RubymineProjects/LiveStreamingExample/bin/rails server -b 127.0.0.1 -p 3000 -e development
=> Booting Puma
=> Rails 4.1.8 application starting in development on http://127.0.0.1:3000
=> Run `rails server -h` for more startup options
=> Ctrl-C to shutdown server
Puma 2.11.0 starting...
* Min threads: 0, max threads: 16
* Environment: development
* Listening on tcp://127.0.0.1:3000
</pre>
This means that PUMA is set as our default server and successfully booted.
 
 
We encountered failure on Windows when trying to install PUMA, the console printed the following error:
<pre>
Building native extensions. This could take a while...
ERROR: Error installing rails:
ERROR: Failed to build gem native extension.

/Users/WillieTran/.rvm/rubies/ruby-2.0.0-p247/bin/ruby extconf.rb
*** extconf.rb failed ***

Could not create Makefile due to some reason, probably lack of necessary
libraries and/or headers. Check the mkmf.log file for more details. You may
need configuration options.
</pre>
 
To solve this problem, we need to install [https://www.openssl.org/ openssl] for windows. And then run the following command<ref>https://github.com/hicknhack-software/rails-disco/wiki/Installing-puma-on-windows</ref>:
<pre>
gem install puma -- --with-opt-dir=c:\openssl
</pre>
 

='''References'''=
<references>

CSC/ECE 517 Spring 2015/ch1a 12 LS

2015-02-16T02:55:25Z

Hwang40: /* Tweaking views */

Live Streaming

='''Introduction'''=
The purpose of live streaming is to send data over the Internet in real-time. This requires a data source, a data encoder, a media publisher and a proper network.

In Rails, the concept of streaming first appeared in [http://weblog.rubyonrails.org/releases/ version 3.1], and is further optimized in Rails 4. Now Rails 4 supports live streaming, which uses handling I/O object and can send data from server to client in real-time.

__TOC__

='''Details'''=
==Template streaming==
Since Rail 3.1, [http://api.rubyonrails.org/classes/ActionController/Streaming.html ''::Streaming'' module] has been added to ActionController. For example, the loading progress in a traditional Rails client-side may look like this<ref> https://github.com/oggy/template_streaming</ref>:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:slow-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 1 progress without streaming</div>
This is because that layouts are rendered before the content, thus causing control flow to be altered to render the page in the order that the client needs (layout first).But for some resources which are static, if they could be loaded while waiting for the server response, a lot of time can be saved.
 
 
The module ''::Streaming'' inverts the regular Rails process of rendering the layout and template. Using ''::Streaming'', Rails will render template first and then layout. It will first run method yield and load up the template, and then renders the assets and layouts. In this way, the progress with streaming looks like this:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:fast-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 2 progress with streaming</div>

===When to use streaming===
For actions like new or edit, it may not be that necessary to use streaming. But for expensive actions like database query and generation of large amount of data, streaming can be extremely important and effective. Take the following action as an example:
<pre>
def storyboard
@stories = Story.all
@developers = Page.all
@comments = Comment.all
end
</pre>

Since most of the queries here are executing in the controller, it might take a while before them to finish, thus causing the front end (user) to wait for long. We can solve this problem and enhance user experience, the above code can be rewrite as follows,
<pre>
def storyboard
# Allow lazy execution of the queries
@stories = Story.all
@developers = Page.all
@comments = Comment.all
render :stream => true
end
</pre>
(Note: '':Streaming'' only works with templates. It doesn’t work with :json or :xml)<ref>http://apidock.com/rails/ActionController/Streaming</ref>
 
 

===Tweaking views===
When using streaming, instance variables that are set in the template and are used in the layout won't need some tweak to work well. This is done by using content_for, provide and yield.
Here’s a simple example where the layout expects the template to tell which title to use<ref>http://apidock.com/rails/ActionController/Streaming</ref>:
<pre>
<html>
<head><title><%= yield :title %></title></head>
<body><%= yield %></body>
</html>
</pre>

Instead of yield, we can also use content_for to specify the title:
<pre>
<%= content_for :title, "Main" %>
Hello
</pre>

And the final result would be:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>

However, if content_for is called several times, the final result would have all calls concatenated.
For instance, if we have the following template:
<pre>
<%= content_for :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>

The final result would be:
<pre>
<html>
<head><title>Main page</title></head>
<body>Hello</body>
</html>
</pre>
This means that, if you have yield '':title'' in your layout and you want to use streaming, you would have to render the whole template (and eventually trigger all queries) before streaming the title and all assets, which kills the purpose of streaming. For this reason Rails 3.1 introduces a new helper called provide that does the same as content_for but tells the layout to stop searching for other entries and continue rendering.

For instance, the template above using provide would be:
<pre>
<%= provide :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>
Giving:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>
That said, when streaming, you need to properly check your templates and choose when to use provide and content_for.
 
 

==Live Streaming==
The module [http://api.rubyonrails.org/classes/ActionController/Live.html ''::Live''] was then added to ActionController at Rail 4. The difference between Streaming and Live is that Streaming is implicitly included whenever you create a new controller class, while ''::Live'' requires explicit include.

===Traditional Response===
In this type of communication between server and client, data will be buffered until all render works are finished, and everything will be sent to the client at the same time. And the stream object behaves just like an IO object. Here’s the sample code:
<pre>
class MessageController < ApplicationController
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a response message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>

When we run the code above, the web page will '''keep loading and remain blank''' for 8 seconds, and shows all 8 lines of “This is a response message!” altogether, as with the following image shows: 
[[File:nostreaming.gif]]

===Live Streaming===
In order to enable live streaming, we need to include a module named ''ActionController::Live''. When this module is mixed into the controller, all actions within that controller will be able to stream data to the client in real time, like the following code:
<pre>
class MessageController < ApplicationController
#here we enabled live streaming
include ActionController::Live
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a live streaming message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>
The above code looks exactly the same as the traditional response, except the newly included module ''ActionController::Live''. Now '''data can be streamed to the client immediately whenever write method is called'''. When we run the code above, the web page will print one line “This is a response message!” for every seconds and repeats 8 times.<ref>http://tenderlovemaking.com/2012/07/30/is-it-live.html</ref> Like the image shows below: 
[[File:streaming.gif]]
 
 

==Server-Sent Event==
Server-sent event (SSE) is a technology where browser can automatically receive update data from a server via HTTP connection. Whenever server sends data, the SSE method in the browser will trigger an event.The SSE EventSource API is standardized as part of HTML5 by the W3C. It can be used together with the Live API to achieve full-duplex communication.<ref>https://en.wikipedia.org/wiki/Server-sent_events</ref>
 
A simple SSE looks like the following :
<pre>
require 'json'
module ServerSide
class SSE
def initialize io
@io = io
end

def write object, options = {}
options.each do |k,v|
@io.write "#{k}: #{v}n"
end
@io.write "data: #{object}nn"
end

def close
@io.close
end
end
end
</pre>
This module assigns the I/O stream object to a hash and converts it into a key-value pair so that it is easy to read, store, and send it back in JSON format.
 
 
Now we can wrap stream object inside the SSE class. By doing this, we need to include SSE module inside the controller, so that the opening and closing of connections will be managed by SSE module. And we also add the ensure clause to make sure that the connection will always be closed after execution.
<pre>
require 'sse'
class MessagingController < ApplicationController
include ActionController::Live

def stream
response.headers['Content-Type'] = 'text/event-stream'
sse = SSE.new(response.stream)
begin
5.times {
sse.write(“Streaming using SSE!”)
sleep 1
}
ensure
sse.close
end
end
end
</pre>
The code above will print the sentence “Streaming using SSE!” once per second, until the loop ends.
 
 
Here’s another sample showing how to use SSE to stream data<ref>https://github.com/rails/rails/blob/6061c540ac7880233a6e32de85cec72c20ed8778/actionpack/lib/action_controller/metal/live.rb</ref>:

# This class provides the ability to write an SSE (Server Sent Event)
# to an IO stream. The class is initialized with a stream and can be used
# to either write a JSON string or an object which can be converted to JSON.
#
# Writing an object will convert it into standard SSE format with whatever
# options you have configured. You may choose to set the following options:
#
# 1) Event. If specified, an event with this name will be dispatched on
# the browser.
# 2) Retry. The reconnection time in milliseconds used when attempting
# to send the event.
# 3) Id. If the connection dies while sending an SSE to the browser, then
# the server will receive a +Last-Event-ID+ header with value equal to +id+.
#
# After setting an option in the constructor of the SSE object, all future
# SSEs sent across the stream will use those options unless overridden.
#
# Example Usage:
#
# class MyController < ActionController::Base
# include ActionController::Live
#
# def index
# response.headers['Content-Type'] = 'text/event-stream'
# sse = SSE.new(response.stream, retry: 300, event: "event-name")
# sse.write({ name: 'John'})
# sse.write({ name: 'John'}, id: 10)
# sse.write({ name: 'John'}, id: 10, event: "other-event")
# sse.write({ name: 'John'}, id: 10, event: "other-event", retry: 500)
# ensure
# sse.close
# end
# end
#
# Note: SSEs are not currently supported by IE. However, they are supported
# by Chrome, Firefox, Opera, and Safari.

Note: By default Rails provides a one-way communication process by writing the stream to the client when data is available. However, if we can add SSEs, we can enable events and responses, thus making it two-way.
 
 

==Benefit of live streaming==
1.Send partial responses to the client immediately.
 
2.Using Server-sent events, the ability to create chat clients, push notifications, and real-time feeds are available within Rails itself
 
3.Continuously inform the user about the progress.
See example below<ref>http://blog.phusion.nl/2012/08/03/why-rails-4-live-streaming-is-a-big-deal/</ref>:
<pre>
def big_work
work = WorkModel.new
while !work.done?
work.do_some_calculations
response.stream.write "Progress: #{work.progress}%\n"
end
response.stream.close
end
</pre>
 

='''Troubleshooting'''=
When running streaming programs, we need to install [http://puma.io/ PUMA] to substitute the original WEBrick server, because puma can handle concurrency better. In order to do this, we need to add the following line to Gemfile:
<pre>
gem 'puma'
</pre>
 
After installed puma, if we start rails server, the console will print the following output:
<pre>
"C:\Program Files (x86)\JetBrains\RubyMine 7.0.2\bin\runnerw.exe" C:\RailsInstaller\Ruby2.0.0\bin\ruby.exe -e $stdout.sync=true;$stderr.sync=true;load($0=ARGV.shift) D:/Cloud/Coding/RubymineProjects/LiveStreamingExample/bin/rails server -b 127.0.0.1 -p 3000 -e development
=> Booting Puma
=> Rails 4.1.8 application starting in development on http://127.0.0.1:3000
=> Run `rails server -h` for more startup options
=> Ctrl-C to shutdown server
Puma 2.11.0 starting...
* Min threads: 0, max threads: 16
* Environment: development
* Listening on tcp://127.0.0.1:3000
</pre>
This means that PUMA is set as our default server and successfully booted.
 
 
We encountered failure on Windows when trying to install PUMA, the console printed the following error:
<pre>
Building native extensions. This could take a while...
ERROR: Error installing rails:
ERROR: Failed to build gem native extension.

/Users/WillieTran/.rvm/rubies/ruby-2.0.0-p247/bin/ruby extconf.rb
*** extconf.rb failed ***

Could not create Makefile due to some reason, probably lack of necessary
libraries and/or headers. Check the mkmf.log file for more details. You may
need configuration options.
</pre>
 
To solve this problem, we need to install [https://www.openssl.org/ openssl] for windows. And then run the following command<ref>https://github.com/hicknhack-software/rails-disco/wiki/Installing-puma-on-windows</ref>:
<pre>
gem install puma -- --with-opt-dir=c:\openssl
</pre>
 

='''References'''=
<references>

CSC/ECE 517 Spring 2015/ch1a 12 LS

2015-02-16T02:54:28Z

Hwang40: /* Live Streaming */

Live Streaming

='''Introduction'''=
The purpose of live streaming is to send data over the Internet in real-time. This requires a data source, a data encoder, a media publisher and a proper network.

In Rails, the concept of streaming first appeared in [http://weblog.rubyonrails.org/releases/ version 3.1], and is further optimized in Rails 4. Now Rails 4 supports live streaming, which uses handling I/O object and can send data from server to client in real-time.

__TOC__

='''Details'''=
==Template streaming==
Since Rail 3.1, [http://api.rubyonrails.org/classes/ActionController/Streaming.html ''::Streaming'' module] has been added to ActionController. For example, the loading progress in a traditional Rails client-side may look like this<ref> https://github.com/oggy/template_streaming</ref>:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:slow-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 1 progress without streaming</div>
This is because that layouts are rendered before the content, thus causing control flow to be altered to render the page in the order that the client needs (layout first).But for some resources which are static, if they could be loaded while waiting for the server response, a lot of time can be saved.
 
 
The module ''::Streaming'' inverts the regular Rails process of rendering the layout and template. Using ''::Streaming'', Rails will render template first and then layout. It will first run method yield and load up the template, and then renders the assets and layouts. In this way, the progress with streaming looks like this:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:fast-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 2 progress with streaming</div>

===When to use streaming===
For actions like new or edit, it may not be that necessary to use streaming. But for expensive actions like database query and generation of large amount of data, streaming can be extremely important and effective. Take the following action as an example:
<pre>
def storyboard
@stories = Story.all
@developers = Page.all
@comments = Comment.all
end
</pre>

Since most of the queries here are executing in the controller, it might take a while before them to finish, thus causing the front end (user) to wait for long. We can solve this problem and enhance user experience, the above code can be rewrite as follows,
<pre>
def storyboard
# Allow lazy execution of the queries
@stories = Story.all
@developers = Page.all
@comments = Comment.all
render :stream => true
end
</pre>
(Note: '':Streaming'' only works with templates. It doesn’t work with :json or :xml)<ref>http://apidock.com/rails/ActionController/Streaming</ref>
 
 

===Tweaking views===
When using streaming, instance variables that are set in the template and are used in the layout won’t need some tweak to work well. This is done by using content_for, provide and yield.
Here’s a simple example where the layout expects the template to tell which title to use<ref>http://apidock.com/rails/ActionController/Streaming</ref>:
<pre>
<html>
<head><title><%= yield :title %></title></head>
<body><%= yield %></body>
</html>
</pre>

Instead of yield, we can also use content_for to specify the title:
<pre>
<%= content_for :title, "Main" %>
Hello
</pre>

And the final result would be:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>

However, if content_for is called several times, the final result would have all calls concatenated.
For instance, if we have the following template:
<pre>
<%= content_for :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>

The final result would be:
<pre>
<html>
<head><title>Main page</title></head>
<body>Hello</body>
</html>
</pre>
This means that, if you have yield '':title'' in your layout and you want to use streaming, you would have to render the whole template (and eventually trigger all queries) before streaming the title and all assets, which kills the purpose of streaming. For this reason Rails 3.1 introduces a new helper called provide that does the same as content_for but tells the layout to stop searching for other entries and continue rendering.

For instance, the template above using provide would be:
<pre>
<%= provide :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>
Giving:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>
That said, when streaming, you need to properly check your templates and choose when to use provide and content_for.
 
 

==Live Streaming==
The module [http://api.rubyonrails.org/classes/ActionController/Live.html ''::Live''] was then added to ActionController at Rail 4. The difference between Streaming and Live is that Streaming is implicitly included whenever you create a new controller class, while ''::Live'' requires explicit include.

===Traditional Response===
In this type of communication between server and client, data will be buffered until all render works are finished, and everything will be sent to the client at the same time. And the stream object behaves just like an IO object. Here’s the sample code:
<pre>
class MessageController < ApplicationController
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a response message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>

When we run the code above, the web page will '''keep loading and remain blank''' for 8 seconds, and shows all 8 lines of “This is a response message!” altogether, as with the following image shows: 
[[File:nostreaming.gif]]

===Live Streaming===
In order to enable live streaming, we need to include a module named ''ActionController::Live''. When this module is mixed into the controller, all actions within that controller will be able to stream data to the client in real time, like the following code:
<pre>
class MessageController < ApplicationController
#here we enabled live streaming
include ActionController::Live
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a live streaming message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>
The above code looks exactly the same as the traditional response, except the newly included module ''ActionController::Live''. Now '''data can be streamed to the client immediately whenever write method is called'''. When we run the code above, the web page will print one line “This is a response message!” for every seconds and repeats 8 times.<ref>http://tenderlovemaking.com/2012/07/30/is-it-live.html</ref> Like the image shows below: 
[[File:streaming.gif]]
 
 

==Server-Sent Event==
Server-sent event (SSE) is a technology where browser can automatically receive update data from a server via HTTP connection. Whenever server sends data, the SSE method in the browser will trigger an event.The SSE EventSource API is standardized as part of HTML5 by the W3C. It can be used together with the Live API to achieve full-duplex communication.<ref>https://en.wikipedia.org/wiki/Server-sent_events</ref>
 
A simple SSE looks like the following :
<pre>
require 'json'
module ServerSide
class SSE
def initialize io
@io = io
end

def write object, options = {}
options.each do |k,v|
@io.write "#{k}: #{v}n"
end
@io.write "data: #{object}nn"
end

def close
@io.close
end
end
end
</pre>
This module assigns the I/O stream object to a hash and converts it into a key-value pair so that it is easy to read, store, and send it back in JSON format.
 
 
Now we can wrap stream object inside the SSE class. By doing this, we need to include SSE module inside the controller, so that the opening and closing of connections will be managed by SSE module. And we also add the ensure clause to make sure that the connection will always be closed after execution.
<pre>
require 'sse'
class MessagingController < ApplicationController
include ActionController::Live

def stream
response.headers['Content-Type'] = 'text/event-stream'
sse = SSE.new(response.stream)
begin
5.times {
sse.write(“Streaming using SSE!”)
sleep 1
}
ensure
sse.close
end
end
end
</pre>
The code above will print the sentence “Streaming using SSE!” once per second, until the loop ends.
 
 
Here’s another sample showing how to use SSE to stream data<ref>https://github.com/rails/rails/blob/6061c540ac7880233a6e32de85cec72c20ed8778/actionpack/lib/action_controller/metal/live.rb</ref>:

# This class provides the ability to write an SSE (Server Sent Event)
# to an IO stream. The class is initialized with a stream and can be used
# to either write a JSON string or an object which can be converted to JSON.
#
# Writing an object will convert it into standard SSE format with whatever
# options you have configured. You may choose to set the following options:
#
# 1) Event. If specified, an event with this name will be dispatched on
# the browser.
# 2) Retry. The reconnection time in milliseconds used when attempting
# to send the event.
# 3) Id. If the connection dies while sending an SSE to the browser, then
# the server will receive a +Last-Event-ID+ header with value equal to +id+.
#
# After setting an option in the constructor of the SSE object, all future
# SSEs sent across the stream will use those options unless overridden.
#
# Example Usage:
#
# class MyController < ActionController::Base
# include ActionController::Live
#
# def index
# response.headers['Content-Type'] = 'text/event-stream'
# sse = SSE.new(response.stream, retry: 300, event: "event-name")
# sse.write({ name: 'John'})
# sse.write({ name: 'John'}, id: 10)
# sse.write({ name: 'John'}, id: 10, event: "other-event")
# sse.write({ name: 'John'}, id: 10, event: "other-event", retry: 500)
# ensure
# sse.close
# end
# end
#
# Note: SSEs are not currently supported by IE. However, they are supported
# by Chrome, Firefox, Opera, and Safari.

Note: By default Rails provides a one-way communication process by writing the stream to the client when data is available. However, if we can add SSEs, we can enable events and responses, thus making it two-way.
 
 

==Benefit of live streaming==
1.Send partial responses to the client immediately.
 
2.Using Server-sent events, the ability to create chat clients, push notifications, and real-time feeds are available within Rails itself
 
3.Continuously inform the user about the progress.
See example below<ref>http://blog.phusion.nl/2012/08/03/why-rails-4-live-streaming-is-a-big-deal/</ref>:
<pre>
def big_work
work = WorkModel.new
while !work.done?
work.do_some_calculations
response.stream.write "Progress: #{work.progress}%\n"
end
response.stream.close
end
</pre>
 

='''Troubleshooting'''=
When running streaming programs, we need to install [http://puma.io/ PUMA] to substitute the original WEBrick server, because puma can handle concurrency better. In order to do this, we need to add the following line to Gemfile:
<pre>
gem 'puma'
</pre>
 
After installed puma, if we start rails server, the console will print the following output:
<pre>
"C:\Program Files (x86)\JetBrains\RubyMine 7.0.2\bin\runnerw.exe" C:\RailsInstaller\Ruby2.0.0\bin\ruby.exe -e $stdout.sync=true;$stderr.sync=true;load($0=ARGV.shift) D:/Cloud/Coding/RubymineProjects/LiveStreamingExample/bin/rails server -b 127.0.0.1 -p 3000 -e development
=> Booting Puma
=> Rails 4.1.8 application starting in development on http://127.0.0.1:3000
=> Run `rails server -h` for more startup options
=> Ctrl-C to shutdown server
Puma 2.11.0 starting...
* Min threads: 0, max threads: 16
* Environment: development
* Listening on tcp://127.0.0.1:3000
</pre>
This means that PUMA is set as our default server and successfully booted.
 
 
We encountered failure on Windows when trying to install PUMA, the console printed the following error:
<pre>
Building native extensions. This could take a while...
ERROR: Error installing rails:
ERROR: Failed to build gem native extension.

/Users/WillieTran/.rvm/rubies/ruby-2.0.0-p247/bin/ruby extconf.rb
*** extconf.rb failed ***

Could not create Makefile due to some reason, probably lack of necessary
libraries and/or headers. Check the mkmf.log file for more details. You may
need configuration options.
</pre>
 
To solve this problem, we need to install [https://www.openssl.org/ openssl] for windows. And then run the following command<ref>https://github.com/hicknhack-software/rails-disco/wiki/Installing-puma-on-windows</ref>:
<pre>
gem install puma -- --with-opt-dir=c:\openssl
</pre>
 

='''References'''=
<references>

CSC/ECE 517 Spring 2015/ch1a 12 LS

2015-02-16T02:51:45Z

Hwang40: /* Tweaking views */

Live Streaming

='''Introduction'''=
The purpose of live streaming is to send data over the Internet in real-time. This requires a data source, a data encoder, a media publisher and a proper network.

In Rails, the concept of streaming first appeared in [http://weblog.rubyonrails.org/releases/ version 3.1], and is better further optimized along with Rails 4. Now Rails 4 supports live streaming, which uses handling I/O object and can send data from server to client in real-time.

__TOC__

='''Details'''=
==Template streaming==
Since Rail 3.1, [http://api.rubyonrails.org/classes/ActionController/Streaming.html ''::Streaming'' module] has been added to ActionController. For example, the loading progress in a traditional Rails client-side may look like this<ref> https://github.com/oggy/template_streaming</ref>:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:slow-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 1 progress without streaming</div>
This is because that layouts are rendered before the content, thus causing control flow to be altered to render the page in the order that the client needs (layout first).But for some resources which are static, if they could be loaded while waiting for the server response, a lot of time can be saved.
 
 
The module ''::Streaming'' inverts the regular Rails process of rendering the layout and template. Using ''::Streaming'', Rails will render template first and then layout. It will first run method yield and load up the template, and then renders the assets and layouts. In this way, the progress with streaming looks like this:
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">
[[File:fast-profile.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">Figure 2 progress with streaming</div>

===When to use streaming===
For actions like new or edit, it may not be that necessary to use streaming. But for expensive actions like database query and generation of large amount of data, streaming can be extremely important and effective. Take the following action as an example:
<pre>
def storyboard
@stories = Story.all
@developers = Page.all
@comments = Comment.all
end
</pre>

Since most of the queries here are executing in the controller, it might take a while before them to finish, thus causing the front end (user) to wait for long. We can solve this problem and enhance user experience, the above code can be rewrite as follows,
<pre>
def storyboard
# Allow lazy execution of the queries
@stories = Story.all
@developers = Page.all
@comments = Comment.all
render :stream => true
end
</pre>
(Note: '':Streaming'' only works with templates. It doesn’t work with :json or :xml)<ref>http://apidock.com/rails/ActionController/Streaming</ref>
 
 

===Tweaking views===
When using streaming, instance variables that are set in the template and are used in the layout won’t need some tweak to work well. This is done by using content_for, provide and yield.
Here’s a simple example where the layout expects the template to tell which title to use<ref>http://apidock.com/rails/ActionController/Streaming</ref>:
<pre>
<html>
<head><title><%= yield :title %></title></head>
<body><%= yield %></body>
</html>
</pre>

Instead of yield, we can also use content_for to specify the title:
<pre>
<%= content_for :title, "Main" %>
Hello
</pre>

And the final result would be:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>

However, if content_for is called several times, the final result would have all calls concatenated.
For instance, if we have the following template:
<pre>
<%= content_for :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>

The final result would be:
<pre>
<html>
<head><title>Main page</title></head>
<body>Hello</body>
</html>
</pre>
This means that, if you have yield '':title'' in your layout and you want to use streaming, you would have to render the whole template (and eventually trigger all queries) before streaming the title and all assets, which kills the purpose of streaming. For this reason Rails 3.1 introduces a new helper called provide that does the same as content_for but tells the layout to stop searching for other entries and continue rendering.

For instance, the template above using provide would be:
<pre>
<%= provide :title, "Main" %>
Hello
<%= content_for :title, " page" %>
</pre>
Giving:
<pre>
<html>
<head><title>Main</title></head>
<body>Hello</body>
</html>
</pre>
That said, when streaming, you need to properly check your templates and choose when to use provide and content_for.
 
 

==Live Streaming==
The module ''::Live'' was then added to ActionController at Rail 4. The difference between Streaming and Live is that Streaming is implicitly included whenever you create a new controller class, while ::Live requires explicit include.

===Traditional Response===
In this type of communication between server and client, data will be buffered until all render works are finished, and everything will be sent to the client at the same time. And the stream object behaves just like an IO object. Here’s the sample code:
<pre>
class MessageController < ApplicationController
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a response message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>

When we run the code above, the web page will '''keep loading and remain blank''' for 8 seconds, and shows all 8 lines of “This is a response message!” altogether, as with the following image shows: 
[[File:nostreaming.gif]]

===Live Streaming===
In order to enable live streaming, we need to include a module named ActionController::Live. When this module is mixed into the controller, all actions within that controller will be able to stream data to the client in real time, like the following code:
<pre>
class MessageController < ApplicationController
#here we enabled live streaming
include ActionController::Live
def message
response.headers["Content-Type"] = "text/event-stream"
8.times {
response.stream.write "This is a live streaming message!\n"
sleep 1
}
ensure
response.stream.close
end
end
</pre>
The above code looks exactly the same as the traditional response, except the newly included module ActionController::Live. Now '''data can be streamed to the client immediately whenever write method is called'''. When we run the code above, the web page will print one line “This is a response message!” for every seconds and repeats 8 times.<ref>http://tenderlovemaking.com/2012/07/30/is-it-live.html</ref> Like the image shows below: 
[[File:streaming.gif]]
 
 

==Server-Sent Event==
Server-sent event (SSE) is a technology where browser can automatically receive update data from a server via HTTP connection. Whenever server sends data, the SSE method in the browser will trigger an event.The SSE EventSource API is standardized as part of HTML5 by the W3C. It can be used together with the Live API to achieve full-duplex communication.<ref>https://en.wikipedia.org/wiki/Server-sent_events</ref>
 
A simple SSE looks like the following :
<pre>
require 'json'
module ServerSide
class SSE
def initialize io
@io = io
end

def write object, options = {}
options.each do |k,v|
@io.write "#{k}: #{v}n"
end
@io.write "data: #{object}nn"
end

def close
@io.close
end
end
end
</pre>
This module assigns the I/O stream object to a hash and converts it into a key-value pair so that it is easy to read, store, and send it back in JSON format.
 
 
Now we can wrap stream object inside the SSE class. By doing this, we need to include SSE module inside the controller, so that the opening and closing of connections will be managed by SSE module. And we also add the ensure clause to make sure that the connection will always be closed after execution.
<pre>
require 'sse'
class MessagingController < ApplicationController
include ActionController::Live

def stream
response.headers['Content-Type'] = 'text/event-stream'
sse = SSE.new(response.stream)
begin
5.times {
sse.write(“Streaming using SSE!”)
sleep 1
}
ensure
sse.close
end
end
end
</pre>
The code above will print the sentence “Streaming using SSE!” once per second, until the loop ends.
 
 
Here’s another sample showing how to use SSE to stream data<ref>https://github.com/rails/rails/blob/6061c540ac7880233a6e32de85cec72c20ed8778/actionpack/lib/action_controller/metal/live.rb</ref>:

# This class provides the ability to write an SSE (Server Sent Event)
# to an IO stream. The class is initialized with a stream and can be used
# to either write a JSON string or an object which can be converted to JSON.
#
# Writing an object will convert it into standard SSE format with whatever
# options you have configured. You may choose to set the following options:
#
# 1) Event. If specified, an event with this name will be dispatched on
# the browser.
# 2) Retry. The reconnection time in milliseconds used when attempting
# to send the event.
# 3) Id. If the connection dies while sending an SSE to the browser, then
# the server will receive a +Last-Event-ID+ header with value equal to +id+.
#
# After setting an option in the constructor of the SSE object, all future
# SSEs sent across the stream will use those options unless overridden.
#
# Example Usage:
#
# class MyController < ActionController::Base
# include ActionController::Live
#
# def index
# response.headers['Content-Type'] = 'text/event-stream'
# sse = SSE.new(response.stream, retry: 300, event: "event-name")
# sse.write({ name: 'John'})
# sse.write({ name: 'John'}, id: 10)
# sse.write({ name: 'John'}, id: 10, event: "other-event")
# sse.write({ name: 'John'}, id: 10, event: "other-event", retry: 500)
# ensure
# sse.close
# end
# end
#
# Note: SSEs are not currently supported by IE. However, they are supported
# by Chrome, Firefox, Opera, and Safari.

Note: By default Rails provides a one-way communication process by writing the stream to the client when data is available. However, if we can add SSEs, we can enable events and responses, thus making it two-way.
 
 

==Benefit of live streaming==
1.Send partial responses to the client immediately.
 
2.Using Server-sent events, the ability to create chat clients, push notifications, and real-time feeds are available within Rails itself
 
3.Continuously inform the user about the progress.
See example below<ref>http://blog.phusion.nl/2012/08/03/why-rails-4-live-streaming-is-a-big-deal/</ref>:
<pre>
def big_work
work = WorkModel.new
while !work.done?
work.do_some_calculations
response.stream.write "Progress: #{work.progress}%\n"
end
response.stream.close
end
</pre>
 

='''Troubleshooting'''=
When running streaming programs, we need to install [http://puma.io/ PUMA] to substitute the original WEBrick server, because puma can handle concurrency better. In order to do this, we need to add the following line to Gemfile:
<pre>
gem 'puma'
</pre>
 
After installed puma, if we start rails server, the console will print the following output:
<pre>
"C:\Program Files (x86)\JetBrains\RubyMine 7.0.2\bin\runnerw.exe" C:\RailsInstaller\Ruby2.0.0\bin\ruby.exe -e $stdout.sync=true;$stderr.sync=true;load($0=ARGV.shift) D:/Cloud/Coding/RubymineProjects/LiveStreamingExample/bin/rails server -b 127.0.0.1 -p 3000 -e development
=> Booting Puma
=> Rails 4.1.8 application starting in development on http://127.0.0.1:3000
=> Run `rails server -h` for more startup options
=> Ctrl-C to shutdown server
Puma 2.11.0 starting...
* Min threads: 0, max threads: 16
* Environment: development
* Listening on tcp://127.0.0.1:3000
</pre>
This means that PUMA is set as our default server and successfully booted.
 
 
We encountered failure on Windows when trying to install PUMA, the console printed the following error:
<pre>
Building native extensions. This could take a while...
ERROR: Error installing rails:
ERROR: Failed to build gem native extension.

/Users/WillieTran/.rvm/rubies/ruby-2.0.0-p247/bin/ruby extconf.rb
*** extconf.rb failed ***

Could not create Makefile due to some reason, probably lack of necessary
libraries and/or headers. Check the mkmf.log file for more details. You may
need configuration options.
</pre>
 
To solve this problem, we need to install [https://www.openssl.org/ openssl] for windows. And then run the following command<ref>https://github.com/hicknhack-software/rails-disco/wiki/Installing-puma-on-windows</ref>:
<pre>
gem install puma -- --with-opt-dir=c:\openssl
</pre>
 

='''References'''=
<references>