Documentation :: Tagging Widget
What is the Tagging Widget?
The tagging widget is a Javascript plugin that adds a tagging interface on selected photos in your HTML page. Using the face.com API, it will automatically detect faces placing the tags in the right spot. Users can enter simple text labels, or their facebook and twitter friends.
Adding the widget to your page
Get your face.com API key
Before you can use the tagging widget, you need to register your face.com application API key.
Add the Javascript code to your HTML page
Load up the api_client.js and tagger.js scripts from face.com:
<br /> <script type="text/javascript" src="http://api.face.com/lib/api_client.js"></script><br /> <script type="text/javascript" src="http://api.face.com/lib/tagger.js"></script><br />
Initialize the face.com API object with your API key:
<br /> <script type="text/javascript"><br /> FaceClientAPI.init(YOUR_API_KEY);<br /> </script><br />
Apply the tagging object on the relevant image tags (in this example it's an <img> tag with ID 'main-image'):
NOTE: This code must be called after the relevant <img> tags have been rendered.
<br />
<script type="text/javascript"><br />
FaceTagger.load("#main-image", {<br />
click_add_tag: false,<br />
resizable: true,<br />
facebook: true,<br />
fade: true,<br />
tags_list: true,<br />
add_tag_button: true<br />
});<br />
</script><br />
FaceTagger Syntax and Options
FaceTagger.clear
Removes the widget display from the img HTML element it was loaded into.
This method also get called automatically when loading the widget to an image (using the "load" message). That way, loading the next image, will make sure the current image was cleared. (For ajax usage)
Syntax:
FaceTagger.clear();
FaceTagger.load
Loads the widget on a given HTML img element.
Syntax:
FaceTagger.load(image_tag,options);
Parameters:
| Name | Description | |
|---|---|---|
| image_tag | a qualified jquery tag selector that applies to one or more images in the HTML page.Common selectors are "#id", ".class", "img" (applies to all images on page). | |
| options | a javascript key:value array with the following options: | |
| users | Array of users to be displayed in the auto-complete menu when tagging.Facebook and Twitter friends are generated by the widget once credentials are given, so no users list from those namesapces needs to be passed to the widget. User may have the following fields:
For example, a format function we use by default to facebook users is: <br />
function(user, search)<br />
{<br />
var name = user.first_name + " " + user.last_name;<br />
var regex = new RegExp("(" + search + ")", "gi");<br />
name = name.replace(regex, "<b>$1</b>");<br />
return '<img src="' + user.profile_pic + '" alt="" width="25" height="25"<br />
style="vertical-align: middle; float: left; margin: 1px 2px 1px 1px;" /> ' + name;<br />
}<br />
| |
| facebook (false) | When true, if the widget is used in a facebook connect site, and there is a logged in facebook user, the fb friends of the user will be added to auto-complete menu.The facebook connect Api Key and Secret Key must be setup for the face.com API Key application | |
| twitter_oauth_user twitter_oauth_token twitter_oauth_secret | OAuth credentials for twitter login, of the corrent user. To be used when the widget is used in a twitter connect site.The twitter connect Api Key and Secret Key must be setup for the face.com API Key application | |
| readonly (false) | disables tagging, works well with 'admin_mode' (see below) | |
| click_add_tag (false) | adds a manual tag when clicking anywhere on the photo | |
| add_tag_button (false) | add a button for adding a manual tag | |
| detect_faces (true) | enables/disable face detection on selected image. When false, only saved tags will be shown. | |
| resizable (false) | allows users to change the size of tags | |
| fade (false) | adds a fade-in effect for tags | |
| tags_visible (true) | when true - tags are always visible. When false - only visible when mouse is over the tag | |
| tags_list (false) | display a comma separated name list near the photo | |
| demo_mode (false) | useful when using the widget as a demo. It will show untagged tags for every different user. (even on same photo). The tags uid is not save - only with label do.Tagged saved in demo-mode will not initiate training for that user. | |
| show_loading (true) | display a blinking "Loading" message during widget processing | |
| max_ac_users (7) | max number of user to be displayed in the auto-complete menu | |
| design (default) | The widget comes with few design theme. Options are: 'default', 'round', 'arch', 'wood', 'facebook'Of course theme can be override by custom css as well. | |
| tagClick | callback function for tag click event. Function prototype is:function (tagDomElement, imageDomElement, caption, tagX, tagY, tagWidth, tagHeight) width, hight, x and y are given in percents of the image size | |
| tagSaved | callback function for successful tag save. Function prototype is:function (uid, caption, url) In this callback, you can notify your users they were tagged, for example. by email, facebook wall post etc. | |
| success | callback function for successful widget load Function prototype is:function (imageDomElement, apiResponse) apiReponse is the a javascript object decoded from the api response for the faces.detect call, called by the widget. See faces.detect for full response details | |
| error | callback function for errors raised in the widget. Function prototype is:function (data) data may be a js exception, or an error string, or a failure response from faces.detect. See faces.detect for full response details. | |
FaceTagger.setDesign
Change the default graphic design (css), of the widget elements.
Available designs: 'default', 'round', 'arch', 'wood'.
Syntax:
FaceTagger.clear(desgin);