Skip to content

Tutorial Build

Jump to bottom Edit New page
Daniel Marshall edited this page Nov 12, 2015 · 3 revisions

Step 3: Build and Run the Tutorial App

NOTE: You must complete the previous steps of this tutorial before proceeding.

This tutorial app will get you started with the FamilySearch JavaScript SDK.

To complete the tutorial you will alternate between running and editing the tutorial.html file.

Create and run tutorial.html

  1. Copy the following code into a text file using your editor.
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Tutorial App - FamilySearch JavaScript SDK</title>
    <script src="//cdnjs.cloudflare.com/ajax/libs/jquery/2.1.4/jquery.min.js"></script>
    <script src="//cdn.jsdelivr.net/familysearch-javascript-sdk/2.0.4/familysearch-javascript-sdk.min.js"></script> 
  </head>
  <body>
  <h2>Welcome to the FamilySearch JavaScript SDK Tutorial!!!</h2>  

  <!-- AUTHENTICATE -->

  <!-- READ CURRENT TREE PERSON  -->

  <!-- SEARCH -->

  <!-- READ PID -->

  </body>
</html>
  1. Name the file tutorial.html and save it in your project folder.
  2. In a browser, load http://127.0.0.1:8080/tutorial.html, then return to these instructions.

Authenticate with FamilySearch

Your app must first authenticate a user with FamilySearch. To authenticate you must use an app key that is assigned to your app by FamilySearch. This app key is used to obtain an access token which is required by each FamilySearch API endpoint.

  1. Insert the following AUTHENTICATE code into the tutorial.html file.
<script>  // Instantiate the SDK client
  var client = new FamilySearch({  
    // Copy your app key into the client_id parameter
    client_id: 'YOURAPPKEYGOESHERE',
    redirect_uri: 'http://127.0.0.1:8080',
    save_access_token: true,
    environment: 'sandbox'
  });

  var login = function() {
    client.getAccessToken().then(function(){
      return client.getCurrentUser();
    }).then(function(response) {
      $('#user-info').append('CONGRATULATIONS!!! User '+response.getUser().getContactName()+' is signed in.<br>The access token has been stored in a session so that future interactions in this tutorial are authenticated.<br><br>Now update the tutorial app to READ CURRENT TREE PERSON.');
    });
  };
</script>
<a href="#" onclick="login()"><h2>Step 1. Click to SIGN IN</h2></a><br><br>
<div id="user-info"></div>
  1. Find your app key in the FamilySearch Developer website on the My Apps page.
  2. Copy your app key into the designated line of the AUTHENTICATE code.
  3. Save tutorial.html and refresh the browser page that is running it.

Read the Current Tree Person

With your access token you can now use any of the methods in the JavaScript SDK. Start by reading the current person in the FamilySearch Tree.

  1. Insert the following READ CURRENT TREE PERSON code into the tutorial.html file.
<script>    // Get the current tree person.
  var readPerson = function (){
    // From the user profile, extract the tree person ID.
    client.getCurrentUser().then(function(userResponse){
      return userResponse.getUser().getPersonId();
    })

    // Retrieve the person
    .then(function(personId){
      return client.getPerson(personId);
    })

    // Get the person from the response and print
    .then(function(personResponse){
      var person = personResponse.getPerson();
      $('#read-person').append('<b>Name: </b>'+person.getDisplayName()+'<br><strong>Birth Date: </strong>'+person.getDisplayBirthDate()+'<br><br>Now update the tutorial app to SEARCH.');
    })

    // Catch any errors
    .catch(function(e){
      $('#read-person').append(displayError(e));
    });
  }
</script>
<a href="#" onclick="readPerson()"><h2>Click to READ THE CURRENT TREE PERSON</h2></a><br><br>
<div id="read-person"></div>
  1. Save tutorial.html and refresh the browser page that is running it.

Search for People in the Tree

You can specify search criteria to perform a search for people in the tree.

  1. Insert the following SEARCH code into the tutorial.html file. There are many search and display options you can program. This tutorial shows only a few.
