Button Component

Function

a!buttonWidget( label, style, confirmMessage, value, saveInto, disabled, submit, validate, validationGroup, size, width, confirmHeader, confirmButtonLabel, cancelButtonLabel, showWhen, icon, accessibilityText, tooltip, recaptchaSaveInto, loadingIndicator )

Displays a button that can conditionally be used to submit a form.

See also: Button design guidance

Parameters

Name Keyword Types Description

Label

label

Text

Optional text to display on the button.

Style

style

Text

Determines the color of the button, where

  • "NORMAL" default) Displays it with accent color label and border.
  • "PRIMARY" Displays it in the accent color.
  • "SECONDARY" Displays it in gray.
  • "LINK" Displays it with an accent color label and no border until focused.
  • "DESTRUCTIVE" Displays it in red.

Confirmation Message

confirmMessage

Text

Text to display in an optional confirmation dialog box where a null argument disables the confirmation dialog box and a text argument enables it with the text entered as the confirmation message.

Value

value

Any Type

The value associated with this button.

Save Value To

saveInto

Save Array

One or more variables that are updated with the button value when the user presses it. Use a!save() to save a modified or alternative value to a variable.

Disabled

disabled

Boolean

Determines if the user is prevented from clicking the button and triggering the state change. Default is false.

Submit

submit

Boolean

Determines whether this button submits a form after saving its value.

Validate

validate

Boolean

Determines whether this button performs validation before saving its value. When submit is true, this defaults to true, otherwise it defaults to false.

Validation Group

validationGroup

Text

When present, components in the same validation group are validated when this button is clicked.

Size

size

Text

Determines the size of the button. Valid values: "SMALL", "STANDARD" (default), and "LARGE".

Width

width

Text

Determines button width. Valid values are "MINIMIZE" and "FILL". Default behavior displays "FILL" width buttons on phone size screens and "MINIMIZE" buttons on wider screens.

  • "MINIMIZE" width is determined by button label.
  • "FILL" width fills the button container.

Confirmation Header

confirmHeader

Text

Text to display at the top of the confirmation dialog.

Confirmation Button Label

confirmButtonLabel

Text

Text to display on the confirmation button. Default: "Yes".

Cancel Button Label

cancelButtonLabel

Text

Text to display on the cancel button. Default: "No".

Visibility

showWhen

Boolean

Determines whether the button is displayed on the interface. When set to false the button is hidden and is not evaluated. Default: true.

Icon

icon

Text

Icon to display before any text inside the button. See the list of available icons.

Accessibility Text

accessibilityText

Text

Additional text to be announced by screen readers. Used only for accessibility; produces no visible change.

Tooltip

tooltip

Text

Text to display on mouseover (web) or long press (mobile).

reCAPTCHA Save Value To

recaptchaSaveInto

List of saves

One or more variables that are updated after reCAPTCHA executes. Use a!verifyRecaptcha() to verify the reCAPTCHA result and a!save() to save a modified or alternative value to a variable. Only for use in Portals.

Show loading indicator on press

loadingIndicator

Boolean

Determines whether the button will display a loading indicator on press and be disabled while processing. Default: false.

Usage considerations

Using the confirmation parameters

  • In the confirmation dialog there are two buttons. The confirm button is in the primary position and the cancel button is in the secondary position.
  • If confirmHeader and confirmMessage are both null, the interface refreshes and the saveInto state change occurs once the user clicks the button. If either is not null, the confirmation dialog box displays. The interface only refreshes and the Save Value To state change only occurs if the user clicks the confirm button.

Styling buttons

  • When style is "DESTRUCTIVE" and a confirmation dialog box is enabled, the confirm button displays in "DESTRUCTIVE" and the cancel button displays in grey. All other style options result in a "PRIMARY" confirm button and a "SECONDARY" cancel button.
  • You can only configure button shapes on sites and not at the component level. The same shape will be applied to all buttons sitewide.

Using the recaptchaSaveInto parameter in a Portal

reCAPTCHA allows you to monitor your public portals for potentially malicious or fraudulent activity. Appian works with Google’s reCAPTCHA services to provide you with a configurable experience that allows you to choose your thresholds for and responses to potential misuses of your Portal.

