Introduction

Aimagin Connect is a framework developed by Aimagin for creating web applications using drag-and-drop components or widgets. Aimagin has already created a few basic components that all users can use to build their web applications. However, mostly, these are more general and standard HTML components to build web pages. For the advanced users these components might not be enough to build their expectation into a web application. Therefore we from Aimagin won't let anyone stop from their imagination and we allow user to create their own elements which they can import to Aimagin Connect and use whenever user want to use them.

 

Creating a custom component for Aimagin Connect is a little complicated. If users want to create a component, they need to have basic web programming knowledge (HTML, CSS, JavaScript, JQuery and etc) to build components. However, in this document, we are going to teach how to create custom components for Aimagin Connect.

Required Software(Optional)

Any JavaScript editing software would be beneficial for the user to troubleshoot, formatting and build the code.

Let's Get Started!

First, lets familiar the HTML structure when creating a web pages

Hello, World!

This is a paragraph of text.

 

First, check these sample component files

aimagin_connect-component.js - this example has 4 dummy components in two main categorizes.

aimagin_connect-buitin-component-example.js - this example has 14 dummy components categorized into 4 sections

aimagin_connect-editbox.js - this example has only one component under a main category named as Forms

 

Note: aimagin_connect-component.js and aimagin_connect-buitin-component-example.js are just dummy formatting files for the user to know syntax and standard functions we used to call from Aimagin Connect

JavaScript file format explain

In this section, the custom component file format will be described in detail where the user can import for the Aimagin Connect.

 

ID

Description: ID is used to define the ID of the package.

Variable type: String

 

Example:

ID="_my_package"

 

Package

Description: Custom components are defined in this variable.

Variable type:  Object

 

Object Names(aka Keys) and descriptions.

name - name of the package.

text - text that shows on the Aimagin Connect for the package.

children - id of the children component.

object - user can add functions and callbacks under this section but user can also leave this section empty as well.

         //explain object what we can do like reduce the code......

 

 

Example:

PACKAGE[ID] = {

   name:"name",

   text:"text",

  children:["Folder1"],

   object:{

       //functions and callbacks can be typed here not necessary to put all the functions and callbacks under here.

       setProperty:function(e) {

           console.log("e.id",e.id);

           document.getElementById(e.id)[e.key] = e.value;            

       },

       getProperty:function(e) {

           console.log(e);

           return document.getElementById(e.id)[e.key];

       }

   }    

};

 

Component/s can be placed directly under the Package or can add multiple sub_folder/s in the Package. ID of the component can be used to put directly under the children, if the user doesn't want to have any folder/s or sub_folder/s. If the user wants to have multiple main folders id of the folder can be mentioned under the children array(["Folder1", "Folder2"]).

 

Adding folder/s, sub_folders and component object for the package

Example code under this is a continuation of create_package_example code. This example code has a child named as Folder1, and in here we are going to add another sub_folder named as SubFolder1. and place two empty components inside the SubFolder1.

Variable type:  Object

 

Object Names(aka Keys) and descriptions.

name - name of the package this will be the text that displayed on the Aimagin Connect.

text - text that shows on the tooltip when the mouse is hovering on the folder or sub_folder.

children - (Folder and Subfolder)id of the child component this can be either component object id or folder id.

(Component) true or false depend on whether another component drag and drop into the creating component in the Aimagin Connect tree design.

parameter - Component parameter objects are defined here. Details will be described in here.

callback - Component callback functions are defined in here. Details will be described in here.

write_head_init - function that will be called to create a component. It must return a string and the string will be written in the <head> section. It is used in cases where there is special js/css to initialize if there is a component type. Many of the same write_head_init Will be called only once.

write_body_start - function that will be called to create a component. It must return a string and the string will be written in the <body> section, opening the tag if this component has The child tag will be written further.

write_body_end - function that will be called to create a component. It must return a string and the string will be written in the <body> section to close the tag. If this component has children write_body_start and write_body_end The child's will be called first. When finished, close the parent tag.

write_body_init - function that will be called to create a component. It must return a string and the string will be written at the end of <body> for use in cases with js. Special /css to initialize if there are multiple components of the same type. write_body_init Will be called only once.

add_body_script - function will be converted to string and placed inside the <script> tag before </body>. This function does not have a return and is used for controlling changes. The web app structure is the only function that will be executed directly when the web page is loaded.

 