<h2>SEARCH FOR PEOPLE IN THE TREE </h2>
<div>
  <div class="row">
    <div class="form-group col-sm-6">
      <label for="givenName">Given Name</label>
      <input type="text" class="form-control" id="givenName" placeholder="given name">
    </div>
    <div class="form-group col-sm-6">
      <label for="surname">Surname</label>
      <input type="text" class="form-control" id="surname" placeholder="surname">
    </div>
    <div class="form-group col-sm-6">
      <label for="birthDate">Birth Date</label>
      <input type="text" class="form-control" id="birthDate" placeholder="birth date">
    </div>
  <p class="text-center"><button id="searchButton" class="btn btn-primary">Search</button></p>
  </div>
</div>

<div id="search-results"></div>

<script> // Search the tree for people
  var $content = $('#search-results');

  // Search when the user clicks on the button.
  $('#searchButton').click(function(){
    $content.html('');    
    var params = {
      givenName: $('#givenName').val(),
      surname: $('#surname').val(),
      birthDate: $('#birthDate').val(),
    };
  
    client.getPersonSearch(params).then(function(searchResponse){   
      $('<h3>').text('Results').appendTo($content);
      var $table = $('<table>').addClass('table');
      $table.append(
        $('<tr>')
          .append('<th>Id</th>')
          .append('<th>Name</th>')
          .append('<th>Birth</th>')
          .append('<th>Death</th>')
      );
    
      var results = searchResponse.getSearchResults();
      for(var i = 0; i < results.length; i++){
        var result = results[i],
            person = result.getPrimaryPerson(),
            $row = $('<tr>').appendTo($table);
        $('<td>').text(person.getId()).appendTo($row);
        $('<td>').text(person.getDisplayName()).appendTo($row);
        $('<td>').text(person.getDisplayBirthDate()).appendTo($row);
        $('<td>').text(person.getDisplayDeathDate()).appendTo($row);
      }
    
      $content.append($table);
      $content.append('<br><br>Now update the tutorial app to READ PID.');
    
    })
    
    // Catch any errors
    .catch(function(e){
      $loader.hide();
      $content.append(displayError(e));
    });
  })
</script>
  1. Save tutorial.html and refresh the browser page that is running it.
  2. Perform a few searches to demonstrate the search capability.

Read a Tree Person by Person ID

If you know a person ID (PID) of someone in the Tree you can read the details of that person.

  1. Insert the following READ PID code into the tutorial.html file.
<br><br><h2>READ A TREE PERSON BY ID</h2>
<div>
  <div class="row">
    <div class="form-group col-sm-6 col-md-4">
      <label for="personIdInput">Person ID</label>
      <input type="text" class="form-control" id="personIdInput" placeholder="Person Id">
    </div>
    <p class="text-center"><button id="submit" class="btn btn-primary">Read Person ID</button></p>
  </div>
</div>

<div id="read-pid"></div>

<script> // Read tree person by ID
  var $pidContent = $('#read-pid');
  // When the user clicks on the button, get that person ID.
  $('#submit').click(function(){
    $pidContent.html('');
    var pid = $('#personIdInput').val();

    // Get the person and display the person information
    client.getPerson(pid).then(function(personResponse){
      var person = personResponse.getPerson();
      $pidContent.append('<b>Name: </b>'+person.getDisplayName()+'<br><b>Birth Date: </b>'+person.getDisplayBirthDate()+'<br><br><h1>Congratulations!</h1><br>You have completed the coding portion of the tutorial.');
    })
  
    // Catch any errors
    .catch(function(e){
      $pidContent.append(displayError(e));
    });
  
  })
</script>
  1. Save tutorial.html and refresh the browser page that is running it.
  2. Use a person ID from your search to read that person by PID.

(Proceed to Step 4 if Desired.)

Add a custom footer

Home

Tutorial

Sample App

Documentation

Design

Clone this wiki locally