Prompt | Drafts Script Reference
Drafts Script Reference
    Preparing search index...

    Class Prompt

    Prompts allow the creation and display of custom dialogs to request information or confirmation from the user.

    let p = new Prompt()
    p.title = "Hello"
    p.message = "World!"

    p.addTextField("textFieldName", "Label", "")
    p.addDatePicker("myDate", "Start date", new Date(), {
      "mode": "date"
    })
    p.addButton("First")
    p.addButton("Second")

    // if `show` returns false, user hit
    // cancel button
    if (p.show()) {
      let textFieldContents = p.fieldValues["textFieldName"]
      let startDate = p.fieldValues["myDate"]
      
      if (p.buttonPressed == "First") {
        // do something
      }
    }

    Display

    helpURL?: string

    If set to a valid URL string, a help button which links to the URL will be visible in the prompt directing the user to web-based information about the action. Useful if prompting for options or configuration information that might require addition information to complete.

    isCancellable: boolean

    If true, a "Cancel" button will be included in the dialog. Defaults to true. If the user selects the cancel button, the show() method will return false. If false, no cancel button will be displayed and the user must select one of the button name options.

    message: string

    A longer message explaining the purpose of the dialog, if needed.

    symbolName?: string

    The name of a valid SF Symbol available on the platform. It will be displayed as a small icon next to the prompt title, if provided. Valid symbol names can be found using Apple's SF Symbols app or other third party tools and online references.

    title: string

    Short title which appears as a heading in the prompt window.

    Field

    • Add a button to the array of buttons to be displayed. All buttons should be created before calling show().

      Parameters

      • name: string
      • Optionalvalue: object

        only needed to associate a different value than will be displayed in the button. For example, if you call prompt.addButton("First Button", 1), after calling prompt.show() if that button is pressed, the prompt.buttonPressed will contain the number value 1.

      • OptionalisDefault: boolean

        used to specify a single button which will be pinned to the bottom of the prompt and respond to cmd + return as the default button. If only one button is added to a prompt, it is assumed to be the default.

      • OptionalisDestructive: boolean

        if true, present the button as a destructive action, typically a red button, in the intereface.

      • OptionaltintColor: tintColor

        Optionally override the default tint color of the button for the purpose of providing visual groupings. Tint colors are drawn from the current theme in use.

      Returns void

    • Add a date and/or time picker to the prompt, with the arguments as below. The fieldValues entry for this will be a date object.

      Parameters

      • name: string

        Identifier for the field. This will be used as the key in the fieldValues dictionary to access the contents of the field after calling show().

      • label: string

        User-friendly text label to place next to the field.

      • initialDate: Date

        The initial date to selected for the field. Minimum and maximum values should be defined in options.

      • Optionaloptions: {
            maximumDate?: Date;
            minimumDate?: Date;
            minuteInterval?: number;
            mode?: "date" | "time" | "dateAndTime";
        }

        A dictionary of options for configuring the text field.

      Returns void

    • Add an dividing line between fields. Dividers are not functional, but offer visual separation in prompts with many fields.

      Returns void

    • Add an information text label to the prompt.

      Parameters

      • name: string

        Identifier for the field.

      • label: string

        The text of the label.

      • Optionaloptions: { textSize?: "body" | "caption" | "headline" }

        A dictionary of options for configuring the text field.

      Returns void

    • Add a text input field setup to accept numberic values to the prompt

      Parameters

      • name: string

        Identifier for the field. This will be used as the key in the fieldValues dictionary to access the contents of the field after calling show().

      • label: string

        User-friendly text label to place next to the field.

      • initialValue: number

        The initial value contents for the field.

      • allowDecimals: boolean

        If true, the field will accept decimal number values. If false, only whole numbers will be allowed.

      • Optionaloptions: {
            autocapitalization?: capitalizationTypes;
            autocorrect?: boolean;
            keyboard?: keyboardTypes;
            placeholder?: string;
            wantsFocus?: boolean;
        }

        A dictionary of options for configuring the text field.

        • Optionalautocapitalization?: capitalizationTypes
        • Optionalautocorrect?: boolean

          Should system autocorrect be enabled in field, Default: true

        • Optionalkeyboard?: keyboardTypes
        • Optionalplaceholder?: string

          Placeholder text to use when field is empty

        • OptionalwantsFocus?: boolean

          If true, focus this field when prompt is displayed

      Returns void

    • Same as addTextField, but the input field will be password masked.

      Parameters

      • name: string
      • label: string
      • initialValue: string

      Returns void

    • Add a picker to the prompt, with the arguments as below. Picker can contain multiple rows. The fieldValues entry for this will be a array of selected index values object.

      Parameters

      • name: string

        Identifier for the field. This will be used as the key in the fieldValues dictionary to access the contents of the field after calling show().

      • label: string

        User-friendly text label to place next to the field.

      • columns: string[][]

        The values to display in the picker. Should be an array containing arrays of string values, each sub-array representing a column in the picker. Example two column picker: [["Item 1", "Item 2"],["Column 2 Item 1", "Column 2 Item 2"]]

      • selectedRows: number[]

        Array of zero-based index values to set the initial selected row in each column.

      Returns void

    • Add a segmented control. Best used for selection between a small number of values. Returns a string value in fieldValues.

      Parameters

      • name: string

        Identifier for the field. This will be used as the key in the fieldValues dictionary to access the contents of the field after calling show().

      • label: string

        User-friendly text label to place next to the field.

      • values: string[]

        The array of string values that will be available in the segmented control.

      • selectedValue: string

        String values that should be initially selected when the prompt is displayed. Value should match value in the values array.

      Returns void

    • Add a select control. Returns an array of string values in fieldValues.

      Parameters

      • name: string

        Identifier for the field. This will be used as the key in the fieldValues dictionary to access the contents of the field after calling show().

      • label: string

        User-friendly text label to place next to the field.

      • values: string[]

        The array of string values that will be available to select.

      • selectedValues: string[]

        Array of string values that should be initially selected when the prompt is displayed. All values in this array should match values in the values array.

      • allowMultiple: boolean

        If false, selecting a value will deselect all other values. If true, the user may select multiple items.

      Returns void

    • Add an on/off toggle switch. The fieldValues entry for this item will be a boolean indicating whether the switch was on.

      Parameters

      • name: string

        Identifier for the field. This will be used as the key in the fieldValues dictionary to access the contents of the field after calling show().

      • label: string

        User-friendly text label to place next to the field.

      • initialValue: boolean

        indicate if the switch should be on or off when initially displayed.

      Returns void

    • Add a text input field to the prompt

      Parameters

      • name: string

        Identifier for the field. This will be used as the key in the fieldValues dictionary to access the contents of the field after calling show().

      • label: string

        User-friendly text label to place next to the field.

      • initialText: string

        The initial text contents for the field.

      • Optionaloptions: {
            autocapitalization?: capitalizationTypes;
            autocorrect?: boolean;
            keyboard?: keyboardTypes;
            placeholder?: string;
            wantsFocus?: boolean;
        }

        A dictionary of options for configuring the text field.

        • Optionalautocapitalization?: capitalizationTypes
        • Optionalautocorrect?: boolean

          Should system autocorrect be enabled in field, Default: true

        • Optionalkeyboard?: keyboardTypes
        • Optionalplaceholder?: string

          Placeholder text to use when field is empty

        • OptionalwantsFocus?: boolean

          If true, focus this field when prompt is displayed

      Returns void

    • Add a text input field to the prompt

      Parameters

      • name: string

        Identifier for the field. This will be used as the key in the fieldValues dictionary to access the contents of the field after calling show().

      • label: string

        User-friendly text label to place next to the field.

      • initialText: string

        The initial text contents for the field.

      • Optionaloptions: {
            autocapitalization?: capitalizationTypes;
            autocorrect?: boolean;
            height?: number;
            keyboard?: keyboardTypes;
            wantsFocus?: boolean;
        }

        A dictionary of options for configuring the text field.

        • Optionalautocapitalization?: capitalizationTypes
        • Optionalautocorrect?: boolean

          Should system autocorrect be enabled in field, Default: true

        • Optionalheight?: number
        • Optionalkeyboard?: keyboardTypes
        • OptionalwantsFocus?: boolean

          If true, focus this field when prompt is displayed

      Returns void

    Other

    • Displays the prompt. Returns true if the user selected one of the buttons in the buttons array, false if the user selected the "Cancel" button. After the dialog has been shown, the buttonPressed property will contain the name of the button selected by the user.

      Returns boolean

    Result

    buttonPressed: string

    After the show() method is called, this property will contain the name of the button selected by the user.

    fieldValues: { [x: string]: any }

    After the show() method is called, this property will contain values from any fields added to the prompt. The dictionary keys will be the names of the fields as passed in when they were created, and the value will be the current contents of that field. They type of data depends on the type of field.

    Display
    Field
    Other
    Result