Widgets in Cliq

Widgets are a great way to customize your Cliq home screen. Imagine having a custom view of all the important data and functionality from the different apps that you use every day. For example, the Twitter widget brings you your twitter feed, the Projects widget shows you recently assigned tasks and bugs, as the the Notes widget lets you view your recent notes or take notes.

Widgets are highly customizable and support a wide range of textual and visual elements to make the data displayed more actionable.

Understanding a widget's structure  

Before you start building a widget, it is valuable to understand how widgets in Cliq are structured. Widgets in Cliq are made up of tabs containing sections that house a combination of various elements.

Widgets

   - Tabs

        - Sections

              - Elements

Tabs

Cliq widgets' tabs are quite similar to any browser's tabs. They're labeled, clickable areas that contain a combination of sections having different elements. Think of a tab as the outermost container or layer that houses the rest of the pieces that form your widget. You can switch between tabs by just clicking on them and just like a browser, the currently selected tab is highlighted than the others. 

Tab Views

Tab views are customizable views that can be created based on the type and amount of data you'd like to display. There are five types of tab views that you can create:

• Sections View

• Info View

• Web View

• Map View

• Form View

Sections View

A section view comprises different varieties of display and actionable elements that can hold crucial information. This information can be solely for the users' consumption or even to perform actions right from the section. In addition to supporting all the widget section elements, the sections view also supports a header and footer.

elements = list();
elements.add({"type":"title","text":"Widget Title"});
elements.add({"type":"text","text":"Here goes the text! Widgets are built as an internal tool similar to commands, bots and message actions. They are listed in the left side bar of Cliq and will be displayed as a full view in Cliq's home screen. Consider widgets as a mini version of any third party integration or a standalone app that works for you, for your team or for the entire organization."});
sections = list();
sections.add({"id":1,"elements":elements});
return {"type":"applet","tabs":{{"label":"Home","id":"homeTab"},{"label":"Configuration","id":"config"},{"label":"Settings","id":"settings"}},"active_tab":"homeTab","sections":sections};

Info View

The info view is typically used to display a piece of important information, mainly for user's consumption, with only one actionable element (button).

return {
	"type":"applet",
	"data_type":"info",
	"tabs":[
	{"label":"Home","id":"homeTab"}
	],
	"info":{
	"title":"Your default portal is not configured yet!",
	"description":"Click here to configure.",
	"image_url":"https://i.ibb.co/gSP05Yr/Cliq-automation.png",
	"button":{
		"label":"Configure",
		"type":"invoke.function",
		"name":"cliqwidget",
		"id":"configuration"
		}
	},
	"active_tab":"homeTab"};

Web View

The web view typically loads a web page in an iFrame right inside the widget. 

return {
	"type":"applet",
	"data_type":"web_view",
	"tabs":[
	{"label":"Home","id":"homeTab"}
	],
	"web_view":{"url":"https://player.vimeo.com/video/742651284?autopause=1&dnt=1&autoplay=1"},
	"active_tab":"homeTab"
};

Map View

With map view, rendering maps within a widget tab is now possible. It allows the developers to plot tickers and provide live tracking.

return {
   "type": "applet",
   "data_type": "map",
   "tabs": [
      {
         "label": "Zoho offices",
         "id": "zoho_offices"
      }
   ],
   "map": {
      "id": "zoho_offices_map",
      "title": "Branches",
      "tickers": {
         "chennai": {
            "title": "Chennai",
           "type": "person",
            "last_modified_time": 1674549259421,
            "latitude": 12.8310776,
            "longitude": 80.0493569,
            "info": "Zoho corporation - Chennai"
         }
      }
   },
   "active_tab": "zoho_offices"
};

Form View

Form view can be used to render a Cliq form within a widget tab. Using the form view, you will have the option to render the tabs and form options in kiosk mode.

form = {
   "title": "Zylker Annual Marathon",
   "mode": "kiosk",
   "name": "marathon",
   "hint": "Register yourself for the Zylker Annual Marathon!",
   "button_label": "Submit",
   "inputs": [
      {
         "name": "select",
         "label": "Events you wish to apply for",
         "placeholder": "Choose from the list of options",
         "multiple": false,
         "mandatory": false,
         "type": "select",
         "options": [
            {
               "value": "half_marathon",
               "label": "Half marathon",
               "thumbnail": "https://w7.pngwing.com/pngs/458/840/png-transparent-people-running-at-marathon-art-half-marathon-running-marathon-miscellaneous-physical-fitness-sport-thumbnail.png"
            },
            {
               "value": "stage_races",
               "label": "Stage races",
               "thumbnail": "https://w7.pngwing.com/pngs/217/130/png-transparent-sprint-long-distance-running-track-field-silhouette-physical-fitness-animals-sport.png"
            }
         ]
      },
      {
         "name": "radio",
         "label": "Running distance",
         "mandatory": false,
         "type": "radio",
         "options": [
            {
               "value": "7",
               "label": "7 Kms"
            },
            {
               "value": "15",
               "label": "15 Kms"
            }
         ]
      }
   ],
   "action": {
      "type": "invoke.function",
      "name": "formFunc"
   }
};
return {"type":"applet","data_type":"form","tabs":{{"label":"Form view","id":"form"}},"active_tab":"form","form":form};

