Webix Jet Framework

Common errors

• ReferenceError: webix is not defined

  cause The Webix library object is not accessible in the global scope (window.webix), which Webix Jet components often expect. This typically happens with module bundlers that don't automatically expose `webix` globally.
  fix Ensure `window.webix = webix;` is executed in your main application entry point after importing the Webix library, or load Webix via a `<script>` tag before your application bundle.

• Event 'app:error:render' triggered: Error rendering view

  cause An error occurred during the rendering of a Webix UI component defined within a JetView's `config()` method, indicating an incorrect UI configuration.
  fix Check the `config()` method of the problematic JetView for syntax errors, incorrect Webix UI component properties, or invalid nesting. Enable debug mode (`debug: true` in `JetApp` config) for more detailed console logs.

• Event 'app:error:initview' triggered: Error initializing view

  cause An error occurred during the initialization of a JetView, indicating an issue with the JetView's lifecycle methods (e.g., `init()`, `urlChange()`) or its integration with Webix UI, rather than a direct UI config problem.
  fix Inspect the `init()` and other lifecycle methods of the affected JetView for logical errors or incorrect API calls. Use the debug mode to trace the execution flow and identify the source of the error.

• Data is not loading into Webix UI component in JetView

  cause Incorrect usage of `parse()` or `load()` methods, or the data structure provided to a Webix data-bound component (like `datatable`, `list`) within a JetView does not match expectations.
  fix Ensure you are calling `this.$$(id).parse(data)` or `this.$$(id).load(url)` within the `init()` method or a data loading handler, and that the `data` or `url` resolves to a compatible format for the Webix component. Verify the data structure.

• Cannot find UI component with id 'myId' using this.$$('myId')

  cause The `this.$$()` method in Webix Jet scopes its search for Webix widgets only within the current `JetView`. The component with `id='myId'` might be in a parent view, a subview, or incorrectly referenced.
  fix If the component is in a parent view, use `this.getParentView().$$('myId')` or pass the ID to a global `webix.$$('myId')` if it's a top-level ID. If it's in a dynamic subview, ensure the subview is loaded before attempting to access its components. Verify the ID is unique within the intended scope.

Warnings

• breaking Webix Jet v3.0 migrated its default toolchain from Webpack to Vite. Existing projects might require updates to `vite.config.js`, `.env` files, and `package.json` scripts to align with the new build process.
  Fix: Review the official 'Migration from Jet 0.x' guide in the Webix Jet documentation and compare your project's build configuration with the latest `jet-start` demo on GitHub for Vite setup. This primarily involves configuring `vite.config.js` and updating `package.json` scripts.
• breaking Starting with Webix Jet v3.0, several API methods changed their behavior. Notably, `getUrl()` and `getUrlString()` for app and view, and the `refresh()` method now returns a Promise, requiring asynchronous handling. `removeView()` of Webix widgets now correctly triggers `destroy()` of nested Jet views.
  Fix: Update calls to `getUrl()`, `getUrlString()`, and `refresh()` to handle Promises if needed. Ensure `removeView()` behavior aligns with expectations for nested Jet views. Consult the 'What's New' section for v3.0 in the official documentation.
• gotcha When using module bundlers (especially Vite), the underlying Webix library must often be exposed globally as `window.webix` for Webix Jet components and certain Webix UI functionalities to work correctly. Directly importing `webix` may not always achieve this global availability automatically.
  Fix: After importing Webix, explicitly assign it to the global `window` object in your main application entry file: `import * as webix from 'webix'; (window as any).webix = webix;` (for TypeScript). Alternatively, include Webix via a `<script>` tag in `index.html`.
• gotcha Asynchronous operations within a `JetView`'s `config()` method, such as fetching data for UI construction, can lead to rendering issues or 'core.js' errors if the UI configuration is not returned as a Promise that resolves when the data is ready.
  Fix: For asynchronous UI generation, wrap the `config()` method's return in a Promise. Fetch data within the `config()` method, and return the UI configuration only after the data is available: `config() { return new Promise(resolve => { webix.ajax('/data').then(data => { resolve({ view: 'datatable', data: data.json() }); }); }); }`.
• deprecated The `WJET` utility for faster prototyping was deprecated with Webix Jet v3.0. While it might still function, its use is discouraged in favor of the standard JetApp/JetView class-based approach and the recommended build tools.
  Fix: Migrate any code using `WJET` to the standard ES6 class-based `JetApp` and `JetView` structure. Refer to the current quickstart guides and demo projects for modern development patterns.

Install

• npm install webix-jet npm
• yarn add webix-jet yarn
• pnpm add webix-jet pnpm

Imports

• JetApp
  wrong:

  const { JetApp } = require('webix-jet');

  correct:

  import { JetApp } from 'webix-jet';

  Primary class for defining the application entry point. Webix Jet is ESM-first and primarily uses ES6 class syntax. CommonJS `require` is generally not recommended for modern Webix Jet projects.
• JetView
  wrong:

  import JetView from 'webix-jet/sources/views/jetview';

  correct:

  import { JetView } from 'webix-jet';

  Base class for defining application views. Direct imports from `sources/` paths are generally internal and can break between versions.
• plugins
  wrong:

  import * as plugins from 'webix-jet/plugins';

  correct:

  import { plugins } from 'webix-jet';

  Provides access to built-in Webix Jet plugins (e.g., Menu, Locale, Status). The `plugins` object is a named export.
• webix (global)
  wrong:

  import 'webix';

  correct:

  import * as webix from 'webix';
  window.webix = webix;

  When using module bundlers like Vite or Webpack, the `webix` library often needs to be explicitly exposed as a global `window.webix` object for Webix Jet and Webix UI components to function correctly, especially for complex widget integration or dynamically loaded modules.

Quickstart

This quickstart initializes a basic Webix Jet application with a single 'TopView' and renders it into the document body. It demonstrates the core setup of `JetApp` and `JetView` using TypeScript, including the necessary global exposure of the `webix` object.

import { JetApp, JetView } from 'webix-jet';
import 'webix/webix.css'; // Or your custom Webix skin
import * as webix from 'webix';

// Ensure Webix is globally available for the UI components
(window as any).webix = webix;

class TopView extends JetView {
    config() {
        return {
            rows: [
                { view: 'toolbar', elements: [{ template: 'My JetApp', type: 'header' }] },
                { template: 'Welcome to your Webix Jet application!', autoheight: true, borderless: true, css: 'webix_shadow_medium' }
            ]
        };
    }
}

class MyApp extends JetApp {
    constructor(config = {}) {
        const defaults = {
            start: '/top',
            views: { top: TopView }, // Define how to resolve 'top' to TopView
            debug: true
        };
        super({ ...defaults, ...config });
    }
}

webix.ready(() => {
    new MyApp().render(document.body);
});