< More about Simple Scan

1. Destinations
2. Custom Destinations
   1. Identification
   2. Email Destinations
   3. Messages Destinations
   4. File Destinations
      1. Folder Limitations
3. About File Names
4. Template Tags
   1. Input
   2. Dates and Times
      1. Formatting Dates
         1. strftime Formats
         2. DateFormatter Formats
      2. Adjusting Dates

Destinations

Simple Scan supports the following destination types for scans:

• Email: Opens an email message with the scan attached to be sent. Simply add recipients and send.
• Messages: Opens a new message in the Messages app to send the scan as an iMessage or SMS. Add recipients and send.
• File: Saves scan as a file. You are prompted to select a folder to save the scanned document.
• Photos: Saves scan as images in your photo library.
• Share: Share the resulting scan using the system share sheet, providing access to many other apps.

Each of these has a default implementation, but you can also create custom destinations in settings to have more control over your output.

Custom Destinations

In Settings (gear icon at top right), additional custom destinations can be configured.

Identification

All destinations have a name, and an icon for identification purposes. To assign an icon, tap on the icon in the configuration screen.

Email Destinations

Email destinations require Apple Mail be configured with at least one email address. Custom email destinations allow configuration of the following options:

• Recipients: A comma-separated list of email addresses to pre-fill the TO: field of the email.
• Subject: Text to use at the Subject line
• From: If you have multiple email address configured on your device, you can specify one of those email addresses here to set the default value the mail window sets for this destination. The value must be just and email address and exactly match one you have configured for use with Mail.app.
• File Name: Template to control the file name to use for the scanned document. Can include template tags as discussed below.

Messages Destinations

Custom messages destinations allow configuration of the following options:

• Recipients: A comma-separated list of phone numbers and/or email addresses to pre-fill the recipients of the message.
• File Name: Template to control the file name to use for the scanned document. Can include template tags as discussed below.

File Destinations

File destinations allow configurations of the following options:

• Save to Folder: If enabled, Simple Scan will bookmark a folder available in Files.app as the save destination, and auto-save the scan to this folder. The bookmarked folder can be selected by using the “Select Folder” button.
• File Name: Template to control the file name to use for the scanned document. Can include template tags as discussed below.

Folder Limitations

Saved folders work through the Files app and file provider extensions on iOS. These work great with iCloud Drive folders, some local storage in other app containers, and some file provider extensions. Not all destinations available when you are manually selecting a file are available to be bookmarked, because the source apps have not implemented support for folders in their file provider extensions.

Note that granting permission to a folder is specific to a device, so if you use Simple Scan on more than one device, you will have to select the folder you wish to associate with a destination on each device.

About File Names

It is recommend you include some timestamp values in the file names of custom destinations to avoid conflicts and similar named files over time. If the file name generated results in a duplicate name, Simple Scan will automatically add a (1), (2), etc. sequence to the file name to avoid overwriting existing files.

Template Tags

Fields configured to construct file names, email subjects, and some other values support template tags to insert date and time in flexible formats to match your needs. These tags in are the form [[tagName|options]] and will be replaced at the time you are exporting to one of your supported destinations.

For example you might want your “Receipts” scanning destination to create file names in the format Receipt_YYYY-MM-DD - to do so, you would enter a file name values of Receipt_[[date|%Y-%m-%d]]. Supported tags and formatting options are described below.

Input

There is a special [[input]] tag that can be used to add a prompt for input when scanning. If used in the configuration of a file name or other field, after scanning you will be prompted to enter a text value and it will be used in place of the [[input]] tag.

This is great if you wish to have a destination which support arbitrary file naming. For example, you might have a file destination with the file name field [[date]]-[[input]]. When run, if you entered “Gas Receipt” for the prompt, the saved file would come out “2024-10-10-Gas Receipt.pdf” (or similar, based on actual date).

Dates and Times

The following date-related template tags are available. All work with the date formatting and adjusting parameter described below.

• [[date]] Current time. Defaults to the format YYYY-MM-DD.
• [[time]] Current time. Defaults to the format YYYY-MM-DD-HH-MM-SS.

The date and time tags are interchangeable if you are providing a format string. They differ only in the default output.

Formatting Dates

Date tags can take an optional format string to specify the formatting of the output string. To include a format string, add a pipe character (|) and the format string to any of the above date tags, like [[date|format]].

