#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. Past and Current project data for both mentors and students will be pulled from the database. Users can add on to it using a text field.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
  * project_details.py (pulled from database) 

Properties of user_page.py
  * user - *ReferenceProperty*         (required)
  * email – *StringProperty*
  * website - *LinkProperty*
  * biography - *TextProperty*
  * profile_picture – *BlobProperty*
  * last_modified - *DateTimeProperty* (required)
  * project_details – *ListProperty*   (required)
  * feed_url - *LinkProperty*
  * user_page_status - *StringProperty*(required)
  * tags - *ListProperty*              (required)

-----
*Suggestion Incorporated* Comment (madhu): I think you must really use tag framework in Melange here and use the tag property.
-----


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.
 * 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:

    * All calendars will be hosted under a single Google account owned by the program_admin. When the accepted organizations are announced, a new calendar can be created for each new organization. If organizations have participated in the program previously and they already have a calendar with the account, then that same calendar can be used.
The Google ids of org_admins can be added to their respective org calendars giving them 
rights to publish on their calendar.
Org_admins can be notified about their org_calendar on acceptance. A short message and link can be added in their acceptance notification emails leading them to their org calendar page. (*Note* : Program_admins will have to provide the google account under which the program and org calendars are to be hosted.)
    * 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.
    * Additionally, users can also subscribe to feeds to be notified about events with certain tags.
 
===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
  * created_by - *ReferenceProperty*  (required)
  * created_on - *DateTimeProperty*   (required)
  * modified_by - *ReferenceProperty*
  * modified_on - *DateTimeProperty*
  * event_name - *StringProperty*     (required)
  * description – *StringProperty*    
  * location – *GeoPtProperty*        (required)
  * is_org_event – *BooleanProperty*  (required)
  * organization - *ReferenceProperty*(required if is_org_event=True)
  * program - *ReferenceProperty*     (required)
  * status - *StringProperty*         (required)
  * time - *DateTimeProperty*         (required)
  * tags - *ListProperty*             (required)

-----
*Suggestion Incorporated* Comment (madhu): 
  # Same as above. You may want to use tag framework for tags. 
  # Also you may want created by and created on along with modified by and modified on properties. 
  # Also you may want to use http://code.google.com/appengine/docs/python/datastore/typesandpropertyclasses.html#GeoPtProperty GeoPtProperty here instead of Lat Lng location float properties. The reason why it was used in previous model was because this property was not in Appengine then. But now we have!
  # You also want reference to program.
-----

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.

----
Comment (madhu): Just to warn you, a user may be involved with two or more Organizations. For example, Sverre is mentoring two students this time :P One for Melange and another for Git
----

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.

  * *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.
  * *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.
  * *declined* : If the calendar owner chooses to decline an event request this state is set.

-----
*Suggestion Incorporated* Comment (madhu): For clarity reasons I think it is better to name these values *requested*, *approved* and *declined* since they are not really Boolean fields but a 3-state property.
-----
=== Calendars in Detail ===

*UseCases for Different User Roles*

Program Admin

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

"Initialize Calendars" use case simply refers to the automated creation of a new calendar for each accepted Organization and the assigning of access rights for all the org_admins and students at the start of the program.

*Org Admin*

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

*Student or Mentor*

http://www.comp.nus.edu.sg/~savitha/gsoc/student-mentor.png


*Calendar Types*:
   * *Program Calendar*: This is a completely public calendar which is visible to all users participating in the program including mentors, students, org_admins and program_admins. 
   * *Organization Calendar*: Every accepted organization has its own private calendar which is visible only to users working for that particular organization such as mentors, students and org_admin of that organization.

