Getting started
Follow these steps to create a Singular widget:
- 6.Share your widget
Open a console and enter following commands:
C:\Users\tm\Singular Widgets>singular createwidget myWidget
Singular Widget – myWidget has been created
C:\Users\tm\Singular Widgets>dir /S /B
C:\Users\tm\Singular Widgets\myWidget
C:\Users\tm\Singular Widgets\myWidget\deploykey.json
C:\Users\tm\Singular Widgets\myWidget\source
C:\Users\tm\Singular Widgets\myWidget\source\icon.png
C:\Users\tm\Singular Widgets\myWidget\source\output.html
This set of commands creates a folder called myWidget on your local disk and clones the widget boilerplate into it. We recommend adding this folder to your source code management tool.
Description of default files
File | Description |
|---|---|
deploykey.json | A file containing the widget deploy key. |
source\output.html | The widget's source code. |
source\icon.png | The widget icon in the .png format. |
<!DOCTYPE html>
<html>
<head>
<style>
/* The default widget style to make output match the bounding box */
html,
body {
background: none;
margin: 0;
padding: 0;
height: 100%;
}
/* Add your custom styles here */
</style>
</head>
<body style="margin: 0; background:none; overflow: hidden;">
<div id='container' style="position: absolute; left:0%; top:0%; width: 100%; height: 100%"></div>
<!-- Your custom html goes here -->
<!-- Singular widget library -->
<script src="https://app.singular.live/libs/singularwidget/1.0.4/singularwidget.js"></script>
<script>
let windowWidth = 0;
let windowHeight = 0;
let compositionInstance = null;
/**
* Initialize a Singular widget object and define its callback functions
*/
SingularWidget.init({
onInit: onSingularInit,
onValue: onSingularValue,
onButtonClicked: onSingularButtonClicked,
onEditComp: onSingularEditComp,
onAnimation: onSingularAnimation
});
/**
* addEventListener for window resizing
* Relevant when your widget displays HTML content or uses widget compositions
*/
window.addEventListener("resize", function() {
if (windowWidth != window.innerWidth || windowHeight != window.innerHeight) {
windowWidth = window.innerWidth;
windowHeight = window.innerHeight;
if (compositionInstance) {
compositionInstance.resize(windowWidth, windowHeight);
}
}
});
/**
* onSingularInit()
* Called when the widget instance is created
*/
function onSingularInit(params) {
console.log("onSingularInit() - params =", params);
windowWidth = window.innerWidth;
windowHeight = window.innerHeight;
}
/**
* onSingularValue()
* Called when the widget instance is created or the instance data has changed
*/
function onSingularValue(json) {
console.log("onSingularValue() - json =", json);
}
/**
* onSingularButtonClicked()
* Called when a push button of the widget is clicked
*/
function onSingularButtonClicked(button) {
console.log("onSingularButtonClicked() - button =", button);
}
/**
* onSingularAnimation()
* Called when the animation state of the widget changes
*/
function onSingularAnimation(anim) {
console.log("onSingularAnimation() - anim =", anim);
if (!compositionInstance) return;
switch (anim.event) {
case "start":
break;
case "stop":
break;
case "jump":
break;
case "seek":
break;
case "init":
break;
}
}
/**
* onSingularEditComp()
* Called when the subcomposition of a widget is edited
*/
function onSingularEditComp(composition) {
console.log("onSingularEditComp() - composition =", composition);
}
</script>
</body>
</html>
To create a Singular.live widget, you need an account that has developer permissions. Check your permissions by navigating to the Singular Dashboard, selecting the User Menu > Settings, and checking your User Settings.
User Administration and Developer Tools should be switched on.
Checking your account's developer permissions
Also on the Singular Dashboard:
1. Select the User Menu > Widget Manager, and then New Widget to create a new widget.
Creating a new widget
2. Enter a name and category for your widget.
The widget name doesn't need to match the name of the folder used in the
singular createwidget command in step one. Nevertheless, we recommend using the same name.Continuing in the Widget Manager:
1. Copy the Deploy Key from the Widget Details and paste it into the
deploykey.json file from step one. 
Copying the deploy key
The file should look like this:
deploykey.json
{
"deploykey": "uS3bDUabcDnYlAZMO87OL2nBckvSIdmE"
}
2. Upload the widget code to Singular using following command in the Node.js console:
C:\Users\tm\Singular Widgets> singular deploywidget myWidget
-----------------------------------------------
Singular.Live widget deploy
Validating files in directory "source"
Creating zip file
Deploying widget to Singular.Live
Widget ID: 4215 successfully deployed
C:\Users\tm\Singular Widgets>
The deploy script will read the deploy.json file, extract the deploy key, create a zip-file of the widget sources, and upload it to the Singular.live Cloud. Your widget then will be visible in the Widget Browser when you create a new widget instance.
Activate the
Show Dev Versions checkbox in the Widget Browser to access the development version of your widget.The status of the
Development version of your widget gets updated every time you deploy new sources for your widget. Refresh the Widget Manager and select your widget to see to see its updated status.Define the widget UI in the UI Definition field.
Copy your widget UI definition
Before you publish your widget, use Chrome's developer tools to debug and optimize it.
When you're done testing your widget, use the
publish function to make it available for other users.The
publish function creates an identical copy of the development version of your widget and tags it as published. When you do this, the development version gets increased by one.Widgets never get deleted from the Singular.live platform. They are always in one of the following states:
- development: Every new widget defaults to the
developmentstatus. Widgets under development and can only be accessed by users with development permissions. Once your widget has been fully developed and tested, you canpublishit to make it available to other users. Widgets withdevelopmentstatus can bepublished. - published: A published widget is available to all members of your account. Only one
publishedversion of a widget can exist at the same time. By default, the latest published version will be used when creating an instance of a widget. Widgets withpublishedstatus can beun-published. - archived: Widgets automatically get archived when a new version is published. Existing widget instances that use an older widget version will stay on the older version. A standard user can manually update the widget in the widget instance by selecting the Update button. Users with developer permissions can also use any archived version of an widget. Widgets with
archivedstatus can bepublishedanddepreciated. - depreciated: Set a widget to
depreciatedstatus when you want or need to force a widget instance to upgrade to the latest published version of an widget. A widget withdepreciatedstatus can bearchived.
Status | Action | New status |
|---|---|---|
development | Publish | Published |
published | Un-publish | Archived |
archived | Publish | Published |
| Depreciate | Depreciated |
depreciated | Archive | Archived |
If you'd like to share your widget with another Singular user, enter their Singular account name in the Share with field in the Widget Manager.
Sharing a widget
Last modified 4mo ago