Creating a Minimal "Hello from Wyn!" Custom Visualization

This quick-start guide helps you build and preview a super-simple custom visualization in Wyn Enterprise using the Dev Tools scenario. No complex charts, SVGs, or data bindings are needed — the goal is to confirm your local development setup works and see something appear in Wyn.

What You'll Achieve

• A gray box that fills the Dev Tools placeholder

• Centered white text: Hello from Wyn!

• Confirmation that Wyn is successfully loading and running your local code (via browser console logs)

Prerequisites

• Node.js and npm installed (download from https://nodejs.org if needed)

• Wyn Enterprise with Developer Mode enabled:

  • Go to Admin Portal → Dashboards Settings → Enable Developer Mode

• Access to the Wyn dashboard designer

Step 1: Install the Wyn Visual Tools CLI

Open a terminal (Command Prompt, PowerShell, Terminal, etc.) and run:

Bash

npm install @wynenterprise/wyn-visual-tools -g

This installs the official command-line tool globally.

Note: If you see permission errors on macOS/Linux, prefix with sudo or use nvm.

Step 2: Create a New Project

In your terminal, run:

Bash

wyn-visual-tools init

• When prompted, enter a project name (e.g., hello-wyn-viz)

• This generates a folder with starter files.

Navigate into the project:

Bash

cd hello-wyn-viz

(Replace hello-wyn-viz with whatever name you chose.)

Step 3: Update visual.json

Open visual.json in your code editor (VS Code recommended) and replace everything with this clean version:

JSON

{
  "id": "helloWynViz",
  "name": "helloWynViz",
  "displayName": "Hello from Wyn Viz",
  "displayNameKey": "",
  "description": "Minimal test visualization",
  "icon": "icon.png",
  "externalJs": [],
  "externalCss": [],
  "dependencies": [],
  "assets": {
    "images": {}
  },
  "configuration": {},
  "cliVersion": "6.1.8"
}

• This avoids common JSON syntax issues.

• Optional: Drop a small icon.png into the assets/ folder for a nicer icon later.

Step 4: Simplify capabilities.json

Replace the contents of capabilities.json with:

JSON

{
  "dataBinding": {
    "aggregate": false
  },
  "options": {},
  "actions": {},
  "analysis": {}
}

This disables data binding (not needed for basic testing).

Step 5: Write the Minimal Visual Code

Open src/visual.ts and replace everything with this:

TypeScript

import "../style/visual.less";

export default class Visual extends WynVisual {
  private container: HTMLDivElement;

  constructor(
    dom: HTMLDivElement,
    host: VisualNS.VisualHost,
    options: VisualNS.IVisualUpdateOptions
  ) {
    super(dom, host, options);

    // Create a full-size container
    this.container = document.createElement("div");
    this.container.style.width = "100%";
    this.container.style.height = "100%";
    this.container.style.display = "flex";
    this.container.style.alignItems = "center";
    this.container.style.justifyContent = "center";
    this.container.style.fontSize = "24px";
    this.container.style.fontWeight = "bold";
    this.container.style.color = "white";

    dom.appendChild(this.container);
  }

  public update(options: VisualNS.IVisualUpdateOptions): void {
    console.log("Update called!", options); // Helps confirm it's running

    // Simple rendering: gray background + text
    this.container.style.backgroundColor = "gray";
    this.container.innerHTML = "Hello from Wyn!";
  }

  public onDestroy(): void {}
  public getInspectorHiddenState(): string[] | null { return null; }
  public getActionBarHiddenState(): string[] | null { return null; }
  public getColorAssignmentConfigMapping(): VisualNS.IColorAssignmentConfigMapping | null { return null; }
}

This uses plain HTML/CSS — no extra libraries required.

Step 6: Start the Local Development Server

In the project folder, run:

Bash

wyn-visual-tools develop

• You should see: Dev server listening on port 3000!

• The server auto-rebuilds when you save files.

• Keep this terminal window open.

(If port 3000 is in use, add -p 3001 and remember to update Wyn later.)

Step 7: Preview in Wyn Enterprise

1. Open your Wyn dashboard designer and create/open a dashboard.

2. From the visualization node (Custom Visualizations section), drag the Dev Tools scenario onto the canvas.

3. Click the Refresh button (reload icon) next to the Dev Tool scenario when selected.

Packaging and Uploading a Custom Visualization to Wyn

Once you’ve developed your custom visual (e.g., hello-world-viz) using wyn-visual-tools, follow these steps to package it and make it available in Wyn dashboards.

Step 1: Package the Visual

1. Open a terminal and navigate to your project folder:

cd ~/hello-world-viz

2. Run the Wyn packaging command:

wyn-visual-tools package

• This compiles your project and creates a .viz file (e.g., hello-world-viz.viz) in the same folder.

• This .viz file contains all your compiled code, assets, and metadata.

Step 2: Upload the .viz file to Wyn

1. Log in to the Wyn Admin Portal.

2. Go to Resource Portal.

3. Click Create (+).

4. Scroll down to Upload.

5. Drag and drop your packaged .viz file.

6. Confirm the upload — the visual is now stored in Wyn.

Step 3: Use the Custom Visual in Dashboards

1. Open the Dashboard Designer in Wyn.

2. In the visualization node, open Custom Visualizations.

3. Locate your uploaded visual (e.g., Hello World Viz).

4. Drag and drop it onto the dashboard canvas.

5. Configure layout, appearance, and settings as needed.