Create interactive prototypes from scratch and design mockups using little code but the full power of the Ember.js ecosystem.
[!NOTE] ember-hotspots was written and is maintained by Mainmatter and contributors. We offer consulting, training, and team augmentation for Ember.js – check out our website to learn more!
TODO: Add animation showing the addon in use
ember install ember-hotspots
This addon has no additional dependencies. However, there are other addons that will make it easier to create prototypes with little if any JavaScript code necessary.
(not)
, (and)
and more.As with all addons, the cost of having these helpers is additional payload size. It won't hurt a standalone prototype to use all of them, but if you use ember-hotspots in an existing application, you may already have similar helpers to your disposal, which is why they do not come as a direct dependency of this project.
Some code examples below make use of ember-truth-helpers
.
This addon provides two components, which can be used to mock features and whole pages in your application or even start a new mock application from scratch.
Image file names ending in @2x
like background@2x.png
are treated as
"Retina" style images, which means they will be displayed at half their actual
pixel size. This allows for crisper rendering on high density displays used in
many mobile devices. No other suffixes are supported. Both <EhBackground />
and <EhHotspot />
will provide feedback if a referenced image is missing.
All images detected by the addon will be preloaded and added to the browsers prefetch list by default. This behavior can be configured in the addons options.
Clicking and holding the left mouse button or tapping and holding on a touch device will reveal all hotspots in the document.
The included dummy application of this addon acts as a online-demo.
Settings can be configured in your applications ember-cli-build.js
.
module.exports = function (defaults) {
// ...
let app = new EmberAddon(defaults, {
// Defaults
'ember-hotspots': {
cwd: '/', // limit image parsing to a subfolder of `/public`. Example: pass `/hotspots` to limit to `/public/hotspots`
// prefetch and preload make sure images are ready when they should be displayed
preload: true, // Preload all images found using a JavaScript preloader which delays your application
prefetch: true, // Put prefetch `<link>` tags in the HTML `<head>` so browsers can preload and cache images
},
});
// ...
};
<EhBackground />
creates a full width background that is centered to the
viewport and automatically grows to the full height of the selected image,
acting as a positional reference for the hotspots.
<EhBackground @src="https://github.com/mainmatter/ember-hotspots/raw/main/path/to/your/image/in/the/public/folder@2x.png">
{{! Add your hotspots here ---}}
</EhBackground>
<EhHotspot />
provides interaction to your mockup and positioned absolute to
the wrapping background. Hotspots may have an optional background image, which
will also provide an automatic size to the hotspot. They can trigger actions
or navigation.
left: 70px, top: 80px, width: 200px, height: 50px Clicking the hotspot will toggle
this.showMenu
fromfalse
totrue
and vice-versa. The variablethis.showMenu
and it's context may not exist explicitly, but they will still work as expected. If you need a more stable state, you may want to reach for a controller or create a wrapping Glimmer/Ember component.
<EhHotspot
@rect={{array 70 80 200 50}}
@action={{fn (mut this.showMenu) (not this.showMenu)}}
/>
On click, navigate to
some/route?optional=true
<EhHotspot
@rect={{array 70 80 200 50}}
@route="some.route"
@queryParams=(hash optional=true)
/>
When adding an image to an hotspot, the height and width default to the dimensions of the image. Specifying width and height will override these defaults. In short, in most cases you only need to pass left and top position to hotspot.
<EhHotspot
@rect={{array 70 80}}
@src="https://github.com/mainmatter/ember-hotspots/raw/main/foo@2x.png"
@action={{fn (mut this.showMenu) true}}
/>
Hotspots react to clicks / taps by default. The @trigger
attribute can be
used to change that to any valid JavaScript DOM event. EhHotspot
also
supports a special event named hover
, which will trigger the @action
twice: Once on mouseenter, once on mouseleave. This can be used to emulate a
hover effect for buttons and other elements like so:
<EhHotspot
@rect={{array 341 671 304 90}}
@src={{if this.buttonHasHover "button-with-hoverstate@2x.png"}}
@action={{fn (mut this.buttonHasHover) (not this.buttonHasHover)}}
@trigger="hover"
/>
In this example the hotspot changes to a background image on hover. The
non-hovered state is expected to be part of the background. You could also add
a second image to the parameter list of the {{if }}
which will be shown when
the condition is falsy.
While not included in the addon, this pattern can be wrapped in a template-only Glimmer component for easier re-use.
/public
folder:
Using the generate commmand of ember-cli
will setup and create
the correct files for your routes.
ember generate route index
will generate templates/index.hbs
, where we can
put this code:
<EhBackground @src="https://github.com/mainmatter/ember-hotspots/raw/main/path/to/your/image/in/the/public/folder@2x.png">
{{! The logo hotspot }}
<EhHotspot
@rect={{array 0 0 200 100}}
@route="index"
/>
{{! The hotspot for the menu toggle }}
<EhHotspot
@rect={{array 900 0 100 100}}
@action={{fn (mut this.showMenu) (not this.showMenu)}}
/>
{{! The menu }}
<EhHotspot
@rect={{array 0 100}}
@src="https://github.com/mainmatter/ember-hotspots/raw/main/menu@2x.png"
@action={{fn (mut this.showMenu) false}}
@route="another-route"
/>
</EhBackground>
ember generate route another-route
will generate
templates/another-route.hbs
, which will hold this code:
<EhBackground @src="https://github.com/mainmatter/ember-hotspots/raw/main/path/to/your/image/in/the/public/folder@2x.png">
<EhHotspot
@rect={{array 0 0 200 100}}
@route="index"
/>
<EhHotspot
@rect={{array 900 0 100 100}}
@action={{fn (mut this.showMenu) (not this.showMenu)}}
/>
<EhHotspot
@rect={{array 0 100}}
@src="https://github.com/mainmatter/ember-hotspots/raw/main/menu@2x.png"
@action={{fn (mut this.showMenu) false}}
@route="another-route"
/>
</EhBackground>
See the Contributing guide for details.
Ember Hotspots is developed by and © Mainmatter GmbH and contributors. It is released under the MIT License.