#summary Project Documentation for Social Features for Melange(GSoC2010)
#labels Phase-Design,Contents-Draft,Importance-Details

<wiki:toc max_depth="3" />

= Introduction =

  This document will be used to documents the progress and details of the Social Features (GSoC 2010) project for Melange. 


= Project Design and Implementation =

== Main Feature 1: Tabbed User Pages ==

===Overview===
User Page feature will be used by each user to share information about 
themselves with the rest of the GSoC community. The UI of this feature is designed with tabs, 
hence users will remain on a single page while navigating between multiple tabs. The details of this feature's design and implementation are as follows.

The tabs of the user page will be as follows:
   * Profile
   * Project
   * My Stuff (to be renamed later)

===Workflow===

Workflow for Users: 
The workflow for using this feature is largely similar for all user roles in the soc framework, with some differences for the program and organization admins.

Workflow for Student, Mentor, Organization Admin User roles

    
    # User receives acceptance notification email that they have been accepted to participate in the program. A short message is appended to this email, mentioning that users can now update their respective user pages on Melange as well as view other users’ pages.
    # There are two possibilities from here:
      # If users click the link, they are redirected to the profile tab of their user page, where they see their partially filled profile based on current user information provided at sign up (i.e. name, current/past user roles).
      # If they do not click on the email link, whenever they next log into Melange, they will see ‘User Page’ on their sidebar under the ‘User’ tab. Clicking on this will take them to the profile tab of their user page.
    # They may further update the data on their profile tab, or the other two (Project, MyStuff) tabs by clicking on the ‘Edit User Page’ button to be redirected to a form where they can edit/add data for all the three tabs. 
    # The *Profile tab* will display a subset of the properties from the user_page data model. Profile related information such as contact, personal profile details, education and job information will be shown here.
    # In the *Project tab*, students can fill in details of the project they are working on, while mentors can provide details about the project they are mentoring for. Organization Admins can use this page to provide information about all their student projects. Program Admins can use this page to provide general information about the GSoC/GHOP program itself.
    # In the *My Stuff tab*, users can click on “Add Blog Feed”, to insert their blog url to display updates from their personal blogs using Melange’s RSS widget. For organization and program admins, there is provision to display two blog feeds. This is to display their own personal blog feed as well their organization/program blog feeds.
    # Once changes are saved, users may return anytime during the course of the program to change and save the information on their user pages.
-----
*Suggestion Incorporated* Comment (Madhu): I think there should be only one edit page where they can edit all the three tabs.
-----   
-----
*Suggestion Incorporated* Comment (Madhu): Nope, that makes the interface too complicated and messy. Or if you would like, don't make it generic, but give Admins options for 2 RSS widgets. Thats the max, not more than that for sure.
-----
    
===Data Models===

*UserPage*

This user_page.py will be the master model for this feature which will enclose the three tabs that make up this feature. The other data models created are for multiple-valued properties such as education, jobs, current/past projects, updates and comments.

The Data Models
  * user_page.py
  * education.py (not finalized)
  * job.py (not finalized)
  * project_details.py
  * project_update.py (Nice to have, if time permits)
  * project_comment.py (Nice to have, if time permits)


Properties of user_page.py
  * user - *ReferenceProperty*
  * email – *StringProperty*
  * phone_number – *IntegerProperty*
  * address - *StringProperty*
  * website - *LinkProperty*
  * about_myself - *StringProperty*
  * activities – *StringProperty*
  * books – *StringProperty*
  * movies – *StringProperty*
  * television - *StringProperty*
  * profile_picture – *BlobProperty*
  * education – *ListProperty*
  * job – *ListProperty*
  * last_modified - *DateTimeProperty*
  * project_details – *ListProperty*
  * feed_url - *LinkProperty*
  * user_page_status - *StringProperty*
  * tags - *StringProperty* (for filtering in maps+calendars searches)


Properties of education.py
  * user - *ReferenceProperty*
  * college_name – *StringProperty*
  * major_name – *StringProperty*
  * start_date – *DateProperty*
  * end_date – *DateProperty*

Properties of job.py
  * user - *ReferenceProperty*
  * employer_name – *StringProperty*
  * position_name – *StringProperty*
  * start_date – *DateProperty*
  * end_date – *DateProperty*

