Loading

Using the Javascript API

Thingiverse apps that are configured to run inside of an iframe can take advantage of the Javascript API to present users with common dialogs for tasks like finding, opening and saving Things. This allows your app to focus only on the most important aspects of your workflow while giving your users a consistent look and feel for the most common tasks.

Getting the library

You can download the Thingiverse Javascript API library from our GitHub.

Requirements

In addition to the Thingiverse Javascript API library you will also need to load json2, jquery, and the jquery postmessage plugin.

      <script src="js/json2.js"></script>
      <script src="js/jquery-1.8.2.min.js"></script>
      <script src="js/jquery.ba-postmessage.min.js"></script>
      <script src="js/tviframesdk.js"></script>
    

Initializing

This will load the SDK and sets all the default options. Only access_token is required. Replace this with the token retrieved from the Thingiverse OAuth access_token endpoint as described in the Getting Started Guide.

      <script>
        TV.init({
          access_token: '[insert user oauth code here]',
          api_url: 'https://api.thingiverse.com',
          target_url: 'https://thingiverse.com',
          target: parent
        });
      </script>
    

Testing Iframe Communication

To ensure that everything is configured correctly and your app is able to talk to Thingiverse using cross-domain postMessage, you can try sending an echo request message. Thingiverse will send a message back to your app containing whatever you send to it. This can be done with the following javascript.

      TV.sendMessage({cmd: 'echo', params: {foo: 'bar'}}, function(data) {
        alert('gotEcho: ' + JSON.stringify(data));
      });
    

Dialogs

Dialogs are an easy way for your app to do common interactions with Thingiverse such as searching for a Thing and selecting a File by popping up a modal window saving you the time to design your own UI. This is done using the TV.dialog() function.

This example shows a search box. If the user cancels the dialog and doesn't select anything, data.status will be cancelled.

      TV.dialog('thing_search', function(data) {
        if (data.status != 'cancelled') {
          alert('You selected Thing #' + data.thing_id);
        }
      });
    

Parameters can also be passed to some dialogs. For instance, this shows a search box with search results for the string makerbot pre-loaded.

      TV.dialog('thing_search', {q: 'makerbot'}, function(data) {
        if (data.status != 'cancelled') {
          alert('You selected Thing #' + data.thing_id);
        }
      });
    

File Select Dialog

Display a list of files associated with a Thing and allows the user to select a file to begin processing.

      TV.dialog('file_select', {thing_id: 1234}, function(data) {
        if (data.status != 'cancelled') {
          alert('You selected file #' + data.file_id);
        }
      });
    

Parameters

  • thing_id - Required number - The thing to select files from.
  • extension - Optional string - Commas delimited list of file extensions to filter by.

Returns

The file_id of the file selected.

Thing Select Dialog

Displays a list of Things associated with the user. The dialog allows the user to filter by several criteria such as Things they have designed, made, collected or liked.

      TV.dialog('thing_select', {}, function(data) {
        if (data.status != 'cancelled') {
          alert('You selected file #' + data.file_id);
        }
      });
    

Parameters

None

Returns

The thing_id of the Thing selected.

Thing Search Dialog

      TV.dialog('thing_search', {q: 'makerbot'}, function(data) {
        if (data.status != 'cancelled') {
          alert('You selected Thing #' + data.thing_id);
        }
      });
    

Parameters

  • q - Optional string - The search term to prepopulate the dialog with

Returns

The thing_id of the Thing selected.

Thing Save Dialog

The Thing Save presents the user with options for saving the Thing they're currently working on. The dialog returns a hash that can then be passed to the REST API to actually create or update the Thing.

      TV.dialog('thing_save', {name:'My Cool Thing', description:'Created by super cool app'}, function(data) {
        if (data.status != 'cancelled') {
          $.ajax({
            url: 'https://api.thingiverse.com/things',
            type: 'POST',
            data: data.thing,
            dataType: 'json',
            headers: { 'Authorization' : 'Bearer ' + this.token },
            success: cb,
            error: err
          });
        }
      });
    

Parameters

  • id - Optional number - The id of the Thing to update. Do not include for new Things
  • name - Optional string - The default name of the Thing to create/update.
  • description - Optional string - The default description of the Thing to create/update.
  • category - Option string - The default category of the Thing to create/update
  • .
  • tags - Option string - Comma-separated list of default tags for the Thing to create/update.
  • license - Option string - The default licene of the Thing to create/update.
  • is_published - Option number - The default setting for publishing the Thing being created/updated.
  • is_wip - Option number - The default setting for marking the Thing as a work-in-progress.

Response

An object that can be passed to the REST API to creating or updating a thing.

REST API Wrapper

Provides a way to access the Thingiverse REST API endpoints (currently read-only GET requests). See API docs for full API documentation. Pass it the endpoint (either relative or full url) and a callback. Here is the basic syntax.

      TV.api('/newest', function(data) {
        newest_thing = data[0];
        alert('gotNewest: ' + JSON.stringify(newest_thing));
      });