...
- 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]
- Create your Python view code, urls.py file, and unit tests
- Ideally you should render your views as Web Fragments
- 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:
- For more details, see How to add a new page to LMS or Studio
- Put your JavaScript files inside of a static directory, namespaced by the name of your app (for instance,
- 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 - In client-side code, you can use relative paths in RequireJS which will resolve to the correct location
- 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
- Don't assume that you can access a file directly with
- In Mako, use
- Apps listed in OPTIONAL_APPS will be dynamically added to Django's INSTALLED_APPS if the app is present
- 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.
...