├── .gitignore ├── .jshintrc ├── .npmignore ├── LICENSE ├── README.md ├── gulpfile.js ├── index.js ├── lib ├── js │ ├── Annotation.js │ ├── AnnotatorForm.js │ ├── Indicator.js │ └── Mixin.js └── styles │ └── annotator.css └── package.json /.gitignore: -------------------------------------------------------------------------------- 1 | # Logs 2 | logs 3 | *.log 4 | 5 | # Runtime data 6 | pids 7 | *.pid 8 | *.seed 9 | 10 | # Directory for instrumented libs generated by jscoverage/JSCover 11 | lib-cov 12 | 13 | # Coverage directory used by tools like istanbul 14 | coverage 15 | 16 | # Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files) 17 | .grunt 18 | 19 | # Compiled binary addons (http://nodejs.org/api/addons.html) 20 | build/Release 21 | 22 | # Dependency directory 23 | # Commenting this out is preferred by some people, see 24 | # https://www.npmjs.org/doc/misc/npm-faq.html#should-i-check-my-node_modules-folder-into-git- 25 | node_modules 26 | 27 | # Users Environment Variables 28 | .lock-wscript 29 | 30 | # Distro files 31 | dist 32 | -------------------------------------------------------------------------------- /.jshintrc: -------------------------------------------------------------------------------- 1 | { 2 | "node": true, 3 | "jasmine": true, 4 | "browser": true, 5 | "esnext": true, 6 | "bitwise": true, 7 | "curly": true, 8 | "eqeqeq": true, 9 | "immed": true, 10 | "indent": 2, 11 | "latedef": true, 12 | "noarg": true, 13 | "regexp": true, 14 | "undef": true, 15 | "unused": true, 16 | "strict": true, 17 | "trailing": true, 18 | "smarttabs": true, 19 | "newcap": false 20 | } -------------------------------------------------------------------------------- /.npmignore: -------------------------------------------------------------------------------- 1 | lib 2 | gulpfile.js 3 | .jshintrc -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2015 Jake Marsh 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | 23 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | react-annotator [![npm version](https://badge.fury.io/js/react-annotator.svg)](http://badge.fury.io/js/react-annotator) 2 | ======================================================================================================================= 3 | 4 | A React mixin to allow for user annotations directly on elements, similar to [Red Pen](https://redpen.io/). An example can be seen [here](http://jakemmarsh.com/react-annotator/). 5 | 6 | --- 7 | 8 | ### Getting Started 9 | 10 | 1. `npm install --save react-annotator` 11 | 2. `var ReactAnnotatorMixin = require('react-annotator').Mixin` 12 | 3. `mixins: [ReactAnnotatorMixin({settings})]` 13 | 4. call `this.renderAnnotationIndicators()` in the component's `render()` function, in order to render the individual indicators at the top-level of the component element. 14 | 15 | ```javascript 16 | var ReactAnnotatorMixin = require('react-annotator').Mixin; 17 | var annotatorSettings = { 18 | element: '.annotator-target', 19 | annotations: [ 20 | { 21 | text: 'This is an annotation on the element.', 22 | xPos: 127, 23 | yPos: 431 24 | }, 25 | { 26 | text: 'This is another annotation on the element.', 27 | xPos: 513, 28 | yPos: 289 29 | } 30 | ] 31 | }; 32 | 33 | var App = React.createClass({ 34 | 35 | mixins: [ReactAnnotatorMixin(annotatorSettings)], 36 | 37 | ... 38 | 39 | render: function() { 40 | return ( 41 |
42 |
43 | ... 44 | {this.renderAnnotationIndicators()} 45 |
46 | ); 47 | } 48 | 49 | }); 50 | ``` 51 | 52 | **Note:** Any interactive elements within the parent component must call `event.stopPropagation()` on click to prevent triggering the new annotation form. 53 | 54 | --- 55 | 56 | ### Options 57 | 58 | A Javascript object is passed to the `ReactAnnotatorMixin` to specify options, as well as any previously created or saved annotations (there is also a method to define these asychronously, discussed below.) The options are: 59 | 60 | - `element` (string): the element selector for the parent element which the annotations are intended for. No default value, and the annotation system will not be rendered without a valid element. 61 | - `annotations` (array): the array of annotations to be displayed on the parent element. Defaults to an empty array. 62 | - `addCallback` (function): a function to be called any time a new annotation is entered. The callback is invoked with a single parameter, an object representing the annotation saved (of the format below). Defaults to an empty function. 63 | 64 | Each "annotation" in the array represents one indicator on the parent element, which triggers its textual annotation when triggered. An annotation has the following structure: 65 | 66 | ```json 67 | { 68 | "text": "The tip, comment, note, etc. that was saved for this annotation.", 69 | "xPos": "The X coordinate of the annotation indicator, in relation to the parent element.", 70 | "yPos": "The Y coordinate of the annotation indicator, in relation to the parent element." 71 | } 72 | ``` 73 | 74 | --- 75 | 76 | ### Methods 77 | 78 | Upon including the mixin, a handful of functions will be available to your component. Some of these are intended strictly for internal use in the mixin (all prefixed with an underscore), but there are a few that are intended to provide you with more complex options and interactions. These are outlined below. 79 | 80 | ##### `setAnnotations(annotations, cb)` 81 | 82 | This function is intended to provide you with a method to asynchronously define your annotations (if they need to be fetched from a database, etc.) It takes a list of annotations (of the form discussed earlier), along with an optional callback function as parameters. This will completely overwrite any existing annotations, setting `this.state.annotations` equal to the `annotations` parameter. Once the state is updated, the callback function will be invoked. 83 | 84 | ##### `setAddCallback(cb)` 85 | 86 | This function allows you to asynchronously define the callback that will be invoked any time a new annotation is entered (mentioned above under Options). Useful when you need to access `props` or `state` in the callback. 87 | 88 | ##### `addAnnotation(annotation, cb)` 89 | 90 | This function takes an annotation (of the form discussed earlier), along with an optional callback function as parameters. It pushes the new annotation onto the existing list, updates its state, and invokes the callback function. 91 | 92 | ##### `removeAnnotation(annotation, cb)` 93 | 94 | This function takes an annotation (of the form discussed earlier), along with an optional callback function as parameters. It iterates over the current list of annotations, removing any determined to be equal to the annotation passed (using [lodash](https://lodash.com/)'s `_.isEqual` function.) The state is then updated accordingly, and the callback function is invoked. 95 | 96 | ##### `getAnnotations()` 97 | 98 | This returns the list of annotations currently within the mixin's state. This is essentially a wrapper for the value `this.state.annotations`. 99 | 100 | --- 101 | 102 | ### Styling 103 | 104 | Some basic styling is provided in `/dist/css/annotator.css`. This can either be included directly in your project, or used as a base for your own custom styles. Below, the HTML structure of the annotation system is also outlined for custom styling. 105 | 106 | The annotation system consists of two main elements for each annotation: an `indicator` and a `tooltip`. An indicator is a small, simple element positioned absolutely on the parent element. Upon hover, the associated annotation is triggered which the user can then read. 107 | 108 | In addition, when an empty space is clicked on the parent element an annotation `form` is triggered. This allows the user to enter the annotation text to be saved for that point. 109 | 110 | ##### Indicator 111 | 112 | ```html 113 |
114 | ``` 115 | 116 | ##### Annotation 117 | 118 | ```html 119 |
120 |

