The SQL List component allows listing data from a table query to a list. This is very useful for specific functions such as transferring data from a table to another or ordering correctly the data of a table, among many other utilities.

1 Introduction

1.1 What is it?

SQL List is the Axional funtionality for listing the data of a table the way we want. It can contain information of a record, in addition to an avatar and/or actions. It can also have the drag and drop funtionality implemented to transfer data from a table to another.

1.2 What can I do?

Basically, SQL List allows you to:

Display data from a table (title and one or two subtitles)
Display an avatar of the record
Create actions that interact with the data of the table (not implemented yet)
Transfer data from different lists with Drag and Drop implementation
Order data from a table with Drag and Drop implementation

1.3 What do I need?

SQL List requires the basic Axional Studio infrastructure, which includes:

Axional Studio Server, properly set up.
Dictionary database
A target database

The previous configuration is explained in detail under the Axional Studio/Installation block.

2 Architecture

2.1 Structure

2.2 Dictionary tables

SQL List component involves two parameterization tables:

SQL List definition (wic_jrep_box_sqllist)
Drag and Drop definition (wic_jrep_box_draganddrop)

SQL List component only requires always the table wic_jrep_box_sqllist; It will be explained when is necessary to use the wic_jrep_box_draganddrop table below.

2.2.1 SQL List definition

wic_jrep_box_sqllist
Label	Description
Box id	Unique identifier of the celldata box.
Title	Column that has the information to show as the title of each item in SQL List.
Subtitle 1	Column that contains the information to show as first subtitle of each item.
Subtitle 2	Column that contains the information to show as second subtitle of each item.
Avatar	Column that contains the url or base64 image to show as item avatar.
SQL Statement	SQL query with the result set that will be shown on the SQL List.

2.2.2 Drag and Drop implementation

When the SQL List has to implement Drag and Drop, it will be necessary the use of wic_jrep_box_draganddrop table.

wic_jrep_box_draganddrop
Label	Description
Box id	Unique identifier of the celldata box.
Source box id	Unique identifier of the source box.
Allow drag	UEL Expression to determine if a record from the source box can be dragged to the SQL List.
Drop statement	Script written in XSQL Script or Javascript to determine what happens when a record is dropped in the SQL List.

3 Implementation

The following section shows how to create an SQL List step by step. It starts by a simple SQL List in the first section, and keep on explaining more situations in further sections.

The SQL List component is defined by one entity:

SQL List definition (wic_jrep_box_sqllist)

The former defined the list, getting the data of a query to fill in the fields in each row of tle list.

3.1 Create SQL Lists

3.1.1 Define the SQL Statement

To begin, the query is created where the data will be obtained to fill the list, and that is done with an SQL statement.

3.1.2 Define the list parameters

Next, the following parameters will be indicated:

Title
Subtitle 1 (not required)
Subtitle 2 (not required)
Avatar (not required)

Title

The Title contains the more important column of the query. Is is always required and must be a column of the SQL Statement.

Subtitle 1/ Subtitle 2

The subtitles contain the secondary information of the record. It is not required and must be a column of the SQL Statement.

Avatar

The Avatar contains the url or the base64 of the image that will be shown like avatar. It is not required and must be a column of the SQL Statement.

After these steps, the following result will be obtained:

3.2 Allow Drag and Drop between SQL Lists

Once having a SQL List created, it can be determined if this list accept draggable rows from another lists.

3.2.1 Define Drag and Drop parameters

To start defining our drag and drop implementation on actual SQL List, the following values will be indicated:

Source box id
Allow drag

Source box id

The Source box id contains the id of the box from which the drag and drop will be made to our list. It is always required.

Allow drag

The Allow drag contains an UEL Expression that will determine whether apply to drag the record from the source list to actual list. It is always required and can contain record columns or parent record columns.

3.2.2 Define XSQL/JS Drop statement

By last, the script to be executed when a record is dropped from the list of the source box id will be defined. This script can be written with two languages, XSQL Script or Javascript.

These variables can be used on the script to accomplish our objective:

source_memo
source_record
target_record

source_memo

source_memo contains the box code (mnemonic) of the source box.

source_record

source_record contains a JSON with the data of the source record.

target_record

target_record contains a JSON with the data of the target record.

