# JSWebComponent ## Overview `JSWebComponent` provides a wrapper for creating and managing web components in the Solution Model. It extends the `JSComponent` model and allows developers to define custom behaviors, attributes, and design-time properties. Web components are essential for building dynamic, responsive forms in web-based Servoy applications. ## Functionality JSWebComponent includes properties such as `cssPosition` and `anchors` for defining layout behaviors, making it adaptable to resizing and responsive designs. Visibility, dimensions, and coordinates can be controlled via properties like `x`, `y`, `width`, `height`, and `visible`. The `typeName` property identifies the type of web component, as defined in the specification file. Methods such as `getAttribute`, `setJSONProperty`, and `getHandler` provide tools for managing attributes, design-time properties, and event handlers. These methods enable dynamic configuration and integration of web components into forms. Utilities like `getAttributes` and `getUUID` facilitate introspection and metadata access. JSWebComponent supports both design-time and runtime modifications, allowing components to be customized during development or adjusted dynamically at runtime. For more details, refer to the [RuntimeWebComponent](https://docs.servoy.com/reference/servoycore/dev-api/forms/runtimeform/elements/runtimewebcomponent) section of this documentation. ## **Extends** [JSComponent](https://docs.servoy.com/reference/servoycore/dev-api/solutionmodel/jscomponent) ## Properties Summarized | Type | Name | Summary | | ------------------------------------------------------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------- | | [Number](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/number) | [anchors](#anchors) | Enables a component to stick to a specific side of form and/or to grow or shrink when a window is resized. | | [CSSPosition](https://docs.servoy.com/reference/servoycore/dev-api/application/cssposition) | [cssPosition](#cssposition) | CSS position is a replacement for anchoring system making it more intuitive to place a component. | | [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean) | [enabled](#enabled) | The enable state of the component, default true. | | [Number](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/number) | [formIndex](#formindex) | The Z index of this component. | | [Number](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/number) | [height](#height) | The height in pixels of the component. | | [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) | [name](#name) | The name of the component. | | [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) | [typeName](#typename) | The webcomponent type (name from the spec). | | [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean) | [visible](#visible) | The visible property of the component, default true. | | [Number](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/number) | [width](#width) | The width in pixels of the component. | | [Number](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/number) | [x](#x) | The x coordinate of the component on the form. | | [Number](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/number) | [y](#y) | The y coordinate of the component on the form. | ## Methods Summarized | Type | Name | Summary | | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------- | | [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object) | [getAttribute(name)](#getattribute-name) | Get the value of an attribute of the element. | | [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array) | [getAttributes()](#getattributes) | Returns the attribute names of an element. | | [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) | [getComment()](#getcomment) | Returns the comment of this component. | | [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object) | [getDesignTimeProperty(key)](#getdesigntimeproperty-key) | Get a design-time property of an element. | | [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array) | [getDesignTimePropertyNames()](#getdesigntimepropertynames) | Get the design-time properties of an element. | | [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) | [getFormName()](#getformname) | Returns the name of the form. | | [JSMethod](https://docs.servoy.com/reference/servoycore/dev-api/solutionmodel/jsmethod) | [getHandler(handlerName)](#gethandler-handlername) | Returns the JSMethod handler with the given name. | | [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object) | [getJSONProperty(propertyName)](#getjsonproperty-propertyname) | Get the design-time value of the given property. | | [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array) | [getJSONPropertyNames(includeAll)](#getjsonpropertynames-includeall) | Get the list of property names this component supports. | | [UUID](https://docs.servoy.com/reference/servoycore/dev-api/application/uuid) | [getUUID()](#getuuid) | Returns the UUID of this component. | | [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean) | [isJSONPropertySet(propertyName)](#isjsonpropertyset-propertyname) | Returns whatever the design-time value of the given property was set. | | [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object) | [putDesignTimeProperty(key, value)](#putdesigntimeproperty-key-value) | Set a design-time property of an element. | | [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) | [removeAttribute(name)](#removeattribute-name) | Remove the attribute of an element. | | [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object) | [removeDesignTimeProperty(key)](#removedesigntimeproperty-key) | Clear a design-time property of an element. | | void | [resetHandler(handlerName)](#resethandler-handlername) | Similar to resetJSONProperty but for handlers. | | void | [resetJSONProperty(propertyName)](#resetjsonproperty-propertyname) | Reset the design-time value of the given property. | | void | [setAttribute(name, value)](#setattribute-name-value) | Set the attribute value of an element. | | void | [setHandler(handlerName, method)](#sethandler-handlername-method) | Set the JSMethod handler for the given handler name. | | void | [setJSONProperty(propertyName, value)](#setjsonproperty-propertyname-value) | Set the design-time value for the given property. | ## Properties Detailed ### anchors Enables a component to stick to a specific side of form and/or to\ grow or shrink when a window is resized. If opposite anchors are activated then the component with grow or\ shrink with the window. For example if Top and Bottom are activated,\ then the component will grow/shrink when the window is vertically\ resized. If Left and Right are activated then the component\ will grow/shrink when the window is horizontally resized. If opposite anchors are not activated, then the component will\ keep a constant distance from the sides of the window which\ correspond to the activated anchors. **Type**\ [Number](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/number) The anchor configuration for the component. **Sample** ```js var form = solutionModel.newForm('mediaForm', 'db:/example_data/parent_table', null, false, 400, 300); var strechAllDirectionsLabel = form.newLabel('Strech all directions', 10, 10, 380, 280); strechAllDirectionsLabel.background = 'red'; strechAllDirectionsLabel.anchors = SM_ANCHOR.ALL; var strechVerticallyLabel = form.newLabel('Strech vertically', 10, 10, 190, 280); strechVerticallyLabel.background = 'green'; strechVerticallyLabel.anchors = SM_ANCHOR.WEST | SM_ANCHOR.NORTH | SM_ANCHOR.SOUTH; var strechHorizontallyLabel = form.newLabel('Strech horizontally', 10, 10, 380, 140); strechHorizontallyLabel.background = 'blue'; strechHorizontallyLabel.anchors = SM_ANCHOR.NORTH | SM_ANCHOR.WEST | SM_ANCHOR.EAST; var stickToTopLeftCornerLabel = form.newLabel('Stick to top-left corner', 10, 10, 200, 100); stickToTopLeftCornerLabel.background = 'orange'; stickToTopLeftCornerLabel.anchors = SM_ANCHOR.NORTH | SM_ANCHOR.WEST; // This is equivalent to SM_ANCHOR.DEFAULT var stickToBottomRightCornerLabel = form.newLabel('Stick to bottom-right corner', 190, 190, 200, 100); stickToBottomRightCornerLabel.background = 'pink'; stickToBottomRightCornerLabel.anchors = SM_ANCHOR.SOUTH | SM_ANCHOR.EAST; ``` ### cssPosition CSS position is a replacement for anchoring system making it more intuitive to place a component.\ CSS position should be set on form, an absolute position form can either work with anchoring or with css position.\ This is only working in NGClient. **Type**\ [CSSPosition](https://docs.servoy.com/reference/servoycore/dev-api/application/cssposition) The CSS position of the component. **Sample** ```js var label = form.newLabel('Label', -1); label.cssPosition.r("10").b("10").w("20%").h("30px") ``` ### enabled The enable state of the component, default true. **Type**\ [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean) True if the component is enabled; false otherwise. **Sample** ```js var form = solutionModel.newForm('printForm', 'db:/example_data/parent_table', null, false, 400, 300); var field = form.newField('parent_table_text', JSField.TEXT_FIELD, 10, 10, 100, 20); field.enabled = false; ``` ### formIndex The Z index of this component. If two components overlap, then the component with higher Z index is displayed above the component with lower Z index. **Type**\ [Number](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/number) The Z-index of the component. **Sample** ```js var labelBelow = form.newLabel('Green', 10, 10, 100, 50); labelBelow.background = 'green'; labelBelow.formIndex = 10; var fieldAbove = form.newField('parent_table_text', JSField.TEXT_FIELD, 10, 10, 100, 30); fieldAbove.background = '#FF0000'; fieldAbove.formIndex = 20; ``` ### height The height in pixels of the component. **Type**\ [Number](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/number) The width of the component in pixels. **Sample** ```js var field = form.newField('parent_table_text', JSField.TEXT_FIELD, 10, 10, 100, 20); application.output('original width: ' + field.width); application.output('original height: ' + field.height); field.width = 200; field.height = 100; application.output('modified width: ' + field.width); application.output('modified height: ' + field.height); ``` ### name The name of the component. Through this name it can also accessed in methods.\ Must be a valid javascript name. (no - in the name or start with number) **Type**\ [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) The name of the component. **Sample** ```js var form = solutionModel.newForm('someForm', 'db:/example_data/parent_table', null, false, 620, 300); var label = form.newLabel('Label', 10, 10, 150, 150); label.name = 'myLabel'; // Give a name to the component. forms['someForm'].controller.show() // Now use the name to access the component. forms['someForm'].elements['myLabel'].text = 'Updated text'; ``` ### typeName The webcomponent type (name from the spec). **Type**\ [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) the type name of the web component, as defined in the specification file. **Sample** ```js var wc = form.getWebComponent('mycomponent'); application.output(bean.typeName); ``` ### visible The visible property of the component, default true. **Type**\ [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean) True if the component is visible; false otherwise. **Sample** ```js var form = solutionModel.newForm('printForm', 'db:/example_data/parent_table', null, false, 400, 300); var field = form.newField('parent_table_text', JSField.TEXT_FIELD, 10, 10, 100, 20); field.visible = false; ``` ### width The width in pixels of the component. **Type**\ [Number](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/number) The width of the component in pixels. **Sample** ```js var field = form.newField('parent_table_text', JSField.TEXT_FIELD, 10, 10, 100, 20); application.output('original width: ' + field.width); application.output('original height: ' + field.height); field.width = 200; field.height = 100; application.output('modified width: ' + field.width); application.output('modified height: ' + field.height); ``` ### x The x coordinate of the component on the form. **Type**\ [Number](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/number) **Sample** ```js var field = form.newField('parent_table_text', JSField.TEXT_FIELD, 10, 10, 100, 20); application.output('original location: ' + field.x + ', ' + field.y); field.x = 90; field.y = 90; application.output('changed location: ' + field.x + ', ' + field.y); ``` ### y The y coordinate of the component on the form. **Type**\ [Number](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/number) The Y-coordinate position of the component. **Sample** ```js var field = form.newField('parent_table_text', JSField.TEXT_FIELD, 10, 10, 100, 20); application.output('original location: ' + field.x + ', ' + field.y); field.x = 90; field.y = 90; application.output('changed location: ' + field.x + ', ' + field.y); ``` ## Methods Detailed ### getAttribute(name) Get the value of an attribute of the element. **Parameters** * [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **name** the name of the attribute **Returns:** [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object) The value of the specified attribute. **Sample** ```js var frm = solutionModel.getForm('orders') var fld = frm.getField('fld') var attributes = fld.getAttributes(); for (var i = 0; i < attributes.length; i++) { application.output(fld.getAttribute(attributes[i])); } ``` ### getAttributes() Returns the attribute names of an element. **Returns:** [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array) An array of attribute names for the component. **Sample** ```js var frm = solutionModel.getForm('orders') var fld = frm.getField('fld') var attributes = fld.getAttributes(); for (var i = 0; i < attributes.length; i++) { application.output(fld.getAttribute(attributes[i])); } ``` ### getComment() Returns the comment of this component. **Returns:** [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) the comment associated with this component. **Sample** ```js var comment = solutionModel.getForm("my_form").getButton("my_button").getComment(); application.output(comment); ``` ### getDesignTimeProperty(key) Get a design-time property of an element. **Parameters** * [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **key** the name of the property **Returns:** [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object) The value of the specified design-time property. **Sample** ```js var frm = solutionModel.getForm('orders') var fld = frm.getField('fld') var prop = fld.getDesignTimeProperty('myprop') ``` ### getDesignTimePropertyNames() Get the design-time properties of an element. **Returns:** [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array) An array of design-time property names for the component. **Sample** ```js var frm = solutionModel.getForm('orders') var fld = frm.getField('fld') var propNames = fld.getDesignTimePropertyNames() ``` ### getFormName() Returns the name of the form. (may be empty string as well) **Returns:** [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) The name of the form containing the component. **Sample** ```js var name = myElement.getFormName(); ``` ### getHandler(handlerName) Returns the JSMethod handler with the given name. **Parameters** * [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **handlerName** the name of the handler to get **Returns:** [JSMethod](https://docs.servoy.com/reference/servoycore/dev-api/solutionmodel/jsmethod) the JSMethod handler associated with the specified handler name. **Sample** ```js var wc = form.getWebComponent('mycomponent'); var handler = wc.getHandler(JSWebComponent.mypackage.mycomponent.onActionMethodID); ``` ### getJSONProperty(propertyName) Get the design-time value of the given property. If the value was never set and\ the component has default value for the give property, that value will be returned.\ To check if the value was set, use isJSONPropertySet. **Parameters** * [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **propertyName** the name of the property to get **Returns:** [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object) the design-time value of the specified property, or the default value if not set. **Sample** ```js var wc = form.getWebComponent('mycomponent'); application.output(wc.getJSONProperty(JSWebComponent.mypackage.mycomponent.mytext)); // will output a string value if present for a string typed property application.output(wc.getJSONProperty(JSWebComponent.mypackage.mycomponent.mynumber)); // getter will return a number if present application.output(JSON.stringify(wc.getJSONProperty(JSWebComponent.mypackage.mycomponent.mycustomtype), null, ' ')); // getter returns an object if present for custom types is spec files application.output(JSON.stringify(wc.getJSONProperty(JSWebComponent.mypackage.mycomponent.myarray), null, ' ')); // getter returns an array type if present for array types application.output(JSON.stringify(wc.getJSONProperty(JSWebComponent.mypackage.mycomponent.myfoundset), null, ' ')); // getter returns an object representing the design settings of the given property if present //In case you want to change a more complex property (e.g. tabs) obtained with getJSONProperty, setJSONProperty must be used: var tabs = jsTabPanel.getJSONPRoperty(JSWebComponent.bootstrapcomponents.tabpanel.tabs); tabs[0].containsFormId = jsForm; jsTabPanel.setJSONProperty(JSWebComponent.bootstrapcomponents.tabpanel.tabs, tabs); ``` ### getJSONPropertyNames(includeAll) Get the list of property names this component supports.\ It can return all properties specified in spec file or only the properties that are set in json. **Parameters** * [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean) **includeAll** whether to return all properties from specification file or only the ones that are set in json **Returns:** [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array) an array of property names supported by the web component. Includes all properties or only set properties based on the includeAll parameter. **Sample** ```js var wc = form.getWebComponent('mycomponent'); application.output(wc.getJSONPropertyNames(true)); // will output all property names from the spec file application.output(wc.getJSONPropertyNames(false)); // will output all property names that are set in component json ``` ### getUUID() Returns the UUID of this component. **Returns:** [UUID](https://docs.servoy.com/reference/servoycore/dev-api/application/uuid) the UUID of this component. **Sample** ```js var button_uuid = solutionModel.getForm("my_form").getButton("my_button").getUUID(); application.output(button_uuid.toString()); ``` ### isJSONPropertySet(propertyName) Returns whatever the design-time value of the given property was set. **Parameters** * [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **propertyName** the name of the property to check **Returns:** [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean) true if the specified property is explicitly set, otherwise false. **Sample** ```js var wc = form.getWebComponent('mycomponent'); var isSet = wc.isJSONPropertySet(JSWebComponent.mypackage.mycomponent.mytext); // returns false wc.setJSONProperty(JSWebComponent.mypackage.mycomponent.mytext, 'Hello World Extended!'); isSet = wc.isJSONPropertySet(JSWebComponent.mypackage.mycomponent.mytext); // returns true ``` ### putDesignTimeProperty(key, value) Set a design-time property of an element. Value should be primitive data (string, boolean or number).\ Complex values should be stringified before call. **Parameters** * [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **key** the name of the property * [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object) **value** the value to store **Returns:** [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object) The previous value of the specified design-time property, or null if none existed. **Sample** ```js var frm = solutionModel.getForm('orders') var fld = frm.getField('fld') fld.putDesignTimeProperty('myprop', 'strawberry') ``` ### removeAttribute(name) Remove the attribute of an element. **Parameters** * [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **name** the name of the attribute **Returns:** [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) the deleted attribute value **Sample** ```js var frm = solutionModel.getForm('orders') var fld = frm.getField('fld') fld.removeAttribute('keylistener') ``` ### removeDesignTimeProperty(key) Clear a design-time property of an element. **Parameters** * [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **key** the name of the property **Returns:** [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object) The removed value of the specified design-time property. **Sample** ```js var frm = solutionModel.getForm('orders') var fld = frm.getField('fld') fld.removeDesignTimeProperty('myprop') ``` ### resetHandler(handlerName) Similar to resetJSONProperty but for handlers. **Parameters** * [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **handlerName** the name of the handler to reset **Returns:** void **Sample** ```js var wc = form.getWebComponent('mycomponent'); // form is extending another form who's 'onActionMethodID' does something nice wc.setHandler(JSWebComponent.mypackage.mycomponent.onActionMethodID, form.getMethod('onCoolerAction')); // hmm, I changed my mind - I like 'nice' action better wc.resetHandler(JSWebComponent.mypackage.mycomponent.onActionMethodID); ``` ### resetJSONProperty(propertyName) Reset the design-time value of the given property.\ This makes it as if it was never set. It can be useful when working with form inheritance. **Parameters** * [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **propertyName** the name of the property to reset **Returns:** void **Sample** ```js var wc = form.getWebComponent('mycomponent'); // form is extending another form who's 'mycomponent' has property 'mytext' set to something... wc.setJSONProperty(JSWebComponent.mypackage.mycomponent.mytext, 'Hello World Extended!'); // hmm I changed my mind - I like simple 'Hello World' better wc.resetJSONProperty(JSWebComponent.mypackage.mycomponent.mytext); ``` ### setAttribute(name, value) Set the attribute value of an element. **Parameters** * [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **name** the name of the attribute * [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **value** the value of the attribute **Returns:** void **Sample** ```js var frm = solutionModel.getForm('orders') var fld = frm.getField('fld') fld.setAttribute('keylistener', 'callback') ``` ### setHandler(handlerName, method) Set the JSMethod handler for the given handler name. The handlerName is checked for existence in the component spec file, if the component does not declare this handler, an error is thrown.\ If the handler is already set, it will be replaced with the new JSMethod. **Parameters** * [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **handlerName** the name of the handler to get * [JSMethod](https://docs.servoy.com/reference/servoycore/dev-api/solutionmodel/jsmethod) **method** the JSMethod to attach to the handler (can be also JSMethod that has arguments) **Returns:** void **Sample** ```js var wc = form.getWebComponent('mycomponent'); wc.setHandler(JSWebComponent.mypackage.mycomponent.onActionMethodID, form.getMethod('onAction')); ``` ### setJSONProperty(propertyName, value) Set the design-time value for the given property. For primitive property types you can just set the value.\ For more complex property types you can set a JSON value similar to what would be generated in the .frm file if you would design what you need using editor/properties view.\ Some property types can be assigned values in the runtime accepted format (for example border, font typed properties have a string representation at runtime and here as well). **Parameters** * [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **propertyName** the name of the property to set * [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object) **value** the new value of the property **Returns:** void **Sample** ```js var wc = form.getWebComponent('mycomponent'); wc.setJSONProperty(JSWebComponent.mypackage.mycomponent.mytext, 'Hello World!'); wc.setJSONProperty(JSWebComponent.mypackage.mycomponent.mynumber, 1); wc.setJSONProperty(JSWebComponent.mypackage.mycomponent.myborder, 'LineBorder,1,#ccffcc'); wc.setJSONProperty(JSWebComponent.mypackage.mycomponent.mydynamicfoundset, { dataproviders: { dp1: "city", dp2: "country" }, foundsetSelector: "" }); // foundset property type using // the parent form's foundset and providing two columns of the foundset to client; see foundset property type wiki page for more information ``` ***