diff --git a/content/docs/authoring/authoring.md b/content/docs/authoring/authoring.md deleted file mode 100644 index 584eee5d..00000000 --- a/content/docs/authoring/authoring.md +++ /dev/null @@ -1,18 +0,0 @@ -# PIE Authoring - -> Status: Draft - -PIE Interaction developers can create configuration panel UI that allow content authors to configure interactions. - - -- A Custom Element that renders a configuration panel can be created by a developer as an ES6 Javascript module. -- The configuration module is a standard independent NPM package, it may be included within a pie in a `configure` directory. -- the PIE cli `pie info` command will load the package when previewing a PIE. - -## Handling File Uploads - -An uploader property will be set on the Config Panel Element that supports handling user file uploads. - -See the [Uploader API](uploader.md) - - diff --git a/content/docs/authoring/introduction.md b/content/docs/authoring/introduction.md new file mode 100644 index 00000000..93b0a5dc --- /dev/null +++ b/content/docs/authoring/introduction.md @@ -0,0 +1,13 @@ +# PIE Authoring + +> Status: Draft + +Authoring depends on the `configure` components of a pie. These are optional packages that a pie developer can add to a pie definition. See [Configur](/docs/developing/configure) for more information. + +> The PIE cli `pie info` command will give a preview of the configure element if run from the foot of a pie item definition. + +## Handling Image Uploads + +Configure elements dispatch an event `'insert.image'`. See the [uploading](uploader.md) for more information. + + diff --git a/content/docs/authoring/uploader.md b/content/docs/authoring/uploader.md index a6c7cbb9..d0bffba8 100644 --- a/content/docs/authoring/uploader.md +++ b/content/docs/authoring/uploader.md @@ -1,96 +1,36 @@ -# File Uploader +# Image Upload > Status: Draft -The File Uploader is provided to Configuration Elements to support uploading of assets that may be needed in a question. -The details of delivering the file to a storage system are external to the Configuration Element. The page +# Insert Image +> See [pie-configure-events](https://github.com/pieelements/pie-elements) for information on the events dispatched. -## How can I use it? -An `uploader` property is set on the Config Panel Element by the page that contains the Element: +Configure elements dispatch a `'insert.image'` event. The `event.detail` is a handler object with the following api: +### `cancel()` -To allow files to be selected and drag-dropped, you need to assign a drop target or a DOM item to be clicked for browsing for files: +Cancels the insert image process. - uploader.assignBrowse(document.getElementById('browseButton')); - uploader.assignDrop(document.getElementById('dropTarget')); +### `done(err?: Error, src:string)` -After this, interaction with `uploader` is done by listening to events: +Completes the insert image process, if `err` is present must be an `Error` with information on why the insertion failed. If `src` is present, it will be used as the href for a new `` element. - uploader.on('fileAdded', function(file, event){ - ... - }); - uploader.on('fileSuccess', function(file, message){ - ... - }); - uploader.on('fileError', function(file, message){ - ... - }); +### `fileChosen(file:File)` +Notifies the handler that the user has chosen a file. +### `progress(percent:number, bytes: number, total:number)` -## `uploader` API +Notifies the handler that progress has been made on uploading the image. -#### Properties +# Delete Image -* `.files` An array of `UploadFile` file objects added by the user (see full docs for this object type below). +Configure elements dispatch a '`delete.image`' event. The `event.detail` will contain: -#### Methods +* src - the src of the image +* done - a function with the following type: `(err?: Error) => void`. -* `.assignBrowse(domNodes, isDirectory)` Assign a browse action to one or more DOM nodes. Pass in `true` to allow directories to be selected (Chrome only). -* `.assignDrop(domNodes)` Assign one or more DOM nodes as a drop target. -* `.on(event, callback)` Listen for event from `uploader` (see below) -* `.upload()` Start or resume uploading. -* `.pause()` Pause uploading. -* `.cancel()` Cancel upload of all `UploadFile` objects and remove them from the list. -* `.progress()` Returns a float between 0 and 1 indicating the current upload progress of all files. -* `.isUploading()` Returns a boolean indicating whether or not the instance is currently uploading anything. -* `.addFile(file)` Add a HTML5 File object to the list of files. -* `.removeFile(file)` Cancel upload of a specific `UploadFile` object on the list from the list. -* `.getFromUniqueIdentifier(uniqueIdentifier)` Look up a `UploadFile` object by its unique identifier. -* `.getSize()` Returns the total size of the upload in bytes. - -#### Events - -* `.fileSuccess(file, message)` A specific file was completed. `message` is the response body from the server. -* `.fileProgress(file)` Uploading progressed for a specific file. -* `.fileAdded(file, event)` A new file was added. Optionally, you can use the browser `event` object from when the file was added. -* `.filesAdded(arrayAdded, arraySkipped)` New files were added (and maybe some have been skipped). -* `.fileRetry(file)` Something went wrong during upload of a specific file, uploading is being retried. -* `.fileError(file, message)` An error occurred during upload of a specific file. -* `.uploadStart()` Upload has been started on the Resumable object. -* `.complete()` Uploading completed. -* `.progress()` Uploading progress. -* `.error(message, file)` An error, including fileError, occurred. -* `.pause()` Uploading was paused. -* `.beforeCancel()` Triggers before the items are cancelled allowing to do any processing on uploading files. -* `.cancel()` Uploading was canceled. -* `.preparationStart(file)` Started preparing file for upload -* `.preparationProgress(file,ratio)` Show progress in file preparation -* `.preparationComplete(file)` File is ready for upload -* `.catchAll(event, ...)` Listen to all the events listed above with the same callback function. - -### `UploadFile` API - -#### Properties - -* `.uploaderObj` A back-reference to the parent `uploader` object. -* `.file` The correlating HTML5 `File` object. -* `.fileName` The name of the file. -* `.relativePath` The relative path to the file (defaults to file name if relative path doesn't exist) -* `.size` Size in bytes of the file. -* `.uniqueIdentifier` A unique identifier assigned to this file object. This value is included in uploads to the server for reference, but can also be used in CSS classes etc when building your upload UI. - - -#### Methods - -* `.progress(relative)` Returns a float between 0 and 1 indicating the current upload progress of the file. If `relative` is `true`, the value is returned relative to all files in the `uploader` instance. -* `.abort()` Abort uploading the file. -* `.cancel()` Abort uploading the file and delete it from the list of files to upload. -* `.retry()` Retry uploading the file. -* `.bootstrap()` Rebuild the state of a `UploadFile` object, including reassigning chunks and XMLHttpRequest instances. -* `.isUploading()` Returns a boolean indicating whether file chunks is uploading. -* `.isComplete()` Returns a boolean indicating whether the file has completed uploading and received a server response. diff --git a/content/docs/developing/configure.md b/content/docs/developing/configure.md new file mode 100644 index 00000000..bbfe3e53 --- /dev/null +++ b/content/docs/developing/configure.md @@ -0,0 +1,28 @@ +# Configure + +The configure package is used to render a configuration ui, that allows a user to update a data model for use with a pie `controller` and `element`. + +The configure package should export a custom element so it can be used as follows: + +```javascript +import MyElConfigure from 'my-el-configure'; +customElements.defined('my-el-configure', MyElConfigure); +``` + +> The default export from the configure package should not define a custom element, this will be handled by pie. + +## Api + +### `set model(m:Object)` + +This sets the model on the element, which in turn should render a UI for the given model. + +### `Event: 'model.updated'` + +This event should be dispatched from the element if the `model` has been updated by the user. + +### `Event: 'insert.image'` + +This event should be dispatched if the user wishes to insert an image. See [Image Upload](/docs/authoring/uploader) for more information. + +> You can used [pie-configure-events](http://github.com/pieelements/pie-configure-events) for the 2 events above. \ No newline at end of file diff --git a/content/docs/developing/controller.md b/content/docs/developing/controller.md index 38e6849b..b894f983 100644 --- a/content/docs/developing/controller.md +++ b/content/docs/developing/controller.md @@ -2,23 +2,10 @@ The PIE Controller is logic that can be provided by your PIE to set the model for the PIE Element for the user interface and to process a user's session to provide an outcome. -This module should export two functions, `model` and `outcome` - +The controller package should export two functions, `model` and `outcome` so it can be used as follows: ```javascript - -export function model(config, session, env) { - return new Promise((resolve, reject) => { - //... - }); -} - -export function outcome(config, session, env) { - return new Promise((resolve, reject) => { - //... - }); - -} +import {model, outcome} from 'my-controller'; ``` diff --git a/content/docs/developing/custom-element.md b/content/docs/developing/element.md similarity index 97% rename from content/docs/developing/custom-element.md rename to content/docs/developing/element.md index 72afaa61..318be784 100644 --- a/content/docs/developing/custom-element.md +++ b/content/docs/developing/element.md @@ -1,7 +1,14 @@ -# Custom Element +# Element The user interface for a PIE is provided in the browser by a [Custom Element](https://www.w3.org/TR/custom-elements/). +The element package must export a custom element so that it may be used as follows: + +```javascript +import MyEl from 'my-el'; +customElements.define('my-el', MyEl); +``` + It should be defined in an ES6 module which is included as the main entry point the package (see [Packaging](../packaging.md)) > The most basic definition of an Element module is an ES6 module (CommonJS is also supported). diff --git a/content/docs/developing/summary.md b/content/docs/developing/introduction.md similarity index 81% rename from content/docs/developing/summary.md rename to content/docs/developing/introduction.md index 97890191..e5c99cae 100644 --- a/content/docs/developing/summary.md +++ b/content/docs/developing/introduction.md @@ -1,8 +1,18 @@ -# Summary +# Introduction Each PIE is an individual UI Element or interaction that is designed to be re-used in the context of assessment. An example of a PIE might be a multi-choice question-type or a question-type that allows a student to make a bar chart or plot points on a graph. However a PIE does not to be a question type, it can be any Custom Element. -Users can configure one or more instances of PIEs to create questions/assessment experiences for students. See [Rendering Items](/using/rendering-items.md) +Users can configure one or more instances of PIEs to create questions/assessment experiences for students. See [Rendering Items](/using/rendering-items.md). + + +# The pieces of a PIE + +A PIE is at a minimum a package that defines a custom element for rendering. It may also define a controller for processing the model before sending it to the ui element and also a configuration ui, that can be used for editing the pie's data model. All these parts are defined by using some packaging conventions. Follow the links below for more detail: + +* [defining a pie package](/developing/packaging) +* [element](/developing/element) +* [controller](/developing/controller) +* [configuration](/developing/confiration) To create a PIE a developer implements: diff --git a/content/docs/developing/packaging.md b/content/docs/developing/packaging.md index 11f593ad..d9a4df59 100644 --- a/content/docs/developing/packaging.md +++ b/content/docs/developing/packaging.md @@ -1,101 +1,111 @@ -## Packaging +# Packaging -PIEs are defined as NPM packages, and as a best practice follow a structure for including documentation and a demonstration of the PIE. +PIEs are defined as NPM packages. -## NPM Package +> The package definition is contained in `package.json` see [npm documentation](https://docs.npmjs.com/files/package.json) for full documentation on npm packages. +There are up to 3 parts that make up a pie: -The following directory structure and files should be present in the package (and included when it is installed with npm): +| Name | Description | Required? | +|----------------------------|----|--| +| `element` | the custom element that renders in an assessment context | yes | +| `controller` | the logic for preparing the data model for the `element` | no| +| `configure` | the custom element that renders a configuration ui for editing the data model. | no| -| File | Description | Required? | -|----------------------------|----------------------------------------------------------------------------------------------------------------------|-------------| -| `README.md` | Documentation to describe the PIE to users | yes | -| `package.json` | Definition for the PIE as an NPM package. Including dependencies needed for rendering | yes | -| `controller/` | Folder containing controller code | no | -| `controller/package.json` | Used to define dependencies and `main` file for the controller. Dependencies should be kept to a minimum and should not use IO | no | -| `docs/schema.json` | JSON schema document that defines the configuration model for the PIE | recommended | -| `docs/demo` | Directory that defines a demonstration assessment item that uses this PIE | recommended | -| `docs/demo/index.html` | The HTML markup for the demo assessment item | recommended | -| `docs/demo/config.json` | The JSON config for the demo assessment item | recommended | -| `src/` | Directory for the PIE Element source code* | recommended | -| `test/` | Directory for the test code | recommended | +### Internal vs External components -> \* The PIE element source code can be placed in any directory as long as the `main` property in `package.json` points to the main module for this code. +A pie may define external or internal packages for `element`, `controller` and `configure` (or any combination thereof). +#### Defining external components -> Additional directories and files may be added at the discretion of the developer, but care should be taken so that only necessary files are included with the package using the `files` property in package.json and `.npmignore` file as necessary. +* add a dependency declaration to the npm package you want to use. +* add a `pie` object to the package.json and within that map either `element`, `controller` or `configure` to the dependency. -> The controller's package name must be `${mainPackageName}-controller`. +Here is an example: -The package definition is contained in `package.json` see [npm documentation](https://docs.npmjs.com/files/package.json) for full documentation on npm packages. - -Example Package.json: - -```json +```javascript { - "name": "my-pie", - "version": "0.0.1", - "main": "src/index.js", - "dependencies": {...}, - "files": ["docs", "src", "controller"], + "name" : "foo", + "dependencies" : { + "my-el" : "^1.0.0", + "my-controller" : "^1.0.0", + "my-configure" : "^1.0.0" + }, + "pie" : { + "element" : "my-el", + "controller" : "my-controller", + "configure" : "my-configure" + } } -``` - - -#### name (required) - -The package `name` property will be used as the Custom Element name. Elements should be named according to W3C [rules](https://www.w3.org/TR/custom-elements/#concepts) for Custom Elements (all-lowercase, must contain a hyphen). The name of the PIE should be unique, as such, we recommend using your organization name as the first part of the name, e.g. `organization-pie-name` - -### version (required) - -This is the [semver](semver.org) version for your PIE. The semver rules should be followed so that breaking changes will not be applied to existing questions that use your pie. - -### main (required) - -This is the entry point for defining the Custom Element for your PIE. - -This file will be defined as a `.js` file and should be an ES6 module that is the entry point module for your Custom Element. (See examples in [Custom Element](custom-element.md)) +``` -> Important: You should not bundle / pack your PIE's dependencies in this file, The [PIE CLI packaging tool](https://github.com/PieLabs/pie-cli) will do that on your behalf. +With the above this pie will use `my-el` as the element, `my-controller` as the controller and `my-configure` as the configure element. +#### Defining internal components -### dependencies +To define internal components you add the source directly to the package. +* for `element` add it to the npm root package +* for `controller` and `configure` add a 'controller' or 'configure' directory (which should also be an npm package) and add the source within that. -Define dependencies that need to be included with your PIE when it is run in the browser. -Care should be taken to only define dependencies that are used in the PIE and to not add too much download size to the PIE when distributed. +Your directory structure will look like this: -### files +```bash +foo/ + package.json + configure + package.json + src/ #configure src here + controller/ + package.json + src/ #controller src here + src/ # element src here +``` -Defines what files should be downloaded when the package is installed. +> Don't forget to set the `main` key in your package.json files to point to your npm package's entry point. -> `README.md`, and `package.json` and some [other files](https://docs.npmjs.com/files/package.json#files) will always be included by npm +> When using internal packages for controller and configure, the name in their package.json files must be `${mainPackageName}-${controller|configure}`. +#### Defining a combination +You can mix the two techniques above when defining your pie. If you only want to use an external `element` package, but keep `configure` and `controller` internal, you can do the following: -## Demo and Docs +```javascript +{ + "name" : "foo", + "dependencies" : { + "my-el" : "1.0.0" + }, + "pie" : { + "element" : "my-el" + } +} +``` -The [pie-cli] `serve` utility helps load and preview PIEs, it enforces some conventions about how a PIE is structured so that it can be easily reviewed in a consistent way. +```bash +foo/ + package.json + configure # internal configure package + package.json + src/ #src here + controller/ # internal controller package + package.json + src/ #src here + # no need for element logic - we use an external package +``` -To support this, as described above, the following files should be present in a PIE package: +## Demo directory -``` -README.md -docs/ - schema.json - demo/ - index.html - config.json -``` +It is useful to add a demo pie item to your package. By default pie expects this to be in `docs/demo`. The demo pie item should consist of: -#### README.md +* index.html - the markup for the item +* config.js OR config.json - the data for the item -This markdown file should describe and document how to use the PIE. +See [defining items](/docs/using/defining-items/) for information on how to define a pie item. -#### schema.json +## Schema directory -This file should be a json schema document, describing the model for the `config` object that needs to be provided by a content author to use an instance of the PIE. +It is useful to add a schema directory. By default pie expects this to be in `docs/schemas`. -#### demo/ +> Note: There may be changes coming in how one defines a schema and how it is validated. -This should contain a sample usage of the PIE, see [Defining Questions](../using/defining-questions.md). diff --git a/content/docs/using/defining-items.md b/content/docs/using/defining-items.md index 6af60dee..36ccf950 100644 --- a/content/docs/using/defining-items.md +++ b/content/docs/using/defining-items.md @@ -5,12 +5,13 @@ Using PIEs (Portable Interactions and Elements) an author can define an Assessme A simple example is a single Multi-Choice question with text prompt and choices. A more advanced example might include more than one question or interaction type, include content like text passages, video or charts, and include tools to support a user like a calculator or accessiblity tools. -To define an Assessment Item a user (or more typically an authoring system) creates a JSON and HTML file: +To define an Assessment Item a user (or more typically an authoring system) creates a JS/JSON and HTML file: -- **config.json** - Contains the definition and configuration data for the PIEs used in the item. +- **config.js | config.json** - Contains the definition and configuration data for the PIEs used in the item. - **index.html** - Contains the Custom Element declarations within html markup. + These files are placed in a directory structure which may also contain any assets that the Item needs such as images, media or metadata. @@ -24,12 +25,14 @@ These files are placed in a directory structure which may also contain any asset > note: formats for metadata for Items is outside the scope of PIE Framework itself. -### Config JSON +### Config JS/JSON -The `config.json` file defines the configuration model for the Assessment Item and for the PIEs in the Item. For example a configuration for a mult-choice PIE question would include the choices, and the correct responses. +The `config.(js|json)` file defines the configuration model for the Assessment Item and for the PIEs in the Item. For example a configuration for a mult-choice PIE question would include the choices, and the correct responses. -The JSON definition contains the following properties: +> Note: If using config.js, it should export an object like so: `module.exports = {}`. + +The JSON definition contains the following properties: #### player (optional) @@ -40,8 +43,6 @@ The JSON definition contains the following properties: This defines the PIE Player npm package to use for rendering the item. If this property is not defined, the latest version of `pie-player` will be used by the packaging tool when assessment item. - - #### `elements` (required) The `elements` object defines all the PIEs that are used in the Assessment Item. @@ -65,7 +66,6 @@ For example using, `~1.0.1` will indicate that any 'patch' / bug fix version of > For advanced use, `elements` can be defined as local files or directories, see [advanced](#advanced) section below. - #### `models` An array of Objects providing configuration data for Interaction Elements in the Assessment Item. diff --git a/src/layouts/DocsPage/index.js b/src/layouts/DocsPage/index.js index f0bc456a..d72bd6ca 100644 --- a/src/layouts/DocsPage/index.js +++ b/src/layouts/DocsPage/index.js @@ -47,16 +47,17 @@ export default function DocsPage(props) {
  • PIE Development
  • Authoring Development