From 8141c7debbb403c810cd1a1e0588b14d9e2cf28e Mon Sep 17 00:00:00 2001 From: Jared Stoffan Date: Fri, 21 May 2021 13:45:10 -0700 Subject: [PATCH] docs: Update documentation to reflect changes in v4.0 (#689) --- README.md | 63 ++------------ docs/CONTRIBUTING.md | 41 +++------ docs/{dev-setup.md => DEVELOPING.md} | 27 +++--- docs/README.md | 18 ++-- docs/add-annotation-type.md | 29 ------ docs/annotator.md | 126 --------------------------- docs/auth.md | 30 ------- docs/controller.md | 48 ---------- docs/dialog.md | 18 ---- docs/enabling-types.md | 95 -------------------- docs/index.html | 87 ------------------ docs/styles.css | 30 ------- docs/thread.md | 45 ---------- docs/usage.md | 28 ------ 14 files changed, 41 insertions(+), 644 deletions(-) rename docs/{dev-setup.md => DEVELOPING.md} (52%) delete mode 100644 docs/add-annotation-type.md delete mode 100644 docs/annotator.md delete mode 100644 docs/auth.md delete mode 100644 docs/controller.md delete mode 100644 docs/dialog.md delete mode 100644 docs/enabling-types.md delete mode 100644 docs/index.html delete mode 100644 docs/styles.css delete mode 100644 docs/thread.md delete mode 100644 docs/usage.md diff --git a/README.md b/README.md index 17ca3fe71..3e0d335ef 100644 --- a/README.md +++ b/README.md @@ -4,18 +4,14 @@ [![build status](https://travis-ci.com/box/box-annotations.svg?branch=master)](https://travis-ci.com/box/box-annotations) [![npm version](https://img.shields.io/npm/v/box-annotations.svg)](https://www.npmjs.com/package/box-annotations) -# [Box Annotations](https://developer.box.com/docs/getting-started-with-new-box-view#section-annotations) +# [Box Annotations](https://support.box.com/hc/en-us/articles/360048016153-Annotating-Documents) -Box Annotations allow developers to provide collaboration capabilities right from within the embedded Box preview in their application. Box Annotations fit a wide range of use cases and can be used to draw the previewer's attention and/or provide feedback on specific parts of a document or images. To learn more about Box Content Preview and for further documentation on how to use it, please go to our page on [Box Content Preview](https://developer.box.com/docs/box-content-preview). - -Box Content Preview currently supports four annotation types - highlight comment, highlight only, draw, and point annotation. Box Annotations are today supported on documents and image previews only. You can find the full list of supported file types for Box Content Preview at https://community.box.com/t5/Managing-Your-Content/What-file-types-and-fonts-are-supported-by-Box-s-Content-Preview/ta-p/327#FileTypesSupported. +Box Annotations allows users to add markup on top of content displayed by [Box Content Preview](https://developer.box.com/docs/box-content-preview). Annotations improve collaboration by allowing users to draw attention and leave specific feedback on specific areas of a document or image. The library currently supports several [annotation types](https://support.box.com/hc/en-us/articles/360059971834-Document-and-Image-Files-You-Can-Annotate) which can vary based on the type of file being previewed. ## Browser Support -- Desktop Chrome, Firefox, Safari, Edge, and Internet Explorer 11 -- Mobile support available for iOS Safari, Android Chrome - -If you are using Internet Explorer 11, which doesn't natively support promises, include a polyfill.io script (see sample code below) or a Promise library like Bluebird. +- Desktop: Chrome, Firefox, Safari, Edge (Chromium), and Internet Explorer 11 +- Mobile: Android Chrome, iOS Safari, ## Supported Locales @@ -23,57 +19,12 @@ If you are using Internet Explorer 11, which doesn't natively support promises, ## Usage -Box Annotations can be used by pulling from our [NPM package](https://www.npmjs.com/package/box-annotations). - -### Instantiating Box Annotations inside Box Content Preview with default options - -```javascript -var preview = new Box.Preview(); -preview.show('FILE_ID', 'ACCESS_TOKEN', { - container: '.preview-container', - showAnnotations: true, -}); -``` - -Where the default enabled types are `point`, `highlight`, and `highlight-comment` for the Document Annotator and `point` for the Image Annotator. - -### Passing an instance of Box Annotations into Box Content Preview - -```javascript -import BoxAnnotations from 'box-annotations'; - -/* global BoxAnnotations */ -const boxAnnotations = new BoxAnnotations(viewerOptions); - -var preview = new Box.Preview(); -preview.show(FILE_ID, ACCESS_TOKEN, { - container: '.preview-container', - boxAnnotations, -}); -``` - -Where `viewerOptions` is an optional object of viewer-specific annotator options and `disabledAnnotationTypes` is an optional string array of valid annotation types to disable. See [Enabling/Disabling Annotations and Annotation Types](docs/enabling-types.md) below for more details on viewer-specific annotation configurations. - -## Access Token - -Box Annotations needs an access token to make Box API calls. You can either get an access token from the token endpoint (https://developer.box.com/reference#token) or generate a developer token on your application management page (https://blog.box.com/blog/introducing-developer-tokens/). - -If your application requires the end user to only be able to access a subset of the Annotations functionality, you can use [Token Exchange](https://developer.box.com/reference#token-exchange) to appropriately downscope your App/Managed or Service Account token to a resulting token that has the desired set of permissions, and can thus, be securely passed to the end user client initializing Annotations. - -See [the following documentation](docs/auth.md) for more details on Annotation-specific scopes to go alongside Token Exchange. These allow developers to enable/disable functionality on Box Annotations by configuring the appropriate scopes on the downscoped token. To learn more, see [Special Scopes for Box UI Elements](https://developer.box.com/v2.0/docs/special-scopes-for-box-ui-elements). - -## Supported Annotation Types - -Point annotations are supported on both document and image formats. Highlight comment, highlight only, and draw annotations are only supported on document formats. - -Supported document file extensions: `pdf, doc, docx, ppt, pptx, xls, xlsm, xlsx` - -Supported image file extensions: `ai, bmp, dcm, eps, gif, png, ps, psd, svs, tga, tif, tiff` +Box Annotations is a plugin and **must** be used in conjunction with [Box Content Preview](https://developer.box.com/docs/box-content-preview). The latest version of Box Annotations is officially supported in the [Box Web Application](https://app.box.com) only. Older versions may be available for use in third-party applications, but are not officially supported. This library is built and deployed as an [NPM package](https://www.npmjs.com/package/box-annotations). ## Development -- [Dev Setup](docs/dev-setup.md) -- [Contributing](docs/contributing.md) +- [Dev Setup](docs/DEVELOPING.md) +- [Contributing](docs/CONTRIBUTING.md) ## Support diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index f47d8f5a1..78b54757f 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -6,9 +6,9 @@ All contributions are welcome to this project. Before a contribution can be merged into this project, please fill out the Contributor License Agreement (CLA) located at: -https://opensource.box.com/cla/ +https://cla-assistant.io/box/box-annotations -To learn more about CLAs and why they are important to the UI Element projects, please see the [Wikipedia entry](http://en.wikipedia.org/wiki/Contributor_License_Agreement). +To learn more about CLAs and why they are important to open source projects, please see the [Wikipedia entry](http://en.wikipedia.org/wiki/Contributor_License_Agreement). ## Code of Conduct @@ -39,38 +39,21 @@ The upstream source is the project under the Box organization on GitHub. To add git remote add upstream git@github.com:box/box-annotations.git ``` -This will be useful later. +### Step 4: Push your feature branch to your fork -### Step 4: Create a feature branch - -Create a branch with a descriptive name, such as `add-search`. - -### Step 5: Push your feature branch to your fork - -As you develop code, continue to push code to your remote feature branch. Please make sure to include the issue number you're addressing in your commit message, such as: +Keep a separate feature branch for each issue you want to address. As you develop code, continue to push code to your remote feature branch. If applicable, please make sure to include the issue number you're addressing in your commit message, such as: ``` -Tag: Short description (fixes #1234) +tag(scope): short description -Longer description here if necessary +fixes #1234 +longer description here if necessary. +include BREAKING CHANGE keyword for breaking changes. ``` -The Tag is one of the following: - -- `Fix` - for a bug fix. -- `Update` - for a backwards-compatible enhancement or a change to a rule that increases the number of reported problems. -- `New` - implemented a new feature. -- `Breaking` - for a backwards-incompatible enhancement or feature. -- `Docs` - changes to documentation only. -- `Build` - changes to build process only. -- `Upgrade` - for a dependency upgrade. -- `Chore` - for refactoring, adding tests, etc. (anything that isn’t user-facing). - -The message summary should be a one-sentence description of the change, and it must be 72 characters in length or shorter. If the pull request addresses an issue, then the issue number should be mentioned at the end. - -Keep a separate feature branch for each issue you want to address. +The message summary should be a one-sentence description of the change, and it must be 72 characters in length or shorter. For a list of tags, please see the conventional changelog [documentation](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional#type-enum). -### Step 6: Rebase +### Step 5: Rebase Before sending a pull request, rebase against upstream, such as: @@ -81,11 +64,11 @@ git rebase upstream/master This will add your changes on top of what's already in upstream, minimizing merge issues. -### Step 7: Run the tests +### Step 6: Run the tests Make sure that all tests are passing before submitting a pull request. -### Step 8: Send the pull request +### Step 7: Send the pull request Send the pull request from your feature branch to us. Be sure to include a description (as mentioned above in step 5) that lets us know what work you did. diff --git a/docs/dev-setup.md b/docs/DEVELOPING.md similarity index 52% rename from docs/dev-setup.md rename to docs/DEVELOPING.md index 59e9e941f..a64fc70c7 100644 --- a/docs/dev-setup.md +++ b/docs/DEVELOPING.md @@ -1,17 +1,16 @@ ## Development Setup -1. Install latest LTS version of Node `https://nodejs.org/en/download`. -2. Install yarn package manager `https://yarnpkg.com/en/docs/install`. Alternatively, you can replace any `yarn` command with `npm`. -3. Fork the upstream repo `https://github.com/box/box-annotations`. -4. Clone your fork locally `git clone git@github.com:[YOUR GITHUB USERNAME]/box-annotations.git`. +1. Install latest LTS version of Node `https://nodejs.org/en/download` +2. Install yarn package manager `https://yarnpkg.com/en/docs/install` +3. Fork the upstream repo `https://github.com/box/box-annotations` +4. Clone the fork locally `git clone git@github.com:[YOUR GITHUB USERNAME]/box-annotations.git` 5. Navigate to the cloned folder `cd box-annotations` -6. Add the upstream repo to your remotes `git remote add upstream git@github.com:box/box-annotations.git`. -7. Verify your remotes are properly set up `git remote -v`. You should pull updates from the Box repo `upstream` and push changes to your fork `origin`. +6. Add the upstream repo remote `git remote add upstream git@github.com:box/box-annotations.git` +7. Verify the remotes are properly set up `git remote -v`. You should pull updates from the Box repo `upstream` and push changes to your fork `origin`. 8. Install dependencies `yarn install` 9. Test your first build! `yarn build` -10. To test only local annotation changes, see [instantiating a custom instance of Box Annotations](https://github.com/box/box-annotations/#passing-an-instance-of-box-annotations-into-box-content-preview). -11. To link and test your local code changes along with your local Preview changes, run `yarn link` in this repository and `yarn link box-annotations` wherever [Box Content Preview](github.com/box/box-content-preview/) is cloned locally. -12. To automatically rsync files after a Webpack build, add a scripts/rsync.json file with a `location` field. This file should look like: +10. To link and test your local code changes along with your local Preview changes, run `yarn link` in this repository and `yarn link box-annotations` wherever [Box Content Preview](github.com/box/box-content-preview/) is cloned locally. +11. To automatically rsync files after a Webpack build, add a scripts/rsync.json file with a `location` field. This file should look like: ``` { @@ -30,9 +29,9 @@ Install the following plugins in your preferred editor ### Yarn commands -- `yarn build` to generate resource bundles and JS webpack bundles. -- `yarn start` to only generate JS webpack bundles on file changes. -- `yarn test` launches Jest. -- `yarn test:watch` launches Jest for debugging. +- `yarn build` to generate resource bundles and JS webpack bundles +- `yarn start` to only generate JS webpack bundles on file changes +- `yarn test` launches Jest +- `yarn test:watch` launches Jest for debugging -For more script commands see `package.json`. Test coverage reports are available under reports/coverage. +For more script commands see `package.json`. diff --git a/docs/README.md b/docs/README.md index 455ce6426..e5a20b75c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,12 +4,12 @@ General explanations of the available functionality and examples of how to use Box Annotations are available by topic: -* [Contributing to Box Annotations](CONTRIBUTING.md) -* [Developer Setup](dev-setup.md) -* [Using BoxAnnotations](usage.md) -* [Tokens + Scopes](auth.md) -* [Enabling/Disabling Annotation Types](enabling-types.md) -* [Annotator](annotator.md) -* [Annotation Thread](thread.md) -* [Annotation Dialog](dialog.md) -* [Creating a new Annotation Type](add-annotation-type.md) \ No newline at end of file +- [Contributing to Box Annotations](CONTRIBUTING.md) +- [Developer Setup](docs/DEVELOPING.md) +- [Using BoxAnnotations](usage.md) +- [Tokens + Scopes](auth.md) +- [Enabling/Disabling Annotation Types](enabling-types.md) +- [Annotator](annotator.md) +- [Annotation Thread](thread.md) +- [Annotation Dialog](dialog.md) +- [Creating a new Annotation Type](add-annotation-type.md) diff --git a/docs/add-annotation-type.md b/docs/add-annotation-type.md deleted file mode 100644 index 3242fb3af..000000000 --- a/docs/add-annotation-type.md +++ /dev/null @@ -1,29 +0,0 @@ -# Adding support for new Annotation types -See [Image Point Annotations](https://github.com/box/box-annotations/tree/master/src/image) for a basic implementation of an annotation type. - -### Abstract Classes -- Annotator: This class is the communicator between the file itself and the [controller](https://github.com/box/box-annotations/blob/master/src/controllers/AnnotationModeController.js). -- Annotation Controller: This class is the communicator between the [Annotator](https://github.com/box/box-annotations/blob/master/src/Annotator.js) and the [Annotation threads](https://github.com/box/box-annotations/blob/master/src/AnnotationThread.js). Each controller maintains an object of pages which contains an [R-tree](https://github.com/mourner/rbush) -- Annotation Thread: This class maintains an annotation associated by a unique thread ID, ie a drawing/higlight/group of comments at a particular location. Each annotation thread has an AnnotationPopover component and associated UI. - -** {**VIEWER**} refers to a viewer in [Box Content Preview](https://github.com/box/box-content-preview#viewers) - -### The following files/abstract methods need to be implemented: -* controllers/{**TYPE**}ModeController.js i.e. controllers/DrawingModeController.js (extends [AnnotationModeController](https://github.com/box/box-annotations/blob/master/src/controllers/AnnotationModeController.js)): - * Abstract methods that should be implemented by subclasses: - * **handleThreadEvents()** - Handles annotation [thread events](thread.md#events) and emits them to the viewer - * **enter()** - Enables the specified annotation mode - * **exit()** - Disables the specified annotation mode - -* {**VIEWER**}/{**TYPE**}Thread.js i.e. doc/DocPointThread.js (extends [AnnotationThread](https://github.com/box/box-annotations/blob/master/src/AnnotationThread.js)): - * Abstract methods that should be implemented by subclasses: - * **show()** - positions and shows the UI indicator for thread (blue icon for point annotations, highlight itself for highlights, etc) - * **position()** - positions the AnnotationPopover component relative to the associated annotation thread - -### The following files need to be modified: -* {**VIEWER**}/{**VIEWER**}Annotator.js i.e. doc/DocAnnotator.js (extends [Annotator](https://github.com/box/box-annotations/blob/master/src/Annotator.js)): - * Methods that should be modified - * **getLocationFromEvent()** - Returns an annotation location on an image from the DOM event or null if no correct annotation location can be inferred from the event. For point annotations, we return the (x, y) coordinates for the point with the top left corner of the image as the origin. See [DocAnnotator.getLocationFromEvent()](https://github.com/box/box-annotations/blob/master/src/doc/DocAnnotator.js#L145) to see how to support multiple annotation types with this method - - -To test the new annotation type in the specified viewer, add the annotation type to the appropriate viewer option when instantiating BoxAnnotations. See [Enabling/Disabling Annotations and Annotation Types](docs/enablingdisabling-annotations-and-annotation-types.md) for more details. diff --git a/docs/annotator.md b/docs/annotator.md deleted file mode 100644 index 792e34403..000000000 --- a/docs/annotator.md +++ /dev/null @@ -1,126 +0,0 @@ -Annotators -------- - -Annotators are the communicators between the file itself and the [controller](controller.md). The name of an annotator can be one of the following `DocAnnotator` or `ImageAnnotator`. Call `boxAnnotations.getAnnotators()` to get the list of possible annotators. - -Additional Methods ------------------- -`annotator.init()` initializes the annotator. - -`annotator.isModeAnnotatable(/* String */ type)` returns whether or not the current annotation mode is enabled for the current viewer/annotator. - -`annotator.loadAnnotations()` shows saved annotations. - -`annotator.setScale()` sets the zoom scale. - -`annotator.getLocationFromEvent(/* Event */ event, /* String */ annotationType)` determines the annotation location object from a DOM event. - -`annotator.getAnnotatedEl(/* HTMLElement */ containerEl)` determines the DOM element to be annotated on. - -`annotator.getAnnotatedEl(/* HTMLElement */ containerEl)` determines the annotated element in the viewer. - -`annotator.hideAnnotations(/* Event */ event)` conditionally hides all saved annotations on the file based on an optional mouse event. - -`annotator.getCurrentAnnotationMode()` determines which annotation mode is currently active. - -`annotator.render()` renders all annotations on the file. - -`annotator.renderPage(/* Number */ pageNum)` renders all annotations for the specified page. - -`annotator.scrollToAnnotation(/* String */ threadID)` scrolls the annotation with the specified threadID into view. - - -Events ------- -Events can be bound to the annotator object with `addListener` and removed with `removeListener`. Event listeners should be bound before `showAnnotations()` is called, otherwise events can be missed. - -```javascript -import BoxAnnotations from 'box-annotations'; - -const boxAnnotations = new BoxAnnotations(); -const annotatorConf = boxAnnotations.determineAnnotator(options, viewerConfig, disabledAnnotationTypes); - -// Construct and init annotator -const annotator = new annotatorConf.CONSTRUCTOR(options); -var listener = (value) => { - // Do something with value -}; - -// Attach listener before calling show otherwise events can be missed -annotator.addListener(EVENTNAME, listener); - -// Initialize a annotator -annotator.showAnnotations(); - -// Remove listener when appropriate -annotator.removeListener(EVENTNAME, listener); -``` - -EVENTNAME can be one of the following - -* `annotator` event will be fired when we have the annotator instance first available. Box Annotations fires this event before `annotationsfetched` so that clients can attach their listeners before the `annotationsfetched` event is fired from Box Annotations. - -* `annotationsfetched` event will be fired when annotations have been fetched from the Box API. - -* `annotationerror` event will be fired when an annotation error has occured. The event data will contain: -```javascript - { - message: 'message', // Error message to show - } -``` - -* `annotatorevent` Each annotator will fire its own sets of events. For example, the Image Annotator will fire `rotate` or `resize`, etc. while other annotator may fire another set of events. The Annotator wrapper will also re-emit events at the Preview level in Box Content Preview, with event data containing: -```javascript - { - event: EVENTNAME, // Event name - data: DATA, // Event data object - annotatorName: ANNOTATORNAME, // Name of the annotator - fileVersionId: fileVersionId // The file version id - fileId: fileId // The file id - } -``` - -### Example event usage -```javascript -preview.addListener('annotator', (annotator) => { - annotator.addListener('annotationsfetched', () => { - // Do something when annotations are fetched on a preview - }); -}); - -// Event listeners can be attached to viewers -preview.addListener('load', (data) => { - var viewer = data.viewer; - viewer.addListener('annotationsfetched', () => { - // Do something when annotations are fetched on a preview - }); -}); - -preview.addListener('annotatorevent', (data) => { - if (data.event === 'annotationsfetched') { - // Do something when annotations are fetched on a preview - } else if (data.event === 'annotationerror') { - // Do something different when an annotation error has occurred - } else {} -}); - -preview.addListener('annotatorevent', (data) => { - if (data.viewerName === 'Image') { - if (data.event === 'annotationsfetched') { - // Do something when annotations are fetched on an image preview - } - } else if (data.viewerName === 'MultiImage') { - if (data.event === 'annotationsfetched') { - // Do something different when annotations are fetched on a multi-page image - } - } else {} -}); - -preview.addListener('annotationsfetched', (data) => { - if (data.viewerName === 'Image') { - // Do something when annotations are fetched on an image preview - } else if (data.viewerName === 'MultiImage') { - // Do something different when annotations are fetched on a multi-page image - } else {} -}); -``` \ No newline at end of file diff --git a/docs/auth.md b/docs/auth.md deleted file mode 100644 index c73816b73..000000000 --- a/docs/auth.md +++ /dev/null @@ -1,30 +0,0 @@ -Access Token ------------- -Box Annotations needs an access token to make Box API calls. You can either get an access token from the token endpoint (https://developer.box.com/reference#token) or generate a developer token on your application management page (https://blog.box.com/blog/introducing-developer-tokens/). - -If your application requires the end user to only be able to access a subset of the Annotations functionality, you can use [Token Exchange](https://developer.box.com/reference#token-exchange) to appropriately downscope your App/Managed or Service Account token to a resulting token that has the desired set of permissions, and can thus, be securely passed to the end user client initializing Annotations. - -Below are a set of new Annotation-specific scopes to go alongside Token Exchange. These allow developers to enable/disable functionality on Box Annotations by configuring the appropriate scopes on the downscoped token. To learn more, see [Special Scopes for Box UI Elements](https://developer.box.com/v2.0/docs/special-scopes-for-box-ui-elements). - -### Base Scope -| Scope Name | What permissions does it grant? | -| --- | --- | -| base_preview | Allows preview access to a file or files in a folder based on user/file/token permissions | - -### Feature Scopes -| Scope Name | What permissions does it grant? | -| --- | --- | -| item_download | Allows files/folders contents to be downloaded | -| annotation_view_self | Allows user to view their own annotations | -| annotation_view_all | Allows user to view all annotations on the file | -| annotation_edit | Allows user to edit their own annotations (includes annotation_view_self) | - -### Sample Scenarios -| Scenario| Scope Combinations | -| --- | --- | -| User wants basic preview functionality + ability to edit own annotations| base_preview + annotation_edit | -| User wants basic preview functionality + ability to edit own annotations + ability to highlight text| base_preview + annotation_edit + item_download | -| User wants basic preview functionality + ability to view all annotations + ability to edit own annotations| base_preview + annotation_view_all + annotation_edit | -| User wants basic preview functionality + ability to view only their own annotations| base_preview + annotation_view_self | - -**Note:** If the access token is not scoped to include `item_download`, the users will not be able to create highlight annotations even if `highlight` or `highlight-comment` is specified as an enabled annotation type. \ No newline at end of file diff --git a/docs/controller.md b/docs/controller.md deleted file mode 100644 index 5dd669fa9..000000000 --- a/docs/controller.md +++ /dev/null @@ -1,48 +0,0 @@ -Controllers -------- - -This class is the communicator between the [Annotator](https://github.com/box/box-annotations/blob/master/src/Annotator.js) and the [Annotation threads](https://github.com/box/box-annotations/blob/master/src/AnnotationThread.js). Each controller maintains an object of pages which contains a [red/black tree](https://github.com/mourner/rbush). - -Additional Methods ------------------- -`controller.init()` initializes the mode controller. - -`controller.getButton(/* String */ controllerSelector)` returns the annotation button element specified by the class selector. - -`controller.showButton()` shows the annotate button for the specified annotation mode. - -`controller.hideButton()` hides the annotate button for the specified annotation mode. - -`controller.toggleMode()` toggles annotation modes on and off. When an annotation mode is on, annotation threads will be created at that location. - -`controller.exit()` disables the annotation mode. - -`controller.enter()` enables the annotation mode. - -`controller.isEnabled()` returns whether or not the current annotation mode is enabled. - -`controller.instantiateThread()` instantiates the appropriate annotation thread for the current viewer. - -`controller.registerThread(/* Annotation */ annotation)` register a thread with the controller so that the controller can keep track of relevant threads. - -`controller.unregisterThread(/* AnnotationThread */ thread)` unregister a previously registered thread. - -Events ------- -All annotation mode conrollers fire the following events. The event data will contain: -```javascript - { - event: EVENTNAME, // Event name - data: DATA, // Event data object - mode: ANNOTATION_MODE // Controller's annotation mode - } -``` - -| Event Name | Explanation | -| --- | --- | -| togglemode | An annotation mode is toggled on/off. || -| annotationmodeenter | An annotation mode was entered. || -| annotationmodeexit | An annotation mode was exited. || -| annotationmodecontrollererror | An error occurred. || - -See [Annotator Events](annotator.md#example-event-usage) for example event usage. \ No newline at end of file diff --git a/docs/dialog.md b/docs/dialog.md deleted file mode 100644 index 1c049f3b0..000000000 --- a/docs/dialog.md +++ /dev/null @@ -1,18 +0,0 @@ -Annotation Dialog --------------------- - -Annotation dialogs maintain the dialog UI corresponding with an [annotation thread](thread.md), displaying the metadata of annotations and buttons to create/update/delete -### Methods -The following methods are available for the annotation dialogs. - -| Method Name | Explanation | Method Parameters | -| --- | --- | --- | -| show | Positions and shows the dialog | || -| hide | Hides the dialog | || -| hideMobileDialog | Hides and resets the shared mobile dialog | || -| addAnnotation | Adds an annotation to the dialog | {Annotation} annotation to add || -| removeAnnotation | Removes an annotation from the dialog | {string} annotation ID || -| postAnnotation | Posts an annotation in the dialog | {string} annotation text to post || -| position | Positions the dialog | || - -See [Annotator Events](annotator.md#example-event-usage) for example event usage. \ No newline at end of file diff --git a/docs/enabling-types.md b/docs/enabling-types.md deleted file mode 100644 index 636b0f98c..000000000 --- a/docs/enabling-types.md +++ /dev/null @@ -1,95 +0,0 @@ -Enabling/Disabling Annotations and Annotation Types ------------- -Annotation types can be selectively disabled through preview options. The default enabled types are `point`, `highlight`, and `highlight-comment` for the Document Annotator and `point` for the Image Annotator. Viewer options override global showAnnotations value, for that viewer. See [Box Content Preview](https://github.com/box/box-content-preview) for more details on how to set up the Preview instances that are used with Box Annotations here. -``` -// Turn on/off annotations for all viewers -preview.show(..., { - showAnnotations: Boolean -}); -``` -Combined with one of the following: -``` -// Enable all default annotation types for the specified viewer -preview.show(..., { - viewers: { - VIEWER_NAME: { - annotations: { - enabled: Boolean, // Enables/disables if set. Respects "showAnnotations" if empty - } - } - } -}); - -// Enable only certain annotation types are enabled for the specified viewer -preview.show(..., { - viewers: { - VIEWER_NAME: { - annotations: { - enabledTypes: String[] | null // List of annotation types to enable for this viewer. If empty, will respect default types for that annotator. - } - } - } -}); -``` -If an instance of BoxAnnotations is being passed into Box Content Preview, annotations options can be specified by viewer. -``` -/* global BoxAnnotations */ -// Turn on/off all annotation types for each viewer -new BoxAnnotations({ - VIEWER_NAME: { - enabled: Boolean - } -}); - -// Enable/disable the default annotation types for each viewer -new BoxAnnotations({ - VIEWER_NAME: { - enabled: Boolean, // Enables/disables if set. Respects "showAnnotations" if empty - } -}); - -// Enable/disable annotation types for each viewer -new BoxAnnotations({ - VIEWER_NAME: { - enabledTypes: String[] | null // List of annotation types to enable for this viewer. If empty, will respect default types for that annotator. - } -}); -``` - -### Examples -Enable all annotations, turn off for Image Viewer, and enable only point annotations on Document Viewer: -``` -// Pass options into Preview -preview.show(fileId, token, { - showAnnotations: true, - viewers: { - Image: { - annotations: { - enabled: false - } - }, - Document: { - annotations: { - enabledTypes: ['point'] - } - } - } -}); -``` -Enable the default annotation types for the Document and Image viewers, disable all annotations off for MultiImage Viewer, and enable only highlight comment and drawing annotations on Presentation Viewer: -``` -// Instantiate BoxAnnotations with options -const boxAnnotations = new BoxAnnotations({ - MultiImage: { - enabled: false - }, - Presentation: { - enabledTypes: ['highlight-comment', 'draw'] - } -}); - -preview.show(FILE_ID, ACCESS_TOKEN, { - container: '.preview-container', - boxAnnotations -}); -``` \ No newline at end of file diff --git a/docs/index.html b/docs/index.html deleted file mode 100644 index c345c7be4..000000000 --- a/docs/index.html +++ /dev/null @@ -1,87 +0,0 @@ - - - - - - - - - - - - - -
-
-
Token:
- - -
- -
-
File ID:
- - -
-
- -
- - - diff --git a/docs/styles.css b/docs/styles.css deleted file mode 100644 index dcec127fd..000000000 --- a/docs/styles.css +++ /dev/null @@ -1,30 +0,0 @@ -* { - font-family: sans-serif; - margin: 0; - padding: 0; - box-sizing: border-box; -} -.setters-container { - height: 25vh; - display: flex; - font-size: 75%; - justify-content: space-around; - padding: 20px; -} - -.setters-container button,input { - padding: 5px; -} - -.container { - text-align: center; -} - -.container > input { - text-align: center; -} - -#preview-container { - width: 100vw; - height: 75vh; -} diff --git a/docs/thread.md b/docs/thread.md deleted file mode 100644 index e143a277a..000000000 --- a/docs/thread.md +++ /dev/null @@ -1,45 +0,0 @@ -Annotation Thread --------------------- - -Annotation threads maintains a 'thread' of annotations associated by a unique thread ID, ie a group of annotations at the same location. This includes multiple [annotations](https://github.com/box/box-annotations/blob/master/src/Annotation.js) linked by a unique threadID. -### Methods -The following methods are available for the annotation threads. - -| Method Name | Explanation | Method Parameters | -| --- | --- | --- | -| position | Positions the AnnotationPopover | || -| show | Shows the annotation indicator | || -| hide | Hides the annotation indicator | || -| reset | Resets thread state to 'inactive' | || -| renderAnnotationPopover | Shows the appropriate dialog for this thread | || -| unmountPopover | Hides the appropriate indicator for this thread | || -| saveAnnotation | Saves an annotation locally and on the server | {string} annotation type, {text} text of annotation to save || -| deleteAnnotation | Deletes an annotation | {string} annotation ID, {boolean} whether or not to delete on server, default true || - -### Events -All annotation threads fire the following events. The event data will contain: -```javascript - { - data: { - type: 'point', // Annotation type - threadID: '123abc', - userId: '456def', - threadNumber: '1' // Thread number from Annotations API - } - } -``` - -| Event Name | Explanation | -| --- | --- | -| annotationpending | An annotation thread was created but has not yet been saved on the server. || -| annotationthreadsaved | An annotation thread was saved on the server. || -| annotationthreaddeleted | An annotation thread was deleted on the server. || -| annotationsaved | An annotation thread was added and saved to an existing annotation thread on the server || -| annotationdeleted | An annotation thread was deleted from an existing thread on the server. The entire annotation thread is not deleted. || -| annotationcanceled | An annotation thread was cancelled from posting on either a new or existing thread. || -| annotationshow | Shows an annotation thread || -| annotationhide | Hides an annotation thread || -| annotationdeleteerror | An error occurs while deleting an annotation on either a new or existing thread. || -| annotationcreateerror | An error occurs while posting an annotation on either a new or existing thread. || - -See [Annotator Events](annotator.md#example-event-usage) for example event usage. \ No newline at end of file diff --git a/docs/usage.md b/docs/usage.md deleted file mode 100644 index 45d9a9116..000000000 --- a/docs/usage.md +++ /dev/null @@ -1,28 +0,0 @@ -Usage ------ -Box Annotations can be used by pulling from our [NPM package](https://www.npmjs.com/package/box-annotations). - -### Instantiating Box Annotations inside Box Content Preview with default options -```javascript -var preview = new Box.Preview(); -preview.show('FILE_ID', 'ACCESS_TOKEN', { - container: '.preview-container', - showAnnotations: true -}); -``` -Where the default enabled types are `point`, `highlight`, and `highlight-comment` for the Document Annotator and `point` for the Image Annotator. - -### Passing an instance of Box Annotations into Box Content Preview -```javascript -import BoxAnnotations from 'box-annotations'; - -/* global BoxAnnotations */ -const boxAnnotations = new BoxAnnotations(viewerOptions); - -var preview = new Box.Preview(); -preview.show(FILE_ID, ACCESS_TOKEN, { - container: '.preview-container', - boxAnnotations -}); -``` -Where `viewerOptions` is an optional object of viewer-specific annotator options and `enabledTypes` is an optional string array of valid annotation types to enable. See [Enabling/Disabling Annotations and Annotation Types](docs/enablingdisabling-annotations-and-annotation-types.md) below for more details on viewer-specific annotation configurations. \ No newline at end of file