Configuration

Each premium extension reads a JSON configuration file that tells it:

where to load the vendor's JavaScript and CSS files from: a CDN, your own server, or embedded resources;
which library version those URLs point to;
the vendor licence key, for the suites that need one;
the default theme.

Every extension embeds a default file that loads the vendor's files from a public CDN, so a widget works out of the box. You only need a file of your own to change any of the above. That includes using a newer library version or setting a licence key, which most production applications need.

The configuration file

The file is named after the extension's namespace:

Extension	File name	Default source	Default version	Default theme
DevExtreme	`Wisej.Web.Ext.DevExtreme.json`	CDN	22.2.4	`material.blue.light`
Syncfusion EJ2	`Wisej.Web.Ext.Syncfusion2.json`	CDN	33.1.44	`material`
Syncfusion EJ1	`Wisej.Web.Ext.Syncfusion.json`	CDN	19.3.0.43	`flat-azure`
Kendo UI	`Wisej.Web.Ext.Kendo.json`	CDN	2023.1.117	`bootstrap-main`
Ignite UI	`Wisej.Web.Ext.Ignite.json`	CDN	`latest`	`infragistics`
Webix	`Wisej.Web.Ext.Webix.json`	CDN	`edge`	`webix`

The versions are the ones in the default files of the 4.1 extensions. To use another version, override the file and change the URLs.

Where the file is looked for

The extension uses the first file it finds, in this order:

A file in the application's root folder, next to Default.json. Remember to deploy it with the application.
An embedded resource in the application's main assembly whose name ends with .Wisej.Web.Ext.<Vendor>.json. To embed it, set the file's Build Action to Embedded Resource.
An embedded resource in the assembly of a derived widget, if you subclassed one of the widget classes in a library of your own.
The default file embedded in the extension.

If none is found, the widget throws Missing configuration file: Wisej.Web.Ext.<Vendor>.json.

The file is read once per application

The configuration is loaded the first time a widget needs it and then cached for the life of the application process. After changing the file, restart the application, for example by recycling the IIS application pool or restarting the Kestrel process.

tip

Start from the default file rather than from scratch. Download it below, or copy it from the extension's source, and change only what you need. The files accept // comments.

Structure

Wisej.Web.Ext.Syncfusion2.json
{
  // Which entry of "sources" to use: "cdn", "local" or "embedded".
  "source": "cdn",

  // Default theme, used when the static Theme property isn't set.
  "theme": "material",

  // Your Syncfusion licence key.
  "licenseKey": "",

  "sources": {
    "cdn": {
      "root": "https://cdn.syncfusion.com/ej2/33.1.44",
      "packages": {
        "jquery.js": "https://code.jquery.com/jquery-3.7.1.min.js",
        "ej2.js": "%root%/dist/ej2.min.js",
        "theme.css": "%root%/%theme%.css"
      }
    },
    "local": {
      "root": "Syncfusion2",
      "packages": {
        "ej2.js": "%root%/dist/ej2.min.js",
        "theme.css": "%root%/%theme%.css"
      }
    },
    "embedded": {
      "root": "resource.wx",
      "packages": {
        "ej2.js": "%root%/dist/ej2.min.js",
        "theme.css": "%root%/%theme%.css"
      }
    }
  }
}

Key	What it does
`source`	The name of the entry in `sources` to use. You can add entries of your own, for example a `"staging"` one.
`theme`	The theme loaded when the suite's static `Theme` property isn't set. See Themes.
`licenseKey`	The vendor licence key. DevExtreme, Syncfusion EJ2 and Kendo UI only. See Licence key.
`sources.<name>.root`	The base URL or folder, available as `%root%` in the package URLs.
`sources.<name>.packages`	The files to load, in order, as `"name": "url"` pairs. The names identify the files in the browser: a file is downloaded only once, however many widgets use it.

The package URLs can contain these placeholders:

Placeholder	Replaced with	Example
`%root%`	The `root` of the selected source	`https://cdn.syncfusion.com/ej2/33.1.44`
`%theme%`	The current theme	`material`
`%culture%`	The full name of the current culture	`de-DE`
`%locale%`	The two-letter language code of the current culture	`de`

note

The packages load in the order they're listed, so put dependencies first: jQuery before the libraries that need it, core scripts before modules.

Default files

These are the default files of the 4.1 extensions:

Wisej.Web.Ext.DevExtreme.json

Wisej.Web.Ext.Syncfusion2.json

Wisej.Web.Ext.Syncfusion.json

Wisej.Web.Ext.Kendo.json

Wisej.Web.Ext.Ignite.json

Wisej.Web.Ext.Webix.json

Licence key

The vendor licence is separate from Wisej.NET