Check given example files(aimagin_connect-component.js, aimagin_connect-buitin-component-example.js, aimagin_connect-editbox.js) to take some idea about writing "write_head_init", "write_body_start", "write_body_end", "write_body_init", "add_body_script". All "write_head_init", "write_body_start", "write_body_end", "write_body_init", "add_body_script" functions has a parameter "e". "e" is a object which have these parameters bellow

e = {

   id: "id",

   type: "type",

   name: "name",

   level: "0",

   "property": {

       "parameter": {

           "Custom": {}

       },

       "callback": {},

       "connection": {}

   },

   children: []

}

 

Example:

PACKAGE.Folder1 = {

name:"Folder1",

text:"Folder1_tooltip",

children:["SubFolder1"]

};

PACKAGE.SubFolder1 = {

name:"SubFolder1",

text:"SubFolder1_tooltip",

children:["Component1","Component2"]

};

PACKAGE.Component1 = {

   name:"Component1", text:"Component1_tooltip", children:false,

   parameter:[],

   callback:[],

   write_head_init:function(e){return ``;},

   write_body_start:function(e){return ``;},

   write_body_end:function(e){return ``;},

   add_body_script:function(e){ }

};

PACKAGE.Component2 = {

   name:"Component2", text:"Text field", children:false,

   parameter:[],

   callback:[],

   parameter:[],

   callback:[],

   write_head_init:function(e){return ``;},

   write_body_start:function(e){return ``;},

   write_body_end:function(e){return ``;},

   add_body_script:function(e){ }

};

 

Parameters

Description: Here is where the users set the component parameters so that anyone can change it's properties.

Variable type:  Object

 

Object Names(aka Keys) and descriptions.

name - name of the parameter.

text - text that shows on the tooltip when the mouse is hovering on parameter. This is usable to add any hint what to enter in the parameter properties.

input - parameter input is an object which has type(input field, dropdown, multi-select dropdown, color, checkbox, and custom) and value(default value). Input types will be discussed in detailed in here

setParameter - setParameter

getParameter - getParameter

 

Example:

  parameter:[

       {

           name:"Label",

           text:"Label_tooltip",

           input:{

               type:"0",

               value:"Label"

           },

           setParameter:function (e) {

           },

           getParameter:function (e) {

           }

       },

       {

           name:"LabelSize",

           text:"Label size(in pixels)",

           input:{

               type:"0",

               value:17

           },

           setParameter:function (e) {

           },

           getParameter:function (e) {

           }

       }

   ],

example codes provided here can be replaced parameter:[].

 

Input types

Input types have 6 different categories that where user can assign to the component properties.

1.type:"0" is input field

2.type:"1" is dropdown

3.type:"2" is multi-select dropdown

4.type:"3" is color

5.type:"4" is checkbox

6.type:"custom" is for customize inputs

 

type:"0" is input field

This will allow user to add input text fields to customize their component. Example code in here can be replaced parameter:[].

Example:

parameter:[

{

name:"Label",

text:"Label_tooltip",

input:{

type:"0",

value:"Label"

},

setParameter:function (e) {

},

getParameter:function (e) {

}

},

],

 

type:"1" is dropdown

This will allow user to add a dropdown to customize their component. Example code in here can be replaced parameter:[].

Example:

parameter:[

{

name:"Type",

text:"Type_tooltip",

input:{

type:"1",

option:[

{value:"text", text:"text"},

{value:"password", text:"password"},

{value:"number", text:"number"}

],

value:"text"

},

setParameter:function (e) {

},

getParameter:function (e) {

}

},

],

 

type:"2" is multi-select dropdown

This will allow user to add a multi-select dropdown to customize their component. Example code in here can be replaced parameter:[].

Example:

parameter:[

{

name:"Text style",

text:"Text_style_tooltip",

input:{

type:"2",

option:[

{value:"Bold", text:"Bold"},

{value:"Italic", text:"Italic"},

{value:"Underline", text:"Underline"}

],

value:""

},

setParameter:function (e) {

},

getParameter:function (e) {

}

},

],

 

type:"3" is color

This will allow user to add a color select option to customize their component. Example code in here can be replaced parameter:[].

Example:

parameter:[

{

name:"background color",

text:"background_color_tooltip",

input:{

type:"3",

value:"#fff"

},

setParameter:function (e) {

},

getParameter:function (e) {

}

}

],

 

type:"4" is checkbox

This will allow user to add a checkbox option to customize their component. Example code in here can be replaced parameter:[].

Example:

parameter:[

{

name:"Visible",

text:"Visible_tooltip",

input:{

type:"4",

value:true

},

setParameter:function (e) {

},

getParameter:function (e) {

}

}

],

 