{Text of annotation.}

121 |
122 | ``` 123 | 124 | ##### Form 125 | 126 | ```html 127 |
128 | 129 |
130 | ``` 131 | 132 | --- 133 | 134 | ### Testing 135 | 136 | All tests for this package are within the `__tests__/` directory. If you wish to run the tests: 137 | 138 | 1. `git clone git@github.com:jakemmarsh/react-annotator.git` 139 | 2. `cd react-annotator` 140 | 3. `npm install` 141 | 4. `npm test` 142 | -------------------------------------------------------------------------------- /gulpfile.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | var gulp = require('gulp'); 4 | var del = require('del'); 5 | var react = require('gulp-react'); 6 | var runSequence = require('run-sequence'); 7 | var stripDebug = require('gulp-strip-debug'); 8 | var gulpif = require('gulp-if'); 9 | 10 | gulp.task('clean', function(cb) { 11 | 12 | return del(['./dist/css/*', './dist/js/*'], cb); 13 | 14 | }); 15 | 16 | gulp.task('styles', function() { 17 | 18 | return gulp.src('./lib/styles/**/*.css') 19 | .pipe(gulp.dest('./dist/css/')); 20 | 21 | }); 22 | 23 | gulp.task('scripts', function() { 24 | 25 | return gulp.src('./lib/js/**/*.js') 26 | .pipe(react()) 27 | .pipe(gulpif(global.isProd, stripDebug())) 28 | .pipe(gulp.dest('./dist/js/')); 29 | 30 | }); 31 | 32 | gulp.task('dev', function() { 33 | 34 | global.isProd = false; 35 | 36 | runSequence(['styles', 'scripts']); 37 | 38 | gulp.watch('./lib/js/**/*.js', ['scripts']); 39 | gulp.watch('./lib/styles/**/*.css', ['styles']); 40 | 41 | }); 42 | 43 | gulp.task('prod', ['clean'], function() { 44 | 45 | global.isProd = true; 46 | 47 | return runSequence(['styles', 'scripts']); 48 | 49 | }); -------------------------------------------------------------------------------- /index.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | module.exports = { 4 | 5 | Mixin: require('./dist/js/Mixin'), 6 | 7 | Indicator: require('./dist/js/Indicator'), 8 | 9 | Annotation: require('./dist/js/Annotation'), 10 | 11 | AnnotatorForm: require('./dist/js/AnnotatorForm') 12 | 13 | }; -------------------------------------------------------------------------------- /lib/js/Annotation.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | var React = require('react/addons'); 4 | 5 | var Annotation = React.createClass({ 6 | 7 | propTypes: { 8 | xPos: React.PropTypes.oneOfType([ 9 | React.PropTypes.number, 10 | React.PropTypes.string 11 | ]).isRequired, 12 | yPos: React.PropTypes.oneOfType([ 13 | React.PropTypes.number, 14 | React.PropTypes.string 15 | ]).isRequired, 16 | position: React.PropTypes.string.isRequired, 17 | annotation: React.PropTypes.object.isRequired 18 | }, 19 | 20 | getDefaultProps: function() { 21 | return { 22 | xPos: -1000, 23 | yPos: -1000, 24 | position: 'bottom', 25 | annotation: {} 26 | }; 27 | }, 28 | 29 | render: function() { 30 | var classes = 'annotator-tooltip ' + this.props.position; 31 | var styles = { 32 | 'position': 'absolute', 33 | 'top': this.props.yPos, 34 | 'left': this.props.xPos 35 | }; 36 | 37 | console.log('visible annotation:', this.props.annotation); 38 | 39 | return ( 40 |
41 |

{this.props.annotation.text || ''}

42 |
43 | ); 44 | } 45 | 46 | }); 47 | 48 | module.exports = Annotation; -------------------------------------------------------------------------------- /lib/js/AnnotatorForm.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | var React = require('react/addons'); 4 | 5 | var AnnotatorForm = React.createClass({ 6 | 7 | mixins: [React.addons.LinkedStateMixin], 8 | 9 | propTypes: { 10 | xPos: React.PropTypes.oneOfType([ 11 | React.PropTypes.number, 12 | React.PropTypes.string 13 | ]).isRequired, 14 | yPos: React.PropTypes.oneOfType([ 15 | React.PropTypes.number, 16 | React.PropTypes.string 17 | ]).isRequired, 18 | saveAnnotation: React.PropTypes.func.isRequired, 19 | closeForm: React.PropTypes.func.isRequired 20 | }, 21 | 22 | getInitialState: function() { 23 | return { 24 | text: '' 25 | }; 26 | }, 27 | 28 | componentDidMount: function() { 29 | this.refs.textarea.getDOMNode().focus(); 30 | }, 31 | 32 | componentDidUpdate: function(prevProps) { 33 | if ( prevProps.xPos !== this.props.xPos || prevProps.yPos !== this.props.yPos ) { 34 | this.setState({ text: '' }); 35 | this.refs.textarea.getDOMNode().focus(); 36 | } 37 | }, 38 | 39 | handleKeyDown: function(evt) { 40 | var keyCode = evt.keyCode || evt.which; 41 | 42 | if ( keyCode === '27' || keyCode === 27 ) { 43 | this.props.closeForm(); 44 | } else if ( keyCode === '13' || keyCode === 13 ) { 45 | evt.preventDefault(); 46 | this.props.saveAnnotation(this.state.text); 47 | } 48 | }, 49 | 50 | render: function() { 51 | var styles = { 52 | 'position': 'absolute', 53 | 'top': this.props.yPos, 54 | 'left': this.props.xPos 55 | }; 56 | 57 | return ( 58 |
59 |