Skip to content

Latest commit

 

History

History
272 lines (215 loc) · 10.2 KB

robodog-form.md

File metadata and controls

272 lines (215 loc) · 10.2 KB
Raw
type title menu permalink order category
docs
Robodog: Form API
Robodog Form
docs/robodog/form/
2
File Processing

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:

const 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.maxTotalFileSize

Maximum file size in bytes for all the files together.

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 @uppy/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 Uppy over the jQuery SDK. Uppy 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 replacement in Robodog.

First, change your import URLs and initialization code:

<!-- The old jQuery way… -->
<script src="//assets.transloadit.com/js/jquery.transloadit-assembly-options-v3-latest.js"></script>
<script>
$(selector).transloadit({
  ...options
})
</script>
<!-- The new Robodog way! -->
<script src="//releases.transloadit.com/uppy/robodog/v2.1.3/robodog.min.js"></script>

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

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

<head>
  <link rel="stylesheet" href="https://releases.transloadit.com/uppy/robodog/v3.0.0-beta.2/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>
  <head>
    <title>Testing Robodog</title>
    <link rel="stylesheet" href="https://releases.transloadit.com/uppy/robodog/v3.0.0-beta.2/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="https://releases.transloadit.com/uppy/robodog/v3.0.0-beta.2/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>

Options

jQuery SDK option Robodog option
service service
region Not supported, instead set the service option to https://api2-regionname.transloadit.com
wait: true waitForEncoding: true
requireUploadMetadata: true waitForMetadata: true
params params
signature signature
modal modal
autoSubmit submitOnSuccess
triggerUploadOnFileSelection autoProceed: true
processZeroFiles alwaysRunAssembly
maxNumberOfUploadedFiles Use restrictions instead. restrictions.maxNumberOfFiles.
locale No longer supported, this will be addressed by the translations option instead.
translations Not available
exclude Not available
fields fields. The CSS selector format is no longer supported. Instead, specify an array of form field names. ['field1'] instead of 'input[name=field1].
debug Obsolete, as Transloadit’s backend has improved error reporting.

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

jQuery SDK option Robodog Event
onStart .on('transloadit:assembly-created', (assembly) => {})
onExecuting .on('transloadit:assembly-executing', (assembly) => {})
onFileSelect .on('file-added', (file) => {})
onProgress .on('progress, (percentage) => {})) for total upload progress taking all files into account.
.on('upload-progress', (file, progress) => {}) for file-specific upload progress.
onUpload .on('transloadit:upload', (file) => {}))
onResult .on('transloadit:result', (stepName, resultFile) => {}))
onCancel .on('transloadit:cancel', (assembly) => {}))
or .on('file-removed', (file) => {}) for individual files
onError .on('error', (error) => {})

The error object might contain an .assembly property with an Assembly status for errors that happened during the execution of the Assembly.
onSuccess .on('transloadit:complete', (assembly) => {})
onDisconnect Not available, use something like is-offline
onReconnect Not available, use something like is-offline