4 Samples

The following section presents a set of samples with the most interesting cases of uses of Axional Studio SQL List component:

4.1 Lists to arrange medical checks of employees

4.1.1 Introduction

This sample shows hot to implement two SQL List for arrange medical checks of the employees of a company.

The current sample is based on the following data structure:

As observed, the first two tables are practically identical with only one difference, the second table has order column because this will be used to determine the medical check schedule. The third table is an auxiliary table to obtain the avatar image of the employees.

The following SQL List shows the content of the first table (the second table is initially empty):

4.1.2 Create SQL Lists

Define the SQL Statement

The SQL Statement for the first list is the following:

Copy

<select>
    <columns>
        studio_employees_trx1.*,
        studio_employees_trx1.first_name || ' ' || studio_employees_trx1.last_name name,
        studio_employees_avatar.avatar
    </columns>
    <from table='studio_employees_avatar'>
        <join table='studio_employees_trx1'>
            <on>studio_employees_trx1.emp_no = studio_employees_avatar.emp_no</on>
        </join>
    </from>
</select>

It is important to select all the columns of the table (besides the ones that will be shown in the list) because to implement the drag and drop this data will be necessary.

And the SQL Statement for the second list is the following:

Copy

<select>
    <columns>
        studio_employees_trx2.*,
        studio_employees_trx2.first_name || ' ' || studio_employees_trx2.last_name name,
        TO_CHAR(TO_DATE(CONCAT("09:", TO_CHAR(studio_employees_trx2.order)), "%H:%M"), "%R") check_time,
        studio_employees_avatar.avatar
    </columns>
    <from table='studio_employees_trx2'>
        <join table='studio_employees_avatar'>
            <on>studio_employees_trx2.emp_no = studio_employees_avatar.emp_no</on>
        </join>
    </from>
    <order>studio_employees_trx2.order</order>
</select>

check_time column will be used to indicate the medical check schedule of each employee. To set itself, it will feed from the order column.

To obtain the proper functioning, it is necessary to indicate a column that determines the order of the list, in this case the column order.

Define the list parameters

The SQL list parameterization for the first list consists of:

Column	Value
Name	name
Subtitle 1
Subtitle 2
Avatar	avatar

In this case subtitles won't be shown because additional information is not necessary.

And the SQL list parameterization for the second list consists of:

Column	Value
Name	name
Subtitle 1	check_time
Subtitle 2
Avatar	avatar

In this case a subtitle will be added to show the medical check schedule of each employee.

4.1.3 Allow Drag and Drop between SQL Lists

For the operation of the lists to be suitable, these conditions must be met:

Employees from first list can be dropped applying order to second list
Employees from second list can be sorted
Employees from second list can be dropped to first list (without applying order)

For each one of these conditions a drag and drop implementation will be created.

Employees from first list can be dropped applying order to second list

Define Drag and Drop parameters

The drag and drop parameterization for that case consists of:

Column	Value
Source box id	First list box id
Allow drag	1==1

The Allow drag condition will always be true because all the records of the list can be dragged.

Define XSQL/JS Drop statement

In this case, the Drop statement will be written in XSQL Script.

The Drop Statement of the drag and drop implementation for the first list is the following:

Copy

<call>
	<args>
		<arg>${source_record}</arg>
		<arg>${target_record}</arg>
	</args>
