Developers Getting Started with OK

Purpose

This a walkthrough of the ok codebase. After reading this document and going through the related function calls, you should be able to develop for ok and figure out (at a high level) what other pieces of ok your code touches and depends on.

Major Files

Backend

There are three files that you will need to know about for most ok feature development. They are:

• models.py: These describe the objects that the ok database stores (e.g. course information, student submissions, etc). Each object, like in OOP, also has many methods that correspond to things that it knows how to do.

• api.py: These describe the API that allow someone from the outside world to interact with our models. Many of these methods have the flavor of "Make sure this user has the right permission to do this action and then call the corresponding method on the model"

• urls.py: Now that we have an API, we need to provide a way for people to get to it. This is what a URL does. The @app.route decorators match an API to the corresponding method. The register_api calls at the end are a formulaic way to make an API out of a class in the api.py file.

Frontend

There are three (important) parts to the front-end:

• Angular.JS: This is our template-rendering engine. Essentially, it defines a set of Controllers, each of which binds methods and variables to a "scope", or an isolated environment. Each of these isolated environments then allows basic program logic to facilitate template rendering. See this AngularJS tutorial page for how this works.

  • Controllers : located under /static/js/[type]/controllers.js
  • URLs : located under /static/js/[type].js

• HTML Files: HTML files are split into two groups -- (1) templates, and (2) partials. "Templates" are run-of-the-mill HTML files you see in every Flask application. Quite simply, they're layout skeletons contained in server/app/templates. "Partials" are bits and pieces of layouts that can be summoned dynamically, using AJAX calls. These can be found in server/static/partials.

  • Statics : This is largely uninteresting. Basically, the directory structure of the server/static folder, is what you get under example.com/static/.

• API Calls : All API calls are made in the aforementioned controllers. To setup a new API call, register a method with one of the objects under /static/js/common/services.js. All methods are static and will correspond to a method specified in api.py.

Removing a Member for a Group

Let's see what happens when a student removes a group member. In this example a member of the group with ID 123 is removing the group member the email [email protected]:

TODO: Make the next paragraph actually say what lines get called where.

First, the user navigates to the page. The frontend code decides how the page is going to look and which buttons correspond with which api calls. Then, the user clicks "remove". At this point, the frontend makes an API call that goes to a URL that looks like:

ok-server.appspot.com/api/v1/group/123/remove_member/email=[email protected]

Now, the server gets a call that says:

/api/v1/group/123/remove_member/email=[email protected]

the /api/v1 just tells the server that it's an API call and not someone navigating to a new page.

The "group" part comes from this register_api line: https://github.com/Cal-CS-61A-Staff/ok/blob/master/server/app/urls.py#L263. That line says when you see the "group", it should look in the GroupAPI class in api.py.

Now, this is where some magic happens (through the webargs framework). The "remove_member" part of the URL says to call the "remove_member" method in the GroupAPI. It first looks in that class' methods dictionary and finds what arguments are needed here: https://github.com/Cal-CS-61A-Staff/ok/blob/master/server/app/api.py#L1650.

That dictionary entry says that there will be a remove_member function in the GroupAPI and it expects email as an argument.

The webargs framework does some magic and passes in the following arguments to the remove_member function:

"group": The group whose ID is 123. "user": The person that was logged in "data": The arguments, as a dictionary. So, for the request above, it just contains the key 'email' with the value [email protected].

[To read more about the magic, you should look at the webargs framework that was imported here: https://webargs.readthedocs.org/en/latest/.

Now, the server executes the "remove_member" function in GroupAPI and returns the value as the API response.

Final Steps

Now you should be ready to develop for ok! Take a look at the README for developer guidelines and installation instructions: https://github.com/Cal-CS-61A-Staff/ok