Properties for project_details.py
  * user - *ReferenceProperty*
  * student - *ReferenceProperty*
  * organization - *ReferenceProperty*
  * mentor – *ReferenceProperty*
  * project_title - *StringProperty*
  * languages – *StringProperty*
  * apis_frameworks – *IntegerProperty*
  * related_url - *LinkProperty*
  * project_overview - *StringProperty*
  * other_general_info – *StringProperty*
  * proposal_link = *LinkProperty*
  * user_project_update – *ListProperty* (Nice to have, if time permits)
  * current_project – *BooleanProperty*
  * past_project - *BooleanProperty*

Properties of for project_update.py
  * project_details - *ReferenceProperty*
  * update_text – *StringProperty*
  * update_time – *DateTimeProperty*
  * project_comment – *ListProperty* (Nice to have, if time permits)

Properties of for project_comment.py
  * project_update - *ReferenceProperty*
  * comment_text – *StringProperty*
  * comment_time – *DateTimeProperty*
  * comment_user – *ReferenceProperty*

The User page feature should be in one of the following states implied by the user_page_status property of the model.
 * Visible - This state occurs after the user is accepted into the program. Only the minimal information about the user already entered during registration period is shown on the user page. In this state, the user may edit or add to his user page at any time during the program.
 * Invisible - This state of the user page can be activated by the user if the user wishes to prevent other users from viewing their profile. (Should this be allowed?)
 * Invalid - The user account has been terminated.

-----
*Suggestion Incorporated* Comment (Madhu): Status is good, but I don't think Uninitialized, Initialized and Updated is a good idea. Instead we can just have three states like, visible, invisible and invalid.
-----
 

-----
*Suggestion Incorporated* Comment (Madhu): Oh! I am extremely sorry for not making this clear earlier, when you started writing it out, but anyways better late than never. You need not create so many Python files and data models. From what I can see all the files and data models you have specified above can be merged into one single file with one single data model. So many reference properties is not good. Also, even if we keep all the data you have specified in a single data model we can write views in such a way that it shows only what data needs to be shown to a specific user and tabbing etc etc can all be controlled by views and templates. So we might not want so many data models. We will have to redesign this together. 
-----

===Views, Templates & Logic===
*Views*

*_soc.modules.social.views.models.user_page.py_* : Since the user_page feature serves more or less the same purpose for all the different user roles in Melange, a single view will be created.

*Templates*

 * *_soc.templates.modules.social.user_page.view_user_page.html_* : Since the user pages will be tabbed, the entire page will not reload when users switch between tabs. With the help of JavaScript, this can be achieved with a single template with different html div and id tags defining the data to be displayed in different tabs :).

 * *_soc.templates.modules.social.user_page.edit_user_page.html_* : A different template with the html form will be created for the 'Edit User Page' function which will be used to update the user_page.py data model.

*Logic*

*_soc.modules.social.logic.models.user_page.py_* : To handle the edit/update of the user data a logic is created which will be used to update the user_page.py data model.

== Main Feature 2: Maps + Calendars for GSoC ==

===Overview===
This feature consists of two main components. The *Calendars* and *My Community* components. These two components will appear in the sidebar in the User section.

The My Community tab will provide a portal for users to explore all the participants of the program by different categories such as location, organization, project tags etc. Users can can get to know their fellow participants by visiting their user page.

The My Community section also allows user to explore community events by location, organization and tags. Non-admin users can also request to add a new event to the calendar by sending "Add Event" requests to their respective admins with the event details.
The My Community tab provides two views for the above-mentioned activities, a simply list view and a global map view(default).

The Calendars component is used to view only the events such as GSoC meetups, irc meetings, conferences and other related events which might be of interest to the community members. Each user can view the public program calendar and the private organization calendar which is owned by the organization admin and is viewable only by users associated with that organization.


===Workflow===

*My Community*