reCAPTCHA works on the button component so that you can apply it to submission buttons in a Portal. This allows you to have more control over what kinds of users are submitting entries using your Portal. To use reCAPTCHA, you must use the a!verifyRecaptcha() function within the recaptchaSaveInto parameter and define logic to determine what to do when a bot may be using your Portal.

You can use the a!save() function to save new or updated values to variables in the same way that you would for configuring any button, but make sure to nest a!save() inside the a!verifyRecaptcha() function.

For more information on using reCAPTCHA in Portals or a breakdown of examples, check out our reCAPTCHA guidance.

reCAPTCHA does not work within Appian designer and will always evaluate the onError parameter of the a!verifyRecaptcha()) function. For more information on testing reCAPTCHA, check out our reCAPTCHA guidance.

Examples

Copy and paste an example into an Appian Expression Editor to experiment with it.

Button styles and sizes

Use the interactive editor below to test out your code:

Icon-only button with tooltip

Use the interactive editor below to test out your code:

Confirmation dialog

Use the interactive editor below to test out your code:

reCAPTCHA in a button

The following is an example of what the expression for a button using reCAPTCHA might look like when separated out from the rest of the interface. If you copy and paste the example into an expression editor, reCAPTCHA will not work. Use this example only as a reference. Only for use in Portals.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
a!localVariables(
  local!submissionDetails: a!map(needsReview: null),
  local!submissionStatus,
  local!confirmationMessage,
  {
    a!buttonArrayLayout(
      buttons: {
        a!buttonWidget(
          label: "Submit",
          recaptchaSaveInto: a!verifyRecaptcha(
            onSuccess: {
              if(
                fv!score > .7,
                /* Score >.7 indicates the user is likely human */
                {
                  /* No need for a manual review since the user was confirmed by reCAPTCHA to be human*/
                  a!save(
                    local!submissionDetails.needsReview,
                    false
                  ),
                  a!writeToDataStoreEntity(
                    dataStoreEntity: cons!PORTAL_ENTITY,
                    valueToStore: local!submissionDetails,
                    onSuccess: {
                      a!save(local!submissionStatus, "SUCCESS"),
                      a!save(
                        local!confirmationMessage,
                        "Your submission is confirmed."
                      )
                    }
                  )
                },
                if(
                  fv!score > .3,
                  /* Score is between .3 & .7 indicating that the user may be human or a bot*/
                  {
                    /* No need for a manual review since the user was confirmed by reCAPTCHA to be human*/
                    a!save(
                      local!submissionDetails.needsReview,
                      true
                    ),
                    a!writeToDataStoreEntity(
                      dataStoreEntity: cons!PORTAL_ENTITY,
                      valueToStore: local!submissionDetails,
                      onSuccess: {
                        a!save(local!submissionStatus, "WARN"),
                        a!save(
                          local!confirmationMessage,
                          "Your submission is processing. You will receive an email shortly with confirmation details. If you do not hear from us soon, please try again or give us a call."
                        )
                      }
                    )
                  },
                  /* Score <.3 indicates the user is most likely a bot*/
                  {
                    a!save(local!submissionStatus, "BOT"),
                    a!save(
                      local!confirmationMessage,
                      "Your submission was not successful. Please try again or call us at (202) 555-7171."
                    )
                  }
                )
              )
            },
            onError: {
              /* Cannot connect to Google reCAPTCHA services.*/
              a!save(local!submissionStatus, "ERROR"),
              a!save(
                local!confirmationMessage,
                "Your submission was not successful. Please try again or call us at (202) 555-7171."
              )
            }
          ),
          width: "FILL",
          style: "PRIMARY",
          loadingIndicator: true
        )
      }
    )
  }
)

Feature compatibility

The table below lists this SAIL component's compatibility with various features in Appian.
Feature Compatibility Note
Portals Compatible
Offline Mobile Compatible
Custom Record Field Expressions Incompatible
Process Reports Incompatible

You cannot use this function to configure a process report.

Process Events Incompatible

You cannot use this function to configure a process event node, such as a start event or timer event.

The following patterns include usage of the Button Component.

Open in Github Built: Mon, Nov 21, 2022 (01:52:20 PM)

On This Page

FEEDBACK