Name: web-editor
Owner: Dojo
Description: :rocket: Making it easy to explore Dojo 2 in a browser
Created: 2017-04-25 16:55:30.0
Updated: 2018-01-12 14:43:55.0
Pushed: 2018-01-12 15:05:08.0
Homepage: https://dojo.io
Size: 14942
Language: TypeScript
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
A package that provides editing and running of Dojo 2 projects in browser.
WARNING This is alpha software. This is not yet production ready, so you should use at your own risk.
The web-editor provides three main errors of functionality:
@dojo/cli-export-project and provide the ability to transpile that project
in the browser.monaco-editor
in a browser.iframe.This package is inteded to be integrated into a website which would provide a more rich user interface to allow editing and running
the project in a browser. There is a minimal API implemented in examples/index.html which allows the loading of example projects
that are included in this package in projects. This example is available at
dojo.github.io/web-editor/
This is a singleton instance of a class which provides an API to load and manage a project. A project file is a JSON file that
conforms to the interface described in
ProjectJson which is part of
the @dojo/cli-export-project package.
Because of the way the monaco-editor works, you can only have one environment per page, and project needs to interface with
this environment to instruct the TypeScript services what is available so the editors and the emit for the project work correctly.
There are several key methods of project:
.load(filename: string): Promise<void> - An async function which will retrieve the specified project bundle and populate the
environment with the information from the project. It will resolve when the loading is complete..isLoaded(): boolean - Returns true if the project is loaded, otherwise false..getFiles(...types: ProjectFileType[]): ProjectFile[] - Returns object representations of the files that can be edited in the
project. By default, it will include all the files in the project, but you can specify as many different file types as arguments
and only those types of files will be returned..getFileNames(...types: ProjectFileType[]): string[] - Returns an array of strings that represent the files that can be edited
in the project. This is useful for populating a user interface element of files. By default, it will include all the files
in the project, but you can specify as many different file types as arguments and only those types of files will be returned..get(): ProjectJson | undefined - Returns the object representation of the project JSON, including any changes that have been made
while the project has been loaded..getProgram(): Promise<Program> - Returns an object which contains the properties of css, dependencies, html, and modules
which are designed to be used with the Runner widget as widget properties to specify the program to run.Typical usage would be something like this:
rt project from '@dojo/web-editor/project';
nc () => {
await project.load('some.project.json');
console.log('Loaded!');
;
This is a widget which wraps the other widgets to provide a workbench for editing files and running projects.
The Workbench has a few key properties:
filename - This is the name of the file in the project which should be being displayed in the Editor.files - This is an array of file names that should be displayed in the file tree for user selection.icons - An object structure used to provide a set of icons to be used when displaying a file in the tree.iconsSourcePath - The path to the file icons to be used.program - This is an emitted Program which is passed to the Runner.onFileOpen - A method that gets called when a file is requested to be opened from the file tree. If appropriate, to change the file being edited, update the filename property with the supplied ID.onRun - A method that gets called when the Runner finishes running the supplied program. This can be used to determine when to update the UI to reflect that program has been run.Workbench is a themeable widget, with workbench.root and workbench.filepane being themeable.
This is a widget which wraps monaco-editor, allowing the editor to seemlessly integrate with the project. It will automatically
display files with the appropriate language intellisense as well as the file is edited, changes will automatically be sent to
the project to keep it updated.
The Editor has two key properties:
filename - This is the name of the file in the project which the editor should be displaying. Changing this property will cause the widget to change the file that is currently being displayed.options - Passed to the monaco-editor when it is created. Needs to conform to the monaco.editor.IEditorOptions interface.Editor is a themeable widget, with the only themeable class being editor.root.
Typical usage would be something like this:
rt project from '@dojo/web-editor/project';
rt Editor from '@dojo/web-editor/Editor';
rt { v, w } from '@dojo/widget-core/d';
rt Projector from '@dojo/widget-core/mixins/Projector';
rt WidgetBase from '@dojo/widget-core/WidgetBase';
nc () => {
await project.load('some.project.json');
class App extends WidgetBase {
render() {
return v('div', [
w(Editor, {
filename: './src/main.ts'
})
]);
}
}
const projector = new (Projector(App))();
projector.append();
;
A widget runs a program in an iframe. Updating the properties related to the program on the widget will
cause it to re-render the program.
The Runner has several key properties which control its behaviour:
css, dependencies, html, and modules - Properties that are part of a Program obtained from the returned promise of
project.getProgram().loader - An optional property which specifies the URI for the AMD loader to use with the program. It defaults to the latest
version of the @dojo/loader.src - An optional URI that will be the src of the iframe until a program is first run. This needs to be a relative URI
to the host in order to ensure that the run program is not impacted by cross-domain restrictions.onError - When a program is running and generates an error, this method would be called, passing a single argument of the error.onInitIframe - Called, with an argument of the iframe which is called when the Runner has configured the iframe in the DOMonRun - A method that is called when the Runner is finished standing up the program. It does not reflect the actual state
of the program.Runner is a themeable widget, with the only themeable class being runner.root.
rt { assign } from '@dojo/core/lang';
rt project, { Program } from '@dojo/web-editor/project';
rt Runner, { RunnerProperties } from '@dojo/web-editor/Runner';
rt { v, w } from '@dojo/widget-core/d';
rt { WidgetProperties } from '@dojo/widget-core/interfaces';
rt Projector from '@dojo/widget-core/mixins/Projector';
rt WidgetBase from '@dojo/widget-core/WidgetBase';
rface AppProperties extends WidgetProperties {
program?: Program
nc () => {
await project.load('some.project.json');
class App extends WidgetBase<AppProperties> {
render() {
return v('div', [
w(Runner, this.properties.program)
]);
}
}
const projector = new (Projector(App))();
projector.append();
const program = await project.getProgram();
project.setProperties({ program });
;
This module wraps @dojo/routing in a way that works well for the web-editor.
The web-editor allows integration with GitHub's Gists, allowing storage of the project.json in a Gist which can then be used to load
the project into the editor.
Set the path on the current page. When a project is loaded, this is used to update the path to reflect the Gist's ID.
startGistRouter() is function that will configure and start the router, returning a pausable handle. The function takes a single options argument which has two required properties:
onGist - Called when the location is /{id}, intended to note a change in the Gist ID.onRoot - Called when the location is /, intended to note that no Gist has been loaded.Typical usage would look like:
rt { startGistRouter } from '@dojo/web-editor/routing';
tGistRouter({
onGist(request) {
// request.params.id contains the requested Gist ID
// so if the project is not loaded, load the project with the supplied ID
},
onRoot() {
// navigation has occured to the root, if the project is not loaded,
// enable UI elements to allow a user to select a project
}
In order to properly transpile CSS that is part of a project, the web-editor needs to utilise postcss with additional plugins for this purpose. Because postcss is distributed as a NodeJS package, it is necessary to make this available in the browser with appropriate fills of NodeJS functionality. This is accomplished by creating a WebPack bundle of the modules and exporting the key modules as globals.
This bundle needs to be loaded prior to loading the AMD loader, otherwise there will be conflicts between the WebPack require() and
the AMD require(). It should look something like this:
CTYPE html>
l><title>Example</title></html>
y>
<script src="node_modules/@dojo/web-editor/external/postcss-bundle.js"></script>
<script src="node_modules/@dojo/web-editor/node_modules/monaco-editor/min/vs/loader.js"></script>
<script>
window.MonacoEnvironment = {
getWorkerUrl: function () {
return '../worker-proxy.js';
}
};
require.config({
paths: {
'vs': 'node_modules/@dojo/web-editor/node_modules/monaco-editor/min/vs',
'@dojo': 'node_modules/@dojo'
}
});
require([ './example' ], function () {});
</script>
dy>
There are several modules which are used to support the functionality of the web editor.
This module is used with @dojo/core/require to make it possible to retrieve inlined resources, like JSON, from a runner application. This
will be injected, like the other transpiled modules, which resolve local resources via AMD and pass remote requests to
@dojo/core/require/providers/xhr.
This module provides the transpilation of CSS for a runner application. It provides the ability to run the CSS through CSSNext and also provides the necessary information to allow CSS Modules to work in Dojo 2 applications.
A module where the default export is a reference to the global DOMParser.
A module that provides tools for working with project.json files that are stored in GitHub Gists.
An async function that resolves to a description and a URL to a package.json for a given Gist ID.
An example of usage:
rt { getById } from '@dojo/web-editor/support/gists';
nc () => {
const gist = await getById(someId);
await project.load(gist.projectJson);
;
An async function that resolves to an array of descriptions, IDs, and URLs to a package.json files stored in Gists for a given user.
An example of usage:
rt { getByUsername } from '@dojo/web-editor/support/gists';
nc () => {
const gists = await getById(someUsername);
gists.forEach((gist) => {
// populate a UI with available Gists
});
;
This module provides the ability to inline JSON to the AMD loader so that local project resources are available to the runner application.
These are modules which export the exposed globals from the postcss-bundle.
This is script which will setup the monaco-editor web workers to be able to provide better performance when editing and running
projects. This file should be configured up in the monaco-editor environment before attempting to load the rest of monaco-editor.
For example, you might have something like this in your web-editor page:
ipt>
window.MonacoEnvironment = {
getWorkerUrl: function () {
return 'node_modules/@dojo/web-editor/support/worker-proxy.js';
}
};
ript>
The package is typically instlaled using npm. The distrubition though comes with a version of monaco-editor that uses the current
version of TypeScript. Therefore it is often better to use that included version than the version that is currently available, as it
appears the general avaialable version lags behind in updating.
This package also includes the following libraries and their dependencies:
monaco-editor - © 2016 Microsoft Corporation. MIT license.postcss - © 2013 Andrey Sitnik. MIT license.postcss-cssnext - © 2014 Maxime Thirouin. MIT license.postcss-modules - © 2015 - 2016 Alexander Madyankin. MIT license.© 2017 JS Foundation. New BSD license.