Getting Started: Widgets

NOTE: This page is prone to frequent changes, as we settle the dust with our new Widget System. The information below is accurate up to version 1.0.1. If this page hasn't been updated to a version higher than 1.0.1, contact us right away!

Overview

Widgets are the user-made mini-apps that reside within the Grid. Widgets are not treated as individual components or modules; rather, the code for all widgets are fetched by WidgetService. The definition for a Widget object can be found here.

This getting-started guide will go over the basics of how to define and create your very own widget! We want to make widget creation easy and accessible to beginner coders, while still offering enough features to satisfy experienced coders. Currently, as the Widget System is still in alpha, things might not be as clear or powerful as we might like, but we will continue to develop the system.

Get Started

If you haven't already, read the readme and the contribution guide.

Once you have the files, it's a good idea to run npm start or ng serve to get a live development server up. If you do this, open up your browser to localhost:4200 to view the live version of ElectroTab. This will update whenever you save any changes. (Optional)

The bulk of what you will be writing is currently in app/grid/widget-db.ts. It's just a constant array of Widgets for now, and this will change very soon! (Don't worry, all of your code will be migrated when we switch.) Here, you can see some examples of other widgets we have created, such as the search bar and speed dial.

Define Your Widget

First, create a new Widget object inside the array by adding a comma (,) after the last entry, pressing enter a few times, and putting a set of curly brackets. Leave yourself plenty of room inside the brackets for the fields.

Every widget has a number of required fields. This section will go through what each of them stands for and how to define them.

Your widget-db should look something like this right now:

...

export const WIDGETS : Widget[] {

//Other widgets
...

  {
    //Your widget :D
  }

ID

This is the numeric identifier for your widget. It must be unique! In order to avoid merge issues, check the Widget List. Do not use any ID from 1 to 100. These are reserved.

Declare the ID using id: x, where x is a number greater than 100.

Name

This is the on-screen name of your widget! In the 'Add Component' drawer, your widget will display exactly this name, so make sure your capitalization and spacing is all correct.

Declare the Name using name: 'Widget Name Here',.

Icon

Put your icon in the assets/images folder. It should be at least 256 by 256. The larger the better! (Must be square)

Declare the icon location relative to the assets/images folder. (ex. icon: 'favicon.png')

Currently, your Widget should look something like this:

...

export const WIDGETS : Widget[] {

//Other widgets
...

  {
    id: 9000,
    name: 'My Widget',
    icon: 'widget.png',
  }

HTML Code

Now comes the fun part! You may use Angular directives such as *ngIf, materialize, and [routerLink]. (Look at the Angular documentation if you need help with this.) You may also use any method within AuthService and WidgetService. Currently, custom TypeScript is not supported, but you can always temporarily add any custom methods into your own service (contact us if you need to do so).

If you use VSCode, you have the luxury of getting real nice formatting with angular2-inline! If you're not using VSCode, then you will get ugly unformatted single-color HTML, and that is no good. 👎

Declare your HTML with template: followed by a set of ` marks. Inside these marks you can code normally, and this code will be injected for you.

Optional Fields

• height: Starting height of your widget.
• width: Starting width of your widget.
• defaultSetting: Sets the default value for the item.setting field. View the GridMenu documentation to learn more about creating custom settings for your widgets.
• menuTemplate: Implement the same way as template. This is the code for the menu that displays in the GridEditPage when you click the menu button for that component.

Submit Your Widget

View the Contributing Guide for the submission checklist.