type:"custom" is for customize inputs

This will allow the user to add customized input for their component. This is a bit advanced process where the user has to write the code to open a window to see what customized input needs to be like. Example code in here can be replaced parameter:[]. There are two additional parameters that the user has to define in custom types, open & save. Open function will be called when the user checks the edit button on the parameters. Save function will execute whenever the user clicks on the save button on the opening window. Check the functionality of the example code it will open a window with a button and when the button is clicked it will append an input field to the window. Saving button will change the component value with an array object of values of input fields.

Example:

parameter:[

{

name:"Custom",

text:"Custom_properties_tooltip",

input:{

type:"custom",

value:{},

open:function(e) {

let div = document.createElement('div');

let button = document.createElement('button');

button.classList.add("btn", "btn-secondary");

button.innerHTML = "Add";

 

let table = document.createElement("table");

table.classList.add("table", "table-bordered", "table-condensed", "table-hover");

let tbody = document.createElement("tbody");

table.appendChild(tbody);

button.onclick = function(e) {

let tr = document.createElement("tr");

let input = document.createElement("input");

input.classList.add("form-control");

let td = document.createElement("td");

td.appendChild(input);

tr.appendChild(td);

tbody.appendChild(tr);

};

 

div.appendChild(button);

div.appendChild(table);

e.container.appendChild(div);

 

//load values back when open

if(e.value.length>0){

e.value.forEach((el,index) => {

let tr = document.createElement("tr");

let input = document.createElement("input");

input.classList.add("form-control");

input.value = el;

let td = document.createElement("td");

td.appendChild(input);

tr.appendChild(td);

tbody.appendChild(tr);

});

}

},

save:function(e){

let array_of_labels = [];

if (e.container.querySelectorAll(".form-control").length>0){

e.container.querySelectorAll(".form-control").forEach(el => {

array_of_labels.push(el.value);

});

}

return array_of_labels;

},

},

setParameter:function (e) {

},

getParameter:function (e) {

}

}

],

When the Edit button is clicked a new window will open to configure.

Add button will append input fields to the window. Save button will save the input field values as an array.

 

setParameter

The function under setParameter will be called when parameters are set. They are called when the web page is created and when changes are made from the callback

setParameter:function(e) {

/*

In e there will be

e.id = id of element

e.key = name of parameter

e.value = is the value that is set

e.previousValue is the value before it was changed.

e.object = object of the package folder is a function to use.

*/

//your code has to enter here depend on the requirement

}

 

getParameter

The function under getParameter will be called when a parameter is asked for a return value. This is usually done via a callback.

getParameter:function(e) {

/*

In e there will be

e.id = id of element

e.key = name of parameter

e.object = object of the package folder is a function to use.

*/

return //your return value need to enter here;

}

 

Callback

Description: Callback accepts two members, Groups and Callbacks. Group is like a grouping folder for the callback and the callbacks can be placed inside the groups.

Variable type: Array of objects

Object Names(aka Keys) and descriptions.

name - name of the group or the callback.

text - text that shows on the tooltip when the mouse is hovering on the group or the callback.

children - children[array of objects] used to store other groups or callbacks

setCallback - Function to called when parameters are set. It is called when the web page is created and when the callback is changed.

 

example codes provided here can be replaced callback:[].

Example:

callback:[

{"name":"callback-group", "text":"callback-group-1", "children":[

{"name":"callback1.1", "text":"callback1.1_tooltip", "setCallback":function(e) {

 document.getElementById(e.id).onchange = e.value; //this is an example for a event triggers for a click

}},

{"name":"callback1.2", "text":"callback1.2_tooltip", "setCallback":function(e) {}}                

]},

{"name":"callback2.1", "text":"callback2.1_tooltip", "setCallback":function(e) {}}

],

Additional information

libraries that can be used to build any component

•bootstrap 4.3.1

•d3.js 5.12.0

•fontawesome 5.11.2 Free only regular and solid icons. Details can be found at https://fontawesome.com/icons?d=gallery&s=regular,solid&m=free

•jquery 3.4.1

•plotly.js 1.50.1

Tips

Components with ability to add children:

component object children should be true. Otherwise user cannot drag and drop any other components to the custom component that created. Picture bellow will show how the two versions will show on the Aimagin Connect

First one allows to drag and drop any other components on to the Component1 and the HTML structure will automatically created how the user has written on the "write_body_start" and "write_body_end".

 

How to import component to aimagin connect

This topic is explained in - How to import a custom component