Wiki Navigation

NOTICE

We've found that our other APIs actually fulfill most of your needs better. Please take a serious look at WritingAddOns and TipsAndTricks before deciding to do this route. If the above mention APIs does indeed serve the needs better, then this API will be deprecated.

As always, for more information, please consult the mailing list or reach us directly using the Contact Us form. Thanks! - choonkeat

Annotation API

SharedCopy's Annotation API allows you to easily introduce the functionality of adding sticky notes on your webpages.

Registering the Application

To use the API, you need an API Key Here is what you need to do to get an API Key.

Create a SharedCopy account

Create a SharedCopy account at http://sharedcopy.com/users/new and activate it.

Apply for an API key

Since the API is currently in private beta, you need to contact us to get an API key. Please use our contact us page to apply for an API key with your account information.

Using the API

The API is designed to suit the needs of both the simple and advanced users.

Basic

1. Add the following script tag to your webpage:

<script src="http://sharedcopy.com/javascripts/api/script.js" type="text/javascript"></script>

2. Add the following CSS file to your page:

<link rel="stylesheet" href="http://sharedcopy.com/stylesheets/api/style.css" type="text/css" />

3. Add the following Javascript snippet to your page:

<script>SharedCopy.basic.init('your api key')</script>

That's it.. you're done! Your site should now have SharedCopy running on it.

Advanced

This section is only for users who want to customize the look/behavior of SharedCopy on their site.

Customizing looks

Downlod the CSS file http://sharedcopy.com/stylesheets/api/style.css. The file has the editable sections marked.

Edit the CSS to get the look you want.

Host the CSS yourself and instead of calling the CSS hosted by us (see step 2 in the Basic section above), make a call to your custom CSS.

Customizing behavior

Instead of the call SharedCopy.basic.init('your api key'), you can make a call SharedCopy.basic.init(config) where config is a configuration variable. Here are the parameters that the config variable accepts:

Param	Type	Purpose	Default
apiKey	String	Your api key	None
defaultName	String	The default name that shows up on top of the sticky note when it is just created	‘Guest’
showToolbar	Boolean	Flag to set the visibility of the default toolbar	false
beforeLoad	Function	A function that would run before the sticky notes are loaded on the page. Must return a Boolean value. The load is initiated only when if the function returns true	A function that returns true
afterLoad	Function	A function that would run after the sticky notes are loaded on the page.	A function that does nothing
minimizeOnLoad	Boolean	Flag to minimize all the stickies when they are loaded. In minimized state, only the name of the commenter is seen.	false
allowSave	Boolean	Set if changes on the page can be saved	True
beforeSave	Function	A function that would run before the page is saved. Must return a Boolean value. The save is initiated only when if the function returns true.	A function that returns true
afterSave	Function	A function that would run after the page is saved.	A function that does nothing
saveLabels	Object {before: String/Boolean, after: String/Boolean, button: String/Boolean }	By default, a small button appears on the top right corner of the page and a status box appears on the top left corner of the page to indicate ‘Saving in Progress’ and ‘Saved’ states of the page. You can override the text of the boxes using the ‘before’,‘after’,or ‘button’ parameters of the saveNotifications object. Please do not define the parameter if you are happy with its default. Alternatively, if you don’t want any of the boxes to appear at all, just define the respective parameter as false.	Object {before: ‘Saving…’, after: ‘Saved’, button: ‘Save Notes’}
pageSuffix	String	All your SharedCopy powered pages are identified in the SharedCopy database as ‘your api key’ + ‘your page suffix’. To uniquely identify each page, you must supply a unique suffix for all your pages	The page URL sans special character, hash strings, and the http://www prefix. Eg: the suffix for http://www.mysite.com/notes/index.html#hello would be mysitecomnotesindexhtml.
noClickZones	String	A sticky note pops up wherever the user clicks on a page. noClickZones are areas on the page where clicking does not open up a sticky. noClickZones should simply be a comma separated list of the CSS selectors of such elements. If an element is identified as a noClickZone, all it's children automatically become noClickZones as well.	‘#karea,#k_save_button’
autoRead	Boolean	Indicates whether stickies should be loaded on page load. If false, sticky load can be initiated whenever you want by making the shcpAPI.read() call.	True
autoWrite	Boolean	Indicates whether the user is allowed to add stickies to the page automatically when the page loads. If false, sticky creation can be initiated whenever you want by making the shcpAPI.write() call. Please note that as of our current version, shcpAPI.read() must precede shcpAPI.write().	True
saveTrigger	String	A comma separated list of CSS selectors of the elements clicking on which initiates the saving of the page.	‘#k_save_trigger,#k_save_button’
welcomeSticky	Object {from: String, message: String}	If there are no stickies on a page, you can choose to show a default welcome sticky. This can be used to ask the user to click to add a sticky or anything else. The ‘from’ parameter is the name that shows up on the sticky, and the ‘message’ is simply the message that shows up.	No welcome sticky shown
baseUrl	String	The URL of the server we are working with. Not Used	‘http://sharedcopy.com/’

Example

//define config variable
var config = {
    apiKey: ‘700000455533434343545’,
    defaultName: ‘John Doe’,
    beforeLoad: function() {showMessage(‘Loading’); return true; },
    afterLoad: function() { hideMessage(‘Loading’); },
    beforeSave: function() { showMessage('Saving'); return true }, afterSave: function() {showMessage('Saved');},
    saveNotifications: {before: false, after: false},
    pageSuffix: 'some_key_generated_by_my_php_code',
    noClickZones: '.nostickies',
    saveTrigger: '#my_save',
    welcomeSticky: {from: 'MySite', message: 'Hey, Click anywhere to add a sticky note'}
}
//make the API call
SharedCopy.basic.init(config);

Download in other formats:

Plain Text