<![CDATA[
<xsql-script>
	<args>
		<arg name="p_source_record" type="string" />
		<arg name="p_target_record" type="string" />
	</args>
	<body>
	    <!-- AVOID AVATAR ERROR -->
	    <set name="m_start_index"><string.find><p_source_record /><string>, name</string></string.find></set>
        <set name="m_end_index"><string.find><p_source_record /><string>rowid</string></string.find></set>
        <set name="p_source_record"><string><string.substring><p_source_record />0<add><m_start_index />2</add></string.substring><string.substring><p_source_record /><m_end_index /></string.substring></string></set>
        <if>
            <expr>
                <gt><string.length><p_target_record /></string.length>2</gt>
            </expr>
            <then>
                <set name="m_start_index"><string.find><p_target_record /><string>, name</string></string.find></set>
                <set name="m_end_index"><string.find><p_target_record /><string>rowid</string></string.find></set>
                <set name="p_target_record"><string><string.substring><p_target_record />0<add><m_start_index />2</add></string.substring><string.substring><p_target_record /><m_end_index /></string.substring></string></set>
            </then>
        </if>
        
	    <!-- INIT VARS -->
	    <set name="m_source_record"><json.parse><p_source_record /></json.parse></set>
	    <set name='m_target_record'><json.parse><p_target_record /></json.parse></set>
	    <set name="m_emp_no"><number.intValue><json.get name="emp_no"><m_source_record /></json.get></number.intValue></set>
	    <set name="m_json_null">deister.webstudio.core.util.json.JSONObject$Null</set>
	    <set name="target_emp_no"><ifthen><isnotnull><json.get name="emp_no"><m_target_record /></json.get></isnotnull><number.intValue><json.get name="emp_no"><m_target_record /></json.get></number.intValue><null /></ifthen></set>
	    
	    <!-- DELETE SOURCE RECORD FROM SOURCE TABLE -->
	    <delete table="studio_employees_trx1">
	        <where>emp_no = <m_emp_no /></where>
	    </delete>

        <!-- PARSE RECORD COLUMNS -->
        <if>
            <expr>
                <isnotnull>
                    <target_emp_no />
                </isnotnull>
            </expr>
            <then>
                <select prefix='m_'>
                    <columns>
                        order
                    </columns>
                    <from table='studio_employees_trx2' />
                    <where>
                        emp_no = <target_emp_no />
                    </where>
                </select>
            </then>
            <else>
                <set name='m_order'>-2</set>
            </else>
        </if>
        <set name="m_order"><add><m_order />1</add></set>
        <set name="m_first_name"><ifthen><eq><variable.typeof><json.get name="first_name"><m_source_record /></json.get></variable.typeof><m_json_null /></eq><null /><json.get name="first_name"><m_source_record /></json.get></ifthen></set>
		<set name="m_last_name"><ifthen><eq><variable.typeof><json.get name="last_name"><m_source_record /></json.get></variable.typeof><m_json_null /></eq><null /><json.get name="last_name"><m_source_record /></json.get></ifthen></set>
		<set name="m_gender"><ifthen><eq><variable.typeof><json.get name="gender"><m_source_record /></json.get></variable.typeof><m_json_null /></eq><null /><json.get name="gender"><m_source_record /></json.get></ifthen></set>
		<set name="m_state"><ifthen><eq><variable.typeof><json.get name="state"><m_source_record /></json.get></variable.typeof><m_json_null /></eq><null /><json.get name="state"><m_source_record /></json.get></ifthen></set>
		
		<!-- INSERT SOURCE RECORD TO DESTINY TABLE -->
		<insert table="studio_employees_trx2">
		    <column name="emp_no"><m_emp_no /></column>
		    <column name="order"><m_order /></column>
		    <column name="first_name"><m_first_name /></column>
		    <column name="last_name"><m_last_name /></column>
		    <column name="gender"><m_gender /></column>
		    <column name="state"><m_state /></column>
	    </insert>
	    
	    <!-- UPDATE ORDER COLUMN -->
	    <set name='i'>0</set>
	    <foreach>
	        <select prefix='studio_employees_trx2_'>
	            <columns>*</columns>
	            <from table='studio_employees_trx2' />
	            <order>order</order>
	        </select>
	        <do>
	            <update table='studio_employees_trx2'>
	                <column name='order'><i /></column>
	                <where>emp_no = <studio_employees_trx2_emp_no /></where>
	            </update>
	            <set name='i'><add><i />5</add></set>
	        </do>
	    </foreach>
	</body>
</xsql-script>
]>
</call>

In a simplified way, the script will execute the following steps:

Step	Explanation
Avoid avatar error	Currently there are problems parsing the JSON that we receive, that is why this part of the code is responsible for preventing exceptions from occurring
Init vars	Parse received JSONs and get the Primary Keys of the records
Delete source record from source table	Delete the dragged record from the first table
Parse record columns	With the help of target record set the correct order of the dragged record, and parse the other information of the record
Insert source record to destiny table	Insert the dragged record to the second table
Update order column	To show the correct medical check schedule of employees, it is necessary to update the order of the columns in the second table

As you can see, the implementation of drag and drop with XSQL Script is quite complex.

Employees from second list can be sorted

Define Drag and Drop parameters

The drag and drop parameterization for that case consists of:

Column	Value
Source box id	Second list box id
Allow drag	1==1

The Allow drag condition will always be true because all the records of the list can be sorted.

Define XSQL/JS Drop statement

In this case, the Drop statement will be written in Javascript.

The Drop Statement of the drag and drop implementation for the first list is the following:

Copy

<script :source_record :target_record>
    // INIT VARS
    var srcEmpNo = {
        emp_no : source_record.emp_no 
    },
        srcRecord = {
        emp_no      : source_record.emp_no,
        first_name  : source_record.first_name,
        last_name   : source_record.last_name,
        gender      : source_record.gender,
        state       : source_record.state
    };
    
	// DELETE SOURCE RECORD FROM SOURCE TABLE
	Ax.db.delete("studio_employees_trx2", srcEmpNo);

	// INSERT SOURCE RECORD TO DESTINY TABLE
	if ('emp_no' in target_record) {
	    var targetOrder = Ax.db.executeGet(`SELECT order FROM studio_employees_trx2 WHERE emp_no = ${target_record.emp_no}`);
	    srcRecord.order = targetOrder + 1;
	} else {
	    srcRecord.order = -1;
	}
	Ax.db.insert("studio_employees_trx2", srcRecord);
	
	// UPDATE ORDER COLUMN
	var rs = Ax.db.executeQuery(
        "SELECT * FROM studio_employees_trx2 ORDER BY order"
    );
    var i = 0;
    for (var row of rs) {
        row.order = i;
        Ax.db.insertOrUpdate("studio_employees_trx2", row);
        i = i + 5;
    }
</script>

In a simplified way, the script will execute the following steps:

Step	Explanation
Init vars	Get the Primary Key of the record and create a record with the necessary information to drop
Delete source record from source table	Delete the sorted record from actual table
Insert source record to destiny table	With the help of target record set the correct order of the dragged record, and insert the sorted record to actual table
Update order column	To show the correct medical check schedule of employees, it is necessary to update the order of the columns in actual table

Unlike in the previous case, the implementation of drag and drop with javascript is much simpler and easier to prepare.

Employees from second list can be dropped to first list (without applying order)

Define Drag and Drop parameters

The drag and drop parameterization for that case consists of:

Column	Value
Source box id	Second list box id
Allow drag	1==1

The Allow drag condition will always be true because all the records of the list can be dragged.

Define XSQL/JS Drop statement

In this case, the Drop statement will be written in Javascript.

The Drop Statement of the drag and drop implementation for the first list is the following:

Copy

<script :source_record>
    // INIT VARS
    var srcEmpNo = {
        emp_no : source_record.emp_no 
    },
        srcRecord = {
        emp_no      : source_record.emp_no,
        first_name  : source_record.first_name,
        last_name   : source_record.last_name,
        gender      : source_record.gender,
        state       : source_record.state
    };
    
	// DELETE SOURCE RECORD FROM SOURCE TABLE
	Ax.db.delete("studio_employees_trx2", srcEmpNo);
	
	// UPDATE ORDER COLUMN FROM SOURCE TABLE
	var rs = Ax.db.executeQuery(
        "SELECT * FROM studio_employees_trx2 ORDER BY order"
    );
    var i = 0;
    for (var row of rs) {
        row.order = i;
        Ax.db.insertOrUpdate("studio_employees_trx2", row);
        i = i + 5;
    }

	// INSERT SOURCE RECORD TO DESTINY TABLE
	Ax.db.insert("studio_employees_trx1", srcRecord);
</script>

In a simplified way, the script will execute the following steps:

Step	Explanation
Init vars	Get the Primary Key of the record and create a record with the necessary information to drop
Delete source record from source table	Delete the dragged record from the second table
Update order column from source table	To show the correct medical check schedule of employees, it is necessary to update the order of the columns in the second table table
Insert source record to destiny table	Insert the sorted record to the first table

In this case, the order does not have to be controlled when inserting in the first table, but the order of the second table must be updated once a record on this table has been deleted.

4.1.4 Execution

Once SQL lists are defined and also drag and drop implementations, the lists are prepared to meet the objectives set, as seen in the following video: