About this tutorial In this tutorial we will see how to build Custom Sections in Visual FoxPro. The target audience is for intermediate developers who have read through and understood the Getting Started with Lianja tutorial. The Lianja App Development process As you should recall from the Getting Started with Lianja tutorial, developing apps in the Lianja App Builder is an iterative process. Let's just quickly review that process. - You visually build a Lianja App using the Lianja App Builder. For non-programmers, the Lianja App Builder providers a wide range of pre-built templates to assist you in building an App quickly and easily. - Lianja Apps are made up of Pages. Pages are made up of Sections. Sections are made up of Fields and Gadgets. - You can group pages into Page Collections. If you require to build a more complex App with a custom UI, you do this by building Custom Sections and/or Custom Gadgets in any of the following scripting languages which are integrated into the Lianja App Builder: - Visual FoxPro JavaScript Python PHP Seeing that the Lianja App Builder has an embedded database built into it, you do not need to install any other software to be able to build multi-user high performance database apps for the desktop, web and mobile devices. The Lianja embedded database engine is highly compatible with Visual FoxPro. It includes a feature-complete cross platform implementation on the Visual FoxPro scripting and database engine. Python, JavaScript and PHP are seamlessly integrated on top of this database engine, allowing 1 / 10
you to build custom UI sections and custom UI gadgets in Visual FoxPro, JavaScript, Python or PHP and make full use of the power of this high performance database engine with local cursors and complete SQL and nosql database support. To facilitate the development of custom UI sections and gadgets, Lianja comes with a cross-platform, UI independent application framework called the Lianja UI Framework. Lianja UI Framework The Lianja UI Framework is a feature rich application framework used to build custom UI elements for the desktop, web and mobile devices. The classes, methods and properties in the framework are compatible with those in Visual FoxPro 9.0 but have been extensively extended to make it easier to build UIs for Apps that will run on the desktop, web and mobile devices. In particular, it has complete Layout Manager support, and provides the ability for each UI component to be skinned using CSS attributes (the Stylesheet property). You use Visual FoxPro, JavaScript, Python or PHP with the Lianja UI Framework to build Custom Sections and Custom Gadgets. All Lianja UI Framework Classes provide integrated data binding to the underlying Lianja embedded database (the Controlsource property). For details of the classes available in the Lianja UI Framework see the Lianja Documentation Wiki. Building a Custom Section Let's get started and build a simple Custom Section that displays some data from a database in a Grid. Firstly, open or create an App and add a Custom Section to a blank page. 2 / 10
Notewill you object-oriented Visual that FoxPro. find Lianja useful programming has when a high building degree in Lianja custom of Visual hassections exactly FoxPro and the compatibility same gadgets syntax e.g. butand namespaces. hasfunctionality many extensions Also asnote thatthat that in Editing the Custom Section code To edit the code for the Custom Section move the mouse cursor over the Section header and click the Keyboard icon. Note that you use this same procedure to edit both Custom Sections and Custom Gadgets but in the case of Gadgets you move the mouse over the gadget header. 3 / 10
The Apps workspace panel will then be displayed and the template code for the Custom Section will be generated and available for you to edit. After you complete the code editing, just click on the Switch to Pages workspace toolbutton. This causes the code you edited to be saved, compiled and reloaded into the custom section on the page. You continue this process iteratively until the custom section UI is complete. Using the Lianja UI Framework As stated earlier you build Custom Sections and Gadgets using the Lianja UI Framework. When building a Custom Section you should subclass the Section class. When building a Custom Gadget you should subclass the Gadget class. Creating a Custom Section Seeing that we are building a Custom Section in this tutorial, let's take a look at the code for a Custom Section which consists of a tabbed PageFrame containing a Grid with a simple address book style navigation ListBox that populates the Grid with data when the ListBox is clicked. 4 / 10
// // Lianja custom section for page "page1" section "section1" // //------------------------------------------------------------------------------ // declare a namespace - this is added by default when you use the template code namespace custom_vfp //------------------------------------------------------------------------------ // when a namespace is active public variables are added to the namespace public ui_grid //------------------------------------------------------------------------------ // Step 1: Define the classes we need // Note that all Lianja UI Framework classes can be subclassed in Visual FoxPro // // Subclass a Section // Note how the event procedures are defined. These correspond to the navigation // buttons in the section header. define class page1_section1 as section proc init() // place your section "init" code here endproc proc add() // place your section "add" code here endproc proc delete() // place your "delete" code here endproc proc first() // place your "first" code here endproc proc previous() // place your move "previous" code here endproc proc next() // place your move "next" code here endproc proc last() // place your "last" code here endproc proc watch() // place your "watch" code here endproc proc refresh() // place your "refresh" code here endproc proc edit() // place your "edit" code here endproc proc search() // place your "search" code here endproc proc save() // place your "save" code here endproc proc cancel() // place your "cancel" code here endproc enddefine //-------------------------------------------------------------------------- // Subclass a Listbox so that we can define the Click event procedure define class cls_listbox as ListBox proc click() ui_grid.clear // Note how the AddItems method of Grid, ListBox and Combobox can take // a SQL SELECT statement as an argument if trim(this.text) = "All" ui_grid.additems('select * from example where last_name!= " "') else ui_grid.additems('select * from example where; upper(left(last_name,1)) = "' + trim(this.text) + '"') endif ui_grid.refresh() endproc enddefine //------------------------------------------------------------------------------- // Define the main procedure in the section file that will create the section and // return it to Lianja. // Note that this must be the same name as the file in which it is contained in. proc page1_section1 //-------------------------------------------------------------------------- // Make sure the database is open if database()!= "southwind" open database southwind endif //-------------------------------------------------------------------------- // Step 2: Create the Custom Section object page1_section1 = createobject("page1_section1") //-------------------------------------------------------------------------- // Step 3: Create a PageFrame class and add it to the Section page1_section1.addobject("tabs", "pageframe") //-------------------------------------------------------------------------- // Step 4: Add a Page to the PageFrame class and set some of its properties tabs.addobject("ui_tab_customers", "page") ui_tab_customers.caption = "Customers" ui_tab_customers.show //-------------------------------------------------------------------------- // Step 5: Add a Container to the Page and set some of its properties ui_tab_customers.addobject("ui_cont", "container") ui_cont.autosize =.t. ui_cont.backcolor = "lightblue" ui_cont.layout = "horizontal" ui_cont.margin = 5 ui_cont.spacing = 5 ui_cont.show //-------------------------------------------------------------------------- // Step 6: Add a subclassed ListBox to the Container and set some of its properties ui_cont.addobject("ui_listbox", "cls_listbox") ui_listbox.fixedwidth = 200 //-------------------------------------------------------------------------- // Step 7: Invoke the AddItems method with a comma-separated list of items // to add to the ListBox ui_listbox.additems("all,a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r,s,t,u,v,w,x,y,z") ui_listbox.show //-------------------------------------------------------------------------- // Step 8: Add a Grid 5 / 10
to the Container // Note that ui_grid is a namespace variable ui_cont.addobject("ui_grid", "grid") ui_grid.show ui_grid.rowheight = 20 ui_grid.readonly =.t. ui_grid.recordmark =.f. ui_grid.closable =.f. ui_grid.caption = "Sample data" ui_grid.additems('select * from example where last_name!= " "') ui_grid.refresh ui_grid.autofit //-------------------------------------------------------------------------- // Step 9: Add a couple more Page classes to the PageFrame tabs.addobject("ui_tab_orders", "page") ui_tab_orders.caption = "Orders" tabs.addobject("ui_tab_shippers", "page") ui_tab_shippers.caption = "Shippers" //-------------------------------------------------------------------------- // Step 10: now we must return the Section back to Lianja return page1_section1 For details of the classes available in the Lianja UI Framework see the Lianja Documentation Wiki. The life of an object At this point it is worth looking into the life of an object. An object is created using the CreateObject( ) function by supplying it with the name of the class that you want to instantiate. e.g. myobj = createobject("container") Each time an object is assigned to a variable (or passed as an argument to a procedure of function) the object is reference counted. As variables become out of scope (return from a 6 / 10
procedure or function) or are dereferenced their reference count is decremented. When the reference count reaches zero they are destroyed. When a Custom Section or Custom Gadget is created, Lianja will automatically handle the reference counting to control its life. Containers, Components and Utility classes The Lianja UI Framework has a wide range of classes available for you to use in Custom Sections and Custom Gadgets. These classes are categorized as Containers, Components or Utility classes. Container classes available in the Lianja UI Framework Container classes are UI classes that can have other UI classes (Containers or Components) added to them to construct a hierarchical tree of visual elements. You add objects to existing objects using the AddObject( ) method of a container. The first argument is the name of the object you want to create and the second is the name of the class that you want to instantiate e.g. // create a new object variable called "mygrid" which is a "Grid" myobj.addobject("mygrid", "grid") Container classes are UI classes that can have other UI classes added to them and include the following. - CommandGroup Container Control Gadget Grid Page PageFrame Section Splitter Tree Component classes available in the Lianja UI Framework 7 / 10
Component classes are UI classes that cannot have other UI classes added to them and include the following. - ActionBar CheckBox Column ComboBox CommandButton DateTextBox DateTimeTextBox Editbox Header Hyperlink Image ImageStrip Label LCDNumber Line ListBox OptionButton OptionGroup PopupMenu ProgressBar Separator Shape Spinner Splitter TextBox ToolBar ToolBox TreeItem WebView Utility classes available in the Lianja UI Framework - Collection - Database - Timer Object Methods, Properties and Events All classes in the Lianja UI Framework have Methods and Properties. Methods are procedures that control the behavior of the object and Properties are attributes that control the appearance 8 / 10
and functionality of the object. All classes in the framework have a common set of Properties and Methods and others that are specific to the class. e.g. Some common properties: - Left Top Width Height BackColor ForeColor Some common methods: - show - hide Events are actions that are triggered when an object is affected by some external action e.g. clicking a CommandButton or editing a TextBox. By subclassing the Lianja UI Framework classes you can define your own Event procedures that will be called when an event is triggered. e.g. let's declare a class that subclasses a CommandButton and responds to the click event. define class mybutton as commandbutton proc click( ) MessageBox("You clicked the button!") endproc enddefine Understanding Namespaces When developing custom sections in the Visual FoxPro scripting language it is a good practice to encapsulate the custom section or gadget code into a unique namespace. You declare a namespace using the namespace command. e.g. namespace mycustomsection 9 / 10
Whenever a namespace is active, all public variables are declared in the namespace. e.g. namespace mycustomsection public state // updating the "state" variable in the namespace state = 1 Whenever any events are dispatched to an object e.g. a click event for a Commandbutton, Lianja will automatically activate the namespace that the object belongs to. This prevents any name clashes across individual custom section or gadget code. You can treat a namespace just like any other object variable and reference property elements in it. e.g namespace mycustomsection public state define class mybutton as commandbutton proc click() if mycustomsection.state = 1 // handle state 1 endif endproc enddefine Summa ry As you can see from this tutorial, it is easy to extend Lianja by building Custom Sections and Gadgets in Visual FoxPro as it is integrated into Lianja as a first class citizen. See Also Lianja Developers Guide Lianja Documentation Wiki 10 / 10