How to add a new feature to LMS or Studio

1 New Guidance
2 Introduction
3 Decide where to host your code
4 How to add a new XBlock in its own Git repository
5 How to create a new IDA
6 How to add a new Django app in its own Git repository
7 How to add a new Django app to the edX platform
8 How to update the platform directly
9 Implementing your new feature

New Guidance

This wiki document may be out of date - please check Options for Extending the Open edX Platform for newer information.

Introduction

This document describes the different options available to you to add a new feature to the edX platform.

Note: If you have not contributed to edX before, be sure to read this guide: Process for Contributing Code.

Decide where to host your code

The first thing you should decide is where you will host your new feature. There are five options to consider which are listed here in order of preference:

For more background when making this decision, see these architecture council meeting notes: 2015.09.23 - IDA discussion.

How to add a new XBlock in its own Git repository

Create your new project using the cookiecutter: https://github.com/edx/cookiecutter-xblock
See the XBlock documentation for more details: https://xblock.readthedocs.org/en/latest/index.html

How to create a new IDA

Be sure to propose your new IDA to the Architecture and Engineering: Home
See the architecture council meeting notes on IDAs: 2015.09.23 - IDA discussion
Create your new project using the cookiecutter: https://github.com/edx/cookiecutter-django-ida
Consider how the IDA will integrate with the edX platform
- Ideally these integrations will be implemented as extension points using a Django app in a separate repo
- Determine how to test all of the integration points

How to add a new Django app in its own Git repository

Create your new project using the cookiecutter: https://github.com/edx/cookiecutter-django-app
See /wiki/spaces/TNL/pages/40862230 for descriptions of some of the issues involved with this approach

How to add a new Django app to the edX platform

These are the steps necessary for adding a new Django app-based feature, based on what was done to add the Teams feature to LMS.

Create a new Django app, where all Python, mako and underscore templates, and JavaScript will live (note that there is an open story to allow sass files to also live in this app)
- Our current best practice it so put new features into the platform directory openedx/features
- Run the following code in an lms-shell (run "make lms-shell" in devstack)
  root@lms:/edx/app/edxapp/edx-platform# mkdir ./openedx/features/[Your App Name] root@lms:/edx/app/edxapp/edx-platform# ./manage.py lms startapp [Your App Name] ./openedx/features/[Your App Name]
Create your Python view code, urls.py file, and unit tests
- Ideally you should render your views as /wiki/spaces/ArchiveEng/pages/157888616
- Your templates should live inside your app's templates directory, namespaced by the name of your app (for instance, teams/templates/teams)
- If you are rendering full-page views you must use Mako:
  - Make sure your Mako files have "## mako" on the first line, so that they are loaded by our Mako template loader.
- For example: https://github.com/edx/edx-platform/blob/master/lms/djangoapps/teams/templates/teams/teams.html
If you have JavaScript and underscore templates:
- Put your JavaScript files inside of a static directory, namespaced by the name of your app (for instance, teams/static/teams/js).
- As a best practice, use RequireJS and Backbone for your JavaScript
- Use Underscore to handle client-side templates and load them using RequireJS Text (example).
- Put your underscore templates inside the same namespaced static directory (for instance, teams/static/teams/templates).
- Put your Jasmine unit tests inside a spec directory within the JS directory (for instance, teams/static/teams/js/spec).
- To enable the Jasmine unit tests as part of running LMS unit tests:
  - Add the names of your specs to lms/static/js/spec/main.js.
  - Add to src_paths, spec_paths, and fixture_paths in lms/static/karma_lms.conf.js (example).
  - Create a symbolic link in lms/static to the location of your static directory so that unit tests can find the appropriate files (example).
- For more details, see /wiki/spaces/ArchiveEng/pages/16646275
Add the name of your app to OPTIONAL_APPS in lms/envs/common.py
- Apps listed in OPTIONAL_APPS will be dynamically added to Django's INSTALLED_APPS if the app is present
  - This is beneficial as some forks of Open edX might choose not to use your new feature
  - If your feature will always be present in the platform, you can instead update INSTALLED_APPS directly
- For example: https://github.com/edx/edx-platform/blob/master/lms/envs/common.py#L2862
- This ensures that the Django pipeline will pick up all of the static assets found beneath your static directory
- You can reference your static files as follows:
  - In Mako, use static.url which resolves a path to the correct location in the Django static directory
    - e.g. https://github.com/edx/edx-platform/blob/master/lms/templates/navigation/navigation.html#L23
  - In client-side code, you can use relative paths in RequireJS which will resolve to the correct location
    - e.g. https://github.com/edx/edx-platform/blob/master/lms/djangoapps/teams/static/teams/js/teams_tab_factory.js
  - All other client-side URLs should be resolved on the server and then passed down to the client
    - Don't assume that you can access a file directly with /static/myApp/foo.jpg because that bypasses the Django pipeline
Add your urls to lms/urls.py, most likely behind a feature flag or configuration setting
- Be sure to have a urls.py within your Django app, and then include it from the platform's urls.py
Write bok choy acceptance tests in common/test/acceptance to verify that your plugin is working.

How to update the platform directly

Determine that there is no better way to implement your feature, as core platform changes are hard to make and have approved
Follow the contribution process to make a pull request against the platform: Process for Contributing Code

Implementing your new feature

Once you have chosen how to provide your new feature, you can add many different types of functionality: