Using the Wijmo Designer Extension for Visual Studio Code

In addition to the web-hosted Wijmo Designer (read about the web-based Wijmo Designer here), we just released a new extension for Visual Studio Code that targets Angular development. Within HTML files, it inserts a CodeLens link above each tag representing a Wijmo control. Clicking the link opens the Wijmo Designer in a separate tab, and initializes it based on the associated markup. After making changes in the designer, with one click you can update the original HTML file with the modified Angular tags.

The Wijmo Designer extension also provides a standalone command that opens the design surface in a separate tab, where you can instantiate controls, such as our Angular DataGrid with sample data, customize their properties, and generate Angular tags that you can copy into your source files.

You can use the Wijmo Designer extension in conjunction with the IntelliSense extension described in this article. For example, you can use IntelliSense to create an Angular tag for a new control, then edit the tag using the visual designer.

Installing the Wijmo Designer extension

You can view a video and step-by-step tutorial here.

To get started, visit the Wijmo designer Demo page. The Wijmo Designer extension is not included with any Wijmo distribution, but has been published to the Visual Studio Marketplace. The easiest way to install it is to open VS Code and go to the Extensions pane. Type wijmo into the search box, then click the Install button to begin downloading the extension.

Click the Reload button when it appears to complete the installation.

Modifying existing control markup

The Wijmo Designer extension is activated whenever you open an HTML file in VS Code. Let’s begin by opening one of the Wijmo samples, HeaderFilters. If you have already downloaded Wijmo, you can find this project in the Samples\TS\Angular2\HeaderFilters\HeaderFilters folder. Open that folder in VS Code, then open the file src\app.html, which contains the following FlexGrid markup:

Notice the gray Wijmo Designer… link that appears above the <wj-flex-grid> tag. In VS Code, this is known as a CodeLens, which Microsoft defines as “actionable, contextual information that is displayed interspersed with the source code.” In our case, the action is to open the design surface in a separate tab, seeding it with the context provided by the Angular markup, and the location of that markup within the source file. Now click the link to open the designer in an adjacent tab.

The FlexGrid control on the design surface is displayed in design mode, which means that you cannot scroll, resize, or otherwise interact with it directly. Instead, you use the Properties pane on the right side of the designer 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.

For example, if you change the value of the allowResizing property from Columns to None, there is no visual difference in the grid’s rendering, since this is a runtime behavior setting. But if you click the Source View button along the left side of the designer, you will see that the extension is aware of the change.

To return to the design surface, click the Design View button below the Wijmo logo.

For controls with collections, such as grid columns, the designer lets you add, delete, and modify individual members. Locate the columns property in the Properties pane, then click the Show Items button on the right side of the property editor to reveal the eight columns defined in the Angular markup.

Hover over the word author and click the link that appears. This will open that column definition for editing. Locate the visible property and change it to False. Now the grid is redrawn to show that the author column has been hidden.

To return to the FlexGrid settings, click the back button in the Properties pane.

When you are satisfied with the changes you have made in the designer, click the Save button below the Wijmo logo to update the editor for the original source file and give it focus. Note that the modified Angular tag is highlighted, and the changes made in the designer are now reflected in the markup. At this point, you can either save or discard your changes just as if you had typed them yourself.

The indentation style of the modified tag may not match the original, as it is governed by the built-in VS Code setting html.format.wrapAttributes. For best results, set this to a value other than auto, such as force-aligned, which is depicted above.

After saving, the Wijmo Designer tab still exists, and if you give it focus it will retain its prior state. However, you should be aware that the extension remembers the document range of the Angular tag from which it was invoked. If you subsequently modify the original source file, you should revisit the CodeLens link to refresh the associated designer tab. Otherwise, if you just switch to the designer tab and click Save, the update may occur in the wrong place.

Creating new control markup

To create Angular markup for a new Wijmo control, press F1 to open the command palette, then execute the Wijmo Designer command to open a standalone version of the design surface. Click the Wijmo logo at the upper left corner of the designer to open the menu.

The Toolbox command opens a collapsible panel of Wijmo controls, grouped by module name (grid, chart, input, gauge, nav, olap). The Themes command lets you see the effect of selecting a different Wijmo theme, although this has no effect on the generated code, which consists of control tags only.

Let’s create a chart control with a trend line. Click Toolbox, expand the chart group, then click the item named FlexChart. Note that it displays live sample data representing “most active” securities.

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. 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. Scroll down in the Properties pane, locate the series property, and click the Show Items button to expand it.

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 standalone mode, there is no source file to update, but you can still generate Angular tags and copy them from the designer to your HTML source. Click the Source View icon on the left side of the designer to show the generated Angular tags. From there, highlight the text to be copied and use a shortcut key (on Windows, Ctrl+C) to copy the text to the clipboard. Note that the Copy command on the Edit menu of VS Code does not work with the designer.

<wj-flex-chart #flexchart1
 [bindingX]="'symbol'"
 [header]="'Most Active'"
 [palette]="['#005fad', '#f06400', '#009330', '#e400b1', '#b65800', '#6a279c', '#d5a211', '#dc0127', '#000000']">
 <wj-flex-chart-axis [wjProperty]="'axisY'" [format]="'c0'"></wj-flex-chart-axis>
 <wj-flex-chart-legend [wjProperty]="'legend'" [position]="'Bottom'"></wj-flex-chart-legend>
 <wj-flex-chart-series [name]="'Latest Price'" [binding]="'latestPrice'"></wj-flex-chart-series>
 <wj-flex-chart-series [name]="'52-Week High'" [binding]="'week52High'"></wj-flex-chart-series>
 <wj-flex-chart-series [name]="'52-Week Low'" [binding]="'week52Low'"></wj-flex-chart-series>
 <wj-flex-chart-trend-line [binding]="'latestPrice'" [fitType]="'Logarithmic'" [visibility]="'Plot'"></wj-flex-chart-trend-line>
</wj-flex-chart>

In our example, the generated markup contains child elements representing the Y-axis, chart legend, three data series, and a trend line. To return to the visual designer, click the Design View button below the Wijmo logo.

Differences between designer versions

The following table summarizes the differences between the web-hosted Wijmo Designer, the VS Code extension when invoked from a CodeLens link in an HTML source file, and the VS Code extension when invoked from the standalone command:

The extension does not provide an Events pane since it can only modify the original control tag---it does not have deep knowledge of the entire Angular project. However, any existing event handlers defined in the original control tag will be preserved when the extension updates the source file.

The extension’s standalone command remembers the state of the visual designer within the current workspace context, even if you close and reopen VS Code.

Limitations

The following Wijmo controls are not supported in the initial version of the designer:

• Menu
• Popup
• TabPanel
• MultiRow
• PdfViewer
• ReportViewer

In Angular projects, it is common for control properties to be bound to a runtime data member instead of a literal value. In such cases, the designer displays the binding in a read-only text box in italics. Bindings are preserved during save operations; however, there is no interface for creating or editing them in the designer.

See the extension’s page on the Visual Studio Marketplace for a current list of limitations related to Angular markup.

Conclusion

The Wijmo Designer extension for VS Code assists with Angular development by providing a WYSIWYG design surface for editing markup tags that represent Wijmo controls, such as our Angular DataGrid Control. It also supports the creation of new Wijmo markup tags by providing a standalone mode where you can experiment with control properties, child objects, and collections.

Download Now!