Generating files

Mechanic has several actions that allow you to pass along a set of files:

  • The "email" action, which accepts an option called "attachments" that contains a hash of file definitions
  • The "files" action, which accepts only a hash of file definitions
  • The "ftp" action, which accepts an option called "uploads" that contains a hash of file definitions

For each of these actions, the hash of files will be evaluated by Mechanic's file generators:

Configuration structure

Each action that supports file generators accepts a hash of file definitions. This hash is constructed with filenames on the left, and generator options on the right. This means that a set of file definitions may look like this:

{
  "hello.txt": "Hello world!",
  "hello.pdf": {
    "pdf": {
      "html": "<p>Hello world!</p>"
    }
  },
  "hello.zip": {
    "zip": {
      "files": {
        "hello.txt": "Hello world!"
      }
    }
  }
}

In this example, we have a plaintext file called "hello.txt", a usage of the "pdf" generator resulting in "hello.pdf", and a usage of the "zip" generator resulting in a zipped copy of "hello.txt".

File generators

Frequently, a file value is a simple string. This works well for text files, CSV tables, or any other text-based file format.

For more complex types that require background processing, Mechanic accepts file values defining the file to be generated.

"base64"

Use "base64" when you already have the exact data you wish to use, encoded in base64. Usage is simple: provide the bas64-encoded string.

{
  "base64": "aGVsbG8gd29ybGQh"
}

If necessary for any reason, you may use Liquid's base64 filter to prepare your data. This is only useful for situations in which the data you have on hand cannot be represented in JSON by itself.

{
  "base64": {{ opaque_data | base64 | json }}
}

The "base64" generator can be paired with any filename, with any file extension.

"pdf"

Here's how the "pdf" file generator can be used:

{
  "pdf": {
    "html": "<h1>This is a document.</h1>"
  }
}

The PDF is generated from the HTML you provide (using wkhtmltopdf on the backend). In addition to "html", you may also pass in any of the following options, as they're defined in wkhtmltopdf's documentation:

collate, no-collate, grayscale, image-dpi, image-quality, lowquality, margin-bottom, margin-left, margin-right, margin-top, orientation, page-height, page-size, page-width, no-pdf-compression, title, outline, no-outline, outline-depth, background, no-background, default-header, encoding, disable-external-links, enable-external-links, disable-forms, enable-forms, images, no-images, load-media-error-handling, minimum-font-size, exclude-from-outline, include-in-outline, page-offset, disable-smart-shrinking, enable-smart-shrinking, disable-toc-back-links, enable-toc-back-links, zoom, footer-center, footer-font-name, footer-font-size, footer-html, footer-left, footer-line, no-footer-line, footer-right, footer-spacing, header-center, header-font-name, header-font-size, header-html, header-left, header-line, no-header-line, header-right, header-spacing, replace, disable-dotted-lines, toc-header-text, toc-level-indentation, disable-toc-links, toc-text-size-shrink

To use additional options from the list above, add them alongside the "html" option:

{
  "pdf": {
    "html": "<h1>This is a document.</h1>",
    "page-width": "6in",
    "page-height": "6in"
  }
}

"url"

The "url" generator retrieves whatever content is located at the specified URL, up to 20MB in size. Use it when you have a file hosted online that you'd like to attach to your email, or include in your FTP upload. (Need somewhere to store your files? Try Shopify's "Files" area.

{
  "url": "https://example.com/paid-course.pdf"
}

"zip"

Here's how the "zip" generator can be used:

{
  "zip": {
    "password": "opensesame",
    "files": {
      "confirmations.txt": "this data was protected with zipcrypto encryption"
    }
  }
}

The "password" option, given here, is optional. If provided, Mechanic will password-protect the generated zip file.

You'll note that the "zip" file generator accepts an option called "files" – this structure is also evaluated for file generators. This means that you can, for example, generate or download a PDF file that is then added to a password-protected zip file, which is then emailed or uploaded to an FTP server.

Examples

Diving right in, here's everything but the kitchen sink, used with the "ftp" action:

{% action "ftp" %}
  {
    "host": "example.com",
    "port": 22,
    "user": "user",
    "password": "password",
    "uploads": {
      "/tmp/journal.txt": "hello world!",
      "table.csv": "Title,SKU\nRed T-Shirt,TEE-R",
      "invoice.pdf": {
        "pdf": {
          "html": "<h1>Order #12345</h1>\n<p>It's due!</p>"
        }
      },
      "secure.zip": {
        "zip": {
          "password": "opensesame",
          "files": {
            "confirmations.txt": "protected!",
            "your-course.pdf": {
              "url": "https://example.com/paid-course.pdf"
            },
            "invoice.pdf": {
              "pdf": {
                "html": "<h1>Order #12345</h1>\n<p>It's due!</p>"
              }
            }
          }
        }
      }
    }
  }
{% endaction %}

... and here's the same set of files, used with the "email" action:

{% action "email" %}
  {
    "to": "user@example.com",
    "subject": "This is a test!",
    "body": "Please see attached.",
    "attachments": {
      "journal.txt": "hello world!",
      "table.csv": "Title,SKU\nRed T-Shirt,TEE-R",
      "invoice.pdf": {
        "pdf": {
          "html": "<h1>Order #12345</h1>\n<p>It's due!</p>"
        }
      },
      "secure.zip": {
        "zip": {
          "password": "opensesame",
          "files": {
            "confirmations.txt": "protected!",
            "your-course.pdf": {
              "url": "https://example.com/paid-course.pdf"
            },
            "invoice.pdf": {
              "pdf": {
                "html": "<h1>Order #12345</h1>\n<p>It's due!</p>"
              }
            }
          }
        }
      }
    }
  }
{% endaction %}
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.