ALS

Class: BaseWidget

.ALS.Widgets. BaseWidget

new BaseWidget(type, id, label, callbackObject, callback, events)

Base class for all widgets.

This class should be used only to create custom widgets. It shouldn't be used in application itself.

See L.ALS.Widgets docs for the example on working with Widgetables and Widgets.

Guidelines on creating custom widgets:

  1. You'll probably need to have a prior knowledge of how widgets works. Please, study the widgets' markup and existing widgets' source code. Yup, that sucks but there's no good workaround.
  2. As an alternative, you can build your widget from scratch, though, it's not recommended. If you choose to do so, please, use ALS classes in your elements to maintain consistency.
  3. Widgets layout is being created at L.ALS.Widgets.BaseWidget#toHtmlElement method. Compose your widget here.
  4. There're couple of useful methods for composing widgets, such as L.ALS.Widgets.BaseWidget#createLabel, L.ALS.Widgets.BaseWidget#createInputElement, etc. Use it to simplify your workflow.
  5. If you want to modify those helper methods, you can either override them or change something at L.ALS.Widgets.BaseWidget#toHtmlElement. Do whatever works better for you.
  6. You can safely remove either input or label from your widget by simply not creating it.
  7. Setters and other public methods should return this, so API users can chain it.
Parameters:
Name Type Description
type string

Type of input
id string

ID of this input. You can select this object using this ID.
label string

Label for this input. Pass locale property to localize the label.
callbackObject Object | L.ALS.Serializable

Object which contains callback. Just pass "this". If you plan to use serialization, this object MUST be instance of L.ALS.Serializable.
callback string

Name of the method of callbackObject that will be called when widget's value changes
events Array.<string>

Array of event's names to bind to the provided callback

Extends

Members

<protected> constructorArguments :Array.<any>

Contains arguments passed to this constructor

Type:
  • Array.<any>
Inherited From:

<protected> container :HTMLDivElement

Container of this widget

Type:
  • HTMLDivElement

<protected> containerForRevertButton :Element

Container to place revert button to. Used by the settings.

Type:
  • Element

<protected, readonly> customContainerClassName

Custom classname for a widget container.

<protected, readonly> customWrapperClassName

Custom classname for an input wrapper. Alternative to setting classname at L.ALS.Widgets.BaseWidget#createContainer manually.

<readonly> id

This widget's ID

<protected> input :HTMLElement

Input element controlled by this widget

Type:
  • HTMLElement

<protected> serializationIgnoreList :Array.<string>

Contains properties that won't be serialized. Append your properties at the constructor.

Type:
  • Array.<string>
Inherited From:

<readonly> undoable

Indicates whether this widget can revert back to its default value. If this widget is undoable, an undo button will be appended to it at settings window.

wrapLabel

Indicates whether this widgets label should be wrapped when it's too wide. Wrapping might affect how your widget displays. Test it with both short labels and long labels.

Methods

callCallback()

Calls callback attached to this widget

Warning: Callback will be called only when widget will be added to the widgetable! Util that all calls will be paused.

Returns:
Type
VoidFunction

<protected> createContainer()

Creates container for this widget

Returns:

Container for this widget

Type
HTMLDivElement

<protected> createInput()

Creates input element. If you're creating different element, override createInputElement() instead of this.

Returns:

Input element

Type
HTMLElement

<protected> createInputElement()

Creates input element. You can also create non-input elements here.

Use it only to create input element. To add input element at L.ALS.Widgets.BaseWidget#toHtmlElement, use L.ALS.Widgets.BaseWidget#createInput

Returns:

Input element

Type
HTMLElement

<protected> createLabel()

Creates label for this widget

Returns:

Label

Type
HTMLLabelElement

getEnabled()

Returns:

True, if this widget is enabled. False otherwise.

Type
boolean

getLabelText()

Returns:

Text of the label of this widget or locale property (if set)

Type
string

getObjectToSerializeTo(newObject, seenObjects)

Registers this object for serialization and deserialization. Returns an object to serialize custom properties to.

Call it first, if you implement your own algrorithm, and serialize to the returned object!

Parameters:
Name Type Description
newObject Object

Object to where you'll serialize
seenObjects Object

Already seen objects
Inherited From:
Returns:

Object to serialize to.

Type
Object

getValue()

Returns:

Value of this widget

Type
*

<protected> onChange(event)

Being called when user changes this widget. Override it to add your functionality like validation.

Default implementation just returns true.

Parameters:
Name Type Description
event Event

Event fired by input
Returns:

If true, the attached callback will be called.

Type
boolean

serialize(seenObjects)

Serializes this object to JSON. If overridden, you MUST perform following operations before returning JSON:

let json = {} // Your JSON
... // Perform serialization
json.constructorArguments = this.serializeConstrutorArguments(); // Serialize constructor arguments
json.serializableClassName = this.serializableClassName; // Add class name to JSON
return json; // Finally return JSON
Parameters:
Name Type Description
seenObjects Object

Already seen objects
Inherited From:
Returns:

This serialized object

Type
Object

serializeConstructorArguments()

Serializes constructor arguments. If your constructor is not empty, result of this method MUST be added to json at L.ALS.Serializable#serialize as "_construtorArgs" property.

Deprecated in favor of L.ALS.Serializable#getObjectFromSerialized which uses this function under-the-hood.

Inherited From:
Deprecated:
  • Yes
Returns:

Serialized constructor arguments

Type
Array

setConstructorArguments(args)

Sets constructor arguments for serialization

Parameters:
Name Type Description
args

Arguments to set
Inherited From:

setEnabled(isEnabled)

Sets whether this widget should be enabled or not

Parameters:
Name Type Description
isEnabled boolean
Returns:

This

Type
L.ALS.Widgets.BaseWidget

setLabelText(text)

Sets label text

Parameters:
Name Type Description
text string

Text to set. Pass locale property to localize the label.
Returns:

This

Type
L.ALS.Widgets.BaseWidget

setValue(value)

Sets value of this widget.

Parameters:
Name Type Description
value *

Value to set
Returns:

This

Type
L.ALS.Widgets.BaseWidget

shouldIgnoreEvent(event)

Whether ALS should ignore given event. If returns true, both L.ALS.Widgets.BaseWidget#onChange and (L.ALS.Widgets.BaseWidget#callCallback) won't be called, and none of the input's attributes will change. event.preventDefault() won't be called though.

Useful for precise control over your widget's behavior. For example, if your widget doesn't behave correctly when working with keyboard, here you can detect which actions shouldn't affect your widget.

You can also use event.preventDefault() here.

Parameters:
Name Type Description
event Event

Event that should be passed or ignored.
Returns:

True, if event should be skipped.

Type
boolean

<protected> toHtmlElement()

Builds this widget, i.e. creates container and puts label and input here.

Default implementation is:

let container = this.createContainer();
container.appendChild(this.createLabel());
container.appendChild(this.createInput());
return container;
Returns:

HTML representation of this widget

Type
HTMLDivElement