README.md 9.47 KB
Newer Older
1
# Advisor
Daniel W Bond's avatar
Daniel W Bond committed
2

3
SRCT Advisor is a dynamic web application that lets users create, compare, and 
4 5
share course trajectories towards graduation. (Not intended as a replacement for
formal academic advising.)
Daniel W Bond's avatar
Daniel W Bond committed
6

7
## On Contributing
Daniel W Bond's avatar
Daniel W Bond committed
8

9 10
Advisor is still in its very early states and needs all the help it can get. 
Even if you don't feel like you can be helpful the more technical aspects, we 
11
definitely need designers, technical writers, and testers.
Daniel W Bond's avatar
Daniel W Bond committed
12

13 14 15
There are many things that can be done with this project (see the "To Do"
section), but sometimes it's the small things that count, so don't be afraid of
contributing just a small spelling mistake.
Daniel W Bond's avatar
Daniel W Bond committed
16

17 18
If you need help at all please contact and SRCT member. We want people to 
contribute, so if you are struggling, or just want to learn we are more than 
19
willing to help.
Daniel W Bond's avatar
Daniel W Bond committed
20 21 22

The project lead for this project is **Daniel Bond**. *dbond2@gmu.edu*

23
Please visit the [SRCT Wiki](http://wiki.srct.gmu.edu/) for more information 
24
on this and other SRCT projects, along with other helpful links and tutorials.
Daniel W Bond's avatar
Daniel W Bond committed
25

26
## Setup
Daniel W Bond's avatar
Daniel W Bond committed
27

Daniel W Bond's avatar
Daniel W Bond committed
28 29 30 31 32 33 34
To get started, you'll need the following installed:

* [Python 2.7.3](http://www.python.org/download/)
* [Git](http://git-scm.com/book/en/Getting-Started-Installing-Git/)
* [Pip](http://www.pip-installer.org/en/latest/installing.html)
* [virtualenv](http://www.virtualenv.org/en/latest/index.html#installation)

35 36 37 38
Type the following commands in your terminal (if you're on Windows, 
[Cygwin](http://www.cygwin.com/) is recommended, or you can install a 
[virtual machine](https://www.virtualbox.org/wiki/Downloads) and install a 
distribution of [Linux](http://www.ubuntu.com/download/desktop) to it (select 
39
the 32 bit version).
Daniel W Bond's avatar
Daniel W Bond committed
40 41 42 43

(also, ssh keys...)

``bash``
44

Daniel W Bond's avatar
Daniel W Bond committed
45
``git clone http://git.gmu.edu/srct/advisor.git``
46

Daniel W Bond's avatar
Daniel W Bond committed
47
``cd advisor``
48

Daniel W Bond's avatar
Daniel W Bond committed
49
``mkdir ~/.virtualenvs``
50

Daniel W Bond's avatar
Daniel W Bond committed
51
``virtualenv ~/.virtualenvs/advisor``
52

Daniel W Bond's avatar
Daniel W Bond committed
53
``source ~/.virtualenvs/advisor/bin/activate``
54 55


Daniel W Bond's avatar
Daniel W Bond committed
56
``pip install -r requirements.txt``
57

58
create the database
59

Daniel W Bond's avatar
Daniel W Bond committed
60
``python manage.py schemamigration trajectories --initial``
61

62 63
``python manage.py syncdb`` (the username and password are just for your
machine-- you can set it as merely "me" and "password" if you like)
64

Daniel W Bond's avatar
Daniel W Bond committed
65 66
``python manage.py runserver``

67
Next, open your web broswer of choice, and go to http//:127.0.0.1:8000/. You 
68
won't see too much. You'll need to add the courses and programs to the database.
Daniel W Bond's avatar
Daniel W Bond committed
69

70 71
I've written some documentation in the docs folder about using the admin 
interface and creating some models. Use the same username and password you set 
72 73
up when you did the `syncdb` command.

74
## How Advisor Works
75

76 77 78 79 80 81 82 83 84 85 86 87 88 89
### Apps

#### Advisor

This app is the base for the whole project, such as things that apply to everything go here, including the index page, the login page, etc. It also manages the other apps, e.g. all of the collected urls are managed here.

#### Trajectories

This is where students create and manage their trajectories, as well as view courses and programs.

#### Analysis

Here students can compare their trajectories, or look at analyses of their and everyone's trajectory and program information.

90
### Models
91

92 93
Model fields are pretty well commented up, but here's a high-level view on how 
everything comes together.
94

95
#### Courses
96

97 98 99 100
Each Course has basic information (name, department, credits), but more 
importantly has prerequisites and corequisites. Prereqs and Coreqs can accept 
null values or lists of other courses. This is how we know whether a student may 
take a class.
101

102
#### CourseCollections
103

104 105 106 107
A CourseCollection is a section of required courses in a program. Usually, 
programs require that a student must take some of these courses and some of 
those. CourseCollections are a list of all possible courses and the number of 
which are required, from all to just one.
108

109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139
#### Programs

A Program is list of CourseCollections, representing a major, minor, or general 
education requirements. All majors take a gened course.

#### Students

Students have the standard user fields, their well as all of their planned 
trajectories, and a big ol' list of all of the courses they have completed.

#### Trajectories

Trajectories represent a student's paths to graduation, represented structurally 
as a tree. A student's existing courses (or if null, their anticipated first 
semester of classes) represents the root of the tree, and a student's potential 
paths towards graduation with different majors representing different branches 
out. Each subsequent trajectory represents a subsequent semester. This makes it 
simple to represent students' changes to their trajectories and their different 
pathways out to different major options. Each takes a trajectory 
"previousCourses", which represents the node's immediate predecessor. 

Already completed courses are kept in a bulk list with each student, and 
potential courses are adjusted accordingly.

What users save and see as "trajectories" on their home page are each discrete 
path to each end node on the branches, e.g. Art History Path I, Art History Path 
II. Modification is therefore as simple as addition of a few new pointers. Each 
trajectory is also associated with a specific list of programs.

Trajectories also track their distance from the root, providing the user with 
the number of semesters until graduation.
140

141
### Templates
Daniel W Bond's avatar
Daniel W Bond committed
142

Daniel W Bond's avatar
sigh  
Daniel W Bond committed
143 144
#### index

145 146
This is where students can create a new trajectory. If students haven't yet 
already selected the classes they've taken, they can select those classes here.
Daniel W Bond's avatar
sigh  
Daniel W Bond committed
147 148 149

#### create

150 151 152 153
Based on the information passed in from the 'index' page, this page shows 
which classes a student is allowed to take the subsequent semester, 
depending on the prereqs and coreqs. It will use ajax to allow the student 
to select their classes and have their next allowed classes returned until 
Daniel W Bond's avatar
sigh  
Daniel W Bond committed
154 155 156 157
they have completed their program.

#### student

158
This template acts as a dashboard for each student, showing their saved 
Daniel W Bond's avatar
sigh  
Daniel W Bond committed
159 160
trajectories, allows them to adjust the classes they've taken, etc.

161
Later along, it will have some social features, like following public 
Daniel W Bond's avatar
sigh  
Daniel W Bond committed
162 163 164 165
trajectories or seeing what classes their "friends" are taking.

#### trajectory / course

166
These templates just display a trajectory or a course on their own for 
Daniel W Bond's avatar
sigh  
Daniel W Bond committed
167 168 169 170
inspection. Trajectories can be made public and shared.

#### compare

171 172 173
This page allows students to compare side-by-side up to three trajectories, 
of their own or others that are public. Analytics are preformed over the 
selected trajectories and displayed, showing, for instance, which has the 
Daniel W Bond's avatar
sigh  
Daniel W Bond committed
174 175 176 177
most courses, which has the most courses 300+, and more.

#### analysis

178 179
This template (to be created in further on) shows which classes are the most 
popular, how long on average each completed trajectory takes, popular classes 
Daniel W Bond's avatar
sigh  
Daniel W Bond committed
180 181
for certain parts of a major, and more.

182 183 184
I'd like the site to also have a separate app for taking the classes that a 
student wants to take for a given semester, and when that semester rolls by, 
it'd perform something along the lines of gmu.schedulizer.com for them, 
Daniel W Bond's avatar
sigh  
Daniel W Bond committed
185 186 187 188
along with the aforementioned social aspects.

#### login

189 190
I'd like this page to have a bit more information, since this is the page 
that students will eventually be directed to if they haven't logged in. It  
Daniel W Bond's avatar
sigh  
Daniel W Bond committed
191
might talk about some of the features and such.
Daniel W Bond's avatar
Daniel W Bond committed
192

193
## To-do
Daniel W Bond's avatar
Daniel W Bond committed
194

Daniel W Bond's avatar
sigh  
Daniel W Bond committed
195
### First orders of business
Daniel W Bond's avatar
Daniel W Bond committed
196

Daniel W Bond's avatar
sigh  
Daniel W Bond committed
197
#### Matters of Functionality
Daniel W Bond's avatar
Daniel W Bond committed
198

199
* Moving things around so that they are where they are supposed to be
200 201 202
* coreqs are listed with each model already, but there must be javascript on the
page preventing students from selecting a course without selecting another in
order for that to mean anything
Daniel W Bond's avatar
Daniel W Bond committed
203
* Add support for APs, and fix the "login required" stuff
204
* Javascript to count the number of credits selected
Daniel W Bond's avatar
Daniel W Bond committed
205

Daniel W Bond's avatar
sigh  
Daniel W Bond committed
206
#### Forms and Views
Daniel W Bond's avatar
Daniel W Bond committed
207

208 209 210 211 212
* JavaScript on the comparison page so that selected trajectories are loaded
immediately
* Analytic functions for comparing trajectories and some corresponding d3
visualization
* Forms on the index and create pages need to submit **actually** information
213 214
* Forms on index and create pages also need to expand to an additional fields;
also needs to take into consideration the max available, show alerts
215 216
* Create page requires AJAX, allowing for continual reloading until program(s)
are completed, then redirect to a student's main page.
217
* LDAP auth/login
218 219
* comparison page needs some lovely analytics on the compared trajectories for
the user
Daniel W Bond's avatar
Daniel W Bond committed
220 221
* polishing, like privacy policy

Daniel W Bond's avatar
sigh  
Daniel W Bond committed
222
#### Database and Webscraping
Daniel W Bond's avatar
Daniel W Bond committed
223

224
* scraping the site to populate the database
225
* moving over to mysql
226 227 228 229 230
* scraping of catalog.gmu.edu for the database (this also means that with a
single command everyone can be working on the same database :3)
* autocomplete js for the course name field (after a user puts in the department
abbreviation and the course name (note unlike bookshare this information needn't
be editable)
231
* map "Second Semester Junior" and the like to numbers for the graduation feature
Daniel W Bond's avatar
Daniel W Bond committed
232

Daniel W Bond's avatar
sigh  
Daniel W Bond committed
233
### Pipe Dreams
Daniel W Bond's avatar
Daniel W Bond committed
234

235 236 237 238
* Making trajectories "public" within the system, so that they can be shared
with other students.
* Making trajectories "public" outside of the system, so that they can be shared
on social and messaging sites.
Daniel W Bond's avatar
Daniel W Bond committed
239
* Support departments to create sample trajectories for their students.
240 241 242 243
* Identifying if courses are available in the semester desired, and if so,
getting professor information, CRNs, and what have you.
* An integrated "schedulizer"-type app for the classes that you've selected you
want for that semester.
Daniel W Bond's avatar
Daniel W Bond committed
244

245
## About GMU SRCT
246 247 248 249 250

**S**tudent-**R**un **C**omputing and **T**echnology (*SRCT*), pronounced
"circuit") is a student organization at George Mason University which enhances
student computing at Mason, SRCT establishes and maintains systems which provide
specific services for Mason's community.