# Widget
Namespace: **Wisej.Web**
Assembly: **Wisej.Framework** (4.0.0.0)
* [Control](https://docs.wisej.com/api/wisej.web/general/control)
* [Widget](https://docs.wisej.com/api/wisej.web/content/widget)
Provides a generic widget that can use most third party javascript widgets.
{% tabs %}
{% tab title="C#" %}
```csharp
public class Widget : Control, IWisejHandler
```
{% endtab %}
{% tab title="VB.NET" %}
```visual-basic
Public Class Widget
Inherits Control
Implements IWisejHandler
```
{% endtab %}
{% endtabs %}
See the [InitScript](#initscript) property for a detailed description on how to initialize the imported widget.
## Constructors
###  Widget()
Initializes a new instance of the [Widget](https://docs.wisej.com/api/wisej.web/content/widget) class.
## Properties
###  BorderStyle
[BorderStyle](https://docs.wisej.com/api/wisej.web/enumerations/wisej.web.borderstyle): Indicates the border style for the control. (Default: `None`)
###  DefaultSize
[Size](https://docs.microsoft.com/dotnet/api/system.drawing.size): The default [Size](https://docs.microsoft.com/dotnet/api/system.drawing.size) of the control.
###  EnableNativeContextMenu
[Boolean](https://docs.microsoft.com/dotnet/api/system.boolean): Enables or disables the browser's context menu. (Default: `False`)
###  InitScript
[String](https://docs.microsoft.com/dotnet/api/system.string): Returns or sets the initialization script.
The initialization script is called after the widget is created and before it is rendered by the browser. It is here that the code should initialize the third party widget, hook up any event, and save any reference it may need. The initialization function is named "init" and must be declared like this:
```csharp
this.init = function(options)
{
// simple example on how to initialize
// an hypothetical widget.
$(this.container).widget(options);
// alternative example on how to
// initialize a widget that needs a specific
// child element.
this.container.innerHTML = "
$('#widget').widget(options);
}
```
The update function is named "update", it is optional, and must be declared like this:
```csharp
this.update = function(options, old)
{
// update the widget either using the
// changed options or by invoking specific methods.
$('#widget').widget(options);
}
```
The "options" parameter is optional. It contains a javascript map with all the options defined in the [Options](#options) property. Within the init function you can refer to the Wisej widget class using "this" and to the HTML element using "this.container". To fire an event back to the server, use "this.fireWidgetEvent() as show in the sample code below:
```csharp
this.init = function(options)
{
// add the onSelect handler to the initialization options
// to relay the client event back to the server side
// representation of the widget.
//
// The e.getId() and e.getText() are just examples, the values
// to send back to the server depend on the third party widget
// and the event specification.
var me = this;
options.onSelect = function(e) {
me.fireWidgetEvent("select", {id:e.getId(), text:e.getText()});
};
$(this.container).widget(options);
}
```
On the server side, you can handle the [WidgetEvent](https://docs.wisej.com/api/general/control#widgetevent) and receive any data passed in the "fireWidgetEvent" call in the [Data](https://docs.wisej.com/api/general/control/wisej.web.widgeteventargs#data) dynamic object.
###  Instance
[Object](https://docs.microsoft.com/dotnet/api/system.object): Returns a [DynamicObject](https://docs.microsoft.com/dotnet/api/system.dynamic.dynamicobject) that can convert any method call into the equivalent JavaScript call targeting the third party "widget" object.
An application can invoke any method on the wrapped third party widget by using the [Instance](#instance) property. Dynamic method calls are automatically transformed to JavaScript client calls.
```csharp
// invokes the setLineColor(color) JavaScript method
// on the third party chart widget.
this.chart1.Instance.setLineColor("red");
// to get a return value you can add either a callback function or
// use the Async version and await the result.
this.chart1.Instance.getSeriesCount((count) => { AlertBox.Show(count.ToString()); });
// all methods have the Async version registered automatically.
var count = await this.chart1.Instance.getSeriesCountAsync();
AlertBox.Show(count.ToString());
```
C# can also attach to client side events fired by the third party widget by simply adding an handler to the event name prefixed by "on". VB.NET cannot attach to dynamic events and must insted use the method [AddListener](#addlistener-eventname-handler-expression) to attach an event listener to an event fired by the widget.
```csharp
// listens to the "zoomChange" event fired by the widget.
this.chart1.Instance.onZoomChange += new WidgetEventHandler(this.chart1_OnZoomChange);
...
private void chart1_OnZoomChange(object sender, WidgetEventArgs e) {
}
```
###  IsLoaded
[Boolean](https://docs.microsoft.com/dotnet/api/system.boolean): Returns whether the JavaScript widget has been initialized.
###  Options
[Object](https://docs.microsoft.com/dotnet/api/system.object): Returns or sets a dynamic object that is passed to the init(options) function upon initialization of the widget and to the update(options, old) when updating the widget.
{% hint style="info" %}
The [Widget](https://docs.wisej.com/api/wisej.web/content/widget) class automatically detects changes to first level fields only. If your code changes a nested object you have to either call [Update](https://docs.wisej.com/api/general/control#update) or notify the [Options](#options) object that a property has changed like this:
{% endhint %}
```csharp
this.widget.Options.value = 10;
// no need to notify, value is a first level field.
this.widget.Options.toolbar.show = true;
// need to notify, show is a field of toolbar.
this.widget.Update();
// or
this.widget.Options.Notify("toolbar.show");
this.widget.Options.toolbar = new { show = true };
// no need to notify, we are setting toolbar.show but the assignment
// changes toolbar which is a first level field.
```
###  Packages
[List\](https://docs.microsoft.com/dotnet/api/system.collections.generic.list-1): List of packages required to run this widget.
Each package is a URL to either a JavaScript or a CSS file. The packages are loaded in the order they are listed. If a script depends on another script, it should be declared after the script it depends on, i.e.: Query usually if the first script in the package list. Wisej.NET uses the name of the package to cache it and load it only once. It's important that you use consistent names when creating multiple widgets in order to load the shared packages only once. You can preload the packages using [LoadPackages](https://docs.wisej.com/api/general/application#loadpackages-packages-callback) with the list of the packages and corresponding names to preload.
###  WiredEvents
[String\[\]](https://docs.microsoft.com/dotnet/api/system.string): Returns or sets the list of events that are fired by the widget wrapper.
Defines the list of events that the widget wrapper can fire. You have to add the code that handles the third party widget's events and fire a server event back to this widget wrapper. If your initialization code fires the event correctly and the event is registered in the [WiredEvents](#wiredevents) list, the application code can attach a listener to the dynamic [Instance](#instance) object like any native event.
```csharp
this.chart1.WiredEvents = new [] {"AreaClick"};
this.chart1.Instance.areaClick += new WidgetEventHandler(chart1_AreaClick);
private void chart1_AreaClick(object sender, WidgetEventArgs e) {
// event data is available at e.Data as a dynamic object.
var data = e.Data;
var x = data.x;
var y = data.y;
var name = data.name;
AlertBox.Show($"Clicked area {name} at {x}, {y}.");
}
```
For the sample code above to receive the "areaClick" event you have to handle the third party widget event and fire a Wisej event. The syntax for the handler registration depends on each wrapped third party widget: some may use native events, other may use third party libraries, and others may use callback methods.
```csharp
var me = this;
this.widget.addEventHandler("areaClick", function(e){
me.fireWidgetEvent("AreaClick", {name:a.areaName, x:e.xPos, y:e.yPos});
});
```
The list of the wired events that the server component expects to receive is available on the client side wrapper using the events array: this.getEvents(). Since 2.5.31 You can attach to the event without having to register it with the [WiredEvents](#wiredevents) collection when you prefix the handler with "on". i.e. this.Instance.onPointClick += new WidgetEventHandler(onPointClick). Wisej will try to attach to the "pointClick" event automatically removing the "on" prefix. When you attach the listener Wisej will automatically add it to the [WiredEvents](#wiredevents) collection. Additionally, instead of having to iterate the this.getEvents() collection in the widget's initScript, you can override "\_addListener", "\_removeListener", "\_getEventData".
```csharp
this._addListener = function(name, handler) {
this.widget.on(name, handler);
}
this._removeListener = function(name, handler) {
this.widget.off(name, handler);
}
this._getEventData = function(type, e, expression) {
if (type === "cellClick") {
return {row:e.rowIndex, column:e.colIndex};
}
}
```
## Methods
###  AddListener(eventName, handler, expression)
Registers the event *handler* to listen to the event *eventName* fired by the third party widget.
| Parameter | Type | Description |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| **eventName** | [String](https://docs.microsoft.com/dotnet/api/system.string) | Name of the event fired by the third party widget. |
| **handler** | [WidgetEventHandler](https://docs.wisej.com/api/wisej.web/general/control/wisej.web.widgeteventhandler) | Function that handles the event on the server side. |
| **expression**  | [String](https://docs.microsoft.com/dotnet/api/system.string) | Optional expression to process the event data: i.e. "{x:e.x, y:x.y}". |
VB.NET muse use this method to attach an event handler to the widget's events.
```csharp
Widget1.AddListener "zoomChanged", AddressOf Widget1_OnZoomChanged
Private Sub Widget1_OnZoomChanged(sender As Object, e As WidgetEventArgs)
End Sub
```
**Throws:**
* [ArgumentNullException](https://docs.microsoft.com/dotnet/api/system.argumentnullexception) *eventName* or *handler* is null.
###  GetResourceString(name)
Returns the content of the embedded resource.
| Parameter | Type | Description |
| --------- | ------------------------------------------------------------- | --------------------------------------------------- |
| **name** | [String](https://docs.microsoft.com/dotnet/api/system.string) | The fully qualified name of the embedded resource.. |
**Returns:** [String](https://docs.microsoft.com/dotnet/api/system.string).
###  GetResourceString(assembly, name)
Returns the content of the embedded resource.
| Parameter | Type | Description |
| ------------ | ---------------------------------------------------------------------------- | --------------------------------------------------- |
| **assembly** | [Assembly](https://docs.microsoft.com/dotnet/api/system.reflection.assembly) | Assembly with the embedded resource. |
| **name** | [String](https://docs.microsoft.com/dotnet/api/system.string) | The fully qualified name of the embedded resource.. |
**Returns:** [String](https://docs.microsoft.com/dotnet/api/system.string).
###  GetResourceURL(name)
Returns the URL to pass to the wisej loader to load the specified embedded resource.
| Parameter | Type | Description |
| --------- | ------------------------------------------------------------- | -------------------------------------------------- |
| **name** | [String](https://docs.microsoft.com/dotnet/api/system.string) | The fully qualified name of the embedded resource. |
**Returns:** [String](https://docs.microsoft.com/dotnet/api/system.string).
###  GetResourceURL(assembly, name)
Returns the URL to pass to the wisej loader to load the specified embedded resource.
| Parameter | Type | Description |
| ------------ | ---------------------------------------------------------------------------- | -------------------------------------------------- |
| **assembly** | [Assembly](https://docs.microsoft.com/dotnet/api/system.reflection.assembly) | Assembly with the embedded resource. |
| **name** | [String](https://docs.microsoft.com/dotnet/api/system.string) | The fully qualified name of the embedded resource. |
**Returns:** [String](https://docs.microsoft.com/dotnet/api/system.string).
###  OnLoad(e)
Raises the [Load](#load) event.
| Parameter | Type | Description |
| --------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| **e** | [EventArgs](https://docs.microsoft.com/dotnet/api/system.eventargs) | A [EventArgs](https://docs.microsoft.com/dotnet/api/system.eventargs) that contains the event data. |
###  OnWebEvent(e)
Processes the event from the client.
| Parameter | Type | Description |
| --------- | ------------------------------------------------------------------------------ | ---------------- |
| **e** | [WisejEventArgs](https://docs.wisej.com/api/wisej.core/general/wisejeventargs) | Event arguments. |
###  OnWebRender(config)
Renders the client component.
| Parameter | Type | Description |
| ---------- | ------------------------------------------------------------- | ----------------------------- |
| **config** | [Object](https://docs.microsoft.com/dotnet/api/system.object) | Dynamic configuration object. |
###  OnWebRequest(e)
Fires the [WebRequest](#webrequest) event.
| Parameter | Type | Description |
| --------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **e** | [WebRequestEventArgs](https://docs.wisej.com/api/wisej.web/content/widget/wisej.web.webrequesteventargs) | A [WebRequestEventArgs](https://docs.wisej.com/api/wisej.web/content/widget/wisej.web.webrequesteventargs) that contains the event data. |
###  RemoveListener(eventName, handler)
Removes the event *handler* for the *eventName* fired by the third party widget.
| Parameter | Type | Description |
| ------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| **eventName** | [String](https://docs.microsoft.com/dotnet/api/system.string) | Name of the event fired by the third party widget. |
| **handler** | [WidgetEventHandler](https://docs.wisej.com/api/wisej.web/general/control/wisej.web.widgeteventhandler) | Function that handles the event on the server side. |
**Throws:**
* [ArgumentNullException](https://docs.microsoft.com/dotnet/api/system.argumentnullexception) *eventName* or *handler* is null.
## Events
###  Load
[EventHandler](https://docs.microsoft.com/dotnet/api/system.eventhandler) Fired when the widget is created on the client.
###  WebRequest
[WebRequestHandler](https://docs.wisej.com/api/wisej.web/content/widget/wisej.web.webrequesthandler) Fired when the widget used the "postbackUrl" to retrieve data from this control.
## Implements
| Name | Description |
| ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| [IUserData](https://docs.wisej.com/api/wisej.web/interfaces/wisej.web.iuserdata) | Provides access to the `UserData` and `Tag` properties associated to the component implementing this interface. |
| [IBindableComponent](https://docs.wisej.com/api/wisej.web/data-binding/wisej.web.ibindablecomponent) | Bindable components implement this interface. |
| [IDropTarget](https://docs.wisej.com/api/wisej.web/interfaces/wisej.web.idroptarget) | Controls that support drag & drop operations implement this interface. |
| [IWisejComponent](https://docs.wisej.com/api/wisej.core/interfaces/wisej.core.iwisejcomponent) | All wisej components implement this interface. |
| [IWisejControl](https://docs.wisej.com/api/wisej.core/interfaces/wisej.core.iwisejcontrol) | All wisej controls derived from the [Control](https://docs.wisej.com/api/wisej.web/general/control) class must implement this interface. |
| [IWisejHandler](https://docs.wisej.com/api/wisej.core/interfaces/wisej.core.iwisejhandler) | Represents a Wisej component that is capable of handling postback requests from the client. |
| [IWisejSerializable](https://docs.wisej.com/api/wisej.core/interfaces/wisej.core.iwisejserializable) | Allows an object to serialize itself. |
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.wisej.com/api/wisej.web/content/widget.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.