Example of form view tab in mobile devices ( non-kiosk mode )

Example of form view tab in mobile devices ( kiosk mode )

Sections

Each tab is made up of sections. Simply put, a section is a combination of different elements, grouped together. 

Single Tab View

The tab list pane will be hidden when a Zoho Cliq widget has just one tab, allowing a more expansive view of the widget's content. This enables a cleaner and a more focused interface when multiple tabs aren't required.

Headers 

Headers are used to display the headings of tabs, which are fixed at the top of sections.  There are two types of headers.

• Title - Used to display the title of the tab

• Breadcrumbs - Indicates the navigational hierarchy and is useful to navigate across data.

Both title and breadcrumbs can have a maximum of three buttons on the right. The attributes to be passed for creation of a header are listed below :

Syntax :

button1 = {"label":$ButtonName1,"type":$Type,"name":$FunctionName,"id":$ID};
button2 = {"label":$ButtonName2,"type":$Type,"name":$FunctionName,"id":$ID};
button3 = {"label":$ButtonName3,"type":$Type,"name":$FunctionName,"id":$ID};
header = {"title":$HeaderTitle,"navigation":new|continue,"buttons":{button1,button2,button3}};

Footers  

Footers are fixed at the bottom of sections. They can hold text on the left, and, just like Headers, they can also have a maximum of three buttons on the right. 
The attributes to be passed for creation of a footer are listed below :

Syntax :  

button1 = {"label":$ButtonName1,"type":$Type,"name":$FunctionName,"id":$ID};
button2 = {"label":$ButtonName2,"type":$Type,"name":$FunctionName,"id":$ID};
button3 = {"label":$ButtonName3,"type":$Type,"name":$FunctionName,"id":$ID};
header = {"title":$FooterTitle,"buttons":{button1,button2,button3}};

Sample Code to depict usage of  Headers, Footers and Breadcrumbs in Cliq Widget :

Let's look at a Sales Performance Tracker Cliq Widget to showcase the Zylker Store's revenue and product distribution stats, effectively utilising headers, footers, and breadcrumbs for a great user experience.

tabsList = {{"label":"Regional Sales","id":"homeTab"}};
if(target.containKey("id") == false)
{
	tab_id = "homeTab";
}
else if(target.containKey("id") == true)
{
	tab_id = target.get("id");
}
if(tab_id.equalsIgnoreCase("homeTab"))
{
	// Header with button added to filter data
	header = {"title":"🏠 Home","navigation":"new","buttons":{{"label":"🔍 Filter","type":"invoke.function","name":"SalesTrackerWidgetButtons","id":"viewComponents","emotion":"positive"}}};
	elements = list();
	elements.add({"type":"text","text":"The *Regional Sales Dashboard for Zylker Products* showcases strong performance in North America, driven by high demand for Zylker Pro devices. Europe follows with steady growth, while Asia shows potential for improvement in Q1."});
	elements.add({"type":"divider"});
	elements.add({"type":"table","headers":{"Product Category","Units Sold","Revenue (USD)","Revenue Contribution"},"rows":{{"Product Category":"Premium Electronics","Units Sold":"600","Revenue (USD)":"$400,000","Revenue Contribution":"40 %"},{"Product Category":"Budget Electronics","Units Sold":"500","Revenue (USD)":"$300,000","Revenue Contribution":"15 %"},{"Product Category":"Add-ons","Units Sold":"450","Revenue (USD)":"$150,000","Revenue Contribution":"15 %"},{"Product Category":"Wearable Devices","Units Sold":"350","Revenue (USD)":"$100,000","Revenue Contribution":"10 %"}},"style":{"text_align":{"center","center","center","center"}}});
	elements.add({"type":"graph","styles":{"preview":"vertical_bar"},"data":{{"category":"Electronics","values":{{"label":"Jan 20","value":9},{"label":"Feb 20","value":8},{"label":"Mar 20","value":5},{"label":"Apr 20","value":2},{"label":"May 20","value":2},{"label":"Jun 20","value":2},{"label":"Jul 20","value":2},{"label":"Aug 20","value":2},{"label":"Sep 20","value":9},{"label":"Oct 20","value":8},{"label":"Nov 20","value":5},{"label":"Dec 20","value":2},{"label":"Jan 21","value":2},{"label":"Feb 21","value":2},{"label":"Mar 21","value":2},{"label":"Apr 21","value":2},{"label":"May 21","value":9},{"label":"Jun 21","value":8},{"label":"Jul 21","value":5},{"label":"Aug 21","value":2},{"label":"Sep 21","value":2},{"label":"Oct 21","value":2},{"label":"Nov 21","value":2},{"label":"Dec 21","value":2}}},{"category":"Devices","values":{{"label":"Jan 20","value":6},{"label":"Feb 20","value":11},{"label":"Mar 20","value":2},{"label":"Apr 20","value":5},{"label":"May 20","value":2},{"label":"Jun 20","value":6},{"label":"Jul 20","value":3},{"label":"Aug 20","value":5},{"label":"Sep 20","value":6},{"label":"Oct 20","value":11},{"label":"Nov 20","value":5},{"label":"Dec 20","value":3},{"label":"Jan 21","value":5},{"label":"Feb 21","value":7},{"label":"Mar 21","value":4},{"label":"Apr 21","value":6},{"label":"May 21","value":9},{"label":"Jun 21","value":8},{"label":"Jul 21","value":5},{"label":"Aug 21","value":2},{"label":"Sep 21","value":4},{"label":"Oct 21","value":6},{"label":"Nov 21","value":2},{"label":"Dec 21","value":3}}}}});
	elements.add({"type":"divider"});
	sections = list();
	sections.add({"id":1,"elements":elements});
	// Footer with button added to display brief stats
	footer = {"buttons":{{"label":"View Detailed Insights ➡️","type":"invoke.function","name":"SalesTrackerWidgetButtons","id":"nextPage"}}};
}
return {"type":"applet","tabs":tabsList,"active_tab":tab_id,"sections":sections,"header":header,"footer":footer};

