Robodog: Form API

Add resumable uploads and Transloadit’s processing to your existing HTML upload forms. Selected files will be uploaded to Transloadit, and the Assembly information will be submitted to your form endpoint.

<form id="upload-form" method="POST" action="/upload">
  <input type="file" multiple>
  ...
</form>

<script>
window.Robodog.form('form#upload-form', {
  params: {
    auth: { key: '' },
    template_id: ''
  }
})
</script>

When the user submits the form, we intercept it and send the files to Transloadit instead. This creates one or more Assemblies depending on configuration. Then, we put the status JSON object(s) in a hidden input field named transloadit.

<input type="hidden" name="transloadit" value='[{"ok": "ASSEMBLY_EXECUTING",...}]'>

Finally, we really submit the form—without files, but with those Assembly status objects. You can then handle that in your backend.

Transloadit

All the options to the Transloadit plugin are supported.

Locale

You can localize the “Choose files” button that is injected into the form, by setting the locale.strings option:

locale: {
  strings: {
    chooseFiles: 'Choose files'
  }
}

Restrictions

Set rules and conditions to limit the type and/or number of files that can be selected. Restrictions are configured by the restrictions option.

restrictions.maxFileSize

Maximum file size in bytes for each individual file.

restrictions.minFileSize

Minimum file size in bytes for each individual file.

restrictions.maxNumberOfFiles

The total number of files that can be selected. If this is larger than 1, the multiple attribute will be added to <input type="file"> fields.

restrictions.minNumberOfFiles

The minimum number of files that must be selected before the upload. The upload will fail and the form will not be submitted if fewer files were selected.

restrictions.allowedFileTypes

Array of mime type wildcards image/*, exact mime types image/jpeg, or file extensions .jpg: ['image/*', '.jpg', '.jpeg', '.png', '.gif'].

If provided, the <input accept> attribute will be added to <input type="file"> fields, so only acceptable files can be selected in the system file dialog.

Progress Reporting

Uploads using HTML forms have no builtin progress reporting. With Robodog, you can use the statusBar option to show an @sme-uploader/status-bar: an element styled like a progress bar, reporting both upload and Assembly execution progress.

Point it to an element or a CSS selector:

<form id="upload-form" ...>
  <div class="progress"></div>
</form>
<script>
window.Robodog.form('form#upload-form', {
  statusBar: '#upload-form .progress'
  // ...
})
</script>

The progress bar will be inserted into that element (thus not replace it).

Separating Uploads from Form Submission

By default, Robodog.form starts uploads when the user submits the form. There can be a use case for not doing this, and instead uploading files in response to some user action, before the form is submitted. For example, when using a Dashboard modal, the user can upload their files first and then return to the form to submit it. When they submit the form, it should not start uploading again.

The triggerUploadOnSubmit: false option is available for this purpose. We recommend using it together with the modal: true and closeAfterFinish: true options:

// Replace file input in #upload-form with a button that opens the modal;
// after the user clicks the "Upload" button inside the modal and all
// files have been successfully uploaded, the modal closes and the user
// can submit the form.
window.Robodog.form('form#upload-form', {
  modal: true,
  closeAfterFinish: true,
  triggerUploadOnSubmit: false
});

Migrating From the jQuery SDK

We now recommend using SME Uploader over the jQuery SDK. SME Uploader is framework- and library-agnostic, and much more extensible.

Like the Transloadit jQuery SDK, this API enhances an existing form. That makes this a good candidate for migration. Most of the jQuery SDK options have a direct equivalent in Robodog.

First, change your import URLs and initialization code:

<!-- The old jQuery way… -->
<script src="https://unpkg.com/browse/jquery@3.5.1/dist/"></script>
<script>
$(selector).transloadit({
  ...options
})
</script>

<!-- The new Robodog way! -->
<script src="CDN/robodog/v1.9.7/robodog.min.js"></script>

<script>
window.Robodog.form(selector, {
  ...options
})
</script>

Make sure to also include the SME Uploader css file in your <head> tag in case you want to use the modal: true option:

<head>
  <link rel="stylesheet" href="CDN/robodog/v1.9.7/robodog.min.css">
</head>

Here is a full copy-pasteable code sample with all updated options and event names and how to use them. Please refer to the explanations below the code sample for details.
Notice how the form is submitted to the inexistant /uploads route once all transcoding is finished. Please do not forget to add your Transloadit auth key to
window.YOUR_TRANSLOADIT_AUTH_KEY.

<html lang="en">
  <head>
    <title>Testing Robodog</title>
    <link rel="stylesheet" href="CDN/robodog/v1.9.7/robodog.min.css">
  </head>
  <body>
    <form id="upload-form" action="/uploads" enctype="multipart/form-data" method="POST">
      <input type="file" name="my_file" multiple="multiple" />
      <input type="text" name="album_id" value="my_album_id" placeholder="Album ID" />
      <input type="text" name="song_id" value="my_song_id" placeholder="Song ID" />
      <button type="submit">Upload</button>
    </form>

    <script src="CDN/robodog/v1.9.7/robodog.min.js"></script>
    <script type="text/javascript">
    window.Robodog.form('#upload-form', {
      waitForEncoding: true,
      waitForMetadata: true,

      modal: true,

      alwaysRunAssembly: true,
      submitOnSuccess: true,
      autoProceed: true,

      fields: ['album_id'],
      params: {
        auth: { key: window.YOUR_TRANSLOADIT_AUTH_KEY },
        steps: {
          resize_to_75: {
            robot: "/image/resize",
            use: ":original",
            width: 75,
            height: 75
          }
        }
      }
    })
    .on('transloadit:assembly-created', (assembly) => {
      console.log(">>> onStart", assembly);
    })
    .on('upload-progress', (bytesIn, totalBytes) => {
      console.log(">>> onProgress", bytesIn, totalBytes);
    })
    .on('transloadit:complete', (assembly) => {
      console.log('>> onSuccess: Assembly finished successfully with', assembly.ok);
    })
    .on('transloadit:assembly-executing', () => {
      console.log('>> Uploading finished!');
    })
    .on('transloadit:upload', (uploadedFile) => {
      console.log('>> Upload added', uploadedFile);
    })
    .on('transloadit:result', (stepName, result) => {
      console.log('>> Result added', stepName, result);
    })
    .on('error', (error) => {
      console.log('>> Assembly got an error:', error);
      if (error.assembly) {
        console.log(`>> Assembly ID ${error.assembly.assembly_id} failed!`);
        console.log(error.assembly);
      }
    });
    </script>
  </body>
</html>

The equivalent options are listed below.

Options

As for the options that are unavailable:

• exclude is intended to exclude certain <input type="file"> inputs from Transloadit processing. It will likely not be added, but we’ll perhaps have a include CSS selector option instead.
• debug will not be added.

Events

There are no on*() options anymore, but .on('...') methods are provided instead on the SME Uploader object that is returned by window.Robodog.form().