HOWTO Working with forms in Lianja
by
, 2022-06-10 at 06:35 (51477 Views)
Lianja provides the ability to visually create forms that will run on Desktop, Web and Mobile devices.
If you come from a VFP background this is the equivalent of the VFP form designer.
You can visually build forms that use any of the following scripting languages as the Lianja UI framework is scripting language independent across Desktop, Web and Mobile Apps.
- LianjaScript/VFP
- Python
- JavaScript
- Typescript
This article builds a form that uses Python as its scripting language.
Forms are based on a tabview section which contains canvas, grid or webview based sections in its tabs.
Forms can be displayed as a modal or non modal dialog.
Forms can optionally contain (attribute settings in the TabView):
- A menubar
- A toolbar
- An actionbar
- A statusbar
Creating a new form
You can create a new form from the "Home" workspace::
or alternatively from the "Develop menu":
or from the "Command window" or the "Command" workspace by typing using the CLI:
The form will be created in its own App as a TabView section with one Canvas section Tab. You can then add other Canvas, Grid, or Webview based sections to it.Code:create form [<form_name>]
Once the new form is created you should specify the scripting language that you want to use for the delegates in the form:
You can then add new "Tabs" to the form by clicking on the "+" icon in the TabView TabBar.
Note that you can "Hide TabBar" in the TabView attributes and programatically show Tab Panels programatically (typically from the menubar or the toolbar) e.g.
Modifying an existing form
You can modify an existing form from the "Component/Form Manager":
or from the "Command window" or the "Command" workspace by typing:
The lifecycle of a formCode:modify form [<form_name>]
During development you customize the forms and activate them by clicking the "Desktop App View" icon:
In code, Forms are activated (made visible) using Lianja.showForm():
When a form is activated the initform delegate is called. This is where you can open a database and its tables and dynamically create the menubar and the toolbar.Code:Lianja.showForm("Window title", "component:/mycomponents/form_name") or Lianja.showForm("Window title", "app:/form_name/form_name") or Lianja.showForm("Window title", "form_name") which activates "app:/form_name/form_name" or Lianja.showForm("form_name") which activates "app:/form_name/form_name" with the default window title
In this delegate thisform references the form itself.
You can reference the menubar, toolbar and actionbar like this:
Creating the menubar dynamicallyCode:thisform.menubar thisform.toolbar thisform.actionbar
The quickest way to layout the Menubar is to assign a layout string to the menubarlayout property like this:
Note that a menuitem may also have an icon associated with it. e.g.Code:thisform.menubarlayout = "File(Open...,Save),Reports(Customers,Orders,Order Details)"
lib:/images/mycustomersicon.png@Customers
When you click a menuitem the menubarclick delegate of the form is called with the fullpath of the menuitem clicked. The fullpath is a | separated list.
e.g
"Reports|Customers|Save as XML..."
You can hide and show the menubar dynamically using:
Creating the Toolbar dynamicallyCode:thisform.menubar = 1 or thisform.menubar = 0
The quickest way to layout the Toolbar is to assign a layout string to the toolbarlayout property like this:
When an icon is clicked the "Tooltip" e.g. "Customers" is passed as an argument to the toolbarclick delegate.Code:thisform.toolbarlayout = "lib:/images/mycustomobersicon.png@Customers,lib:/images/myordersicon.png@Orders"
You can hide and show the toolbar dynamically using:
Hiding and showing the Actionbar dynamicallyCode:thisform.toolbar = 1 or thisform.toolbar = 0
You can hide and show the actionbar dynamically using:
This is typically done in the toolbarclick delegate as you hide and show Tabs of the TabView container in the Form.Code:thisform.actionbar = 1 or thisform.actionbar = 0
Referencing UI controls dynamically
You can dynamically reference UI controls in the Form like this:
You dynamically reference UI elements in the Form by by objectname using:Code:otabview = thisform.controls( 1 )
When referencing objects by name you should use the fully qualified name e.g. "page1.section1.field1". All objects in the form and its child containers will be introspected and an object reference to the UI control will be returned.Code:el = thisform.controls ( cname ) // or el = thisform.getElementByID ( cname ) // or el = thisform.get ( cname )
Dynamically setting attributes
You can dynamically reference the attributes of a UI element using:
e.gCode:el.attribute = expression
Each time a "Form" is activated the activated delegate is called and each time it is deactivated the deactive delegate is called.Code:el.text = “hello world”
Dynamically binding delegates
Delegates are normally specified in the Assistant (or the Attributes) for a UI element.
If required you can dynamically bind delegates like this:
Python:
LianjaScript:Code:def myafterclose(self): # place your code here pass thisform.afterclose = myafterclose
Code:proc myafterclose() // place your code here endproc thisform.afterclose = myafterclose
JavaScript:
Code:function myafterclose() { // place your code here }; thisform.afterclose = myafterclose;
Understanding events and delegates
Custom Forms are built in the Canvas Designer. You drag and drop UI controls onto the canvas. Clicking on the border of a UI control (a formitem in Lianja terminology) selects the control and its caption in the "Assistant" and the "Attributes". You can then customize the appearance and the behavior of the UI control.
A UI control handles events e.g. Click of a CommandButton, InteractiveChange of a ComboBox or Change of text in a TextBox using "Delegates". Delegates are scripting language independent event handlers.
You edit delegates by selecting them in the "Delegates" combobox of the "Assistant" or in the "Attributes".
When an event occurs e.g. Change the text in a TextBox the event delegate is executed. In the event delegate you can reference the UI control (the formitem) that the event occurred for using:
Python:
In Python use self.
LianjaScript:
In LianjaScript/VFP use this.
JavaScript:
In JavaScript use this.
You can get an object reference to other UI controls on the form using:
thisform.get("page1.section1.formitem1")
or
thisform.controls("page1.section1.formitem1")
Handling click events from the menubar
You normally specify a menubarclick delegate for the form in the TabView section attributes.
When you click a menubar item the menubarclick delegate of the form is called with the fullpath of the menuitem clicked. The fullpath is a | separated list.
e.g
"Reports|Customers|Save as XML..."
You can edit the menubarclick delegate in the Canvas Designer attributes.
Python:
LianjaScript:Code:def mymenubarclick(action): action = action.lower() if (action == "file|open..."): # handle action pass thisform.menubarclick = mymenubarclick
JavaScript:Code:proc mymenubarclick(action) action = lower(action) if action = "something" // handle action elseif action = "something else" // handle action endif endproc thisform.menubarclick = mymenubarclick
Code:function mymenubarclick(action) { action = lower(action); if action == "something" { // handle action } else if action == "something else" { // handle action } } thisform.menubarclick = mymenubarclick;
Handling click events from the toolbar
You normally specify a toolbarclick delegate for the form in the TabView section attributes.
When you click an toolbar button the toolbarclick delegate of the form is called with the text of the tool button tooltip that was clicked. In this delegate you typically show Tab panels containing the UI elements of your form..
You can edit the toolbarclick delegate in the Canvas Designer attributes.
Python:
LianjaScript:Code:def mytoolbarclick(action): action = action.lower() if (action == "something"): # handle action elif (action == "something else"): # handle action thisform.toolbarclick = mytoolbarclick
Code:proc mytoolbarclick(action) // place your code here endproc thisform.toolbarclick = mytoolbarclick
JavaScript:
Code:function mytoolbarclick(action) { // place your code here }; thisform.toolbarclick = mytoolbarclick;
Handling click events from the actionbar
You can specify a actionbarclick delegate for the form in the TabView section attributes. If the TabView has a recordsource data navigation is automatically handled for the form without any coding requirement. See Data Binding below.
When you click an actionbar button the actionbarclick delegate of the form is called with the text of the tool button tooltip that was clicked. In this delegate you can navigate, add, update and delete records.
You can edit the actionbarclick delegate in the Canvas Designer attributes.
Python:
LianjaScript:Code:def myactionbarclick(action): action = action.lower() if (action == "add"): # handle Add action elif (action == "delete"): # handle Delete action elif (action == "refresh"): # handle Refresh action elif (action == "first"): # handle First action elif (action == "previous"): # handle Prev action elif (action == "next"): # handle Next action elif (action == "last"): # handle Last action elif (action == "edit"): # handle Edit action elif (action == "save"): # handle Save action elif (action == "cancel"): # handle Cancel action thisform.actionbarclick = myactionbarclick
Code:proc myactionbarclick(action) // place your code here endproc thisform.actionbarclick = myactionbarclick
JavaScript:
You can update the recno and the reccount in the actionbar like like:Code:function myactionbarclick(action) { // place your code here }; thisform.actionbarclick = myactionbarclick;
You can update the statusbar like this:Code:thisform.actionbar.recno = nExpr thisform.actionbar.reccount = nExpr
You can provide user feedback like this:Code:thisform.message = "Hello world"
Code:thisform.showSuccessMessage("Operation succeeded") thisform.showErrorMessage("Operation failed") thisform.showWarningMessage("Operation succeeded with warnings") thisform.showInfoMessage("Operation is being performed. Please wait.") thisform.hideMessage()
Data binding
Specifiying a "Data source" in the formitem attributes in the Canvas Designer binds a control to a table.column.
In the initform delegate for the form you can assign a database!table or a SQL statement to the recordsource property of the TabView.
As you navigate records in the form by clicking the icons in the actionbar, the bound controls will automatically be refreshed on the form.
All CRUD (Create, Read, Update, Delete) operations will be handled automatically for you.
Alternatively, you can call the recordsource data navigation methods manually on the container if you have your own navigation controls on the form as custom commandbuttons.
The relevant methods available on a container are:
add()
delete()
first()
next()
previous()
last()
save()
cancel()
refresh()
Responsive UI using anchors
The UI elements (formitems) that you add to Canvases in your form are not responsive to changes in geometry of screen sizes (e.g. phones, tablets, maximising the form window etc). To make your forms responsive you can use anchors which you will find in the Assistant.
You can check the top, botton, left and right anchors to make the UI control adjust its geometry and respond to changes in display geometry.
Dynamically referencing UI controls in delegates
The best way to reference UI controls on forms is to use the fully qualified name with Lianja.get(). This works in LianjaScript, Python and JavaScript.
e.g.
Lianja.get("page1.section1.field1").text = "Hello world"
Building a standalone form executable
You can build a form as a standalone executable.
See this article for details.
Using forms in Web and Mobile Apps
Forms and Components are generated when you save an App. The Form is also saved as a component that can be used in Web Apps with Lianja.showDialog(), Lianja.showDialogPanel() and Lianja.showDialogForm(). To use this in Web Apps they should be developed in JavaScript or Python.
Forms are based in TabView sections inside an App with the same name as the form. The app if javascript or Python is the selected scripting language will also run in the Web or can be generated as an Electron App or (coming soon) a React Native mobile App.