Custom Widgets Overview
  • 23 May 2023
  • 5 Minutes to read
  • Contributors

Custom Widgets Overview


Article summary

Build your own widgets in Tulip using HTML, CSS and JavaScript

Custom Widgets Overview

Build your own features in Tulip using HTML, CSS and JavaScript.
Library widgets available here: https://tulip.co/library/?query=Widgets

Introduction

The items that you drag-and-drop into your app are called "Widgets". These can be buttons, images, input boxes, and anything else available from the Toolbar.

Custom widgets allow you to write your own code and create your own widgets that you can then drag-and-drop onto your application and interact with. This capability allows Tulip users to stretch the boundaries of what is possible in Tulip.

In this article, we'll give you a quick overview of how custom widgets work.


Custom Widget Basics

The custom Widget management screen can be found within your account settings page. This is where you can create and delete widgets. The custom widget editor allows you to write your widget code, create Props and Events, and preview your widget. Below is a diagram describing what props and events are:

Props: Props are data that are shared between custom widgets and Tulip applications. Props will be exposed in the application editor and will allow app editors to select which variables, table records, or other information to associate with the prop.

Events: Events are signals that your Widget can send to your application. Events allow your application to respond with a trigger and can carry information along with them.

Custom widgets are accessible through the Custom down selector in the App Editor.


Creating a Widget

Warning

Only users with access to account settings (Account Owners) can access the custom widget editing UI.

The Widget editor screen is broken down into four sections. Code that you write in the bottom left section will appear in the preview section once you click into the preview section. Prop values can be changed directly in the preview section for testing purposes.

Special functions for interacting with Props and Events.

Getting the Value of Props

Warning

It is not guaranteed that the prop being used by a widget will load before that widget loads, so all props associated with Table record fields, Aggregations, or any other dynamic value should include logic to support cases where they are null at the point the widget is loaded. See this section for details on triggering logic when a prop changes.

//Getting the Value of a Prop 
getValue('My Prop'); 
//Store prop to a variable
let myVariable = getValue('My Prop');

Do Something when a Prop Changes

//Do something anytime a prop value changes
getValue('My Prop', (internalVariable) => {    
    doSomething(internalVariable);
});

Setting the Value of a Prop

**Setting the Value of a Prop** 
setValue('My Prop', *value\_to\_set*); 

//Set value of a text prop to 'hello!'
setValue('My Text Prop', 'hello!');

//set value of an item in an object
setValue('My Object Prop', { 'Key inside object': 'new value' });

Fire an Event

**Fire an event** 
fireEvent('event', *payload*); 

//fire an event with no payload
fireEvent('My Event');

//fire event with payload
fireEvent('My Event', myVariable);

Example widget build video


Importing/Exporting Apps

Export

  1. From the custom widget overview, select the 3 dots next to the widget you want to export.

  1. Select "Export".

Import

  1. From the custom widget overview screen, select the 3 dots at the top.

  1. Select "Import".

  1. Find the .json custom widget file.

Enabling External Libraries

External libraries further extend what custom widgets can do. External libraries handle lots of the dirty work of writing html directly in JavaScript. External libraries must be enabled for each widget where you want to use them.

  1. While in your Widget, click on the 3 dot menu in the ribbon.

  1. Select "Enable External Library".

  1. Select the extension you want to enable.

Here is a basic description of what each of these do, many of them excel in many areas, so feel free to explore.

  • jQuery - enables more streamlined selection of html elements, along with element manipulation.
  • D3 - The gold standard for visualization of data, a steep learning curve but tons of flexibility.
  • Google Visualization - A great tool for doing as the name implies, visualization.
  • javaascript-Ip-solver - Ip solver is an external library that can handle complex computations to solve equations.
  • Lodash - Lodash provides a ton of tools that make working with javascript datatypes easier.
  • ChartJS - About the simplest graphing library possible with tons of online resources.
  • Moment - Moment provides tons of tools to work with dates and times.

Was this article helpful?