Menu Click Handler

Overview

The menu click handler will be triggered whenever the user selects the custom menu option from the dropdown. It can be used to perform a simple one-step action such as sharing a post link to a particular user on Cliq, or open a form to receive user input. This is a default handler, and you can customize the action performed by this handler using deluge scripts.

Once the defined action is completed, the response (success/failure message) will be displayed to the user.

Configuring the menu click handler

The Menu click handler has the following parameters that are mapped with the relevant information whenever the menu is executed.

user	Details of the user executing the menu.
entity	Details of the entity in which the menu is being used.
network	Details of the network in which the menu is being used.

Implementation of menu click handler

If the action performed by the menu click handler is a simple one step action without any intermediate steps, then the response will be in the structure below:

Attribute	Property	Description
result	Options: success / failure Default option: success	The status of the function execution.
message	Data type: String Maximum limit: 250 characters	A message informing the user about the status of the menu execution.

Table 1

For example, let's consider you want to share the link of a Connect post in your team's Cliq channel. The sample code of menu click handler for this use case would be as follows:

entityUrl = entity.get("url");

message = "Hi HR team, \n Check out this [Zoho Connect Post]
(" + entityUrl + ")";
//hrdepartment - channel unique name from channel's connector section
//zohocliqoauth - Connection created with required oauthscopes to perform
 post to channel action
response = zoho.cliq.postToChannel("hrdepartment",message,"zohocliqoauth");
info response;
responseMap = map();
if(response.containKey("status") && response.get("status") == "success")
{
 responseMap.put("result", "success");
 responseMap.put("message", "Post shared successfully to the 
              HR Department Channel"); 
}
else 
{
 responseMap.put("result", "failure");
 responseMap.put("message", "Sorry, something went wrong. 
               We're unable to share the post."); 
}
return responseMap;

Form Object

Let's consider you want to select the channel in which the link has to be shared instead of sharing it with one particular channel. For such scenarios, a simple form dialog box that receives user input in real-time can be opened whenever the user clicks the menu.

To open a form, the menu click handler should return the form object as a response. The attributes of the form object are as follows:

Attribute	Type	Description	Pre-requisite
title	String (25)	The title of the form	Mandatory
hint	String (250)	A small description explaining the purpose of the form.	Mandatory
fields	JSONArray	Array of fields collecting user information. (Detailed explanation in Table 3)	Mandatory
buttonLabel	JSONObject	The submit buttons in the form. (Detailed explanation in Table 5)	Optional

Table 2 (Attributes of form Object)

Field object

A form can have a maximum of 20 fields to receive user inputs. Each field should have a unique label and it can be a text field, date & time field, or a dropdown field with a set of options. The table below explains the field types available, and their properties.

Attribute

Property

Description

Supported field types

Pre-requisite

type

Choose the type of field that you'd need.

All fields

Mandatory

name

Supports only alphanumeric characters and underscore

A unique identifier for the parameter. The information collected from the user in this field will be associated with the identifier. The name field also acts as a unique ID for each field.

All fields

Mandatory

label

String (250)

The title of the field that has to be displayed in the form.

All fields

Mandatory

hint

String (200)

A short description to explain what the field is for.

All fields

Optional

placeholder

String (100)

The placeholder text that has to be displayed within the field input box.

textBox | textArea | multiSelect | select

Optional

value

Field type
Format
textBox |
textArea
String (5000)
select
option ID
multiSelect
CSV of option IDs
dateTime
dd-mm-yyyy hh:mm:ss
date
dd-mm-yyyy

To set the field value for each field in the form.

All fields

Optional

maxLimit

Range: 2-5000

To set a limit for the maximum number of characters entered by the user.

textBox | textArea

Optional

minLimit

Range: 2-5000

To set a limit for the minimum number of characters entered by the user.

textBox | textArea

Optional

mandatory

Available values: true | false

Default value: true

Set this attribute as true, if the user must fill this field in order to submit the form.

All fields

Optional

readOnly

Available values: true | false

Default value: false

Set this attribute as true, if the user cannot change the value in this field.

textBox | textArea

Optional

hide

Available values: true | false

Default value: false

Define whether to show the field to the user or not.

All fields

Optional

dataSource

Available values: user | group | network | board

To load the field options from the user's Connect data.

select | multiSelect

Optional

triggerOnChange

Available values: true | false

Default value: false

Set this value as true, if user input in this field should trigger the form change handler

All fields

Optional

lookup

Available values: true | false

Default value: false

Set this value as true, if an input made in this field should trigger the field lookup handler

select | multiSelect

Optional

triggerLength

Range: 1-5

Default value: 1

Set the number of characters to be given by the user after which the field lookup handler should be triggered.

select | multiSelect

(If lookup property is set true)

Optional

options

JSONArray

Maximum Size: 3000

Array of options to be displayed in the dropdown.

(Detailed explanation in Table 4)

select | multiSelect

Optional

Table 3 (Attributes of field object)

The options to be listed in a select or multi Select field should have the following attributes:

Attribute	Type	Description	Prerequisite
id	String (100) Only Alphanumeric characters and underscore.	Unique string value to identify an option.	Mandatory
label	String (100)	Name of the option listed in the form. This is the name that is visible to the user.	Mandatory
value	String (100)	Value of the option	Optional
iconUrl	URL (500)	URL of the Icon (if any) that has to displayed next to the option	Optional

Table 5 (Attributes of option object)

A form will have two buttons: cancel and done. The label of these options can be changed as per the form requirements. The buttonLabel object should have the following attribute:

Attribute	Type	Description	Prerequisite
cancel	String (15) Default Value: Cancel	The label of the cancel button can be renamed.	optional
done	String (15) Default Value: Done	The label of the submit button can be renamed.	optional

Table 6 (Attributes of buttonLabel object)

When the user clicks the cancel button, the form gets closed. And, when the user clicks the done button, the form submit handler gets triggered. Please note that the custom menu will not be able to complete the action unless the form submit handler is implemented. This is because the form submit handler collects and validates the user inputs, then perform the defined action.

In case you have used the form object in the menu click handler, the form submit handler should be used to validate user data and transfer them to the destination API.