Workflow for all Users: 
    
    * When users click on 'My Community' in the sidebar, under the 'User' tab, they will be redirected to the _MapView_ which is the default view. Here, they will see a world map which they can manipulate to show either *users or events*.
    * In the _MapView_
         # Once users or events are selected, the map can be further manipulated to show the data based on location, organization and tags(i.e. C#, PHP, Django etc).
            # If users are selected: The map will point to all user locations based on the filters selected. A mouse-over on a particular user, will show a link to user profile, which can be clicked to be directed to the user page.
            # If events are selected: The workflow is same as users, except that events are shown on the map. The users can mouse-over and click on a particular event to view the details as a pop-up widget.
    * In the _ListView_
         # Once users or events are selected, the same filters as above can be applied, except the data will be shown in a text-based list format. Clicking on any row in the list, will lead to the corresponding user page or the pop-up event widget respectively.

*Calendars*

Workflow for Users:

    * Click on 'Calendars' under the User tab in the sidebar. They view a single calendar containing events in the Program calendar as well as the events in their organization calendar. (Organization admins are owners of their respective org calendars.)
    * From this point onwards, users may choose any of the following:
       * *For Admins* Add a new event by clicking on the 'Add Event' button, which will take them to a form where they can fill in the event details and it will be shown on the org calendar.
       * *For Admins* They can choose to approve or decline requests sent by other users to publish events in their calendar by clicking on the 'Requests' button. They will be redirected to a page showing a list of event requests. After inspecting the event details, they can approve or decline the events.
       * *For Non-Admins* User can choose to request to add a new event by clicking on the  'Request Add Event' button. They will be redirected to a similar form as the admins 'Add Event' function. They can submit it and this event will be shown on the respective org or program calendar after it is approved by the respective admin.
       * View user's org events only.
       * View Program events only.
 
===Data Models===

Currently, the additional data model required here is for the event objects. 

_soc.modules.social.models.event.py_

Properties of for event.py
  * owner - *ReferenceProperty*
  * event_name - *StringProperty*
  * description – *StringProperty*
  * location – *StrinkProperty*
  * is_org_event – *BooleanProperty*
  * organization - *ReferenceProperty*
  * status - *StringProperty*
  * time - *DateTimeProperty*

An event can only be published in one calendar(i.e. program calendar or org calendar). If is_org_event is true, then it will be published in the current user's org calendar, if is_org_event is set to false, then the event will be published in the program calendar.
These two status properties differentiate the program admin and the org admins.

Based on the calendar(org or program) in which the event is meant to be published, the status property is set to either of the three values.

  * *is_requested* : If the current user is not the owner of the calendar where the event is to be published, then this state is set by default. When it is approved by the owner, this is set to is_approved.
  * *is_approved* : If the current user is the owner of the calendar where the event is to be published, then this state is set by default. Else if the event is approved by the owner, this state is set for the event.
  * *is_declined* : If the calendar owner chooses to decline an event request this state is set.


===Views, Templates & Logic===


== Use-Case Diagrams ==

===User Page Feature===

http://www.comp.nus.edu.sg/~savitha/gsoc/user_page_usecase4.png

===Maps + Calendar Feature===

*Maps*

http://www.comp.nus.edu.sg/~savitha/gsoc/maps_usecase.png


*Calendars*

http://www.comp.nus.edu.sg/~savitha/gsoc/calendars_usecase1.png

= Specification & Requirements =
  The detailed project specification will be added and updated here.  

= Timeline =
  The tentative project timeline will be added here.

= Meetings and Agendas =

== Friday April 30, 2010 13:30:00 in UTC ==
===Meeting Logs===
    Meeting start: http://www.thousandparsec.net/~irc/logm/%23melange.2010-04-30.log.html#t2010-04-30T13:30:05

    Meeting End: http://www.thousandparsec.net/~irc/logm/%23melange.2010-04-30.log.html#t2010-04-30T14:19:13    
    

===Meeting Notes===

  Location: #melange on freenode

  Time: 13:30:00 Friday April 30, 2010 in UTC 

  Chaired by: Madhusudan C.S

  Notes taken by: Savitha R 


    * A general overview of the project design was discussed.
       * Users should be able to view fellow GSoC students/mentors/admin by (i) geographic location (perhaps like a global map) (ii) by organization attached to (iii) by type of work/projects they are doing (iv) a complete list of all users in the program.
       * Users should be able to find other users using the above categories and then further have the option of finding out more information by clicking to view their personal GSoC user pages.
       * Privacy & Visibility issues: Users might need to have the option to keep their location and personal information private. In their personal user pages they may or may not choose to share their personal profile. However, they can share information about their projects such as progress, issues and other information related to the project.  Further discussion on the specific details is required.
       * In addition to finding fellow users by location, users can also choose to view events/calendars by selecting to view the happenings in certain locations only. In this case, the location will dictate the calendar to be displayed.

    * Tips on getting familiar with the code and documentation.
       * Select or get assigned to a simple patch/issue. Fix and submit the patch.
       * Homework assignments during community bonding period to get familiar with Melange code base.