SalesTrackerWidgetButtons - Widget button function

A widget button function to view detailed insights of Zylker Store products, showcasing the usage of breadcrumbs in widgets.

tabsList = {{"label":"Home","id":"homeTab"}};
// Functions consist of Target argument via which user can obtain information of the invoked Button such as Button Label , Tab from which the button is clicked etc.,.
buttonLabel = target.get("label");
tab_id = target.get("tab_id");
footer = Map();
if(buttonLabel.equalsIgnoreCase("View Detailed Insights ➡️"))
{
	// Navigation value added as continue to proceed with breadcrumbs navigation (Similar to that of Web browser search results)
	header = {"title":"Detailed Analytics","navigation":"continue"};
	elements = list();
	elements.add({"type":"fields","data":{{"Best-Selling Product":"Zylker Prime (38%)\nDominates sales with 700 units and $500K revenue."},{"Fastest Growth":"Zylker Neo (+12%)\nPopular in price-sensitive regions like Asia."},{"Total Products Sold":"1267\nTotal units sold for Zylker product categories."},{"Revenue Leader":"Premium Electronics (38%)\nPrime products contribute the highest revenue."}},"style":{"short":true}});
	dataList = list();
	eachData = Map();
	eachData.put("title","💎 Zylker Prime");
	eachData.put("description","The flagship product leads the revenue charts.");
	dataList.add(eachData);
	eachData = Map();
	eachData.put("title","🛍️ Zylker Neo");
	eachData.put("description","Affordable and highly demanded in emerging markets.");
	dataList.add(eachData);
	eachData = Map();
	eachData.put("title","🔧 Zylker Flex");
	eachData.put("description","Modular design appeals to versatile customers.");
	dataList.add(eachData);
	elements.add({"type":"cards","data":dataList,"style":{"view":"gallery","size":"medium"}});
	elements.add({"type":"divider"});
	elements.add({"type":"text","text":"*Product Revenue Contribution Chart*"});
	productStats = {{"label":"Zylker Prime","value":40},{"label":"Zylker Neo","value":20},{"label":"Zylker Flex","value":8}};
	elements.add({"type":"percentage_chart","styles":{"preview":"pie"},"data":productStats});
	elements.add({"type":"divider"});
	sections = list();
	sections.add({"id":1,"elements":elements});	
}
return {"type":"applet","tabs":tabsList,"active_tab":tab_id,"sections":sections,"header":header,"footer":footer};

Elements

Section elements are the building blocks of your Cliq widget. They provide the structure, carry the content and layout required to bring your widget to life, precisely! Cliq supports a wide variety of elements to present your content. 

• Title
  1. With a single button
  2. With overflow buttons
• Text
• Subtext
• Divider
• Buttons
• User Activity
• Table
• Fields
  1. Single columned
  2. Multi columned
• Cards
• Images
• Charts
• Graphs