Lightning Developer Reference v2.0.0

Lightning
Developer Reference
Version 2.0.0
Lightning Developer Reference Copyright 20092013 Graham Langley Ltd. All rights reserved. Lightning and the Lightning Developer Reference are written by Graham Langley.
Software Licence Agreement

1 INTRODUCTION 1.1 This Licence Agreement ("Agreement") is an agreement between you and Graham Langley Ltd. ("the Author"). Please read these terms and conditions carefully before downloading any software and applicable documentation as they contain important information about your rights and obligations. It governs your use of the software ("the Software") supplied to you by the Author and related documentation. In particular, please read clause 8 (limitation of liability). By downloading, installing or otherwise using the Software you agree to be legally bound by this Licence Agreement as it may be modified and posted on the Author's website from time to time. 1.2 If you do not wish to be bound by this Agreement, then you may not download or use the Software. 7 WARRANTY 7.1 Subject to the limitations upon its liability set out in clause 8, the Author warrants that: 7.1.1 for a period of 90 days from you purchasing the Software, it will materially conform to the electronic documentation provided with it; and 7.1.2 with respect to any physical diskette(s), the same shall be free from defects in materials and workmanship for a period of 90 days from purchase. 7.2 In the event of notification within the warranty period stated in clause 7.1, The Author shall replace the defective Software and/or diskette(s). Your remedy for breach of the warranties set out in clause 7.1 shall be limited to replacement of the defective materials and shall not encompass any other damages. 7.3 Save as stated herein, the Author expressly disclaims all other conditions, warranties, terms and undertakings, expressed or implied, statutory or otherwise, relating to the Software and related documentation or technical support including but not limited to warranties of quality, performance, satisfactory quality or fitness for a particular purpose.
2 LICENCE 2.1.1 You may make a reasonable number of backup copies of the Software for your use provided all copies bear the Authors copyright notice. 2.1.2 You may use this Software to create an unlimited number of custom or commercial databases or applications created by the original licencee. No additional product license or royalty is required except as noted below. Databases created with the Software may be distributed only if they present the Software in a COMPILED form.
8 LIMITATION OF LIABILITY 8.1 Nothing in this Agreement shall limit the Authors liability for: 8.1.1 fraud or other criminal act; 8.1.2 personal injury or death caused by our negligence; 8.1.3 any other liability that cannot be excluded by law.
3 RESTRICTIONS ON USE 3.1.1 You may not distribute the NONCOMPILED, open source code of the Software without written permission from the Author. 3.1.2 You may not distribute copies of the Software, even if substantially modified, to any client, customer, developer or other person or organization, for use as a competitive product. 3.1.3 You shall not copy any written documentation accompanying the Software. 3.1.4 You shall not remove or obscure any copyright and trademark notices or other proprietary notices relating to the Software. All notices must be duplicated as it appears on the Software on all authorised copies. 3.1.5 You may not rent, transfer, or grant any rights in the Software to any person without the prior written consent of the Author. 3.1.6 You shall not reverse engineer, decompile or disassemble the Software except to the extent expressly permitted by any applicable local laws which may overrule this restriction. 3.1.7 You shall not make copies of the Software additional to those expressly permitted in this Licence Agreement. 3.1.8 You shall not use the Software in any way other than in a manner specifically licensed under this Agreement. 3.1.9 You shall not display the Software on a public bulletin board, website, chat room or by any other unauthorised means.
8.2 Subject to clause 8.1, the Author accepts no liability for any indirect or consequential loss or damage, or for any loss of data, profit, revenue, anticipated savings or business, however caused and even if foreseeable or made known to the Author. 8.3 Except as provided in clause 8.1, the Authors maximum liability to you for any cause whatsoever will be limited to the amount paid for the Software.
9 SEVERABILITY If a Court or other competent authority decides that any provision of this Agreement is void or otherwise ineffective in whole or in part then any other part and the other terms and conditions of this Agreement shall continue in full force and effect.
10 THIRD PARTY RIGHTS The parties do not intend that any term of this Agreement shall be enforceable solely by virtue of the Contracts (Rights of Third Parties) Act 1999 by any person who is not a party to this Agreement.
11 ENTIRE AGREEMENT This Agreement constitutes the entire agreement between the parties with respect to the subject matter of this Agreement and supersedes all previous agreements, arrangements or undertakings between the parties relating to the subject matter of this Agreement and any representations or warranties previously given or made to it.
4 INTELLECTUAL PROPERTY RIGHTS The copyright, patents, trade marks and all other intellectual property rights in the Software and related documentation are owned by and remain the property of the Author and are protected by national laws and international treaty provisions. You do not obtain any rights in the Software other than those expressly granted in this Agreement. 12 ASSIGNMENT You may not assign this Agreement nor any of its rights or obligations hereunder nor sub license the use (in whole or in part) of the Software without the Authors prior consent.
5 TERMINATION This Agreement is effective until terminated. This Agreement will terminate automatically if you fail to comply with any provision of this Agreement. Upon notice of termination from the Author you shall destroy the documentation and all copies of the Software promptly.
13 NOTICES 13.1 All notices shall be given: 13.1.1 to the Author via email at mail@grahamlangley.co.uk; 13.1.2 to you at either the email or postal address you provide during any ordering process.
6 UPDATE POLICY The Author may create, from time to time, updated versions of the Software. The Author will make any such updated versions available to licencees who have paid the update fee. If you acquire an updated version of the Software then all copies of the previous version must be destroyed and not used, except for one copy which may be retained solely for archival purposes.
13.2 Notice will be deemed received when an email is received in full (or else on the next business day if it is received on a weekend or a public holiday in the place of receipt) or 3 days after the date of posting.
14 GOVERNING LAW This Agreement is governed by and interpreted in accordance with English law. Any disputes or claims relating to this Agreement shall be subject to the exclusive jurisdiction of the English Courts.
Lightning Developer Reference
Table of Contents
Introduction........................................................................... 8
About The Author.......................................................................................................8 Acknowledgements.....................................................................................................8
About Lightning...................................................................... 8
Why should I use Lightning?........................................................................................8 System Requirements.................................................................................................9 4th Dimension.......................................................................................................9 Web Server Licence................................................................................................9 Computer .............................................................................................................9 Operating System...................................................................................................9 Browsers...............................................................................................................9
What's New in Version 2.0?.....................................................10

New New New New New Features...........................................................................................................10 Callback Methods...............................................................................................10 Component Methods..........................................................................................10 JavaScript Functions..........................................................................................11 Tags.................................................................................................................11
Getting Started..................................................................... 12
Lightning Sales.........................................................................................................12 Installation..............................................................................................................13 Database Folder Stage 1.....................................................................................13 Database Methods Stage 2..................................................................................14 Web Server Publishing Stage 3............................................................................15 Testing....................................................................................................................16 Login......................................................................................................................17 Registration.............................................................................................................17 Demonstration mode.................................................................................................17
The Recycle Bin.....................................................................18

Deleting Records......................................................................................................18 Filtering Records.......................................................................................................19
Component Methods..............................................................20
Ltg_Action_GetCurrent..............................................................................................20 Ltg_Action_GetReturn...............................................................................................22 Ltg_Conn_IsRequest.................................................................................................22 Ltg_Conn_ProcessRequest.........................................................................................23 Ltg_Doc_GetDirectoryDelimiter..................................................................................24 Ltg_Doc_GetProperties..............................................................................................24 Ltg_Doc_Receive......................................................................................................25 Ltg_Doc_Send..........................................................................................................26
Ltg_Err_Argument....................................................................................................27 Ltg_Err_Description..................................................................................................27 Ltg_Focus_Set.........................................................................................................28 Ltg_Folder_Get.........................................................................................................29 Ltg_Form_Display.....................................................................................................30 Ltg_JS_Send............................................................................................................30 Ltg_Login................................................................................................................31 Ltg_Msg_Error.........................................................................................................32 Ltg_Msg_Information................................................................................................32 Ltg_Msg_Stop..........................................................................................................32 Ltg_Msg_Warning.....................................................................................................33 Ltg_RB_Add.............................................................................................................33 Ltg_RB_Count..........................................................................................................34 Ltg_RB_Filter...........................................................................................................35 Ltg_RB_IsDeleted.....................................................................................................35 Ltg_RB_Remove.......................................................................................................36 Ltg_Rec_ClearCheckedSelection.................................................................................36 Ltg_Rec_GetCheckedSelection....................................................................................37 Ltg_Rec_GetCurrent..................................................................................................37 Ltg_Rec_GetReturn...................................................................................................37 Ltg_Rec_LoadCurrent................................................................................................38 Ltg_Rec_LoadCurrentSelection...................................................................................38 Ltg_Rec_LoadReturn.................................................................................................38 Ltg_Rec_Lock...........................................................................................................39 Ltg_Rec_Select.........................................................................................................40 Ltg_Register............................................................................................................40 Ltg_RI_DeleteAll.......................................................................................................41 Ltg_Search_SetActive...............................................................................................41 Ltg_Search_SetField.................................................................................................42 Ltg_Session_GetCurrent ...........................................................................................42 Ltg_Session_GetProperties .......................................................................................43 Ltg_Shutdown..........................................................................................................44 Ltg_Sort_SetField.....................................................................................................44 Ltg_SqNo_Get..........................................................................................................45 Ltg_SqNo_Reuse......................................................................................................45 Ltg_Started.............................................................................................................45 Ltg_Startup.............................................................................................................46 Ltg_Str_Encode........................................................................................................46 Ltg_Str_ToArray.......................................................................................................47 Ltg_Table_GetCurrent ..............................................................................................47 Ltg_Table_GetReturn.................................................................................................48 Ltg_User_GetValue...................................................................................................48 Ltg_User_SetValue...................................................................................................49 Ltg_Users_Get.........................................................................................................50 Ltg_Version_Get.......................................................................................................51
Ltg_XML_Flush.........................................................................................................51
Host Methods........................................................................ 52
Ltg_Conn_HandleRequest..........................................................................................52 Ltg_List_Get............................................................................................................53 Ltg_Var_Get............................................................................................................53
Callback Methods..................................................................54
Overview.................................................................................................................54 On Cancel Record.....................................................................................................55 On Delete Record.....................................................................................................55 On Display Record....................................................................................................56 On List Records........................................................................................................56 On Localise..............................................................................................................56 On Login.................................................................................................................57 On Logout...............................................................................................................57 On New Record........................................................................................................58 On Password Forgotten..............................................................................................59 On Save Record........................................................................................................59 On Undelete Record..................................................................................................60 On Validate Login.....................................................................................................61
JavaScript Functions..............................................................62
ltgExecuteMethod.....................................................................................................62
Forms.................................................................................. 63
Custom Form...........................................................................................................63 Detail Form..............................................................................................................63 List Form.................................................................................................................64 Select Form.............................................................................................................66
Tags.................................................................................... 67
ltgbutton...............................................................................................................67 ltgbuttons..............................................................................................................69 ltgcaption..............................................................................................................70 ltgcol.....................................................................................................................71 ltgdetail.................................................................................................................71 ltgdocument...........................................................................................................71 ltgfield...................................................................................................................71 ltgform..................................................................................................................76 ltghead..................................................................................................................77 ltgif.......................................................................................................................77 ltginclude...............................................................................................................78 ltglist....................................................................................................................78 ltglistbody............................................................................................................78 ltglistfoot.............................................................................................................79 Lightning Developer Reference 5
ltglisthead............................................................................................................79 ltgloop...................................................................................................................79 ltgmethod..............................................................................................................80 ltgnavigation..........................................................................................................81 ltgrow...................................................................................................................81 ltgselectall............................................................................................................81 ltgselect................................................................................................................82 ltgsort...................................................................................................................82 ltgswitch................................................................................................................83 ltgtable..................................................................................................................84 ltgvar....................................................................................................................84
Web User Interface (WUI).......................................................85

Overview.................................................................................................................85 lightningxml.......................................................................................................85 WebFolder...............................................................................................................85 lightningcustom..................................................................................................85
images.......................................................................................................................85 scripts........................................................................................................................86 themes.......................................................................................................................86 <root>.......................................................................................................................86 mobile........................................................................................................................86 modules......................................................................................................................86 scripts........................................................................................................................86 themes.......................................................................................................................86 xliff............................................................................................................................86 xml............................................................................................................................86
lightningweb......................................................................................................86
Command Bar..........................................................................................................87 Synch..................................................................................................................87 Tools...................................................................................................................88