*Calendar Account*:
    * All the organization calendars and the single program calendar will be hosted in a *single* Google account owned by the program_admin. (this can be the program_admins own account or analternative account such as gsummerofcode@gmail.com where the current program  [http://www.google.com/calendar/hosted/google.com/embed?src=gsummerofcode@gmail.com&ctz=America/Los_Angeles calendar] is being hosted.)
    * Every org_admin will be given owner access to their org calendar. Google's Calendar API provides access control lists for each calendar. Hence, each org_admin can be given owner  access(user can make changes to events) while org students are given read access(this user can see all event details). (Ref: http://code.google.com/apis/calendar/data/1.0/developers_guide_python.html#SharingACalendar)

*Access Rights for User Roles*
When users access their Calendars, the respective calendars and rights will be triggered based on the account in which they are logged in. For example, if bob@gmail.com is an org_admin, and is logged in. He will automatically have "owner" access to his org calendar and "read" access to the program calendar.

*Program_Admin*:
  * Has "owner" access for all org calendars and program calendar

*Org_Admin*:
  * Has "read" access to program calendar.
  * Has "owner" access to their org_calendar.

*Mentors*:
  * Has "read" access to their org calendar and program calendar.

*Student*:
  * Has "read" acess to their org calendar and program calendar.

Users who do not have access to a particular calendar but want to add an event can send requests to the owner who can approve it. This is an internal feature to be implemented within Melange and not visible to Google Calendar API. The calendar will view the event as being added by the owner. (This is depicted in the Calendars User case [http://code.google.com/p/soc/wiki/SocialFeaturesMelangeGSoC2010?ts=1274515831&updated=SocialFeaturesMelangeGSoC2010#Maps_+_Calendar_Feature below]) 

=== APIs & Libraries ===
   * Google Calendars API
   * Google Maps API
   * CalVi's UI library
   * GeoModel (filtering locations, tentative)
 (more coming up...)

-----
Comment (madhu): Want to see them soon. Esp. jQuery plugins for tabbed pages since you are starting with User pages in two days.
-----

== 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_usecase1.png


*Calendars*

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

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

===Week 1(22 May - 28 May)===

*To Do*:
  # Code the models, views/templates and logic for User Pages as per design above.  
  # Modify existing code to accommodate new feature (sending out user page link in acceptance notifications etc.)
  # Test code on localhost instance of Melange
  # Find out how to pull data from past year databases (how to test this? can we import the database files from somewhere?)

-----
Comment (madhu): Simple, create your own dummy data. If Felix has something to seed by then, we can probably use it. But in the first week I doubt it. But yeah you can create your own data.
-----

*Deliverables*:
  # Partial User Page feature:
      * On receiving acceptance notification, users can click on the link to their User Page or access it from the User tab in Melange.
      * User's will see default values on their User Page.
      * Users can view only their *own* user page. (search and view others' user pages not added yet).
      * Users can edit their user page data using forms.


===Week 2(29 May - 4 June)===

*To Do*:
  # Develop an All Users ListView for viewing all users (who are not private) where clicking on a user takes them to the User pages
  # Work on providing filtering in the list view based on user-tags, location and org
  # Testing and Debugging previous weeks' work. 

*Deliverables*:
  # Almost-There User Page feature:
      * Users can use ListView to sift through the rest of the users and click on them to view their user pages.
      * Users can apply dynamic filtering to view users by location, org and tags using ListView.
      
-----
Comment (madhu): This is already there. Can you please tell us what you want to do other than this? http://socghop.appspot.com/gsoc/program/list_projects/google/gsoc2010
-----

===Week 3(5 June - 11 June)===

*To Do*:
  # Tie up loose ends and bugs for User Page feature.  
  # Testing of feature plus writing tests(to be confirmed).
  # code event.py data model.
  # Design UI for calendar to be displayed (CSS/ CalVis).

*Deliverables*:
  # Fully-Functional User Page feature:
      * User can view/edit their own user pages.
      * Users can have a list view of all users participating in the program and view them by location, org and tags.
      * Users can view user pages of other users by clicking on their names in the ListView.


===Week 4(12 June - 18 June)===

*To Do*:
  # Modify View, Logic for Program_admin to authenticate an account where the program calendar and org calendar will be hosted. Create new org calendars once accepted orgs are announced.
  # Modify Views and Logic for users and admins, to view the program and their org calendars Clicking on calendars in their User tab.
  # Create templates for viewing the calendars based on user roles.
  # Use calendar api to import calendars and display them in Melange.
*Deliverables*:
  # Very-Partial Calendars feature:
      * On org acceptance, new calendars are created for each org.
      * All users can access their 'Calendars' link in their User tab.
      * They get to view their respective org and program calendars.


===Week 5(19 June - 25 June)===

*To Do*:
  # Code or modify existing user Views, create forms and templates for event creation/requests based on user roles.
  # Create templates and modify Views for org_admins and program_admins to approve or decline event requests.
  # Add event.py Logic to add new event in the actual Google calendar using API once its status is set to is_approved.
  # When adding event, use Maps Api to show a mini-map which users can use(optional) to point to the location of the event. Store this as Lat,Long attributes of event.py data model.

*Deliverables*:
  # Partial Calendar feature:
      * Users can view Calendars
      * Admins can add events to their respective calendars and approve/decline requests.
      * Non-admins can send requests to add event.
      

===Week 6(26 June - 2 July)===

*To Do*:
  # Write a feed function using Django's feed generator(to be confirmed) allowing users to subscribe to rss feeds on events with certain tags.
  # Test previous weeks' code.
  # Fix Bugs, complete lagging work from previous week.
  # Write tests?

*Deliverables*:
  # Almost-there Calendar feature:
      * All deliverables from Week 4 and 5.
      * Users can subscribe to feeds for events with certain tags.


===Week 7(3 July - 9 July)===

*To Do*:
  # Develop ListView for events (similar to users ListView)  
  # Allow dynamic filtering by tags, location.
  # Users can click on events they are interested in to see a pop-out widget with the event details.

*Deliverables*:
  # Almost-there Calendar feature:
      * All deliverables from weeks 4,5 and 6.
      * Calendars ListView
      * Event filtering by categories.
      * View event using pop-up widget.


===Week 8(10 July - 16 July)===

*To Do*:
  # Any left-over todo's from previous weeks.
  # Testing, Testing and Testing.  
  # Bug fixing.
  # Documentation
  # Get ready for mid-term evaluations.  

*Deliverables*:
  # User Page feature
      * View/edit User Page
      * View User Pages of all other users in the program.
      * Use ListView to filter users by location, org and tags.
  # Calendars Features
      * View Program and User's org calendar.
      * Add or Request to add Events.
      * ListView of all program and org events and all other events marked as public.
      * View a particular event's details.


Post Mid-term timeline will be up shortly.

= 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.