The DevExpress, Syncfusion, Telerik, Infragistics and Webix components are commercial products. You need a licence from the vendor to use them, bought directly from the vendor, in addition to your Wisej.NET licence. See Licensing.

Recent releases of several suites also check a licence key in the browser and show a banner or watermark when it's missing. For the suites that support it, enter the key in the configuration file:

{
  "source": "cdn",
  "theme": "material",
  "licenseKey": "YOUR-LICENSE-KEY",
  ...
}

The wrapper registers it with the vendor's own API when the first widget is created in the browser:

Suite	Registered with	Where to get the key
DevExtreme	`DevExpress.config({ licenseKey })`	DevExpress licensing
Syncfusion EJ2	`ej.base.registerLicense(key)`	Syncfusion licensing
Kendo UI	`KendoLicensing.setScriptKey(key)`	Kendo UI licensing

Kendo UI can also take its key from a telerik-license.js script. The default Kendo file includes a commented-out package entry for it. Uncomment the entry and deploy the script. The Syncfusion EJ1, Ignite UI and Webix wrappers have no licenseKey setting. Follow the vendor's instructions for those suites.

Treat the key as visible

The licence key is sent to the browser, which is how the vendors designed it. Anyone using the application can read it. Use the key type the vendor issues for client-side deployment, never an account password or an API secret.

Put the file in the main assembly

To keep the key out of a loose file on the server, embed the configuration file in your application's main assembly: set its Build Action to Embedded Resource. See Where the file is looked for.

Themes

Each suite's base class has a static Theme property that sets the theme for all its widgets in the current session. When it isn't set, the extension uses the theme from the configuration file. The value replaces %theme% in the package URLs, so it must be a theme name the vendor actually publishes at that location.

C#
VB.NET

// DevExtreme: loads dx.material.teal.dark.css.
dxBase.Theme = "material.teal.dark";

// Syncfusion EJ2: loads fluent2.css.
ej2Base.Theme = "fluent2";

// Back to the theme in the configuration file.
kendoBase.Theme = null;

' DevExtreme: loads dx.material.teal.dark.css.
dxBase.Theme = "material.teal.dark"

' Syncfusion EJ2: loads fluent2.css.
ej2Base.Theme = "fluent2"

' Back to the theme in the configuration file.
kendoBase.Theme = Nothing

Changing the theme updates every widget of that suite in the session.

note

The vendor theme and the Wisej.NET theme are independent. Choose a vendor theme that sits well next to the Wisej.NET theme of your application, for example a Material vendor theme with a Material Wisej.NET theme, or a dark one with a dark one.

Localization

Each base class also has a static Culture property. It defaults to Application.CurrentCulture. Its value replaces %culture% and %locale% in the package URLs, so you can load the vendor's message and culture files for the user's language. It's also passed to the widgets themselves.

C#
VB.NET

dxBase.Culture = new CultureInfo("de-DE");   // loads dx.messages.de.js
kendoBase.Culture = new CultureInfo("it-IT"); // loads kendo.culture.it-IT.min.js

dxBase.Culture = New CultureInfo("de-DE")   ' loads dx.messages.de.js
kendoBase.Culture = New CultureInfo("it-IT") ' loads kendo.culture.it-IT.min.js

Changing the culture re-creates the widgets

Setting Culture re-creates every widget of that suite in the session, which loses any state that exists only in the browser, such as a scroll position or an unsaved edit. Set it once at startup, before the widgets are created.

Make sure the files for each culture you support exist at the URL the placeholders produce. Not every vendor publishes every language, and a missing file just leaves the texts in English.

Deployment

Choose the source with the source key of the configuration file.

CDN

The default. The browser downloads the vendor's files from the URLs in the file, usually the vendor's own CDN. There's nothing to deploy, but the browser must be able to reach the CDN.

tip

Use local or embedded for intranet applications without internet access, for applications with a strict Content Security Policy, and when you need to control exactly which version reaches your users.

Local

The vendor's files are served by your application. Copy the vendor's distribution into a folder of the application (by default named after the suite, for example Syncfusion2 or DevExtreme), keeping the folder structure the package URLs expect, and deploy it with the application.

Embedded

The vendor's files are compiled into an assembly as embedded resources and served through resource.wx, so nothing has to be copied to the server. Keep the folder structure the vendor ships, since the package URLs point into it.

Keep the files in step with the URLs

Whatever the source, the package URLs in the configuration file must match the files that are actually there. A wrong path doesn't show up until a widget loads, and then only as a 404 in the browser's network log and a widget that never appears. After changing the configuration, open the browser's developer tools and check that every package loads.

The configuration file​

Where the file is looked for​

Structure​

Default files​

Licence key​

Themes​

Localization​

Deployment​

CDN​

Local​

Embedded​