Application..................................................................................................................88 Forms.........................................................................................................................89 Tables.........................................................................................................................92 Tabs...........................................................................................................................94 User Access.................................................................................................................95 Log............................................................................................................................96 Sessions.....................................................................................................................97
Form Editor..............................................................................................................................90 Table Editor..............................................................................................................................92
Search................................................................................................................98 Settings.............................................................................................................102 Tab Bar..................................................................................................................103 Tab Bar (Mobile example)........................................................................................103 Sidebar.................................................................................................................104 Quick Create......................................................................................................104 Recent Items......................................................................................................104 Recycle Bin........................................................................................................104 Content Area..........................................................................................................105
Advanced Search..........................................................................................................99 Quick Search.............................................................................................................101
Troubleshooting...................................................................107
Lightning Developer Reference 6
On Web Authentication............................................................................................107 4D Compatibility Settings........................................................................................107 NTK Web Server.....................................................................................................108
Appendix A. Error Codes and Descriptions...............................109

Startup Errors........................................................................................................109 Licence Errors........................................................................................................109 Parameter Errors....................................................................................................109 Session Errors........................................................................................................109 Recycle Bin Errors...................................................................................................110 Document Errors....................................................................................................110 Form Errors............................................................................................................110 User Validation Errors..............................................................................................110
Introduction
About The Author
My name is Graham Langley and I have been developing software for over 25 years. I started with BASIC, then progressed on to dBase, Clipper, Visual Basic and 4D. I have been a 4D developer since 1995 and, since 2004, specialise solely in Web applications. I am based in London, England.
Acknowledgements
The Langley family for their continual support and encouragement. The following people have been instrumental in the production of Lightning, a BIG thanks to them... Walt Nelson Foundation App Store Proprietor David Ringsmuth Business Brothers, Inc. Tim Coogan Atlantic Associates Peter Klimon Equitable Services, Inc. Dave Nasralla CleanAir John Convey Scido Communications Edouard Guilbert 4D
About Lightning
Lightning is a 4D Component, available for 4D v11 and later versions, that you can install into a new or existing 4D database to create a Web 2.0 application for Desktop and Mobile devices. Facilities are provided for controlling user access, designing form layouts, validating data entry and much more. Lightning is designed for the beginner, intermediate and advanced 4D developer. Lightning operates in "noncontextual" mode, if you are unfamiliar with this term, please refer to the "Web Server, Overview" section of the 4D documentation to understand the differences between contextual and noncontextual modes. The online content is available here; http://www.4d.com/docs/CMU/CMU02008.HTM
Why should I use Lightning?

Without Lightning, developing a 4D web application requires additional development skills outside of the traditional doubleclickable 4D application. With Lightning, you are only required to have very basic HTML knowledge to get your 4D database up and running on the web. You can continue to write your code in the 4D Method Editor "comfort zone", and let Lightning do the rest, it's that easy. Without Lightning, web application development is a very time consuming and costly exercise, for you and your client.
About Lightning
For a small investment, you can quickly and easily create a highly functional, browser independent application, for all of your 4D applications, safe in the knowledge that future releases of Lightning will incorporate the latest technology and additional features to enable you to stay "one step ahead" of your competition.
System Requirements
4th Dimension
To use Lightning, you will need; 4D v11.4 or later 4D Server v11.4 or later
Web Server Licence

To use Lightning for permanent web applications you will require either a 4D Web Application licence or a licence for the NTK* plugin from Pluggers Software https://www.pluggers.nl/ !Important: The Lightning installation files include NTK v2.5.1. The supported versions of the NTK plugin are v1.1.3 to v2.5.1. If you do not have a suitable licence, you will still be able to use either Web Server in trial mode.
Computer
Lightning can be used on any computer supporting the required versions of 4D.
Operating System
Lightning can be used with any operating system compatible with the required versions of 4D.
Browsers
The following browsers are recommended and supported; FireFox v3 or later Google Chrome all versions Internet Explorer* v7 or later Opera* v9.5 or later Safari* v3 or later
* Certain versions of these browsers may not fully support the enhanced code editor of the Form Editor. See also Web User Interface (WUI) Form Editor
About Lightning
What's New in Version 2.0?

Here are the new additions in Lightning v2.0;
New Features
Mobile Applications Utilising the jQuery Mobile framework to design Mobile forms NTK Web Server An alternative choice of Web Server to the builtin 4D Web Server Application Settings Alter aspects of the web user interface (WUI) without any code Relations Search and Sort using related fields Remember Me Enable/disable with optional password storage (cookie) Log File Logs a variety of user actions
New Callback Methods

On Localise On Login On Logout On Password Forgotten
New Component Methods

Ltg_Doc_GetDirectoryDelimiter Ltg_Focus_Set Ltg_Rec_ClearCheckedSelection Ltg_Rec_GetCheckedSelection Ltg_Rec_LoadCurrent Ltg_Rec_LoadCurrentSelection Ltg_Rec_LoadReturn Ltg_Register Ltg_RI_DeleteAll Ltg_Search_SetActive Ltg_Search_SetField Ltg_Sort_SetField
10
Ltg_Str_ToArray Ltg_Table_GetCurrent Ltg_Table_GetReturn Ltg_User_GetValue Ltg_User_SetValue Ltg_Users_Get Ltg_Version_Get
New JavaScript Functions

ltgExecuteMethod
New Tags
ltgbuttons ltgdocument ltglist, ltglisthead, ltglistfoot, ltglistbody, ltgrow, ltgcol ltgif, ltgelse ltghead ltgloop ltgmethod ltgnavigation ltgswitch, ltgbreak, ltgcase, ltgdefault ltg-table ltgvar
11
Getting Started
Lightning ships with folders for each supported 4D version. Inside each folder there are two folders, Lightning Install and Lightning Sales.
Lightning Sales
The best way to learn about Lightning, and what it can achieve, is to take a thorough look at the Lightning Sales demonstration database that ships with the component. To use this demonstration database, please do the following; 1. Open Lightning Sales using a supported version of 4D 2. Open a supported browser, refer to the recommendations in the System Requirements section 3. Type in the address http://127.0.0.1* 4. Login as one of the following users;
User role Administrator Customer Designer User User name Administrator Meredith Hammond Designer User Password LetAdminIn CSS <none> LetUserIn
* This assumes 4D is running on the same computer. Refer to the Web Server Publishing and Testing sections below for more information on IP addresses and port numbers. !Important: If you are running Mac OSX it is important that you change the port number of the Lightning Sales demo to 8080 as you may receive a port 80 warning message similar to the screenshot below, you can proceed by clicking "OK" if required but this is not recommended. This warning is due to using any port number under 1024, unless you run your 4D application with elevated privileges (which is not recommended by Apple because of security reasons). Please refer to the Web Server Publishing Stage 3 section later in this chapter to adjust the port setting.
4D Web Server port warning
Getting Started
12
Installation
Installation is divided into three stages; Database Folder, Database Methods and Web Server Publishing.
Database Folder Stage 1

Note: If you are using Mac OSX, you may need to rightclick on your database and select "Show Package Contents" to view the Database Folder contents. To install Lightning into a new or existing 4D database, open the "Lightning Install" folder and copy the Components, Plugins and WebFolder folders* into the root of your (host) database folder. * If your database already has a one of these folders then open the respective folder within the Lightning Install folder and copy the contents into your existing folder. Once you have completed the above step, open your database with 4D, and use the Explorer to navigate to Methods Component Methods, expand this section to reveal installed components, GL Lightning should be listed if it has been successfully installed.
Getting Started
13
Database Methods Stage 2

Note: You do not need to use the On Web Authentication Database Method with Lightning as it is not necessary. Steps 1. Open up the On Startup (4D) method or On Server Startup (4D Server) method and enter a call to Ltg_Startup 2. Open the On Exit (4D) or On Server Shutdown (4D Server) method and enter a call to Ltg_Shutdown 3. 4D Web Server* Open up the On Web Connection method and enter a call to Ltg_Conn_ProcessRequest
* When using the NTK based web server you will instead need to implement the Host method Ltg_Conn_HandleRequest to handle web connection requests as On Web Connection is solely for the built-in 4D Web Server. See also Component Methods Ltg_Conn_ProcessRequest, Ltg_Shutdown, Ltg_Startup Host Methods Ltg_Conn_HandleRequest
Getting Started
14
Web Server Publishing Stage 3

