Skip to content

Web Part Documentation

Jump to bottom
Peter Graham edited this page Dec 3, 2013 · 46 revisions

This is the documentation for the Bandido sharing service web part.

URLs

Prerequisites

In order for the web part button click JSONP call to work, the request must contain a valid ATT cookie that is associated with a user who can access the shared content. Thus, to completely test the web part, we recommend that you push code to dev or stage and login as a valid Ancestry user beforehand.

Dependencies

The following are required dependencies for the web parts:

Warning

Note that some of these javascripts (e.g. modal.js) and stylesheets (e.g. icon.css) will not work correctly if you load the same Javascript/CSS file twice. The CSS issue is due to IE9+ incorrectly combining pseudo elements styles rather than overriding them. Therefore, ensure that you only have one copy of each of the above files being loaded onto the page.

Combining CSS

To reduce the amount of requests needed to download the above assets to the browser, you can use the combo.ashx endpoint. Here is an example that combines the main.css, button.css, icon.css, and modal.css in that order: http://c.mfcreative.com/lib/tgn/combo.ashx?x/css/v1/main.css&x/css/v1/button.css&x/css/v1/icon.css&x/css/v3/modal.css

Example HTML

<div id="ShareRegion" data-tree-id="116448" data-person-id="18003641377"
     data-collection-id="6224" data-record-id="121231141"
     data-referrer-client="website-stage" data-referrer-page="example-share-webpart">
</div>

HTML data attributes

The following specifies data attributes that you should add for the parent <div> of the web part.

Search records

  • Required
    • data-collection-id the collection ID of the search record (sometimes referred to as dbid)
    • data-referrer-client for the website, this should be "website", "website-stage", or "website-dev". For iOS this should be "ios")
    • data-referrer-page the name of the page that this web part is being implemented on (e.g. "interactive-image-viewer", "all-hints", etc.)
  • One of the following is required:
    • data-record-id (preferred) the record ID of the search record
    • data-image-id (specify only if record ID is unavailable) the image ID of the search record
  • Optional
    • data-tree-id the tree that the search record is attached to
    • data-person-id the person that the search record is attached to
    • data-locale - see below for details
    • data-prepopulate-email-modal if set to "false", email modal inputs will not be prepopulated with sharer name and email. By default, these inputs will be prepopulated.

UGC photos and stories (audios and videos are TBD)

  • Required
    • data-object-id the object ID of the user-generated content
    • data-tree-id
    • data-referrer-client
    • data-referrer-page
  • Optional
    • data-person-id
    • data-locale - see below for details
    • data-prepopulate-email-modal if set to "false", email modal inputs will not be prepopulated with sharer name and email. By default, these inputs will be prepopulated.

data-locale

Specify either string or Windows codes

"en-US" : "1033"
"en-CA" : "4105"
"fr-CA" : "3084"
"en-UK" : "2057"
"sv-SE" : "1053"
"it-IT" : "1040"
"de-DE" : "1031"
"fr-FR" : "1036"

Button styles

The following button styles can be specified using the style= query param. The default style is button-horizontal. Below are the supported styles:

Web part region IDs

Region CSS ID can be specified using the region= GET param to allow for multiple bandido web parts on the same page. The default CSS ID is ShareRegion.

Server-side implementation

We recommend against using the server-side implementation as it will slow down page load speed. If you do, here are some tips:

  • Set the useHttpPost parameter to false, which will tell the web part framework to use HTTP GET to request the web part endpoint.
  • Set a reasonable timeout on the web part.

Client-side implementation

Requirements

The following two JavaScripts are required for client-side implementation (both should be included below jQuery):

Implementation

Instructions

  • Add a share region <div> tag to the page as described above with all required data attributes filled out.
  • On document ready, call AjaxManager.send, passing cache: true, jsonpCallback: "<insert CSS ID for the share region>" and the Bandido/Bandido+ web part endpoint URL.

AjaxManager.send Options

  • cache: (boolean, required) should always be set to true
  • jsonpCallback: (string, required) should be set to the CSS ID of the web part region
  • url: (string, required) should be set to the Bandido web part endpoint
  • success, failure, and after: (functions, optional): These callback functions will be called on success/failure of the web part view rendering. The after callback will be called regardless of success or failure.

Example implementation

<div id='Region123' data-object-id='123' data-tree-id='456' data-referrer-client='website' data-referrer-page='AllHints'></div>
<script>
$(function() {
  AjaxManager.send({
    cache: true,
    jsonpCallback: "Region123",
    url: "http://sharing-webpart.ajax.ancestry.com/webparts/share.json?region=Region123"
  });
});
</script>

Clone this wiki locally