Annotation API
This is intended to be used by webmasters/bloggers wishing to add pop-up annotation to their web pages. If you are interested in adding this functionality to your browser instead, you should look at the annotation bookmarklet.
Yes, this is completely free.Quick Start
Add the following before </body>
, where you'd usually put Google analytics and such
<script src="//mandarinspot.com/static/mandarinspot.min.js" charset="UTF-8"></script> <script>mandarinspot.annotate();</script>
Send a quick note indicating URL of your website. This is not strictly necessary, but helps with avoiding surprises with capacity planning.
That's it. It should work with all the assumed defaults.
Now some more details
The script can be loaded anywhere, but to avoid delaying loading of the main content, it either needs to be done asynchronously or at the bottom of the body as suggested above.
Te call to the annotate()
has to be done after the script is loaded and the DOM (at least the part that we want to annotate) is ready.
Again, placing the call at the bottom of the page, as suggested in the previous section, will work well.
The main call is mandarinspot.annotate(selector, options)
. Both arguments are optional.
- a DOM element, like document.body, for example;
- element ID, could be "#chinesetext";
- or class name, ".post" or something.
options is an object with three optional members:
phonetic
, can either be"pinyin"
or"zhuyin"
, pinyin is the default;show
, boolean value to indicate whether pop-ups need to be shown initially, default istrue
;inline
, boolean value to indicate whether phonetics should also be shown inline above text, default isfalse
;
These two calls can be used to switch pop-ups on and off respectively
mandarinspot.showPopups(true); mandarinspot.showPopups(false);
If you want pop-ups initially be inactive, you can call it like this:
<script>mandarinspot.annotate('#chinesetext', {phonetic: 'pinyin', show: false});</script>
It's now also possible to show phonetics above text. To do this you need to add option inline: true
like this:
<script>mandarinspot.annotate('#chinesetext', {inline: true});</script>
To control visibility of inline phonetics you can use the following calls:
mandarinspot.showInline("visible")
- to show inline,
mandarinspot.showInline("hidden")
- to hide phonetics without reformating text,
mandarinspot.showInline(false)
- to remove phonetics completely.
If something is unclear or if you think there is something else needs to be implemented, changed or fixed, please ask.
Compatibility
This doesn't work in IE7 and earlier and all versions of Opera before 12.00 due to cross origin requests not being implemented properly in these browsers. So if you choose to have pop-ups on/off switchable, you probably have to hide the switch UI element in case it can't work.
To detect whether API is supported in the browser you can call mandarinspot.supported()
, which will return true or false based on best guess after detecting some browser features.