===Next Meeting===

Location: #melange on freenode

Time: 13:30:00 Wednesday May 5, 2010 in UTC

Attendees: C.S.Madhusudan, Savitha

Agenda:
       * Detailed Project requirements
       * Design and Implementation details of project
       * Discuss and assigning of patch/bug-fixing home works to be taken up.


== Wednesday May 5, 2010 13:30:00 in UTC ==
===Meeting Logs===
    Meeting start: http://www.thousandparsec.net/~irc/logm/%23melange.2010-05-05.log.html#t2010-05-05T13:30:33

    Meeting End: http://www.thousandparsec.net/~irc/logm/%23melange.2010-05-05.log.html#t2010-05-05T15:19:58    
    

===Meeting Notes===

  Location: #melange on freenode

  Time: 13:30:00 Wednesday May 5, 2010 in UTC 

  Chaired by: Madhusudan C.S

  Notes taken by: Savitha R 


    * General discussion on version control.
       * Cloning project. - Done
       * Learn and understand mercurial version control system as well as commands etc. How to make changes, submit patches, push changes etc.
       * Fix and submit a patch a.s.a.p. for the issue no. 890 bug
    * APIs to be used – Google Calendar API, Maps API, CalVi UI library, GeoModel for filtering in maps, Google AJAX APIs, default GMAPs UI.
    * Project features in detail -  Maps
       * Global map indicating GSoC students/mentors/etc. and events occurring at specific locations.
       * Filtering data displayed on global map using different categories such as 
          (i)show all GSoC students from specific location 
          (ii)show all students from specific organization 
          (iii) show all events organized by program 
          (iv) show all events for a specific organization 
          (v) show all events between given date range 
          (vi) show all students based on the work they are doing (e.g all students working with C/C++ project tags)
          issue:  have to check app engine quota restrictions
       * Maps can be used to display student items or event items with any combination of the above filters.
       * UI – An AJAX-based UI which shows the map and a section for users to type in their filtering options, as they type input, map display gets updated dynamically. When users mouse over and click indicated points on the map, there will be a pop-out widget providing more information. If a user scrolls over and clicks on a GSoC meet up event at Singapore then a small widget will pop out showing the details such as time, venue and info about the event.
    * Project features in detail – Calendars
       * Other than maps view, there will be calendar-only display, to just view events.
       * Program calendar and their own organization calendar will be shown in this view.
       * If organization admins choose to make their org calendar “public”, this can also be viewed in the calendar display.
       * Events can be added by calendar owners only, such as org admins and program admins. Other wishing to share events, can submit a simple form with event details, which calendar owners can approve and publish on their calendar.
       * Display-only UI as users will not be allowed to edit calendar events without authorization.
       * Pop-out widget like In the maps, with event information and optional Google map view and optional YouTube video embed related to the event.
    * Project Features in detail – User pages
       * User pages will contain (i)personal profile (ii) picture (iii)project updates (iv) rss widget (iv) (if time permits) twitter widget also!
       * UI to be like face book profile pages, with tabs. (i) Profile tab for users to share personal, educational and professional information. (ii) Project tab for users to share info about their project progress, updates  and issue. (iii) Other stuff tab where users can add other social widgets such as rss widget for their blog feed.
       * Simple forms to be used to get users to fill in profile information etc. Under “Project” tab users can post using a text field which takes in “html”.
    * Discussion on resolving issue 890 and submitting patch this weekend. Posting weekly updates to dev blog and submit patches by Friday night (compulsory!).
    * Todo List for Savitha
       * Keep updating wiki with project design, workflows and formalized implementation details over the week.
       * Post on Dev Blog this weeks’ update.
       * Fix issue 890 and submit patch.