Skip to content

Commit

Permalink
docs: Update documentation to reflect changes in v4.0 (#689)
Browse files Browse the repository at this point in the history
  • Loading branch information
@jstoffan
jstoffan authored May 21, 2021
1 parent 2d353cf commit 8141c7d
Show file tree
Hide file tree
Showing 14 changed files with 41 additions and 644 deletions.
63 changes: 7 additions & 56 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,76 +4,27 @@
[![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

`en-AU`, `en-CA`, `en-GB`, `en-US`, `bn-IN`, `da-DK`, `de-DE`, `es-419`, `es-ES`, `fi-FI`, `fr-CA`, `fr-FR`, `hi-IN`,`it-IT`, `ja-JP`, `ko-KR`, `nb-NO`, `nl-NL`, `pl-PL`, `pt-BR`, `ru-RU`, `sv-SE`, `tr-TR`, `zh-CN`, `zh-TW`

## 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

Expand Down
41 changes: 12 additions & 29 deletions docs/CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -39,38 +39,21 @@ The upstream source is the project under the Box organization on GitHub. To add
git remote add upstream [email protected]: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:

Expand All @@ -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.

Expand Down
27 changes: 13 additions & 14 deletions docs/dev-setup.md → docs/DEVELOPING.md
View file
Original file line number Diff line number Diff line change
@@ -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 [email protected]:[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 [email protected]:[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 [email protected]: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 [email protected]: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:

```
{
Expand All @@ -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`.
18 changes: 9 additions & 9 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
- [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)
29 changes: 0 additions & 29 deletions docs/add-annotation-type.md
View file

This file was deleted.

Loading

0 comments on commit 8141c7d

Please sign in to comment.