Skip to content

CodeCoupler UI Widget

Basics

A Widget can be created with the method widget(definition) which is available in all System, Stage, Application and Widget instances. These instance we call "parent instances". A widget is therefore always assigned to a parent instance.

A widget will be initialized within a container element. The container element itself will not be touched. Instead, one or two more elements are created within the container. By default two elements will be created. The first one will provide a custom scroller and the second is just a plain div. This inner div is the element which can be used to implement the widget interface.

The scroll functionality guarantees the widget to use the entire width and height of the inner div and the container to keep its dimensions. This is a basic principle that should be retained: the container defines the dimensions.

Default Structure:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
+--------------------------------------------------------------------------+
|                                                                          |
|  This is the container defined in the definition argument.               |
|  Accessible over env.container or env.$container                         |
|                                                                          |
|  +--------------------------------------------------------------------+  |
|  |                                                                    |  |
|  | div.cc-widget-container                                            |  |
|  | Container in where the PerfectScrollbar will be initialized.       |  |
|  | Accessible over env.scroll or env.$scroll                          |  |
|  | height: 100%; width: 100%; position: relative; overflow: hidden;   |  |
|  |                                                                    |  |
|  |  +--------------------------------------------------------------+  |  |
|  |  |                                                              |  |  |
|  |  | div                                                          |  |  |
|  |  | Here is the place where the widget will be initialized.      |  |  |
|  |  | Accessible over env.element or env.$element                  |  |  |
|  |  | min-height: 100%; min-width: 100%;                           |  |  |
|  |  |                                                              |  |  |
|  |  +--------------------------------------------------------------+  |  |
|  |                                                                    |  |
|  +--------------------------------------------------------------------+  |
|                                                                          |
+--------------------------------------------------------------------------+

The argument env contains the properties container, scroll and element to access the single elements. The properties $container, $scroll and $element are the jQuery counterparts. Normally you should not manipulate the container and the scroll element. The scroll element can be used to scroll your widget. You can use here plain JavaScript DOM methods scrollTop and scrollLeft.

If the scroll container is actually not needed, the widget can announce this via a static property ui. In this case the inner div will get the style overflow: "hidden"; height: "100%"; width: "100%". This guarantees the container to keep its dimensions.

Structure without Scroller:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
+------------------------------------------------------------------------+
|                                                                        |
|  This is the container defined in the definition argument.             |
|  Accessible over env.start.stage.element or  $element                  |
|                                                                        |
|  +------------------------------------------------------------------+  |
|  |                                                                  |  |
|  | div                                                              |  |
|  | Here is the place where the widget will be initialized.          |  |
|  | Accessible over env.element or env.$element                      |  |
|  | height: 100%; width: 100%; position: relative; overflow: hidden; |  |
|  |                                                                  |  |
|  +------------------------------------------------------------------+  |
|                                                                        |
+------------------------------------------------------------------------+

Vue Widget

In addition to the JavaScript-based widget, you can also create a Vue-based widget. In this case you have to provide a Vue application which will be instantiated.

You have to specify if the Vue application use a single root template or not. Depending ob this the inner div is the root element (this.$el) of your application or just a parent container:

Single root Vue application:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
+------------------------------------------------------------------------+
|                                                                        |
|  The parent containers and all styles will be                          |
|  constructed like with JavaScript-based widgets                        |
|                                                                        |
|  +------------------------------------------------------------------+  |
|  |                                                                  |  |
|  | Root element of your Vue template                                |  |
|  | env.element or env.$element are not available                    |  |
|  |                                                                  |  |
|  +------------------------------------------------------------------+  |
|                                                                        |
+------------------------------------------------------------------------+

Multiple root Vue application:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
+------------------------------------------------------------------------+
|                                                                        |
|  The parent containers and all styles will be                          |
|  constructed like with JavaScript-based widgets                        |
|                                                                        |
|  +------------------------------------------------------------------+  |
|  |                                                                  |  |
|  | div                                                              |  |
|  | Accessible over env.element or env.$element                      |  |
|  |                                                                  |  |
|  |  Multiple root elements of your Vue template:                    |  |
|  |  +------------------------------------------------------------+  |  |
|  |  |                                                            |  |  |
|  |  +------------------------------------------------------------+  |  |
|  |  +------------------------------------------------------------+  |  |
|  |  |                                                            |  |  |
|  |  +------------------------------------------------------------+  |  |
|  |  +------------------------------------------------------------+  |  |
|  |  |                                                            |  |  |
|  |  +------------------------------------------------------------+  |  |
|  |                                                                  |  |
|  +------------------------------------------------------------------+  |
|                                                                        |
+------------------------------------------------------------------------+

Create a Widget

To create a widget you have to specify the definition which is an an object with the following properties:

container

HTMLElement or jQuery Object

This is the container where the widget structure will be build. The container itself will be not touched. All additional elements will be created inside of this container.

id

String (Optional, Default: Random String)

An unique id that represents the widget instance. You cannot create two widgets with the same id on the same parent instance. If you do not specify an id a random id will be used. You should always use an id if you need to access the widget instance over the property widgets which is avaliable in all parent instances.

type

String (Optional, Default: "widget")

Can be widget, vue, vue-sr or vue-mr. It specify the type of the widget class which can be a plain JavaScript Widget class or a Vue application.

widget

Class or Vue

The widget class or widget vue application to instantiate.

options

Object

Options which should be passed on to the widget.

fullvisible

Callback Function (Optional)

Function which will be called to determine if the widget is visible. This will be chained with the fullvisible callback function of the parent instance.

The Widget Class

If you want to write an own widget you have to write a class that extends the CodeCoupler class Widget. The class have to provide an async method named init.

1
2
3
4
5
6
7
import { Widget } from "@codecoupler/cc-ui";
export default class extends Widget {
  async init(env, options) {
    //Write your code here
    //Do with env.element or env.$element whatever you want
  }
}

Optionally you can define a static property ui. You should use the following syntax to keep your code Future-proof in the case that the ui property receives additional properties:

1
2
3
4
5
6
7
8
9
import { Widget } from "@codecoupler/cc-ui";
export default class extends Widget {
  static ui = Object.assign({}, super.ui, {
    scroll: false,
  });
  async init(env, options) {
    //Write your code here
  }
}

For now you can only define if the widget need a scrollbar with the property scroll:

scroll

Boolean

1
Set to `false` if you do not need a scrolling container.