Update documentation for developing canvas-rce
closes CORE-2593 Test Plan: - Documentation makes sense Change-Id: I68ff4e16e00909951513d649b68a35b66f2913fc Reviewed-on: https://gerrit.instructure.com/186891 Tested-by: Jenkins Reviewed-by: Ryan Shaw <ryan@instructure.com> QA-Review: Ryan Shaw <ryan@instructure.com> Product-Review: Ryan Shaw <ryan@instructure.com>
This commit is contained in:
Clay Diffrient
parent
0f39b77d3a
commit
3b0ba2d55e
|
|
@ -0,0 +1,97 @@
|
|||
# Canvas Rich Content Editor - Development Guide
|
||||
|
||||
This guide is written for those planning to develop `canvas-rce` itself. It will
|
||||
guide you to getting things set up in a way that allows you to get off the
|
||||
ground and get going quickly.
|
||||
|
||||
## Canvas RCE API
|
||||
|
||||
In order for all features of `canvas-rce` to work you'll also need a running copy
|
||||
of `canvas-rce-api`. You can get it from [canvas-rce-api](https://github.com/instructure/canvas-rce-api). You'll want to follow the setup instructions for it in that repository as
|
||||
they will be the most up to date.
|
||||
|
||||
## Developing
|
||||
|
||||
Here we'll talk about how to develop on `canvas-rce` without the use of Canvas.
|
||||
|
||||
You can get the "demo" development environment up and running by executing:
|
||||
|
||||
```shell
|
||||
|
||||
yarn dev
|
||||
|
||||
```
|
||||
|
||||
Then navigate to http://localhost:8080/demo.html and you will see the `canvas-rce` editor.
|
||||
Any changes you make to files under `/src` will be reflected in this editor.
|
||||
|
||||
### Developing inside Canvas
|
||||
|
||||
Because this package lives in the Canvas packages workspace, you can make modifications to it without first needing to do a `yarn install` in Canvas.
|
||||
|
||||
You can start up the watch mode of this package by running `yarn build:watch` inside the `canvas-rce` directory. Then in Canvas proper, you can run `yarn build:js:watch` and things generally work out. If for some reason you get errors with the watch modes, you can fallback to the regular builds `yarn build:canvas` inside of `canvas-rce` and `yarn build:js` inside of Canvas.
|
||||
|
||||
## Plugins
|
||||
|
||||
Canvas RCE specific plugins require using the [Canvas RCE API](#Canvas-RCE-API) normally, however
|
||||
by default the demo environment provides a fake shim so that you can develop without actually
|
||||
needing to use `canvas-rce-api` or Canvas.
|
||||
|
||||
There is a section available on the page that allows you to connect to a real `canvas-rce-api
|
||||
`instance and to a real Canvas instance. You can put a URL pointing to a running
|
||||
`canvas-rce-api` instance as well as a JWT from Canvas. You can get the JWT from Canvas by
|
||||
going to any page with an RCE instance and typing `ENV.JWT` into the JavaScript console. If you do these things you will pull real data from Canvas into the RCE demo environment.
|
||||
|
||||
### Adding New Plugins
|
||||
|
||||
If you are creating a plugin that works with Canvas RCE , you should also put in the appropriate
|
||||
fake data which can be done in the [fake data store](./src/sidebar/sources/fake.js).
|
||||
|
||||
Custom plugins live under the plugins [directory](./src/rce/plugins/).
|
||||
|
||||
## Upgrading TinyMCE
|
||||
|
||||
### Language Packs
|
||||
|
||||
Translations for TinyMCE are not shipped with the `tinymce` npm package. When
|
||||
upgrading to a new version be sure to download the latest language packs. Visit
|
||||
https://www.tinymce.com/download/language-packages/ and select all languages. It
|
||||
is easier to just download all and only commit the changes to existing files
|
||||
than try to only select the locales currently used. Download the file and
|
||||
extract all of th `.js` files to `./src/rce/languages/`. After commiting the
|
||||
changed locale files you can run `git clean -f ./src/rce/languages/` to remove
|
||||
the untracked language files.
|
||||
|
||||
## Adding Languages
|
||||
|
||||
### TinyMCE Language Pack
|
||||
|
||||
Download the new TinyMCE language pack by visiting
|
||||
https://www.tinymce.com/download/language-packages/ and select the language.
|
||||
Copy the JavaScript file to `./src/rce/languages/`.
|
||||
|
||||
### Locale Code Mappings
|
||||
|
||||
Since different projects have a hard time agreeing on locale code format, a file
|
||||
mapping Canvas locale codes to TinyMCE locale codes needs to be updated. This is
|
||||
found in `./src/rce/editorLanguage.js`.
|
||||
|
||||
### Recognized Languages
|
||||
|
||||
The `./src/rce/normalizeLocale.js` file includes a list of valid locales. The
|
||||
new locale should be added here.
|
||||
|
||||
### Locale Module
|
||||
|
||||
A locale module should be added for each new locale, with a name matching the
|
||||
Canvas locale code. This file adds the translations to the `canvas-rce`
|
||||
formatMessage namespace, and loads the TinyMCE translations.
|
||||
|
||||
#### Example
|
||||
|
||||
```js
|
||||
import formatMessage from "../format-message";
|
||||
import locale from "../../locales/locale-code.json";
|
||||
import "../rce/languages/tinymce_locale";
|
||||
formatMessage.addLocale({ "locale-code": locale });
|
||||
```
|
||||
|
|
@ -12,7 +12,7 @@ The first customer of the `canvas-rce` was the `canvas-lms` LMS so documentation
|
|||
and references throughout documentation might reflect and assume the use of
|
||||
`canvas-lms`.
|
||||
|
||||
# Install and setup
|
||||
## Install and setup
|
||||
|
||||
As a published npm module, you can add canvas-rce to your node project by doing
|
||||
the following:
|
||||
|
|
@ -39,51 +39,6 @@ canvas-rce:
|
|||
```
|
||||
(See: https://polyfill.io/v2/docs/ for more info)
|
||||
|
||||
# Development
|
||||
## Development
|
||||
|
||||
## Upgrading TinyMCE
|
||||
|
||||
### Language Packs
|
||||
|
||||
Translations for TinyMCE are not shipped with the `tinymce` npm package. When
|
||||
upgrading to a new version be sure to download the latest language packs. Visit
|
||||
https://www.tinymce.com/download/language-packages/ and select all languages. It
|
||||
is easier to just download all and only commit the changes to existing files
|
||||
than try to only select the locales currently used. Download the file and
|
||||
extract all of th `.js` files to `./src/rce/languages/`. After commiting the
|
||||
changed locale files you can run `git clean -f ./src/rce/languages/` to remove
|
||||
the untracked language files.
|
||||
|
||||
## Adding Languages
|
||||
|
||||
### TinyMCE Language Pack
|
||||
|
||||
Download the new TinyMCE language pack by visiting
|
||||
https://www.tinymce.com/download/language-packages/ and select the language.
|
||||
Copy the JavaScript file to `./src/rce/languages/`.
|
||||
|
||||
### Locale Code Mappings
|
||||
|
||||
Since different projects have a hard time agreeing on locale code format, a file
|
||||
mapping Canvas locale codes to TinyMCE locale codes needs to be updated. This is
|
||||
found in `./src/rce/editorLanguage.js`.
|
||||
|
||||
### Recognized Languages
|
||||
|
||||
The `./src/rce/normalizeLocale.js` file includes a list of valid locales. The
|
||||
new locale should be added here.
|
||||
|
||||
### Locale Module
|
||||
|
||||
A locale module should be added for each new locale, with a name matching the
|
||||
Canvas locale code. This file adds the translations to the `canvas-rce`
|
||||
formatMessage namespace, and loads the TinyMCE translations.
|
||||
|
||||
#### Example
|
||||
|
||||
```js
|
||||
import formatMessage from "../format-message";
|
||||
import locale from "../../locales/locale-code.json";
|
||||
import "../rce/languages/tinymce_locale";
|
||||
formatMessage.addLocale({ "locale-code": locale });
|
||||
```
|
||||
See [DEVELOPMENT.md](./DEVELOPMENT.md)
|
||||
|
|
|
|||
|
|
@ -1,74 +0,0 @@
|
|||
# Development
|
||||
|
||||
NOTE: The `RichContentService` and `canvas-rce-api` are the same project. It
|
||||
started out as `RichContentService` and was later renamed `canvas-rce-api`.
|
||||
|
||||
`git clone` the code and do the following:
|
||||
```bash
|
||||
cd canvas-rce
|
||||
npm
|
||||
```
|
||||
|
||||
There is a built-in demo application to the `canvas-rce` that allows you to
|
||||
develop locally without having to setup an instance of `canvas-rce-api`
|
||||
this works for many things you might want to develop against, but not all
|
||||
things.
|
||||
|
||||
## Debugging the module
|
||||
|
||||
### debug using the demo app
|
||||
|
||||
There is a demo app included in the `canvas-rce` that will allow you to see
|
||||
many of the changes that You make. you can run this demo app by executing
|
||||
`npm run dev` and then browsing to http://localhost:8080/demo.html
|
||||
|
||||
This demo app loads up with some fake data that makes interaction between
|
||||
the sidebar and the editors not work out well. You can, however, load up the
|
||||
demo app with real data by doing the following
|
||||
|
||||
1. Start the demo app (`npm run dev`) and open it up in a browser:
|
||||
http://localhost:8080/demo.html
|
||||
2. In a separate window, start your `canvas-lms` instance. This instance should
|
||||
be configured to hit the RCS (so you need to have RCS running as well).
|
||||
3. Go to a page in `canvas-lms` that has the RCE loaded through the RCS
|
||||
4. Open the developer console and on the commandline enter `ENV.JWT`. This will
|
||||
display the JWT token. copy this token into your buffer.
|
||||
5. Go back to the RCE Demo app and below the sidebar, click on the
|
||||
"Show Options" button
|
||||
6. In the "Canvas JWT" field, paste your JWT token.
|
||||
7. In the "API Host" field, enter `http://rce.docker` to hit your local RCS.
|
||||
8. Make sure the "Context Type" field is selected for whatever context you
|
||||
pulled the ENV.JWT from (usually "course").
|
||||
9. Make sure the "Context ID" field contains the ID for whatever context you
|
||||
pulled the ENV.JWT from (if "course" above, then this is the course id).
|
||||
10. Select "Update" and you'll be able to use the Demo app for real data.
|
||||
|
||||
### debug in canvas-lms
|
||||
|
||||
If you need/want to see these changes in Canvas, you need to get a
|
||||
local version of canvas-lms to use a new module. Follow these steps to get your
|
||||
local version of canvas to use the newly changed npm module.
|
||||
|
||||
1. Make sure you have a running copy of `canvas-lms` configured to hit a
|
||||
running copy of `canvas-rce-api`.
|
||||
2. Perform a "local publish" of the npm module by executing the
|
||||
`scripts/npm_localpublish.sh` script from the root `canvas-rce` directory.
|
||||
The script handles both local file system copy and docker-machine copy.
|
||||
example1: `scripts/npm_localpublish.sh -t /tmp/canvas-rce`
|
||||
example2: `scripts/npm_localpublish.sh -t /tmp/canvas-rce -d dinghy`
|
||||
3. Modify your local `canvas-lms`'s `package.json` file to change the
|
||||
`"devDependencies"` entry for `canvas-rce` from: `"canvas-rce": "x.y.z",` to:
|
||||
`"canvas-rce": "file:/tmp/canvas-rce",`.
|
||||
4. Run `yarn install` in your `canvas-lms` root directory to install the
|
||||
the `canvas-rce` version you are working on.
|
||||
example1: `yarn install`
|
||||
example2: `docker-compose run --rm web yarn install`
|
||||
|
||||
When you have the module loaded into `canvas-lms`, you can test out the module
|
||||
by seeing what changes were made to the `canvas-lms` environment. It's also
|
||||
useful to to debug the npm module while it's loaded into `canvas-lms`. The
|
||||
non-obvious part is figuring out where the module is in the webpack build. In
|
||||
chrome, just open the 'developer tools', then select the 'sources' tab. In the
|
||||
'sources' tree, browse to 'webpack://' > '.' > '~' > 'canvas-rce' > 'lib' and
|
||||
you'll be able to see all the canvas-rce src files under there. Set your
|
||||
breakpoints as needed and troubleshoot for what you need.
|
||||
Loading…
Reference in New Issue