Final stage. Open up the 4D Preferences and click on Web. Steps 1. Tick "Publish Database at Startup" 2. Set the TCP port number to "80" on Microsoft Windows or "8080" on Mac OSX, or an alternative port for use with the Web Server 3. Tick "Allow SSL for Web Server" 4. Set the HTTPS port number to "443", or an alternative port when using the Web Server for encrypted connections 5. Set the Default HTML Root to "WebFolder/", or the name of your existing root folder 6. Set the Default Home Page to "/lightningweb/login.shtm" 7. Select "Noncontextual Mode" 8. Click OK The above settings assume you may wish to use a secure web connection, if that is not the case you can ignore steps 3 and 4. Please refer to the relevant 4D documentation for your version of 4D when configuring the SSL protocol. Note: The "Default HTML Path" and "Default Home Page" settings are case sensitive and must match their respective destination names exactly. !Important: Lightning will use these settings for both the 4D and NTK based Web Servers
Getting Started
15
Testing
After you have completed the installation, restart your database and check for and resolve any startup error messages, or errors generated by the Syntax Check facility in the 4D Compiler. Open up your web browser and enter the IP address (and port number if you're not using 80) of the computer running your 4D application. If you are using the browser on the same computer as your 4D (Lightning) application, you can enter the following (replace <port> with the port number configured in the Web Server Publishing section above); http://127.0.0.1:<port> e.g. http://127.0.0.1:80 If you are using the browser on a computer which is not running your 4D (Lightning) application, you need to find out the IP address of that computer (replace <port> with the port number configured in the Web Server Publishing section above); http://<computer ip address>:<port> e.g. http://172.15.1.5:80 If everything is working correctly you should see the Lightning Sales login form below;
Lightning Sales Login Form (Desktop)
Lightning Sales Login Form (Mobile)
!Important: When using the Mobile application on iOS it is highly recommended to add an icon to the Home screen of the device to launch the application. This will utilise all of the capabilities of the jQuery Mobile interface and provide the best results. See also http://www.apple.com/ios/add-to-home-screen/
Getting Started
16
Login
When Lightning is first installed into a database, you should login as Designer using the correct password (if any) as set in the 4D Toolbox Users section of the 4D application. User name The user name Password The users password Language The languages available when Lightning localises and displays internal values Application The application type to use, Desktop or Mobile
Registration
If you have not yet registered Lightning, the next form to appear after login will be the Registration form. When you purchase Lightning, you will be sent an email containing your licence information. Enter this information into the form and click "Register Now". If you have not yet purchased Lightning, click "Register Later" and the component will operate in "Demonstration" mode.
Demonstration mode
Demonstration mode is limited to a single user session and will timeout 60 minutes after calling Ltg_Startup. You will need to restart your database in order to restart Lightning. In Demonstration mode, if another user attempts to login, any existing user session will be closed without warning to allow the new user access.
Getting Started
17
The Recycle Bin

The Recycle Bin engine provides you, should you require it, with a fresh approach to record reuse, possibly avoiding any data compact requirements, therefore downtime, in the future.
Deleting Records
When a user deletes a record within the WUI (web user interface), you either have the option (on a per table basis) to delete the record immediately from the table, or place the record in the Recycle Bin for recycling. Records added to the Recycle Bin will still exist in the table until such time as the Recycle Bin is purged, a record "retention period" has expired and the record is recycled or the record is "undeleted". If a record exists in the Recycle Bin but is deleted outside of the WUI, you must implement a routine to check for the existence of the record in the Recycle Bin, and update the Recycle Bin accordingly, otherwise the table data and the Recycle Bin data will not be consistent. Here is an example of some code that checks for the existence of a record in the Recycle Bin, if it exists and is successfully removed, the record is then permanently deleted; C_BOOLEAN($flDeleted) C_INTEGER($nError) $nError:=Ltg_RB_IsDeleted (>[Customers];>[Customers]Customer_No;>$flDeleted) If ($nError = 0) ` Does the customer record exist in the Recycle Bin? If ($flDeleted) ` Remove the entry, and check it went OK $nError:=Ltg_RB_Remove (>[Customers];>[Customers]Customer_No) If ($nError = 0) ` Go ahead and permanently delete the customer record DELETE RECORD([Customers]) End if End if End if
The Recycle Bin
18
Filtering Records
In order to arrive at a selection of records in a table that are not "recyclable" the Ltg_RB_Filter method is provided as a filtering solution. How do I integrate the Recycle Bin into my existing database? If you are installing Lightning into an existing database you must update record selection methods by including a call to Ltg_RB_Filter. Here is an example of some code you may have in your database; ` Find all customers whose name begins with "A" QUERY([Customers];[Customers]Customer_Name = "A@") ` Display the customers DISPLAY SELECTION([Customers]) You should update the above code to read; ` Find all customers whose name begins with "A" QUERY([Customers];[Customers]Customer_Name = "A@") ` Filter out recyclable records C_INTEGER($nError) $nError:=Ltg_RB_Filter(>[Customers]) ` Display the customers DISPLAY SELECTION([Customers]) Does the Recycle Bin slow down my record selections? No, as long as the number of recyclable records per table does not run into thousands, the performance hit by using Ltg_RB_Filter should be minimal. The Recycle Bin data is loaded into memory upon startup, processed in memory, and committed to disk upon shutdown. Lightning will maintain the Recycle Bin for you using expiry rules set via the Table Editor. See also Web User Interface (WUI) Table Editor
The Recycle Bin
19
Component Methods
Ltg_Action_GetCurrent
Syntax: Ltg_Action_GetCurrent Text
Parameter Function result Type Text Description The current action being processed
The Ltg_Action_GetCurrent method can be used to retrieve the current "action" being processed by the Ltg_Conn_ProcessRequest method. If the current action is not available an empty value is returned. Common actions are; autocomplete Displaying the AutoComplete popup list button Button clicked (excluding the builtin button actions) cancel "Cancel" button clicked delete "Delete" button clicked edit Displaying a Detail form index Displaying a List form new "New" button clicked on_change A field with a 4D method attached has its value changed save "Save" button clicked select Display a Select form select_cancel Cancelling of the Select form without a record selection tab Tab clicked
Component Methods
20
Examples The following example is executed via the On List Records callback and illustrates the various actions available for record filtering prior to Lightning performing any active search criteria set by the current user. C_TEXT($txtAction) $txtAction:=Ltg_Action_GetCurrent Case of :($txtAction = "tab") ` Display the record selection in a List form via a Tab click. :($txtAction = "index") ` Display the record selection in a List form. :($txtAction = "autocomplete") ` Display the record selection in a AutoComplete popup. End case The following example executes a method attached to a field on a Detail form using the ltgfield tag. C_TEXT($txtAction) $txtAction:=Ltg_Action_GetCurrent Case of :($txtAction = "on_change") ` The field value has been changed by the user. :($txtAction = "select_cancel") ` The Select form attached to the field has been cancelled by the user. End case See also Component Methods Ltg_Conn_ProcessRequest
Component Methods
21
Ltg_Action_GetReturn
Syntax: Ltg_Action_GetReturn Text
Parameter Function result Type Text Description The returning/previous action
The Ltg_Action_GetReturn method can be used to retrieve the returning/previous "action". See also Component Methods Ltg_Action_GetCurrent
Ltg_Conn_IsRequest
Syntax: Ltg_Conn_IsRequest (url) Boolean
Parameter url Function result Type Text Boolean Description URL The url is a Lightning connection request
The Ltg_Conn_IsRequest method should be called from within the On Web Connection Database Method to detect whether url is a Lightning connection request to be handled by the Ltg_Conn_ProcessRequest method, or to be routed to another handler. Note: If you are not using the 4D/NTK based Web Server for anything other than Lightning connections, calling this method is not necessary. Example C_TEXT($1;$2;$3;$4;$5;$6) ` Is this a Lightning connection request? If (Ltg_Conn_IsRequest ($1)) ` Connect to Lightning and process the request $nError:=Ltg_Conn_ProcessRequest ($1;$2;$3;$4;$5;$6) Else ` Process the request using other means... End if See also Component Methods Ltg_Conn_ProcessRequest
Component Methods
22
Ltg_Conn_ProcessRequest
Syntax: Ltg_Conn_ProcessRequest(url; http header; client ip address; server ip address; user name; password) Integer
Parameter url http header client ip address server ip address user name password Function result Type Text Text Text Text Text Text Integer Description URL HTTP Header IP address of the web client IP address of the Web Server User name Password Error code
The Ltg_Conn_ProcessRequest method handles all Lightning web connection requests from the web browser. To incorporate this method into your 4D database, use the 4D Explorer to navigate to Database Methods and the On Web Connection method when using the 4D Web Server or refer to the Host method Ltg_Conn_HandleRequest when using the NTK based Web Server. Enter the following; C_TEXT ($1;$2;$3;$4;$5;$6) C_INTEGER ($nError) $nError:=Ltg_Conn_ProcessRequest ($1;$2;$3;$4;$5;$6) If ($nError # 0) ' Issue a "Stop" error Ltg_Msg_Stop ("Lightning Error ("+String($nError)+"): "+ Ltg_Err_Description ($nError)) End if If Lightning started correctly but a connection is unsuccessful, an alert message will be displayed in the WUI. See also Component Methods Ltg_Conn_IsRequest Host Methods Ltg_Conn_HandleRequest 4D Database Methods On Web Connection
Component Methods
23
Ltg_Doc_GetDirectoryDelimiter
Syntax: Ltg_Doc_GetDirectoryDelimiter Integer
Parameter Function result Type Integer Description Character code of the delimiter
The Ltg_Doc_GetDirectoryDelimiter method is used to retrieve the character code of the directory delimiter (separator) of the host operating system.
Ltg_Doc_GetProperties
Syntax: Ltg_Doc_GetProperties(document; name; type) Integer
Parameter document name type Function result Type Pointer Pointer Pointer Integer Description Pointer to the document BLOB captured by the browser Pointer to a Text variable to store the document name Pointer to a Text variable to store the document type Error code
You can use the Ltg_Doc_GetProperties method to obtain information about the document associated with a ltgdocument tag. See also Component Methods Ltg_Doc_Receive Tags ltgdocument
Component Methods
24
Ltg_Doc_Receive
Syntax: Ltg_Doc_Receive(document) Integer
Parameter document Function result Type Pointer Integer Description Pointer to the document BLOB captured by the browser Error code
You can use the Ltg_Doc_Receive method to receive (upload) a document via the users web browser. Note: The variable attached to the ltgdocument tag must be declared in both the callback method and the "Compiler_Web" project method which you should create if this does not exist in your database. Example The following example is a 4D method attached to a ltgbutton tag which verifies that the document selected via a ltgdocument tag is an image, uploads the document and stores the content to a pointer. C_INTEGER($0) C_POINTER($1) C_BLOB(document_blob) ` The variable attached to the ltgdocument tag C_TEXT($txtDocument_Name; $txtDocument_Type) C_INTEGER($nError) $nError:=Ltg_Doc_GetProperties (>document_blob;>$txtDocument_Name; >$txtDocument_Type) If($nError = 0) If($txtDocument_Type = "image@") $nError:=Ltg_Doc_Receive (>document_blob) BLOB TO PICTURE(document_blob;$1>) Else Ltg_Msg_Error ("The type of file selected does not appear to be an image file: "+$txtDocument_Name) End if End if $0:=$nError
Component Methods
25
Ltg_Doc_Send
Syntax: Ltg_Doc_Send(document [; display]) Integer
Parameter document display Type Text Boolean Description Fully qualified file name Indicates whether the the document should be displayed within the browser window (the default behaviour if the MIME type is supported by the browser) or whether a "Save As..." dialogue should be presented Error code
Function result
Integer
Web users are restricted to accessing documents/files located within the html root folder and its subfolders. You should use the Ltg_Doc_Send method when you need to send (upload) a local document/file to the browser that is outside of the html root folder. Example The following example, taken from Lightning Sales Documents, is a method callback attached to the Document_Name field in the List form. The Documents table contains document names stored in a Documents folder located in the host Database root folder. C_INTEGER($nError) C_TEXT($txtPath) ` Get the path to the Documents folders in the host Database folder $txtPath:=Ltg_Folder_Get("host")+"Documents"+ Char(Ltg_Doc_GetDirectoryDelimiter) ` Upload the document to the browser $nError:=Ltg_Doc_Send ($txtPath + [Documents]Document_Name; True) See also Component Methods Ltg_Doc_GetDirectoryDelimiter, Ltg_Folder_Get
Component Methods
26
Ltg_Err_Argument
Syntax: Ltg_Err_Argument Text
Parameter Function result Type Text Description Argument which triggered an error
Ltg_Err_Argument method can be used to retrieve the argument which triggered an error. If the argument is unavailable, an empty string is returned.
Ltg_Err_Description
Syntax: Ltg_Err_Description (error) Text
Parameter error Function result Type Integer Text Description Error code returned from Lightning component methods Description of the error
The Ltg_Err_Description method is used to describe an internal Lightning error code. For errors that occur within a Lightning user session, a message describing the error will automatically be displayed to the user within the WUI. See also Appendix A. Error Codes and Descriptions
Component Methods
27
Ltg_Focus_Set
Syntax: Ltg_Focus_Set Text
Parameter element Function result Type Text Integer Description The id of the element for which to set input focus Error code
Ltg_Focus_Set method can be used set the input focus of an element within the WUI. Note: Elements are referenced using their html "id" attribute. For 4D fields you need to use the fully qualified name "[table_name]field_name". Example The following example checks that the user has entered a Product Code for a Sales Order Item, if not the Product Code field will receive the input focus and a message will be displayed, otherwise the Quantity field will receive the input focus; If ([Sales_Order_Items]Product_Code = "") Ltg_Focus_Set("[Sales_Order_Items]Product_Code") Ltg_Msg_Warning("Please enter a Product Code") Else Ltg_Focus_Set("[Sales_Order_Items]Quantity") End if
Component Methods
28
Ltg_Folder_Get
Syntax: Ltg_Folder_Get (folder) Text
Parameter folder Function result Type Text Text Description Folder name Path to the specified folder
The Ltg_Folder_Get method is used to retrieve the path to a specific folder. The following folder names and corresponding paths are available, the forward slash will be replaced with the directory delimiter of the host operating system;
Folder custom customimages customscripts customthemes host web webimages webmodules webmodulesapplication webmodulesforms webmodulesformstemplates webmoduleslog webmodulesrecyclebin webmodulessearch webmodulessessions webmodulessettings webmodulestables webmodulestabs webmodulesuseraccess webscripts webthemes webxliff webxml xml Path <hostfolder>/<webfolder>/lightningcustom/ <hostfolder>/<webfolder>/lightningcustom/images/ <hostfolder>/<webfolder>/lightningcustom/scripts/ <hostfolder>/<webfolder>/lightningcustom/themes/ <hostfolder>/ <hostfolder>/<webfolder>/lightningweb/ <hostfolder>/<webfolder>/lightningweb/images/ <hostfolder>/<webfolder>/lightningweb/modules/ <hostfolder>/<webfolder>/lightningweb/modules/application/ <hostfolder>/<webfolder>/lightningweb/modules/forms/ <hostfolder>/<webfolder>/lightningweb/modules/forms/templates/ <hostfolder>/<webfolder>/lightningweb/modules/log/ <hostfolder>/<webfolder>/lightningweb/modules/recyclebin/ <hostfolder>/<webfolder>/lightningweb/modules/search/ <hostfolder>/<webfolder>/lightningweb/modules/sessions/ <hostfolder>/<webfolder>/lightningweb/modules/settings/ <hostfolder>/<webfolder>/lightningweb/modules/tables/ <hostfolder>/<webfolder>/lightningweb/modules/tabs/ <hostfolder>/<webfolder>/lightningweb/modules/useraccess/ <hostfolder>/<webfolder>/lightningweb/scripts/ <hostfolder>/<webfolder>/lightningweb/themes/ <hostfolder>/<webfolder>/lightningweb/xliff/ <hostfolder>/<webfolder>/lightningweb/xml/ <hostfolder>/lightningxml/
Component Methods
29
Ltg_Form_Display
Syntax: Ltg_Form_Display (table, name) Integer
Parameter table name Function result Type Pointer Text Integer Description Pointer to the table of which the form is associated The name of the form Error code
The Ltg_Form_Display method is used to display a Lightning form within the content area of the WUI. Example The following example is taken from the Customer_LocationMap method that is included in the Lightning Sales demonstration database. C_INTEGER($nError) $nError:=Ltg_Form_Display (>[Customers];"Customer Location Map")
Ltg_JS_Send
Syntax: Ltg_JS_Send (javascript) Integer
Parameter javascript Function result Type Text Integer Description JavaScript code Error code
The Ltg_JS_Send method can be used to send javascript directly to the WUI. Example The following example is a 4D method executing within a connection request which checks on the credit limit of the current [Customers] record and displays an alert message within the WUI if the credit limit has been exceeded; C_INTEGER($nError) If([Customers]Credit_Limit < SUM([Invoices]Total_Due)) $nError:=Ltg_JS_Send("alert('Credit limit exceeded!');") End if
Component Methods
30
Ltg_Login
Syntax: Ltg_Login (user; password; groups; role; language; ip address; allow concurrent logins; session id) Integer
Parameter user password groups role language ip address allow concurrent logins session Function result Type Text Text Text Text Text Text Boolean Pointer Integer Description User name Password User group membership User role User language code IP address Allow concurrent logins for this user Session id Error code
The Ltg_Login method is provided to allow the developer to create a session for a user other than by using the standard Lightning login form. The method is best placed during a call to the On Web Connection database method so that the user can be routed directly to the Lightning WUI. Example In the example below, using the On Web Connection database method, a "Guest" is automatically logged on and routed to a "Products" list. C_TEXT ($1;$2;$3;$4;$5;$6) C_INTEGER ($nError) C_TEXT (sSession) If (Ltg_Conn_IsRequest($1)) Ltg_Conn_ProcessRequest($1;$2;$3;$4;$5;$6) Else $nError:=Ltg_Login ("Guest";"";"Guests";"Guest";"enGB";$3;False; >sSession) SEND HTTP REDIRECT ("/4DCGI/? session="+sSession+"&module=Products&action=index") End if See also 4D Database Methods On Web Connection
Component Methods
31
Ltg_Msg_Error
Syntax: Ltg_Msg_Error (message)
Parameter message Type Text Description The "error" message to display
The Ltg_Msg_Error method displays a message to the user within the content area of the WUI using the "#error_message" class of the current theme.
Ltg_Msg_Information
Syntax: Ltg_Msg_Information (message)
Parameter message Type Text Description The "information" message to display
The Ltg_Msg_Information method displays a message to the user within the content area of the WUI using the "#information_message" class of the current theme.
Ltg_Msg_Stop
Syntax: Ltg_Msg_Stop (message)
Parameter message Type Text Description The "stop" message to display
The Ltg_Msg_Stop method can be used to display a "stop" error message to the user. This method should be used to abort the current request and return the user to the login form in the event of a serious error.
Component Methods
32
Ltg_Msg_Warning
Syntax: Ltg_Msg_Warning (message)
Parameter message Type Text Description The "warning" message to display
The Ltg_Msg_Warning method displays a message to the user within the content area of the WUI using the "#warning_message" class of the current theme.
Ltg_RB_Add
Syntax: Ltg_RB_Add (table; record) Integer
Parameter table record Function result Type Pointer Pointer Integer Description Pointer to the Table for which to add the record Pointer to the primary key of the record to add Error code
The Ltg_RB_Add method can be used to add the record belonging to table to the Recycle Bin. See also Component Methods Ltg_RB_Remove The Recycle Bin
Component Methods
33
Ltg_RB_Count
Syntax: Ltg_RB_Count (table; count) Integer
Parameter table count Function result Type Pointer Pointer Integer Description Pointer to the Table for which to query records Pointer to a Longint variable to store the record count Error code
The Ltg_RB_Count method is used to query the Recycle Bin for the total number of records that exist for table. Example This example could be placed in a method called by the On Record Delete callback from the WUI to check for the deletion limits of [Customers]; C_BOOLEAN($0) C_INTEGER($nbError) C_LONGINT(nbDeleted) ` Initialise return value $0:=False $nError:=Ltg_RB_Count (>[Customers]; >nbDeleted) If ($nError = 0) If ($nbDeleted >= 100) Ltg_Msg_Warning ("The limit of 100 deleted Customers has been reached.") Else ` Allow deletion, return True $0:=True End if End if See also Callback Methods On Record Delete
Component Methods
34
Ltg_RB_Filter
Syntax: Ltg_RB_Filter (table) Integer
Parameter table Function result Type Pointer Integer Description Pointer to the Table for which to filter records Error code
The Ltg_RB_Filter method is used to filter out records belonging to table that have been added to the Recycle Bin. Filtering is based on the current record selection. All records for table that have an entry in the Recycle Bin will be excluded from the current selection. You should use this solution for general filtering of recyclable records. See also Component Methods Ltg_RB_Add The Recycle Bin
Ltg_RB_IsDeleted
Syntax: Ltg_RB_IsDeleted (table; record; deleted) Integer
Parameter table record deleted Function result Type Pointer Pointer Pointer Integer Description Pointer to the Table for which to query the record Pointer to the primary key of the record to query Pointer to a Boolean variable to store the result Error code
The Ltg_RB_IsDeleted method is used to determine whether record belonging to table exists within the Recycle Bin. See also The Recycle Bin
Component Methods
35
Ltg_RB_Remove
Syntax: Ltg_RB_Remove (table; record ) Integer
Parameter table record Function result Type Pointer Pointer Integer Description Pointer to the Table for which to remove the record Pointer to the primary key of the record to remove Error code
The Ltg_RB_Remove method can be used to remove record belonging to table from the Recycle Bin. See also Component Methods Ltg_RB_Add The Recycle Bin
Ltg_Rec_ClearCheckedSelection
Syntax: Ltg_Rec_ClearCheckedSelection(table) Integer
Parameter table Function result Type Pointer Integer Description Pointer to the table for which the selection is to be cleared Error code
The Ltg_Rec_ClearCheckedSelection method resets the ltgselect checkboxes for the current List form belonging to table. See also Component Methods Ltg_Rec_GetCheckedSelection Tags ltgselect
Component Methods
36
Ltg_Rec_GetCheckedSelection
Syntax: Ltg_Rec_GetCheckedSelection(table; record) Integer
Parameter table record Function result Type Pointer Pointer Integer Description Pointer to the Table for which to retrieve the selection Pointer to an array to store the key values Error code
The Ltg_Rec_GetCheckedSelection method populates an array with the key values of the records which have been "checked" in a List form via the ltgselect tag. See also Tags ltgselect
Ltg_Rec_GetCurrent
Syntax: Ltg_Rec_GetCurrent Text
Parameter Function result Type Text Description Record key value
The Ltg_Rec_GetCurrent method returns the primary key value of the current record of the current table.
Ltg_Rec_GetReturn
Syntax: Ltg_Rec_GetReturn Text
Parameter Function result Type Text Description Returning/previous record key value(s)
The Ltg_Rec_GetReturn method returns the primary key value(s) of the record(s) the browser will return to after the current action is completed.
Component Methods
37
Ltg_Rec_LoadCurrent
Syntax: Ltg_Rec_LoadCurrent Integer
Parameter Function result Type Integer Description Error code
The Ltg_Rec_LoadCurrent method will load the record key returned by Ltg_Rec_GetCurrent belonging to the table returned in Ltg_Table_GetCurrent.
Ltg_Rec_LoadCurrentSelection
Syntax: Ltg_Rec_LoadCurrentSelection Integer
The Ltg_Rec_LoadCurrentSelection method loads all records available to the List form of the current table (not just those displayed in the current page of the form).
Ltg_Rec_LoadReturn
Syntax: Ltg_Rec_LoadReturn Integer
The Ltg_Rec_LoadReturn method will load the record key(s) returned by Ltg_Rec_GetReturn beloning to the table returned in Ltg_Table_GetReturn.
Component Methods
38
Ltg_Rec_Lock
Syntax: Ltg_Rec_Lock (table) Boolean
Parameter table Function result Type Pointer Boolean Description Pointer to the Table for which to lock the current record The lock was successful
The Ltg_Rec_Lock method attempts to lock the current record of table for modifying. Three attempts are made, one per second, before an error is reported. If there is a problem locking the record, feedback will automatically be provided to the user within the content area of the WUI. If you already have a record locking method and wish to continue using it, all you should do is use the Ltg_Msg_Error method, for example, to alert the user of any locking issues within the WUI. Note: You are not required to use Ltg_Rec_Lock within a method called by the On Save Record event from the WUI, Lightning will automatically attempt a record lock before calling the host database. This method is only needed when updates to tables other than the current table are necessary. Example If (Ltg_Rec_Lock(>[Suppliers])) ` The current [Suppliers] record is locked, do something... Else Ltg_Msg_Error("The supplier could not be updated, please try later.") End if
Component Methods
39
Ltg_Rec_Select
Syntax: Ltg_Rec_Select (table; field; method) Integer
Parameter table field method Function result Type Pointer Pointer Text Integer Description Pointer to the Table from which to select a record Pointer to a field to store the key value of the selected record The method to execute after a record is selected Error code
The Ltg_Rec_Select method can be called from within 4D and is used to display the "Select record" form within the browser. Note: Some browsers may require "popups" to be enabled for the url in which Lightning operates. Example C_INTEGER($nError) ALL RECORDS([Products]) $nError:=Ltg_Rec_Select (>[Products]; >[Sales_Order_Items]Product_Code;"SalesOrderItem_Product")
Ltg_Register
Syntax: Ltg_Register Integer
Parameter name number Function result Type Text Text Integer Description Licenced to name Licence number Error code
The Ltg_Register method is an alternative way of submitting your licence information as opposed to using the web based Registration form. The method should be called immediately after Ltg_Startup.
Component Methods
40
Ltg_RI_DeleteAll
Syntax: Ltg_RI_DeleteAll Integer
The Ltg_RI_DeleteAll method deletes all entries, for all users, in the Recent Items list on the Sidebar of the WUI.
Ltg_Search_SetActive
Syntax: Ltg_Search_SetActive(user; table; description) Integer
Parameter user table description Function result Type Text Pointer Text Integer Description The user name for whom to set the active search Pointer to the Table for which the search applies Saved search description Error code
The Ltg_Search_SetActive method can be used to activate a saved search for the current user. Note: To reduce the record selection to zero, pass "*" as the description parameter. To clear any active search and pass an empty string. Example The following example is executed via the On Login callback to initialise the number of displayed [Customers] records to zero when the user logs in; $nError:=Ltg_Search_SetActive($txtUsername;->[Customers];"*") See also Callback Methods On Login Component Methods Ltg_Session_GetProperties, Users_Get Web User Interface (WUI) Search
Component Methods
41
Ltg_Search_SetField
Syntax: Ltg_Search_SetField(user; table; field; selected) Integer
Parameter user table field selected Function result Type Text Pointer Pointer Boolean Integer Description The user name for whom to set the search field Table Field Selects (True) or Deselects (Field) the field Error code
The Ltg_Search_SetField method selects or deselects a Quick Search field. Example The following example selects the field [Customers]Customer_Name for inclusion in the [Sales_Orders] Quick Search for the user "MyUser". The [Sales_Orders] table has an automatic Many To One relationship with the [Customers] table; $nError:=Ltg_Search_SetField("MyUser";->[Sales_Orders]; ->[Customers]Customer_Name;True) See also Web User Interface (WUI) Search Quick Search
Ltg_Session_GetCurrent
Syntax: Ltg_Session_GetCurrent Text
Parameter Function result Type Text Description Session ID
The Ltg_Session_GetCurrent method can be used to retrieve the 16 character Session ID of the current connection request. See also Component Methods Ltg_Session_GetProperties
Component Methods
42
Ltg_Session_GetProperties
Syntax: Ltg_Session_GetProperties (session; user; groups; role; application) Integer
Parameter session user groups role application Function result Type Text Pointer Pointer Pointer Pointer Integer Description Session ID User name Groups to which the user belongs User role Application type (Desktop or Mobile) Error code
The Ltg_Session_GetProperties method can be used to retrieve session information for the current connection request. The role will return one of the following values; Administrator The user logged on as "Administrator" Designer The user logged on as "Designer" User The user is neither of the above
Example The following example is taken from the Lightning Sales demonstration database using the On List Records callback for the Sales Orders table, and is used to determine whether the current user belongs to the Customers group and if so, the record selection is limited to the records associated with their Customer Number; C_INTEGER($nError) C_TEXT(txtUsername) C_TEXT(txtGroups) C_TEXT(txtRole) C_TEXT(txtApplication) $nError:=Ltg_Session_GetProperties(Ltg_Session_GetCurrent;>txtUsername; >txtGroups;>txtRole;>txtApplication) If ($nError=0) If (txtGroups="Customer") QUERY([Contacts];[Contacts]Contact_Name=txtUsername) QUERY SELECTION([Sales_Orders]; [Sales_Orders]Customer_Number=[Contacts]Customer_Number) End if End if
Component Methods
43
Ltg_Shutdown
Syntax: Ltg_Shutdown Integer
The Ltg_Shutdown method is used to shutdown processing of Lightning web connection requests and overall functionality, and to flush xml data to disk. The method should be called from either the On Exit (4D) or On Server Shutdown (4D Server) database methods. Regardless of the return value, no further Lightning web connection requests will be accepted after calling this method. See also Component Methods Ltg_Startup 4D Database Methods On Exit, On Server Shutdown
Ltg_Sort_SetField
Syntax: Ltg_Sort_SetField(user; table; field; ascending [; field2; ascending2]) Integer
Parameter user table field ascending [field2] [ascending2] Function result Type Text Pointer Pointer Boolean Pointer Boolean Boolean Description The user name for whom to set the sort field Pointer to the table to sort Pointer to the sort field Ascending sort (true), Descending sort (false) Pointer to the second sort field Ascending sort (true), Descending sort (false) Error code
The Ltg_Sort_SetField method can be used to set the sort order for table when displaying a List form. Example The following example selects the field [Customers]Customer_Name for inclusion in the [Sales_Orders] List form sort for the user "MyUser". The [Sales_Orders] table has an automatic Many To One relationship with the [Customers] table; C_INTEGER($nError) $nError:=Ltg_Sort_SetField("MyUser";>[Sales_Orders]; >[Customers]Customer_Name;True)
Component Methods
44
Ltg_SqNo_Get
Syntax: Ltg_SqNo_Get (table; number) Integer
Parameter table number Function result Type Pointer Pointer Integer Description Pointer to the Table for which to retrieve the sequential number Pointer to a field or variable to store the next available sequential number Error code
The Ltg_SqNo_Get method is used to retrieve the next available sequential number for table.
Ltg_SqNo_Reuse
Syntax: Ltg_SqNo_Get (table; number) Integer
Parameter table number Function result Type Pointer Longint Integer Description Pointer to the Table for which to add the sequential number The number to reuse Error code
The Ltg_SqNo_Reuse method is used add a number to the list of reusable sequence numbers for table.
Ltg_Started
Syntax: Ltg_Started Boolean
Parameter Function result Type Boolean Description Indicates whether Lightning has started and is operational
The Ltg_Started method is used to determine whether Lightning has successfully started and is operational.
Component Methods
45
Ltg_Startup
Syntax: Ltg_Startup([Web Server]) Integer
Parameter Web Server Function result Type Text Integer Description The Web Server to use for connection requests Error code
The Ltg_Startup method is used to startup Lightning so that it can accept web connection requests. The method should be called by either the On Startup (4D) or On Server Startup (4D Server) database methods. The optional Web Server parameter allows you to specify which Web Server to use for connection requests; 4D Standard 4D Web Server (default) NTK <version>* Alternative Web Server based on the NTK plugin. You must specify the NTK plugin version when choosing this option, please see the example below.
*Please visit www.pluggers.nl for more details on purchasing the NTK plugin Example The following example attempts to start Lightning using version 2.5.1 of the NTK based Web Server; C_TEXT($nError) $nError:=Ltg_Startup("NTK v2.5.1") See also Component Methods Ltg_Shutdown 4D Database Methods On Startup, On Server Startup
Ltg_Str_Encode
Syntax: Ltg_Str_Encode(string) String
Parameter string Function result Type Text Integer Description String to be encoded Error code
The Ltg_Str_Encode method is used to encode strings with HTML Entity Codes prior to sending to the browser via <!4DSCRIPT>, <!4DHTMLVAR> or <!4DVAR> tags. You should use this method when you have data containing accented characters that need to be displayed within the browser.
Component Methods
46
Ltg_Str_ToArray
Syntax: Ltg_Str_ToArray( string; delimiter; array )
Parameter string delimiter array Type Text Text Pointer Description The delimited string to convert into array elements The delimiter Pointer to a text array to store the converted values
The Ltg_Str_ToArray method can be used to convert a delimited string into individual array elements. Example The following example takes a text parameter $1 and converts the contents into an array; ` (input) $1 = "Param1/Param2/Param3" ARRAY TEXT(atxtParams;0) Ltg_Str_ToArray($1; "/"; ->atxtParams) ` (output) ` atxtParams{1} = "Param1" ` atxtParams{2} = "Param2" ` atxtParams{2} = "Param3"
Ltg_Table_GetCurrent
Syntax: Ltg_Table_GetCurrent Pointer
Parameter Function result Type Pointer Description Pointer to the current table
The Ltg_Table_GetCurrent method can be used to obtain a pointer to the table relating to the current connection request.
Component Methods
47
Ltg_Table_GetReturn
Syntax: Ltg_Table_GetReturn Pointer
Parameter Function result Type Pointer Description Pointer to the previous/returning table
The Ltg_Table_GetReturn method can be used to obtain a pointer to the previous/returning table.
Ltg_User_GetValue
Syntax: Ltg_User_GetValue( user; element; value ) Integer
Parameter user element value Function result Type Text Text Pointer Integer Description The name of the user as it appears in users.xml The element name for which to retrieve the value Pointer to a text variable to store the value Error code
The Ltg_User_GetValue method can be used to retrieve an element value from the users.xml file. In addition to retrieving any custom element values you have created, the following built-in elements are available; dateFormat The date format to use in the WUI language The selected language code theme The selected theme
See also Component Methods Ltg_Users_SetValue, Ltg_Users_Get
Component Methods
48
Ltg_User_SetValue
Syntax: Ltg_User_SetValue( user; element; value ) Integer
Parameter user element value Function result Type Text Text Text Integer Description The name of the user as it appears in users.xml The element name for which to store the value The value of the element Error code
The Ltg_User_SetValue method can be used to set an element value in the users.xml file. Example The following examples demonstrates the storing of a custom element "colour" and value "Green" while processing a connection request for the current user session. If successful the user will receive a message displaying their stored colour; C_INTEGER($nError) C_TEXT(txtUsername) C_TEXT(txtGroups) C_TEXT(txtRole) C_TEXT(txtApplication) C_TEXT(txtColour) $nError:=Ltg_Session_GetProperties(Ltg_Session_GetCurrent;>txtUsername; >txtGroups;>txtRole;>txtApplication) If($nError=0) $nError:=Ltg_User_SetValue(txtUsername;"colour";"Green") If($nError=0) $nError:=Ltg_User_GetValue(txtUsername;"colour";->txtColour) If($nError=0) Ltg_Msg_Information("Your colour is "+txtColour) End if End if End if See also Component Methods Ltg_Users_Get
Component Methods
49
Ltg_Users_Get
Syntax: Ltg_Users_Get( array ) Integer
Parameter array Function result Type Pointer Integer Description Pointer to a text array to store the user names Error code
The Ltg_Users_Get method can be used to retrieve the user names stored in the users.xml file. Example The following example can be used immediately after calling Ltg_Startup to ensure each user account is set to use a custom theme named "MyTheme"; C_INTEGER($iUser;$nError) ARRAY TEXT(atxtUsers;0) $nError:=Ltg_Users_Get(->atxtUsers) For($iUser;1;SIZE OF ARRAY(atxtUsers)) $nError:=Ltg_User_SetValue(atxtUsers{$iUser};"theme";"MyTheme") End for See also Web User Interface (WUI) lightning-xml
Component Methods
50
Ltg_Version_Get
Syntax: Ltg_Version_Get Text The Ltg_Version_Get method returns the version information for the installed Lightning component. A sixteen character text value is returned and is configured as follows; 1 B (Beta) or (F) Final 2,3,4 Beta release number 5,6 Major version number 7 Minor version number 8 Revision number 9,10,11,12 Build year 13,14 Build month 15,16 Build day
Ltg_XML_Flush
Syntax: Ltg_XML_Flush Integer
The Ltg_XML_Flush method can be used at your discretion to commit updates made to the various xml files which Lightning utilises. Lightning automatically flushes the xml data after the following events; Synch Shutdown
See also Web User Interface (WUI) lightningxml
Component Methods
51
Host Methods
Ltg_Conn_HandleRequest
Syntax: Ltg_Conn_HandleRequest(url; http header; client ip address; server ip address; user name; password)
Parameter url http header client ip address server ip address user name password
The Ltg_Conn_HandleRequest method should be created in the Host database to enable support for the NTK based Web Server option and is a direct replacement for the On Web Connection 4D Database Method when using the NTK based Web Server. To install this method into your database, create a method named Ltg_Conn_HandleRequest, then copy the code from the Lightning Sales demonstration database from the method of the same name and tick the Method property "Shared by components and host database". See also Component Methods Ltg_Startup
Host Methods
52
Ltg_List_Get
Syntax: Ltg_List_Get (list) Text
Parameter list Function result Type Text Text Description The name of the Choice List A pipe delimited list of items
The Ltg_List_Get method should be created in the Host database to enable support for fields that have an associated 4D Choice List. This method will be called by Lightning for displaying fields with an associated list. To install this method into your database, create a method named Ltg_List_Get, then copy the code from the Lightning Sales demonstration database from the method of the same name and tick the Method property "Shared by components and host database". Note: If the list is a hierarchical list, only the top level items will be returned. If you do not use 4D Choice Lists then you do not need to implement this method. See also Tags ltgfield
Ltg_Var_Get
Syntax: Ltg_Var_Get (name) Text
Parameter name Function result Type Text Text Description The name of the variable A pipe delimited list of items
The Ltg_Var_Get method should be created in the Host database to enable Lightning to retrieve values of variables from the host database. To install this method into your database, create a method named Ltg_Var_Get, then copy the code from the Lightning Sales demonstration database from the method of the same name and tick the Method properties "Available through 4DACTION, 4DMETHOD and 4DSCRIPT" and "Shared by components and host database". See also Tags ltgvar
Host Methods
53
Callback Methods
Overview
For each and every method in your host database requiring interaction with Lightning (a callback), the method property "Shared by components and host database" must be checked for correct operation. If you have created a method within your host database for use with Lightning and it is not working correctly, the first thing to check is this property. Should you still receive an error message within the Web User Interface (WUI), see the example below, check that the method name is spelt correctly, and perform a TRACE command on the interpreted code to make sure that no runtime errors are being generated.
Method Property "Shared by components and host database"
Callback error (example)
Callback Methods
54
On Cancel Record
Syntax: <your method name> The On Cancel Record callback is made prior to cancelling a Detail Form. See also Web User Interface (WUI) Table Editor
On Delete Record
Syntax: <your method name> Boolean
Parameter Function result Type Boolean Description The record can be added to the Recycle Bin
The callback is invoked when a user has selected one or more records in the List Form, or a single record in the Detail Form, and clicks the "Delete" button. The flow of events are; 1. The user selects one or more records in the WUI and clicks "Delete". 2. A call is made to your On Delete Record method, for each selected record. 3. Function result; True The record can be deleted False The record cannot be deleted. For clarity, your method should display a message to the user, using Ltg_Msg_Error or Ltg_Msg_Warning, to explain the problem
Note: The record(s) will not be physically deleted, instead they will be added to the list of deleted records in the Recycle Bin and you should use the Ltg_RB_Filter method to remove them from record selections. See also Component Methods Ltg_RB_Filter Web User Interface (WUI) Table Editor
Callback Methods
55
On Display Record
Syntax: <your method name> The On Display Record callback is executed prior to displaying a single record in a Detail Form. See also Web User Interface (WUI) Table Editor
On List Records
Syntax: <your method name> The On List Records callback is executed prior to displaying records in a List Form/AutoComplete popup and can be used to control user access to certain records. See also Web User Interface (WUI) Table Editor
On Localise
Syntax: <your method name>(text; language) Text
Parameter text language Function result Type Text Text Text Description The text to localise The language code of the current user The localised text
The On Localise callback is provided to allow you to localise your application for a particular language. To implement this method callback, refer to the User Access section in the Web User Interface (WUI) chapter. See also Tags ltgbutton, ltgcaption Web User Interface (WUI) User Access
Callback Methods
56
On Login
Syntax: <your method name> The On Login callback is executed when a user session is opened. This method gives you the opportunity to perform any initialisation requirements prior to displaying the WUI. See also Component Methods Ltg_Session_GetProperties Web User Interface (WUI) User Access
On Logout
Syntax: <your method name> The On Logout callback is executed when a user session is closed. This method gives you the opportunity to perform any "cleanup" requirements. See also Component Methods Ltg_Session_GetProperties Web User Interface (WUI) User Access
Callback Methods
57
On New Record
Parameter Function result Type Boolean Description The record can be created
The flow of events are; 1. The user clicks "New". 2. A call is made to your On New Record method 3. Function result; True The new record is displayed in the Detail Form False Your method should display a message, using Ltg_Msg_Error, to explain the problem
See also Component Methods Ltg_Msg_Error Web User Interface (WUI) Table Editor
Callback Methods
58
On Password Forgotten
Syntax: <your method name>(user; email)
Parameter user email Type Text Text Description The name of the user The email address of the user
The On Password Forgotten callback is executed when a user submits the Forgotten Password form (below). This feature is activated once you enter your method name. Once activated, the login form will display a "Forgot your password?" link.
Forgotten Password form
See also Web User Interface (WUI) User Access
On Save Record
Parameter Function result Type Boolean Description The record can be saved
See also Web User Interface (WUI) Table Editor
Callback Methods
59
On Undelete Record
Parameter Function result Type Boolean Description The record can be removed from the Recycle Bin
The flow of events are; 1. The user selects one or more records in the WUI and clicks "Undelete". 2. A call is made to your On Undelete Record method, for each selected record. 1. Function result; See also Web User Interface (WUI) Table Editor True The record can be undeleted False The record cannot be undeleted
Callback Methods
60
On Validate Login
Syntax: <your method name>(user; password; group; role) Boolean
Parameter user password group role Function result Type Text Text Pointer Pointer Boolean Description User name Password Pointer to a Text variable to store the user group(s) Pointer to a Text variable to store the user role Login validated
If you are using a custom user name/password validation system, as opposed to the 4D builtin system (Toolbox Users), you should create a callback to your method. Example The following code represents a very simple example that validates two users, Designer and Administrator. Both are validated using their a password (in this example not casesensitive), all other user names will be rejected; C_BOOLEAN($0) C_TEXT($1;$2) C_POINTER($3;$4) C_BOOLEAN($flValid) Case of :($1="Designer") $3>:="Design" $4>:="Designer" $flValid:=($2="LetDesignerIn") :($1="Administrator") $3>:="Admin" $4>:="Administrator" $flValid:=($2="LetAdminIn") Else End case $0:=$flValid See also Web User Interface (WUI) User Access $flValid:=False
Callback Methods
61
JavaScript Functions
ltgExecuteMethod
Syntax: ltgExecuteMethod(method [; parameter])
Parameter method parameter Type Text Text Description The 4D method to execute Optional parameter
The ltgExecuteMethod JavaScript function can be used to execute a 4D method with an optional parameter. Example The following example is a checkbox element within a Lightning form which passes its current state to the 4D method "MyMethod" which then displays a JavaScript alert of the current state; <input type="checkbox" onchange="ltgExecuteMethod('MyMethod',this.value);" /> 4D Method MyMethod; C_TEXT($1) $nError:=Ltg_JS_Send("alert('Checkbox state is "+$1+"');") See also Component Methods Ltg_JS_Send
JavaScript Functions
62
Forms
Lightning v2.0 provides the facility to design forms for both Desktop and Mobile devices. Lightning supports the following form types;
Custom Form
Custom forms are intended to allow you to design a standard html form for display within the Lightning WUI. An example of Customs forms would be the Customer Location Maps found in the Lightning Sales demonstration database.
Detail Form
Detail forms are designed to view or edit an individual record. Example The following example illustrates the anatomy of a typical two column Detail form as found in the Lightning Sales demonstration database. The form anatomy is the same for both Desktop and Mobile versions; <ltgform > [<ltghead />] <ltgbuttons> <ltgbutton /> </ltgbuttons> <ltgdetail> <ltgrow> <ltgcol> <ltgtable> <ltgrow> <ltgcol> <ltgcaption /> </ltgcol> <ltgcol> <ltgfield /> </ltgcol> </ltgrow> </ltgtable> </ltgcol> <ltgcol> <ltgtable>
Forms
63
<ltgrow> <ltgcol> <ltgcaption /> </ltgcol> <ltgcol> <ltgfield /> </ltgcol> </ltgrow> </ltgtable> </ltgcol> </ltgrow> </ltgdetail> </ltgform>
List Form
List forms are designed to list multiple records. The tags used to create List forms for Desktop and Mobile applications are the same with the exception that Mobile List forms utilise fewer tags as can be seen in the examples below; Example The following example illustrates the anatomy of a List form for a "Desktop" application; <ltgform > <ltgnavigation/> <ltgbuttons> <ltgbutton /> </ltgbuttons> <ltglist> <ltglisthead> <ltgrow> <ltgcol> <ltgsort /> </ltgcol> </ltgrow> </ltglisthead> <ltglistfoot> <ltgrow> <ltgcol> <ltgfield /> </ltgcol>
Forms
64
</ltgrow> </ltglistfoot> <ltglistbody> <ltgloop> <ltgrow> <ltgcol> <ltgfield /> </ltgcol> </ltgrow> </ltgloop> </ltglistbody> </ltglist> </ltgform> The following example illustrates the anatomy of a List form for a "Mobile" application; <ltgform > <ltgnavigation/> <ltgbuttons> <ltgbutton /> </ltgbuttons> <ltglist> <ltglisthead> <ltgcaption /> </ltglisthead> <ltglistbody> <ltgloop> <ltgrow> <ltgfield /> </ltgrow> </ltgloop> </ltglistbody> </ltglist> </ltgform>
Forms
65
Select Form
Select forms are designed as an alternative List form used specifically for selecting a related record from a Detail form. Select forms share the same structure as List forms but allow you to present a different view for record selections. See also Tags Web User Interface (WUI) Form Editor
Forms
66
Tags
In addition to full support of the standard 4D HTML tags (4DVAR, 4DSCRIPT, 4DIF, 4DLOOP etc.), Lightning includes a macro tag language which is very similar to html and adopts the xHTML syntax. !Important: Lightning Tag attribute values must be enclosed with double quotes ("value") only and not single quotes ('value') or smart quotes (value). Please check this prior to reporting an error.
ltgbutton
Syntax: <ltgbutton action="<action>" class="<css class>" disabled="<true/false>" groups="<user groups>" method="<method name[/parameter]>" onclick="<javascript>" selection="<record selection>" style="<inline css>" table="<table name>" target="<target>" title="<title>" /> Attributes:
Attribute action class Description A specific internal action to execute Specifies the name of a css class. To specify multiple classes, separate the class names with a space. The corresponding class must either exist in a referenced external ".css" file or using a "<style>" tag within the form code Indicates whether the button is enabled or disabled The user groups(s) for which the button is visible The 4D method to execute when the button is clicked. You may also pass a single parameter. JavaScript code to execute when the button is clicked. The JavaScript is executed prior to calling any 4D method specified in the <method> attribute The record selection scope CSS style attributes The table name which the button relates to Specifies where to display the results The title of the button
disabled groups method onclick
selection style table target title
The ltgbutton tag is used to display a standard html button. The visual style of the button is initially determined by the "button" class of the current theme which may then be modified with the class and style attributes. The action attribute may be one of the following; cancel delete Cancels the current form and returns to the previous form. See also the On Cancel Record callback method. Deletes the current record of table. See also the On Delete Record callback method.
Tags
67
home new save
Navigates the user back to the "Home" page (mobile only) Creates a new record for table. See also the On New Record callback method. Saves the current record of table. See also the On Save Record callback method.
When used on a List form, the selection attribute can be used to create a selection of records, prior to calling a 4D method, as follows; checked current none A record selection will be created using those records whose checkboxes are checked in the List form. Validation will be performed to make sure at least 1 record is checked. A record selection will be created using all records in the current selection across all pages in the List form. The default behaviour. A record selection will not be created.
Examples The following example, taken from Lightning Sales, executes a callback method which displays a Google Map for each Customer record where the checkbox has been checked in the List form. <ltgbutton method="Customer_LocationMap" selection="checked" table="Customers" title="Map" /> The following example uses the "%" prefix which is the instruction to execute any On Localise callback method for a general string; <ltgbutton method="Customer_LocationMap" selection="checked" table="Customers" title="%Map" /> See also Callback Methods On Localise
Tags
68
ltgbuttons
Syntax: <ltgbuttons>...</ltg-buttons> The ltgbuttons tag is used to display a button bar within forms. The button bar will contain one or more ltg-button tags. See also Tags ltg-button
Tags
69
ltgcaption
Syntax: <ltgcaption class="<css class>" groups="<user groups>" header="<true/false>" style="<inline css>" title="<title>" />
Attribute class Description Specifies the name of a css class. To specify multiple classes, separate the class names with a space. The corresponding class must either exist in a referenced external ".css" file or using a "<style>" tag within the form code The user groups(s) for which the caption is visible Displays the caption as a header (h3) in the ltglisthead section CSS style attributes The title of the caption
groups header style title
The ltgcaption tag is used to display a caption (e.g. a field name) alongside fields and other form elements. The visual style of the caption is initially determined by the "caption" class of the current theme which may then be modified with the class and style attributes. Examples The following example displays the static text "Customer Name:"; <ltgcaption title="Customer Name:" /> The following example uses the "[" prefix which is the instruction to execute any On Localise callback method for a structure element (table or field); <ltgcaption title="[Customers]Customer_Name" /> The following example uses the "%" prefix which is the instruction to execute any On Localise callback method for a general string; <ltgcaption title="%Customer_Name" /> See also Callback Methods On Localise
Tags
70
ltgcol
Syntax: <ltgcol>...</ltg-col> The ltgcol tag is used to a new column. Note: The ltg-col tag is converted into a standard html "td" tag and supports all of the associated attributes. See also Forms
ltgdetail
Syntax: <ltgdetail>...</ltg-detail> The ltgdetail tag is used to define the main section of a Detail form. See also Forms
ltgdocument
Syntax: <ltgdocument var="<variable name>" />
Attribute var Description The name of a 4D process BLOB variable which must be declared in the "Compiler_Web" 4D method.
The ltgdocument tag allows the user to select a local document for uploading. See also Component Methods Ltg_Doc_Receive
ltgfield
Syntax: <ltgfield alt="<text>" autocomplete="<off/begins/contains/ends>" class="<css class>" disabled="<true/false>" editor="<editor name>" format="<format>" groups="<user groups>" hidden="<true/false>" key="<field name>" link="<table name>" list="<choice list>" method="<method name>" name="<field name>" mandatory="<true/false>" onblur="<javascript>" onchange="<javascript>" onclick="<javascript>"
Tags
71
onfocus="<javascript>" onmouseout="<javascript>" onmouseover="<javascript>" readonly="<true/false>" style="<inline css>" suppress="<true/false>" target="<target>" type="<html element type>" value="<value>" />
Attribute autocomplete class Description Sets the search comparison to use when displaying the AutoComplete popup Specifies the name of a css class. To specify multiple classes, separate the classnames with a space. The corresponding class must either exist in a referenced external ".css" file or using a "<style>" tag within the form code. Specifies the name of an installed and supported Javascript based text editor, for Text fields only. Sets the display format Refer to the formats available for the 4D STRING command. The user groups(s) for which the field is visible The hidden attribute, when set to "true" is used to store values that are not displayed on the form. Used in conjunction with the <link> attribute to provide an alternative lookup key value to the field specified in the <name> attribute Provides a hyperlink to a Detail form of <table> based on the value of the field specified in the <name> attribute, or alternatively, a lookup value specified using the value of the field in the <key> attribute An associated 4D Choice List, or userdefined list. A dropdown menu will be displayed containing the list items The 4D method to execute when the field value is changed The fully qualified field name Indicates whether the field must be completed prior to saving the record (true/false) JavaScript code to execute when the field loses input focus JavaScript code to execute when the field value is changed. The JavaScript is executed prior to calling any 4D method specified in the <method> attribute JavaScript code to execute when the field gains focus from the mouse pointer JavaScript code to execute when the field loses focus from the mouse pointer Indicates whether the field is readonly or enterable (true/false) CSS style attributes Suppresses (True) output in the case of empty values Overrides the default html element type based on the field value type An alternative value to display for List form fields
disabled editor format groups hidden key link
list method name mandatory onblur onchange
onmouseover onmouseout readonly style suppress type value
The ltgfield tag is used to incorporate 4D fields in Lightning forms. Examples The following example is a field on a List form which will be displayed as a hyperlink. When clicked, the form Lightning Developer Reference Tags 72
"Customer_Detail" from the [Customers] table will be displayed. The appropriate Customer record will be loaded based on the value of the [Sales_Orders]Customer_No field; Note: When using the link attribute without a key attribute, the primary field setting of the linked table will be used. See Web User Interface (WUI) Command Bar Tools Table Editor for this setting. <ltgfield name="[Sales_Orders]Customer_Name" link="[Customers]!Customer_Detail" key="[Sales_Orders]Customer_No" /> Fields placed in a Detail form where the field has a Many to One relation with another table, two icons will be automatically placed to the direct right of the field providing the readonly attribute has not been set to "false"; <ltgfield name="[Sales_Orders]Customer_No" method="SalesOrder_Customer" />
Field with a Many to One relation example
Select Record Clicking this icon will display a list of related records from the "One" table. If the user selects a record, any 4D method specified in the method attribute will be executed. Deselect Record Clicking this icon will remove the related value and execute any associated method specified in the method attribute.
Tags
73
Tags
74
Tags
75
Tags
76
Tags
77
Tags
78
Tags
79
Tags
80
Tags
81
Select Record example
In addition to the automatic "Select record" relational lookup feature, fields with a Many to One relationship also gain a relational "Autocomplete" feature. The following example, taken from the Lightning Sales Sales Order Items Detail form, demonstrates the use of the Autocomplete feature using the [Sales_Order_Items]Product_Code field which has a Many to One relationship with the [Products] table. As the user begins typing, a dropdown menu of available Products records is displayed. As the user continues to type, the dropdown interactively populates the listing without refreshing the page;
Tags
82
Autocomplete (examples)
The following example displays a list of choices using the list attribute to specify an inline list; <ltgfield name="[Sales_Orders]Payment_Terms" list="{7 Days, 14 Days, 30 Days, 60 Days}" /> The following example displays a list of choices using the list attribute to specify a 4D Choice List; <ltgfield name="[Sales_Order_Items]Tax_Rate" list="Tax Rates" /> The following example displays a supported editor "ckeditor" to provide rich text editing for a text field; <ltgfield editor="ckeditor" name="[Customers]Notes" /> Note: At this time ckeditor is the only supported editor. Please visit www.ckeditor.com for more information.
Tags
83
ltgform
Syntax: <ltgform method="<method name>" name="<form name>" [height="height" width="width"] relatemany="<true/false>" relateone="<true/false>" type="<form type>">...</ltgform>
Attribute height method name relatemany relateone type width Description Specifies the height, in pixels, of "popup" Custom forms displayed within an AJAX callback. A 4D method to execute when the form is loaded The name of the form. This will be automatically updated via the Form Editor. Automatically relate all ONE records. The default is "false". Automatically relate all MANY records. The default is "false". The type of the form. This will be automatically updated via the Form Editor. Specifies the width, in pixels, of "popup" Custom forms displayed within an AJAX callback.
The ltgform tag should be placed at the top of the form code and closed at the bottom of the form code. The method attribute can be used to execute a 4D method prior to displaying the form content, it is the equivalent of executing a method during the On Load event in native 4D forms. !Important: If you do use the method attribute, this will override any On Display Record (Detail forms) or On List Records (List forms) callback method you set via the Table Editor. Example The following example, taken from Lightning Sales, is placed at the top of the Sales Orders List form, and executes a method which filters records depending on user access rights. <ltgform method="SalesOrder_List" name="Sales_Orders List" relateone="true" type="list"> ...code... </ltgform> See also Callback Methods On Display Record, On List Records Forms Web User Interface (WUI) Table Editor
Tags
84
ltghead
Syntax: <ltghead title="<form title>" />
Attribute title Description The title to display for the current form
The ltghead tag can be used to override the default title of a Detail form. The default title will be made up of the localised table name and Description field as set via the Table Editor. Example <ltghead title="[Customers]Customer_Name" /> See also Web User Interface (WUI) Table Editor
ltgif
Syntax: <ltgif test="<condition>">[<ltgelse></ltgelse>]</ltgif>
Attribute test Description A logical condition to evaluate
The ltgif tag and associated ltgelse tag may be used to test a condition and branch to a section of code to execute depending on the result. Example The following example tests the value of [Customers]Credit_Limit to determine if it is zero or less and displays a message depending on the result; <ltgif test="[Customers]Credit_Limit <= 0"> <span style="color: red;">Customer does not have a credit limit!</span> <ltgelse/> <span style="color: green;">Customer is good to go!</span> </ltgif> See also Tags ltgswitch
Tags
85
ltginclude
Syntax: <ltginclude groups="<user groups>" name="<form name>" table="<table>" />
Attribute groups name table Description The user groups(s) for which the form is visible The name of the form The name of the table the form is associated with
The ltginclude tag may be used to include additional forms within the current form. The name attribute may be either an actual form name or one of the following; !Detail Specifies the default Detail form of table !List Specifies the default List form of table
Example <ltginclude name="!List" table="Sales_Order_Items" />
ltglist
Syntax: <ltglist>...</ltglist> The ltglist tag is used to define the main section of a List form. See also Forms
ltglistbody
Syntax: <ltglistbody>...</ltglistbody> The ltglistbody tag is used to define the body section of a record listing. See also Tags ltgfield, ltgselect
Tags
86
ltglistfoot
Syntax: <ltglistfoot>...</ltglistfoot> The ltglistfoot tag is used to define the footer section of a record listing.
ltglisthead
Syntax: <ltglisthead>...</ltglisthead> The ltglisthead tag is used to define the header section of a record listing. See also Tags ltgsort
ltgloop
Syntax: <ltgloop>...</ltgloop> The ltgloop tag is used to loop through records in a List form. See also Forms
Tags
87
ltgmethod
Syntax: <ltgmethod name="<name>" />
Attribute name Description The name of the 4D method to execute from the host database
The ltgmethod tag is designed to execute a method with optional parameters in the host database from within the WUI. !Important Your method must declare the two following variables regardless of whether they are used by the method; C_TEXT($0) ` Return value C_TEXT($1) ` Single parameter Example The following example will execute a method named "MyMethod". The parameters "/Param1/Param2/Param3" will be passed as a single text value to the method, however you can use the method Ltg_Str_ToArray to extract each parameter which are delimited with the "/" character; <ltg-method name="MyMethod/Param1/Param2/Param3" /> See also Component Methods Ltg_Str_ToArray
Tags
88
ltgnavigation
Syntax: <ltgnavigation /> The ltgnavigation tag is used to display a navigation bar within List forms;
Navigation Bar (Desktop example)
ltgrow
Syntax: <ltgrow>...</ltg-row> The ltgrow tag is used to create a new row. Note: For Desktop only applications, the ltg-row tag is converted into a standard html "tr" tag and supports all of the associated attributes. See also Forms
ltgselectall
Syntax: <ltgselectall counter="<true/false>" />
Attribute counter Description Displays the count of selected records
The ltgselectall tag is designed to be used in the ltglisthead area of a List form and should be combined with ltgselect tags in the ltglistbody section to allow the user to select all records being displayed on the current page of a List form. The optional counter attribute will display the count of selected records when set to "true". See also Tags ltglisthead, ltgselect
Tags
89
ltgselect
Syntax: <ltgselect /> The ltgselect tag is designed to be used in the body area of a List form and allows the user to select a single record.
ltgsort
Syntax: <ltgsort name="<field name>" title="<title>" />
Attribute name title Description Fully qualified field name The title for the heading
The ltgsort tag is designed to be used in the ltghead section of a List form and allows the user to sort records on an individual field. Example <ltgsort name="[Customers]County" title="County" />
Tags
90
ltgswitch
Syntax: <ltgswitch test="<condition>"><ltgcase>...<ltgbreak/></ltgcase><ltg default>...</ltgdefault></ltgswitch>
Attribute test Description A logical condition to evaluate
The ltgswitch tag may be used to test a condition and branch to a section of code to execute upon a successful match. You can use the ltgbreak tag to exit the switch statement upon a successful match, if you do not use the ltgbreak tag, the remaining case statements will be processed. You should use the ltgdefault tag for trapping instances where a matching case has not been found. Example The following example test the value of the current day number and outputs the associated day name; <ltgswitch test="Day number(Current Date)"> <ltgcase value="1"> <p>Today is Sunday</p><ltgbreak/> </ltgcase> <ltgcase value="2"> <p>Today is Monday</p><ltgbreak/> </ltgcase> <ltgcase value="3"> <p>Today is Tuesday</p><ltgbreak/> </ltgcase> <ltgcase value="4"> <p>Today is Wednesday</p><ltgbreak/> </ltgcase> <ltgcase value="5"> <p>Today is Thursday</p><ltgbreak/> </ltgcase> <ltgcase value="6"> <p>Today is Friday</p><ltgbreak/> </ltgcase> <ltgdefault> <p>Today is Saturday!</p> </ltgdefault> </ltgswitch> See also Tags ltgif Lightning Developer Reference Tags 91
ltgtable
Syntax: <ltgtable>...</ltg-table> The ltgtable tag is used to create a new table. Note: The ltg-table tag is converted into a standard html "table" tag and supports all of the associated attributes. See also http://www.w3schools.com/html/html_tables.asp
ltgvar
Syntax: <ltgvar name="<name>" />
Attribute name Description The name of a process or inter-process variable from the host database
The ltgvar tag is designed to allow the use of variable values from the host database within the WUI. Examples The following example displays the value of "txtToday"; Today is <ltg-var name="txtToday" /> The following example demonstrates the use of ltg-var with JavaScript; if ('<ltg-var name="txtToday" />' == 'Saturday') { alert('Take the rest of the day off!'); } See also Host Methods Ltg_Var_Get
Tags
92
Web User Interface (WUI)

Overview
The Lightning Web User Interface (WUI) consists of the following visual and functional elements; Command Bar Tab Bar Sidebar Content area
lightningxml
Lightning uses xml files to store and retrieve data. The lightningxml folder will be created automatically for a new installation and is placed in the host database folder. The necessary files will be created when you install and startup Lightning in your own database, they are; application.xml Application settings forms.xml Form information and code licence.xml Licence details log.xml Logging information recentitems.xml The last 10 items viewed for each user recyclebin.xml Deleted records available for recycling searches.xml A variety of user specific search options and criteria tables.xml Table information and settings users.xml User information
WebFolder
lightningcustom
The lightningcustom folder is where you can store your own files such as images, scripts and stylesheets. The lightningcustom folder has the following structure;
images
The images folder is where the logos for the Login and main WUI forms are placed for both Desktop and Mobile applications, together with your own application specific image files. This folder also contains the favicon.ico file which is used to display an icon in the browser address bar.
93
scripts
You can use the scripts folder to store your own JavaScript library files.
themes
You can use the themes folder to store your own custom themes.
lightningweb
The lightningcustom folder has the following structure;
<root>
The root of lightningweb contains the Desktop versions of the Home, Login, Messages, Password Forgotten and Registration forms.
mobile
The mobile folder contains the necessary files for Mobile applications.
modules
The modules folder contains various files that are dynamically included within the WUI when required.
scripts
The scripts folder contains JavaScript code libraries.
themes
The themes folder contains the standard visual themes. To create your own theme, copy one of the existing theme folders, rename the folder to a suitable theme name and place it in the themes folder of lightningcustom. You can then edit the style.css file and change/add any images in the images subfolder to suit.
xliff
The xliff folder contains language translation files for all supported languages.
xml
The xml folder contains a file to encode and decode reserved HTML entities See also Component Methods Ltg_Folder_Get
94
Command Bar
Note: The Command Bar is currently only available for Desktop applications.
The Command Bar (example)
Synch
Whenever you make changes to your 4D structure by adding or modifying tables, you should tell Lightning about these changes by clicking the Synch command. If any synch issues are encountered, they will be listed within the content area with instructions on how to resolve them. !Important: Do not navigate away from the page or click another link until this operation has completed.
95
Tools
Note: The Tools command and associated items are currently only available for Desktop applications.
Application
The Application command allows you to set application specific options;
Application settings
Application name The name of the application as it should appear in the browser window title Display all tabs Turns the display of the "..." tab on or off Display sidebar Turns the display of the sidebar on or off
96
Forms
The Forms command allows you to list, maintain and create the various forms for your application. Click on a Form name to access the Form Editor and the available options and code;
Forms List (example)
97
Form Editor
The Form Editor includes a code editor, so you are able to develop forms inside your browser from any location, rather than having to logon to your server and update individual html files. You can however copy/paste content from/into the code editor using your favourite html editor if required. Clicking on "Show options" will display the available options;
Form Editor options
Form name A unique name to describe the form Table name The table the form is associated with Form type The form type which can be "Custom", "Detail", "List" or "Select" Default Indicates whether the form is the default for the selected form type
98
99
100
101
102
103
Form Editor (example)
Note: The colourised code editor is not compatible with certain browsers, if you do use these browsers to code your forms then you can use the "Toggle editor" settings to use a plain text version. Desktop The form code for the Desktop version of the form Mobile The form code for the Mobile version of the form
See also Getting Started System Requirements
104
Tables
The Tables command allows you to list and maintain table and field options for all of the visible tables within your 4D structure. Click on a Table name to access the Table Editor.
Tables List (example)
Table Editor
Section Table Table Option Table name Form icon Description The name of the table An icon file to use when displaying table records in the List and Detail forms and the Recent Items listing. The recommended location for the file is in the images subfolder of the lightningcustom folder. The 4D project method to execute before records are displayed in a List form. The 4D project method to execute before a record is displayed in a Detail form. The 4D project method to execute when a record is created. The 4D project method to execute when a record is saved. The 4D project method to execute when a record is cancelled. The 4D project method to execute before a record is deleted.
Methods Methods Methods Methods Methods Methods
On List Records On Display Record On New Record On Save Record On Cancel Record On Delete Record
105
Methods User Groups User Groups User Groups User Groups User Groups
On Undelete Record Create Records Delete Records Read Records Undelete Records Write Records
The 4D project method to execute before a record is undeleted. The user group(s) allowed to create records for the current table The user group(s) allowed to delete records for the current table The user group(s) allowed to read/view records for the current table The user group(s) allowed to undelete records for the current table The user group(s) allowed to write/modify records for the current table
Fields
Section Primary Field Description Field Option Primary Field Description Field Description The primary field used to identify records. This field must be mandatory and unique. The field used to describe a record in the Recent Items list, Select related record list and the title bar of the Detail form.
Records
Section Recycling Sequence Numbers Sequence Numbers Sequence Numbers Option Retention Period Next Number Format Reusable Numbers Description The number of days a deleted record will be retained before it is recycled. The next unique sequence number to use (if no reusable numbers are available). See the Ltg_SqNo_Get Component Method. A custom numbering format to use for alphanumeric fields Unique sequence numbers available for reuse.
Search
Section Quick Search Quick Search Option Comparison Fields Description The default Quick Search comparison for new user accounts The default Quick Search fields for new user accounts
106
Tabs
The Tabs command allows you to maintain which tables appear as tabs in the header area of the WUI and the order in which they appear;
Tabs (example)
Available Tables that are available to place in the Tab Bar
Selected Tables which have been selected for display in the Tab bar and the order in which they appear
Note: Tabs are displayed based on the current user access rights for the associated table. The minimum requirement is "Read" access otherwise the tab is hidden. See also Web User Interface (WUI) Table Editor
107
User Access
User Access (example)
Section Methods
Option On Validate Login
Description The 4D method to execute when validating individual user logins. If left blank, the 4D User/Password system will be used, otherwise your own access system can be used by placing a call to your method here. The 4D method to execute when a user logs in and a new session is created. The 4D method to execute when a user either manually performs a logout, or their session expires. The 4D method to execute when localising structure and text values The 4D method to execute when a user clicks on the "Forgot your password?" link. This link will appear once you have entered a method name. Specifies the number of minutes that a session can remain idle before it is automatically terminated. When this setting is "on" a checkbox will appear on the Login form so that the user can save their username to a local cookie. In conjunction with the above, the password of the user will also be saved to a cookie. The password will not be encrypted so use of this feature is at the discretion of the developer. The date format for display and data entry validation, either dd/mm/yyyy or mm/dd/yyyy depending on the users location. The theme the user has selected
Methods Methods Methods Methods
On Login On Logout On Localise On Password Forgotten
Sessions Cookies Cookies
Session Timeout Remember user name Remember password
Users (listing) Users (listing)
Date format Theme
108
Log
The log command will display the user actions captured in the "log.xml" file,
Log (example)
Actions captured are; Delete Record deletion Edit Record edit Login User login Logout User logout Undelete Record undeletion
See also Web User Interface (WUI) lightning-xml
109
Sessions
The Sessions command displays a form which lists all active users sessions, including the user name, user role, chosen application type, login time and last access time (connection request).
Sessions form (example)
110
Search
Note: The Search Editor is currently only available for Desktop applications. Mobile applications will still have access to the Quick Search feature, which shares the settings from the Desktop version;
(Quick Search Mobile example)
Note: The remainder of this section is solely for the Desktop version... Clicking on the Search command dropdown icon will present the user with a menu of further options;
Search Options dropdown (example)
111
Advanced Search
The Advanced Search facility is similar to the 4D Query editor, allowing the user to build and save complex queries. The example below uses two fields from a [Customers] table. Both fields have an associated 4D Choice List and the available list items are presented via a drop-down menu for selecting a list item value;
Search Editor Advanced Search (example)
Clicking on "Show options" will display the available options;
Advanced Search Options
112
Searches Allows the user to load a previously saved search Description The description of the saved search Method A 4D method to execute to perform the search as an alternative to using the editor Available to The users for whom the saved search is available to
Searches which have been saved using the Advanced Search editor will be listed in the Search Options drop down menu for the appropriate table.
113
Quick Search
Quick Search is activated either by entering a value in the Quick Search text box and clicking "Search", pressing the "Enter" key, or directly from the Quick Search tab of the Search Editor. The current table is selected by default but you can add more tables using the "Scope" section. Each table that is selected for the Quick Search will have their results displayed within the content area. When additional tables are selected from the "Scope" section they will be searched on the basis that one or more field names match those selected in the "Fields" section of the current table. Note: The Quick Search facility requires each user to specify which fields to query, clicking on the "Reset" button will default the current settings to those entered in the Table Editor Search tab, new users will receive these settings automatically. If the Quick Search settings have not been created for the current user they will receive a warning message.
Quick Search text box - search for "vacations"
Search Editor Quick Search (example)
114
Settings
Note: The Settings form is currently only available for Desktop applications. The user settings form is selected by clicking on the Username link to the left of the Logout link;
This form allows the user to change the current theme.
User Settings form
See also Web User Interface (WUI) WebFolder Themes
115
Tab Bar
Please refer to the Tabs section of the Command Bar for more information on configuring tabs.
Tab Bar (Desktop example)
Tab Bar (Mobile example)
116
Sidebar
Note: The Sidebar is currently only available for Desktop applications. The Sidebar is a collapsible panel that appears to the direct left of the content area and provides access to some useful features;
Quick Create
Quick Create, displayed as "New...", provides a drop down list of available tables, clicking on a table name will allow the user to create a new record for the selected table. Note: When a table is selected, Lightning will check if you have provided a method for the On New Record callback and execute accordingly.
Recent Items
The Recent Items facility provides the user with the last, 15 as default, records they viewed, and the order in which they were viewed.
Recycle Bin
The Recycle Bin allows the user to view and undelete records that have been previously deleted.
Sidebar (example)
Recycle Bin Listing (example)
117
Content Area
The Content Area is used for displaying Detail, List, Custom forms and Messages.
Content Area List Form (Desktop example)
Content Area List Form (Mobile example)
118
Content Area Detail Form (Desktop example)
Content Area Detail Form (Mobile example)
119
Troubleshooting
On Web Authentication
If you are using the On Web Authentication 4D Database Method you may encounter problems with Lightning. You should update your code to always return True whenever a Lightning connection request is being processed.
4D Compatibility Settings
4D Databases upgraded from earlier versions of 4D may need to have their Compatibility Settings updated to work with Lightning. Please check you have the correct settings as below;
4D v11 Web Compatibility Settings
4D v12/v13 Web Compatibility Settings
120
NTK Web Server

You may receive the following error when attempting to lanch the NTK based Web Server;
NTK Web Server Startup error
This may be due to the following; You are using Mac OSX via port 80 Change the port to 8080 and retry You have checked "Enable SSL" in the 4D Web Server settings Uncheck this option and retry
121
Appendix A. Error Codes and Descriptions

Startup Errors
Error code 5000 5001 5002 5003 5004 5005 5006 5007 5008 Description 4D v11.4 or greater is required The 4D Web Server has not started Cannot load xml Cannot load html Cannot load xliff Cannot load themes Lightning has not started Lightning has already started Licence not available for the Web Server
Licence Errors
Error code 5100 5101 Description The demonstration time limit has expired Invalid licence number
Parameter Errors
Error code 5200 5201 5202 Description Invalid number of parameters Invalid parameter type Invalid table
Session Errors
Error code 5300 5301 5302 Description Session not found Session has timed out Session access denied
Appendix A. Error Codes and
122
Recycle Bin Errors

Error code 5400 5401 Description The record does not have an entry in the Recycle Bin The record could not be removed from the Recycle Bin
Document Errors
Error code 5500 5501 Description Empty document path Cannot upload document
Form Errors
Error code 5600 Description Form not found
User Validation Errors

Error code 5700 Description Invalid user (username and/or password)
Appendix A. Error Codes and Descriptions
123

Lightning Developer Reference v2.0.0

Загружено:

Сведения о документе

Исходное описание:

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

Lightning Developer Reference v2.0.0

Загружено:

Авторское право:

Доступные форматы

Lightning

Software Licence Agreement

Lightning Developer Reference

What's New in Version 2.0?.....................................................10

The Recycle Bin.....................................................................18

Lightning Developer Reference

Lightning Developer Reference

Web User Interface (WUI).......................................................85

Appendix A. Error Codes and Descriptions...............................109

Lightning Developer Reference

Why should I use Lightning?

Lightning Developer Reference

Web Server Licence

Lightning Developer Reference

What's New in Version 2.0?

New Callback Methods

New Component Methods

Lightning Developer Reference

What's New in Version 2.0?

Ltg_Str_ToArray Ltg_Table_GetCurrent Ltg_Table_GetReturn Ltg_User_GetValue Ltg_User_SetValue Ltg_Users_Get Ltg_Version_Get

New JavaScript Functions

Lightning Developer Reference

What's New in Version 2.0?

4D Web Server port warning

Lightning Developer Reference

Database Folder Stage 1

Lightning Developer Reference

Database Methods Stage 2

Lightning Developer Reference

Web Server Publishing Stage 3

Lightning Developer Reference

Lightning Sales Login Form (Desktop)

Lightning Sales Login Form (Mobile)

Lightning Developer Reference

Lightning Developer Reference

The Recycle Bin

Lightning Developer Reference

The Recycle Bin

Lightning Developer Reference

The Recycle Bin

Lightning Developer Reference

Lightning Developer Reference

Lightning Developer Reference

Lightning Developer Reference

Lightning Developer Reference

Lightning Developer Reference

Lightning Developer Reference

Lightning Developer Reference

Lightning Developer Reference

Lightning Developer Reference

Lightning Developer Reference

Lightning Developer Reference

Lightning Developer Reference

Lightning Developer Reference

Lightning Developer Reference

Lightning Developer Reference

Lightning Developer Reference

Lightning Developer Reference

Lightning Developer Reference

Lightning Developer Reference

Lightning Developer Reference

Lightning Developer Reference

Lightning Developer Reference