Custom Buttons
Custom buttons are interactive elements that trigger specific actions within your application. Buttons can execute custom functions, invoke URLs, display widgets, or open web tabs. Custom buttons can be placed on record detail pages, list views, edit pages, create/clone record pages, and related lists, enabling diverse automation workflows.
For example, you could create a custom button that creates a follow-up task for the current Contact, opens an external URL with record information, or launches a widget for sending an SMS.
Where to access and configure custom buttons
- Log into your Developer Console
- Navigate to Components in the left sidebar
- Click Links and Buttons
- Click Create New Button
Custom buttons are fully packagable. Any buttons created in the Developer Console are included when you publish your application and available to subscribers when they upgrade.
Custom button availability
The following table describes where custom button placements and action types are available in Vertical Studio.
Type | Feature | Developer Console | Subscriber organizations |
Placement | List View - Mass Action Menu | Available | Available |
Placement | List View - Each Record | Available | Available |
Placement | List View - Utility Menu | Available | Available |
Placement | Create/Clone Page | Available | Available |
Placement | Edit Page | Available | Available |
Placement | Details Page | Available | Available |
Placement | Related Lists | Not available | Available |
Placement | Wizards | Not available | Available |
Action | Writing Custom Function | Available | Available |
Action | Invoke URL | Available | Available |
Action | Invoke Widget | Available | Available |
Action | Function from Gallery | Not available | Available |
Action | Function from Existing Actions | Not available | Available |
Action | Open Web Tab | Not available | Available |
Creating a custom button
- In Components > Links and Buttons, click Create New Button
- Complete the following fields
- Module: The module where this button must appear
- Button Name: The display label users see (e.g., "Send Contract", "Generate Invoice"). The name can be of maximum 30 characters. Use clear, descriptive names so subscribers immediately understand what will happen when they click the button.
- Description: Add purpose and usage notes for this button. The maximum limit for this field is 250 characters. Provide clear guidance about what the button does, when to use it, and what will happen when clicked.
- Placement: Where the button appears on the module's pages.
- Action Type: What the button does (Custom Function, Invoke URL, Invoke Widget, Open Web Tab).
- Permissions: Which user roles can access this button
- Configure the action based on your selected Action Type (see sections below)
- Click Save
Button placement options
You can position buttons in the following locations.
1. In record pages:
- Create/Clone page: Available when subscribers are creating or duplicating records
- Edit page: Available when editing existing records
- Details page: Available on the record view page
When a button is placed inside a record, you can select the layouts where the button should be available.
If the button is not associated with a particular layout, it appears under the Unused section and can be added to the layout later.
2. In list views:
- Utility menu: Positioned next to the More (...) menu
- Each record: Displayed on every row in the list
- Mass Action menu: Available only when one or more records are selected
Note:
- If a button is placed in a list view, you cannot select a layout for it. For buttons placed in a list view, select at least one record before executing the button action when the action requires record information.
- When a button is placed in the List View - Utility Menu, it is not associated with a specific record. As a result, record information is not available while configuring the button's action. For example, you cannot use the current record's field values directly when configuring a function or invoking a URL from a Utility Menu button.
3. Other locations:
- Related lists: Placed next to the related list on a record's details page
- Wizards: Available during wizard-based data entry
- Email threads: Appears next to the Forward button in email interactions.
These placements are available only in subscriber organizations.
Button limits and naming
The following limits apply to custom buttons:
Property | Limit |
Custom buttons per module | 50 |
Button name | 30 characters |
Description | 250 characters |
Invoke URL | 3000 characters |
Setting button permissions
Permissions control which user roles in your subscriber organizations can access the button:
- In the Permissions section, select the profiles that should have access
- Only users assigned to those profiles will see and use the button
- Users with administrative permissions can always modify button permissions after publishing
Carefully consider which user roles should have access to sensitive operations. Use permission restrictions to control button visibility by profile and prevent unauthorized actions.
Managing button visibility
In the subscriber org, subscribers can:
- Pin buttons: Users can favorite frequently-used buttons for quick access
- Reorder pinned buttons: Pinned button order is specific to each user, page, and layout
Button actions
Every custom button must have an action associated with it.
Depending on where the button is being configured, you can use the following action types:
- Custom Function
- Invoke URL
- Invoke Widget
- Open Web Tab
- From Gallery
- From Existing Actions
The availability of these actions depends on whether the button is being configured in the Developer Console or in a subscriber organization.
1. Custom function
Executes a Deluge script when the button is clicked. The script can update records across modules, call external APIs, trigger notifications, or execute complex business logic. When you select this action type, a code editor opens where you can write your function. You have access to the current record's field values through implicit variables.
For example, for a button created on the Contacts module, the editor provides the following function signature:
string Button_Function(map contact)
You only need to enter the function code in the editor. You do not need to define the function signature yourself.
Accessing the current record
The current record is provided to the function as a map parameter. You can use this parameter to access the record's field values.
For example, to retrieve the ID of the current Contact:
contactId = contact.get("id");
The fields available in the map depend on the button's module and execution context.
Example: Create a follow-up task
You can create a custom button on the Contacts module to create a follow-up task for the current Contact.
Use the following code:
contactId = contact.get("id");
taskData = Map();
taskData.put("Subject","Follow up with Contact");
taskData.put("Who_Id",contactId);
taskData.put("Due_Date",zoho.currentdate.addDay(2));
response = zoho.crm.createRecord("Tasks",taskData);
return "";
When the button is clicked:
The function retrieves the ID of the current Contact.
- A new Task is created.
- The Task is associated with the current Contact.
- The Task subject is set to Follow up with Contact.
- The due date is set to two days after the current date.
Multiple-record handling
Custom buttons placed in list views can be used with multiple selected records. When a button is executed as a mass action, the values passed to the function can contain multiple record values separated by |||.
Ensure that your function handles multiple values appropriately when processing multiple records.
Testing the function
Test the function with different records before publishing your application. Verify that the function works as expected, in all conditions, and that exceptions and errors are handled properly.
You can use the Save and Execute Script option in the Deluge Script Editor to test and validate the function before using it with the button.
Reusing functions
In subscriber organizations, you can use functions from the Gallery or Existing Actions where supported. These options allow you to use prebuilt or previously created actions instead of writing the function again.
Note: Functions from the Gallery and Existing Actions are not available for configuration in the Developer Console.
Success and error messages
Custom functions can return response information that displays to users as alerts or notifications:
- Success messages: Confirm that the button action completed successfully
- Error messages: Alert users if something went wrong
- Pop-up notifications: Display custom feedback after the button is clicked
By default, custom functions return an empty string. Configure message responses in your Deluge script to provide meaningful feedback to subscribers.
2. Invoke URL
The Invoke URL action opens an external URL when a user clicks the button.
You can use field values from the current record to construct a dynamic URL. For example: https://example.com/customer/?id=${Contacts.ID}&name=${Contacts.First Name}
Configure an Invoke URL action
- Create a custom button.
- Select Invoke URL as the Action Type.
- Enter the URL to be opened.
- Select where you want to display the content of the button action:
- New Tab: Opens the URL in a new browser tab.
- New Window: Opens the URL in a new browser window.
- Existing Tab: Opens the URL in the current browser tab.
- Click Save.
You can include merge fields from the current record in the URL. When the button is clicked, the corresponding field values are substituted into the URL.
For example: https://example.com/customer/?id=${Contacts.ID}
When the button is clicked from a Contact record, the Contact's ID is passed as part of the URL.
Note: The URL can contain a maximum of 3000 characters.
3. Invoke Widget
The Invoke Widget action allows you to open a widget when a user clicks a custom button. You can use widgets to provide interactive functionality or integrate with external applications without requiring users to leave your application.
Before configuring the button, create and configure the required widget in Connected Apps.
To configure an Invoke Widget action:
- Create a custom button.
- Select Invoke Widget as the Action Type.
- Select the Connected Application that contains the widget.
- Enter the Sandbox URL. This URL is automatically populated based on the selected connected application.
- Specify the widget dimensions. You can define the Width and Height in either pixels or percentage.
- Select the Profiles whose users should be able to access the button.
- Click Save.
When the button is clicked, the configured widget opens using the specified dimensions.
For example, you can create a Send SMS button on the Contacts module that invokes a widget from a connected application. The widget can provide an interface for composing and sending an SMS related to the current Contact.
Packaged custom buttons
A packaged custom button is a button created in the Developer Console and included when you publish your application. Subscribers receive packaged buttons at signup or during application upgrades.
Packaging behavior
The following table describes the packaging behavior for custom buttons:
Property | Upgrade Type | Subscriber Modify Access |
Module | Non-editable | No |
Name | Upgradable | No |
Button Placement | Non-editable | No |
Action | Upgradable | No |
Description | Upgradable | No |
Permissions | Non-upgradable | Yes |
Important constraints:
- Subscribers cannot edit or delete a packaged custom button
- Button placement is non-editable. Once saved, you cannot update it.
- Permission changes are subscriber-editable, allowing organizations to customize which roles can use buttons
Changes and upgrade impacts
You add a new button
New subscribers receive the button when they sign up. Existing subscribers receive it when they upgrade to the new application version.
You modify a button's action or name
Suppose you added a "Send Email" button that invokes a URL to an email service and published your application. Version 1 subscribers now have this button. Later, you decide to change the button to execute a custom function that logs the email action to your CRM before sending it. You update the action, rename the button to "Log and Send Email", and publish Version 2.
When existing Version 1 subscribers upgrade to Version 2, the button name and action change for them. Their button is replaced with the new configuration. New subscribers signing up for Version 2 receive the updated button directly. Subscribers cannot customize packaged buttons, so the change applies automatically.
You delete a button
Suppose you created a "Quick Quote" button that invokes a widget to generate quotes on-the-fly. Version 1 subscribers have this button. After several months, you decide the widget is no longer needed or you are replacing it with a different approach. You delete the button from the Developer Console and publish Version 2.
When existing Version 1 subscribers upgrade to Version 2, the button is removed from their organizations. The button definition cannot be recovered after deletion. Any customizations that subscribers made to the button's permissions are also lost.
Subscriber permission changes
Subscribers can customize button permissions (which profiles have access) in their organization. Their customizations are retained when they upgrade, as long as the button exists. If you change permissions in the Developer Console, new subscribers receive the updated permissions, but existing subscribers keep their customized settings.
Editing and managing buttons
Editing existing buttons
You can edit button names, actions, descriptions, and other properties at any time:
- Go to Components > Links and Buttons in your Developer Console
- Find the button you want to edit
- Click the Edit icon
- Modify the button configuration as needed
- Click Save
Changes to upgradable properties (Name, Action, Description) are deployed to subscribers when they upgrade to the next application version.
Deleting buttons
To remove a button from your application:
- Go to Components > Links and Buttons
- Locate the button you want to delete
- Click the Delete icon
- Confirm the deletion
After you delete a button and publish that version, the button is removed from all subscriber organizations on their next upgrade. The button definition cannot be recovered.