Feature/pie 10.1.0

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.
+
+

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 `<img>` 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.
 

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.

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';
 ```
 
 

content/docs/developing/custom-element.md → 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).

content/docs/developing/summary.md → 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: