How to Use the Wijmo Designer
Introducing the Wijmo Designer, a new web-hosted tool that provides a design surface and code generator for Wijmo controls. The Wijmo Designer lets you create control instances, specify properties and events, and generate the corresponding HTML/JavaScript that you can incorporate into your applications. The designer is particularly useful for exploring complex objects such as grids and charts.
If you are developing with Angular, you should try the Wijmo Designer extension for Visual Studio Code, which provides a visual interface for creating and editing Angular tags representing Wijmo controls.
Getting started with Wijmo Designer
You can view a video tutorial here.
When the page first opens, the design surface contains a single FlexGrid control with some live sample data, as shown above. To remove it, click the Delete button on the Edit toolbar.
The designer’s main menu is collapsed initially and is displayed as a vertical strip of icons. Click the Wijmo logo at the upper left corner of the page to expand the menu.
The Toolbox command opens a collapsible panel of Wijmo controls, grouped by module name (grid, chart, input, gauge, nav, olap). Expand the input group and click Calendar to add a new control named calendar1.
The design surface should now look something like this:
To collapse the main menu, click the Wijmo logo again, or click anywhere within the interior of the design surface (the region below the Edit toolbar).
Controls on the design surface are displayed in design mode, which means that you cannot scroll, resize, or otherwise interact with them directly. Instead, you use the Properties pane on the right side of the page to manipulate the control’s object model. Each available property displays an editor of the appropriate type, and any changes you make there are immediately applied to the selected control. Set the monthView property to False, and the formatMonths property to MMMM.
The calendar control now displays the full names of the months of the current year.
Click the arrow icon to the right of the Properties tab to show the Events pane, which displays a toggle button for each event exposed by the selected control. For each event that is turned on, the designer will emit boilerplate event handling code. Turn on the control for the valueChanged event.
You can collapse the properties/events sidebar by clicking the arrow at the right edge of the page.
The design surface supports multiple controls with sequential layout. Open the Toolbox again and add an InputDateTime control to the design surface. Click the Move Up button on Edit toolbar to swap the positions of the two controls.
You can also use the designer to see the effect of selecting a different Wijmo theme. Click the Wijmo logo to close the Toolbox, click Themes to show the list of available themes, then click a different value, such as Cerulean.
Generating code
When you are satisfied with the state of the visual designer, you can generate code for use in your applications. Click the Wijmo logo to close the Themes list, then click Source View to show the generated HTML.
The initial version of the web-hosted designer generates pure JavaScript and is not tied to any specific framework such as jQuery or Angular.
Use the Save icon on the left to write the HTML to a file or select the desired fragments and use the browser’s UI to copy them to the clipboard. The generated code contains the following elements:
- A
<head>tag that references the primary Wijmo CSS file and the selected theme file, if any. - Wijmo
<script>tags for any combination of controls that the designer supports. You can omit any module references that you do not need. - A
<body>tag that contains an empty<div>for each control created in the designer. - An inline
<script>block that instantiates each control created in the designer and applies any custom property/event settings. In our example, the script contains the following code:
// var key = "your-license-key";
// wijmo.setLicenseKey(key);
var inputdatetime1 = new wijmo.input.InputDateTime("#inputdatetime1");
var calendar1 = new wijmo.input.Calendar("#calendar1", {
formatMonths: "MMMM",
monthView: false
});
calendar1.valueChanged.addHandler(function (s, e) {
});
The first two lines are commented out. If you were to deploy this code to a public server, this is where you would insert the Wijmo license key for your application. The two assignment statements invoke the appropriate Wijmo constructor on the empty <div>tags.
The call to the Calendar constructor specifies an argument containing modified values for the formatMonths and monthView properties. However, the InputDateTime constructor has no arguments since no properties were changed. Finally, the last line adds a boilerplate handler for the calendar’s valueChanged event.
To return to the visual designer, click the Design View button (below the Save button) on the left side of the page.
If you want to save designer layouts for future use, use the Save button on the main toolbar to write the current state to a JSON file, then subsequently use the Open button on the main toolbar to reload the contents of the selected file. Note that the designer does not restore state from saved HTML in source view, only from saved JSON in design view.
Working with charts
Now let’s consider a more complex example. Delete all controls from the design surface, then expand the chart group in the Toolbox and click the item named FlexChart. Note that the chart displays live sample data representing “most active” securities. This is the same data set displayed in the default FlexGrid when the designer was first opened, limited to the first six rows.
In the Properties pane, note that there are four properties representing complex objects on the chart: axisX, axisY, dataLabel, and legend. Click the gear icon for the axisY property, then set the format property to the string c0, denoting a currency value with zero decimal places. The design surface should now look something like this:
Note the currency symbols shown in the Y-axis. Click the back button in the Properties pane to return to the settings for FlexChart. Next, click the gear icon for the legend property and change its position setting to Bottom.
Return to the FlexChart settings by clicking the back button as before. Give the chart a title by setting its header property to Most Active. Locate the palette property, click the Show Colors button in the editor, and select one of the predefined values such as dark. Now the chart looks something like this:
The Wijmo Designer is especially useful for manipulating collections such as chart series. For example, you can easily add a trend line to a chart by adding a new series element of the appropriate type. Before we do that, let’s look at the default series collection generated by the designer. Scroll down in the Properties pane, locate the series property, and click the Show Items button to expand it.
Hover over the words Latest Price and click the link that appears. Note that it has a binding value of latestPrice, corresponding to the actual field name in the data source. The name property, which is shown in the chart legend, has proper capitalization and a space between words.
Click the back button to return to the FlexChart settings, then expand the series property as before. Now click the Add Item link to add a new chart series to the end of the collection. Click the down arrow at the right edge of the newly added item, then select TrendLine from the list of available series types.
The newly added item will now appear as [Trend Line]. Hover over the bracketed text and click the link that appears. Now the Properties pane displays properties that are specific to the TrendLine class. Set binding to latestPrice, fitType to Logarithmic, and visibility to Plot. You don’t need to provide a value for the name property because this series is being omitted from the legend. With the trend line added to the chart, the designer now looks something like this:
In source view, the generated code begins with a call to the FlexChart constructor. Note the child object arguments for axisY and legend.
var flexchart1 = new wijmo.chart.FlexChart("#flexchart1", {
axisY: {
format: "c0"
},
bindingX: "symbol",
header: "Most Active",
legend: {
position: "Bottom"
},
palette: ["#005fad", "#f06400", "#009330", "#e400b1", "#b65800", "#6a279c", "#d5a211", "#dc0127", "#000000"]
});
Individual chart series are pushed onto the series collection property in the order in which they were specified in the designer. The trend line, which is added last, uses a specialized TrendLine constructor instead of the default Series constructor.
flexchart1.series.push(new wijmo.chart.Series({
name: "Latest Price",
binding: "latestPrice"
}));
flexchart1.series.push(new wijmo.chart.Series({
name: "52-Week High",
binding: "week52High"
}));
flexchart1.series.push(new wijmo.chart.Series({
name: "52-Week Low",
binding: "week52Low"
}));
flexchart1.series.push(new wijmo.chart.analytics.TrendLine({
binding: "latestPrice",
fitType: "Logarithmic",
visibility: "Plot"
}));
The default series names and bindings are provided so that you can get a sense of what the actual chart will look like when deployed with real data in your application. You can replace the default series with your own bindings for code generation, but the designer will not plot any data points.
Limitations
The following Wijmo controls are not supported in the initial version of the designer:
- Menu
- Popup
- TabPanel
- MultiRow
- PdfViewer
- ReportViewer
The following creatable objects that add functionality to Wijmo controls are not supported in the initial version of the designer:
- DataMap
- FlexGridFilter
- FlexSheetFilter
- LineMarker
- RangeSelector
- ChartTooltip
- ChartAnimation
- ChartGestures
- AnnotationLayer
- PlotArea
Conclusion
The Wijmo Designer makes it easier to build applications with Wijmo controls by providing a visual design surface that lets you experiment with control properties, child objects, and collections. It generates pure JavaScript code that you can add to your projects, which saves time while minimizing coding errors and typos.
John Juback