GedcomX - JavaScript SDK

This JavaScript SDK is a high-level JavaScript wrapper around the FamilySearch REST API.

See the wiki for the following:

• A tutorial to help get you started.
• A sample app github project and running version that demonstrates how to fulfill common use cases.
• Documentation of the JavaScript SDK and other FamilySearch API development guides.

Installation

Node.js

Node versions 0.10 and 0.12 are officially supported.

npm install familysearch-javascript-sdk

Browser via a CDN

Available via both jsDelivr and unpkg.

<script src="//cdn.jsdelivr.net/npm/[email protected]/dist/familysearch-javascript-sdk.min.js"></script>

<script src="//unpkg.com/[email protected]/dist/familysearch-javascript-sdk.min.js"></script>

Features

• Wrapped REST API Calls

JavaScript functions wrap the underlying REST API calls. The objects returned by the functions include convenience functions for extracting information from the returned JSON. For example, the following logs the name of a person along with their spouses and chilren.

```javascript
client.getPerson('KW7S-VQJ', {persons:true}).then(function(response) {
  console.log(response.getPrimaryPerson().getDisplayName());
});
```

• Promises

Asynchronous functions (like the one above) return promises to make it easy for you to refer to their results from anywhere in your code.

• Well Documented

Each function is well-documented and has an editable jsFiddle to demonstrate its functionality and allow you to experiment.

• Popup Authentication

In the browser, authentication is handled using a popup window. You do not need to create an OAuth redirect page. All you need to do is register a callback URI that shares the same hostname and port as your code.

• Automatic Authentication

If you make a call without first authenticating, the authentication process will be initiated first automatically.

• Token Storage

There is an option to store your access token in a session cookie.

• Throttle Handling

Retry in the case of throttled responses is handled for you.

• Cross-platform

Works both in the browser and in node. See the examples.

• Object-oriented

SDK functions return objects, which have convenience functions to make getting or setting data easy.

• Consistent update API

Each object has save and delete functions to persist changes or delete the object respectively.

Contributing

Thank you for your interest in contributing! We love pull requests.

Follow these steps to properly setup your development environment:

• Fork this repo
• Run npm install to install the build dependencies.
• Run npm test to run the tests.
• Run npm run build to build the project.

This project uses .editorconfig to help configure your editor for consistent code indentation and styling. Please follow the existing style in your changes.

Grunt runs jshint on the files using a rather strict .jshintrc file, which finds a lot of potential problems almost immediately. Your changes should pass the jshint checks. If you have a good reason not to follow a particular check for a particular statement, you can disable the jshint test for that statement. Some editors (e.g., WebStorm) can be configured to read the .jshintrc file to notify you immediately when something doesn't pass.

Grunt runs unit tests using jasmine. Please create unit tests for your changes. See the existing unit test files for examples.

Grunt also generates documentation for the project. Nearly a third of the code consists of comments that is turned into online documentation. Please comment your changes.

When choosing what to work on, you may pick an existing issue to implement or create a new issue. We suggest that you describe what you plan to implement in order to get feedback prior to implementation and issuing a pull request, though you are also free to issue a pull request and ask for comments afterward.