Page Comparison

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.

...

1. Create a new XBlock in its own Git repository
   • XBlocks allows you to define new types of components that can be used in courseware, e.g. new problem types
   • For edX to consume your XBlock, it should just be added as a requirement to: https://github.com/edx/edx-platform/blob/master/requirements/edx/github.in
   • Consider the following before choosing to create an XBlock:
     • Testing of authoring views is challenging as there is no straightforward way to run with the block embedded in Studio
     • There are aspects of XBlock integration into Studio that have not been completed, e.g.

       • Jira Legacy
         server JIRA (openedx.atlassian.net) serverId 13fd1930-5608-3aac-a5dd-21b934d3a4b4 key TNL-851

       • Jira Legacy
         server JIRA (openedx.atlassian.net) serverId 13fd1930-5608-3aac-a5dd-21b934d3a4b4 key TNL-850

   • Examples of XBlocks:
     • Recommender XBlock: https://github.com/pmitros/RecommenderXBlock
     • Staff Graded Assignment XBlock: https://github.com/mitodl/edx-sga
     • XBlock Poll: https://github.com/open-craft/xblock-poll
   • See the documentation below: Create a new XBlock in its own Git repository
2. Create a new IDA (independently deployable application)
   • If a feature doesn't need to be tightly integrated into Studio or the LMS then it can be built as an independent app
   • It can make use of the Open edX ReST APIs to get any platform data that it requires
   • IDAs are a good choice when:
     • They need to scale independently of the edX platform
     • They will be built, deployed and managed by a separate team
     • LMS and Studio should continue unaffected even if the application goes down
   • Consider the following before choosing to make a new IDA:
     • There is more operational complexity for the community to deploy and manage your feature
     • There are performance implications with introducing extra network calls
     • There is more application complexity when working with related data from external APIs, e.g. joins and referential integrity must be implemented in the application layer
   • Examples of IDAs:
     • edX Analytics Dashboard: https://github.com/edx/edx-analytics-dashboard
     • edX eCommerce Service: https://github.com/edx/ecommerce
     • edX Student Notes API: https://github.com/edx/edx-notes-api
   • See the documentation below: Create a new IDA
3. Create a new Django app in its own Git repository
   
   • New Django apps can be implemented in a separate repo and pip installed into the platform
   • A Django app in its own repository is a good choice when:
   1. • it provides new services that will be consumed by other parts of the platform
      • if it requires new UI for LMS or Studio, it provides it via extensions and does not introduce new URLs
        • See OEP-12 for the recommended way to add pluggable user interfaces
   • Consider the following:
     • If the feature has no UI then it may be better suited as an IDA if it doesn't require direct access to platform data models
     • See /wiki/spaces/TNL/pages/40862230 for descriptions of some of the challenges involved with this approach
   • Examples of Django apps in their own repositories:
     • ORA 2: https://github.com/edx/edx-ora2
     • Submissions: https://github.com/edx/edx-submissions
     • Milestones: https://github.com/edx/edx-milestones
   • See the documentation below: Create a new Django app in its own Git repository
4. Add a new Django app to the edX platform
   
   • If your feature cannot be built using the existing extension points, then it can be added directly to the edx-platform
   • Consider the following:
     • It would be better to introduce a platform extension point and then use it from a separate app
     • It is best to build your new Django app in its own directory so that there is an option to move it into its own repo later
       • Our current thinking is to add your new Django app to the directory openedx/features
     • See Web Fragments /wiki/spaces/ArchiveEng/pages/157888616 for the recommended way to add pluggable user interfaces
   • Examples of Django apps in the edX platform:
     • LTI Provider: https://github.com/edx/edx-platform/tree/master/lms/djangoapps/lti_provider
     • Teams: https://github.com/edx/edx-platform/tree/master/lms/djangoapps/teams
   • See the documentation below: Adding a new Django app to edx-platform
5. Update the platform directly
   • This is the option of last resort
   • When should you update the platform directly?
     • When the feature you are implementing updates core functionality in fundamental ways
     • When there are no extension points that you can use to build the functionality you need
   • Consider the following before doing this:
     • Features which update the platform directly require the most scrutiny in code review
     • There is far more risk of unexpected fallout from your changes
     • Consider whether it is possible to introduce a platform extension point and then use it
     • Be sure to discuss your proposed approach with the Open edX community first to ensure that this is the best way to move forward
   • Examples:
     • Cohorted Courseware: PR 6299
     • CCx (custom courses): PR 6636
   • See the documentation below: Update the platform directly

...

1. 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)

     Code Block
     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]

     
     

2. Create your Python view code, urls.py file, and unit tests
   • Ideally you should render your views as Web Fragments/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
3. 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 How to add a new page to LMS or Studio/wiki/spaces/ArchiveEng/pages/16646275
4. 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
5. 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
6. Write bok choy acceptance tests in common/test/acceptance to verify that your plugin is working.

...

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

• How to add a new page to LMS or Studio/wiki/spaces/ArchiveEng/pages/16646275
• Adding a new course tab
• See a full list here

...