Formats can be provided using strftime markup, or using Apple’s DateFormatter style patterns, per the discussion below.

strftime Formats

strftime formats are a great option when building a specifically formatted date string.

By default, format strings are assumed to use strftime formatting. strftime is a common library to format dates using a set of % flags as placeholders for values from the date/time. Some commonly used placeholders:

• %Y - Year as a four digit number, like 2020
• %m - Month as a two digit number
• %d - Date as a two digit number
• %r - Time in 12-hour format

When evaluated, spacing and punctuation in a strftime format string are maintained, and just the placeholder values replaced.

The strfime website is a great tool for building strftime-compatible format strings to be used in Drafts templates. A few examples of complete date tags with format strings:

• [[date|%Y-%m-%d]] => Example Output: 2020-01-02
• [[date|%A, %B %e, %Y]] => Example Output: Tuesday, December 6, 2022
• [[date|%r]] => Example Output: 08:14:22 AM

DateFormatter Formats

If you need more flexible date formats that are aware of system settings and localizable to different languages and region formats, date format strings can be specified that use Apple’s DateFormatter class.

Drafts will process your format string as a DateFormatter string if it begins with the character ~ or =.

To begin with, there are several pre-configured special values which are used most often to get standard, localized date and time formats that match your configured options in OS Settings > Languages & Regions. These are:

• [[date|=shortDate]] => The numeric date, in the format specified in your OS settings. The default in U.S. English would be something like 12/30/2020.
• [[date|=shortDateTime]] => The numeric date and time, also based on formatting options in OS settings.
• [[date|=longDate]] => Full written date. In U.S. English, like December 6, 2022. This will be localized in the active language on the device.
• [[date|=longDateTime]] => Full written date and time. In U.S. English, like December 6, 2022 at 9:24:08 AM CST. This will be localized in the active language on the device.
• [[date|=iso8601]] => Output standard ISO 8601 formatted date string.

Custom formatting strings utilize the placeholder define by DateFormatter for the different date/time components. There is an excellent reference of these placeholders at NSDateFormatter.com. Custom formatting strings can be constructed in two ways:

• ~ starting a format string says, “I’m tell you the date/time components I want included, output the best localized string including those components”. When using ~ any spacing and punctuation will be ignored, and the system will determine approprate punctuation based on localization. Examples:
  • [[date|~yyyyMMdd]] => A numeric date including year, month, and date. In U.S. English, this would output a numeric date in Month/Date/Year order, in U.K. English, in Date/Month/Year order.
  • [[date|~yyyyMMddHHmmss]] => A numeric date including year, month, date, hour, minutes, and seconds.
• = starting your format string says, “I’m am providing a specific format, only replace the placeholders in the template”. Any whitespace or punctuation provided will be maintained and the component values inserted. Examples:
  • [[date|=dd.MM.yy]] => Example Output: 22.10.2022
  • [[date|=MMM d, h:mm a]] => Example Output: Dec 6, 4:00 PM

DateFormatter formats also support overriding the current device localization by specifying a preferred locale string in parentheses before the format string. Example:

• [[date|=(it_IT)EEEE]] => Outputs the name of the current day of the week in Italian, always, regardless of current device settings.

Locales are specified using in the standard language-country abbreviated format. Examples: en_US (English-United States), it_IT (Italian-Italy), es_MX (Spanish-Mexico).

Adjusting Dates

The date tags in the section above can all also accept an optional adjustment expression that moves the date forward and backward in time. Expressions are in the format (+|-)(integer) (unit). Example expressions:

• +1 year: Advanced the date by one year.
• -3 months -12 hours: Move the date backwards by three months and 12 hours.

Supported unit values are: year, month, day, hour, minute, second. Each can be provided in singular or plural form.

Adjustments are applied in order, and are “smart” around calendars. For example applying “+1 month” to a date on May 31st will result in a date of June 30th, since June only has 30 days.

To adjust a date tag, include an additional parameter before the format string, separate by a | character, examples:

• [[date|+1 year|%Y-%m-%d]]: Today’s date next year.
• [[date|+2 days +2 hours|%Y-%m-%d %H-%M]]: Today’s date plus two days and two hours.

Date adjustment can also done in script. See adjustDate function documentation.