Button Component

SAIL Design System guidance available for Buttons The wrong button in the wrong place at the wrong time can stop a user's workflow dead in its tracks. Learn how to configure and display buttons appropriately to create a beautiful, intuitive, and efficient workflow experience for your application.

Function

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

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

See also: Button design guidance

Parameters

Usage considerations

Using the submit parameter

For buttons that are used to submit a start form or task, set the value of the submit parameter to true in order to submit the start form or task. Otherwise, use the default value, false.

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 displays. The interface only refreshes and the Save Value To state change only occurs if the user clicks the confirm button.

Button styles and colors

• The "GHOST" and "OUTLINE" styles use a transparent background.
• When the color is applied to the background of the button, on "SOLID" and "GHOST", the color of the label is automatic for better contrast. For example, if the button background is dark, the label will be white.

Confirmation dialog button colors

When a confirmation dialog is enabled, the value of the color parameter of the button will affect the color of the confirmation button in the dialog. The cancel button always uses "SECONDARY".

Button shapes

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.

Examples

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

Button styles and sizes

Button styles and colors

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: "SOLID",
          loadingIndicator: true
        )
      }
    )
  }
)

Feature compatibility

Old versions

There are older versions of this interface component. You can identify older versions by looking at the name to see if there is a version suffix. If you are using an old version, be sure to refer to the corresponding documentation from the list below.

To learn more about how Appian handles this kind of versioning, see the Function and Component Versions page.

Related Patterns

The following patterns include usage of the Button Component.

• Add Multiple Validation Rules to One Component (Validation): Enforce that the user enters at least a certain number of characters in their text field, and also enforce that it contains the "@" character.

• Add Validations to an Inline Editable Grid (Validation, Grids, Looping): Allows the user to change data directly in a grid, and validate a various entries.

• Add and Populate Sections Dynamically (Looping): Add and populate a dynamic number of sections, one for each item in a CDT array.

• Add, Edit, and Remove Data in an Inline Editable Grid (Grids, Looping): Allow the user to change data directly in an inline editable grid.

• Add, Remove, and Move Group Members Browser (Hierarchical Data, Group Management): Display the membership tree for a given group and provide users with the ability to add, remove, and move user members from a single interface.

• Alert Banner Patterns (Choice Components): The alert banners pattern is good for creating a visual cue of different types of alerts about information on a page.

• Build a Wizard with Milestone Navigation (Wizards): Use the milestone component to show steps in a wizard.

• Build an Interface Wizard (Wizards): Divide a big form into sections presented one step at a time with validation.

• Call to Action Pattern (Formatting): Use the call to action pattern as a landing page when your users have a single action to take.

• Cards as Choices Pattern (Card Choices, Rich Text): Use this pattern to display sets of choices that are quick and easy to navigate.

• Configure Buttons with Conditional Requiredness (Validation): Present two buttons to the end user and only make certain fields required if the user clicks a particular button

• Configure a Boolean Checkbox (Choice Components): Configure a checkbox that saves a boolean (true/false) value, and validate that the user selects the checkbox before submitting a form.

• Configure a Dropdown Field to Save a CDT (Choice Components): When using a dropdown to select values from the database, or generally from an array of CDT values, configure it to save the entire CDT value rather than just a single field.

• Configure a Dropdown with an Extra Option for Other (Choice Components): Show a dropdown that has an "Other" option at the end of the list of choices. If the user selects "Other", show a required text field.

• Delete Rows in a Grid (Grids): Delete one or more rows of data in a read-only grid.

• Dual Picklist Pattern (Choice Components, Cards, Checkboxes, Buttons): Use this pattern to view side-by-side lists and move items from one list to the other. The dual picklist is great for moving items from one state to another, like from active to inactive.

• Form Steps (Stamps): Use the form steps patten to break down complicated forms into a series of quickly completed steps that are well organized and easy to navigate. This pattern uses a combination of cards and rich text to create steps that can represent fields from one or more interfaces.

• Inline Survey (Radio Buttons, Checkboxes, Buttons): Use this pattern to create a clean and easy to navigate survey.

• Make a Component Required Based on a User Selection (Validation): Make a paragraph component conditionally required based on the user selection.

• Milestone Patterns (Looping): There are three options for milestone patterns which all display some form of a progress indicator to guide users through a series of steps.

• Refresh Data After Executing a Smart Service (Auto-Refresh, Smart Services):

• Refresh Data Using a Refresh Button (Auto-Refresh):

• Refresh Until Asynchronous Action Completes (Auto-Refresh): Use a refresh interval to display the results of an asynchronous action automatically.

• Save a User's Report Filters to a Data Store Entity (Grids, Smart Services, Filtering, Reports): Allow a user to save their preferred filter on a report and automatically load it when they revisit the report later.

• Searching on Multiple Columns (Grids, Filtering, Reports): Display a grid populated based on search criteria specified by end users.

• Set the Default Value Based on a User Input (Default Value): Set the default value of a variable based on what the user enters in another component.

• Set the Default Value of CDT Fields Based on a User Input (Default Value): Set the value of a CDT field based on a user input.

• Set the Default Value of an Input on a Start Form (Default Value): Display a default value in some form inputs on a start form, and save the value into the process when submitting.

• Set the Default Value of an Input on a Task Form (Default Value): Display a default value in some form inputs on a task form, and save the value to process when submitting.

• Showing Validation Errors that Aren't Specific to One Component (Validation): Alert the user about form problems that aren't specific to one component, showing the message only when the user clicks "Submit".

• Tabs Patterns (Formatting, Choice Components, Buttons, Rich Text, Cards): The tabs patterns provide an ideal style and design for creating tabbed interfaces.

• Task Report Pattern (Grids, Filters, Process Task Links, Task Reports): Provides a simple way to create and display an Appian task report.

• Track Adds and Deletes in Inline Editable Grid (Grids): In an inline editable grid, track the employees that are added for further processing in the next process steps.

• Trend-Over-Time Report (Charts, Reports): This report provides an attractive, interactive design for exploring different series of data over time.

• Update an Entity-Backed Record from its Summary View (Records, Smart Services): Enable users to make quick changes to a record by updating it right from a record view.

• Use Links in a Grid to Show More Details and Edit Data (Grids): Allow end users to click a link in a read-only grid to view the details for the row, and make changes to the data. The data available for editing may include more fields than are displayed in the grid.

• Use Links in a Grid to Show More Details and Edit Data in External System (Grids, Web Services): Allow end users to click a link in a read-only grid to view the details for the row, and make changes to the data.

• Use Selection For Bulk Actions in an Inline Editable Grid (Grids): Allow the user to edit data inline in a grid one field at a time, or in bulk using selection.

• Use Validation Groups for Buttons with Multiple Validation Rules (Validation): Present two buttons to the end user that, based on the selection, will validate only after a particular button is clicked.

• Use the Write Records Smart Service Function on an Interface (Smart Services, Looping): Allow the user to publish several rows of data to a database table with the a!writeRecords() smart service function.

• Use the Write to Data Store Entity Smart Service Function on an Interface (Smart Services, Grids, Looping): Allow the user to publish several rows of data to a table through the a!writeToDataStoreEntity() smart service function.

Feedback