AngularJS directive for implementing pan and zoom on any DOM element
The 1.0.0 release introduced a breaking change in how the panzoom widget publishes its API. Migration guide here
Get the code from github. Or simpler yet, use bower:
bower install angular-pan-zoom
- Zoom using mouse wheel, double click, or control widget
- Pan using click and drag. When releasing mouse button while panning, the pan will come to a gradual stop.
- AngularJS integrated. Models are used as APIs for communicating
- Widget with zoom controls provided. Use this or design your own controls if you so prefer.
- AngularJS (obviously)
- jQuery (used for managing timing loops)
- Hamster.JS (for mouse wheel support)
- angular-mousewheel (which integrates HamsterJS with angular)
For convenience, these requirements are checked in as part of the project. They are also described by the bower.json file.
Click here for an online demo of the functionality.
When declaring your module:
angular.module('your_module', ['panzoom', ..])
In your controller:
$scope.config = {}; // use defaults
$scope.model = {}; // always pass empty object
In your markup:
<body>
..
<!-- create panzoom, passing models from controller -->
<panzoom config="config" model="model" style="width:800px; height: 600px">
<!-- your content here -->
</panzoom>
..
<!-- include scripts -->
<script src="bower_components/jQuery/dist/jQuery.js"></script>
<script src="bower_components/hamsterjs/hamster.js"></script>
<script src="bower_components/angular/angular.min.js"></script>
<script src="bower_components/angular-mousewheel/mousewheel.js"></script>
<script src="bin/panzoom.js"></script>
</body>
This will provide zoom and pan functionality using default settings. It will, however, not provide any widget to control the zoom and pan.
To use the bundled <panzoomwidget>, you need to
- include bin/panzoomwidget.css on your page
- make your AngularJS module depend upon the panzoomwidget module
- declare an
idattribute on your<panzoom>tag - use a
<panzoomwidget>directive in the markup, specifying itspanzoom-idattribute to be the same value as theidof the<panzoom>tag You will probably also want to position the widget above the zoomed contents be means of CSS. Check ./test.html for a working example.
Refer to panzoomwidget.js for an example of how this may be done. Whether or not you create it as a directive is up to you. To access
the API of a panzoom directive, you need to look it up using the getAPI() method on the bundled PanZoomService, passing the id of the
<panzoom> widget. The method will return a promise.
Example usage:
// assuming the PanZoomService to be a dependency and panzoomId to be the ID of the <panzoom> directive ...
PanZoomService.getAPI(panzoomId).then(function (api) {
// you can now invoke the api
}
The API object contains the following properties:
| Method | Description |
|---|---|
model |
the model object which was passed to the panzoom directive |
config |
the config object which was passed to the panzoom directive |
changeZoomLevel(newZoomLevel [,clickPoint]) |
change zoom level to a new value using a quick animation |
zoomIn() |
shorthand for increasing zoom level by one |
zoomOut() |
shorthand for decreasing zoom level by one |
zoomToFit(rectangle) |
zoom to display a part of the contents. Example rectangle: { "x": 0, "y": 100, "width": 100, "height": 100 } |
getViewPosition(modelPosition) |
takes a argument a {x:.., y:..} in the original, untransformed contents. Returns the current pixel position of this point. |
getModelPosition(viewPosition) |
the reverse operation of getViewPosition() |
May be used to pass configuration options to the panzoom directive. The directive will fill in any "blanks" with default values.
For a list of configuration keys and values you may inspect the object one you get it back.
The config object is not intended to be modified once initialized.
[TBD: List options and explanations here]
When initializing, you should pass an empty object. The directive will initialize the object. You can read the current zoom and pan state at any time from this object.
Any code contributions to the project will be appreciated. A few guidelines follow.
Bower is used for obtaining 3rd party libraries. The libraries in bower_components are also committed along with the project. A 1:1 correspondence between bower.json and the contents of bower_components is expected at all times.
Gulp is used for building the minified files and for running jshint. The gulpfile.js contains instructions for installing npm dependencies. Please commit an up-to-date minified file along with your code, and please make sure that the code passes jshint. The rules are not overly Nazi.
Oh, and the unit tests. You can run gulp test to see if they pass. [TBD: More tests]