4D Ajax FrameWork

Developer’s Guide

4th Dimension®
© 1985 - 2007 4D SAS/4D, Inc. All rights reserved.
4D Web 2.0
4D Ajax Framework Developer’s Guide
Copyright© 1985 - 2007 4D SAS / 4D, Inc.
All rights reserved.

The software and the manual are copyrighted and may not be reproduced in whole or in part except for the
personal licensee’s use and solely in accordance with the contractual terms. This includes copying the elec-
tronic media, archiving, or using the software in any manner other than that provided for in the Software
license Agreement.
4D, 4D Draw, 4D Write, 4D Insider, 4th Dimension®, 4D Server and the 4th Dimension and 4D logos are reg-
istered trademarks of 4D S.A.S.
Windows, Windows NT, Windows XP and Microsoft are registered trademarks of Microsoft Corporation.
Apple, Macintosh, Mac OS, Mac OS X, QuickTime are trademarks or registered trademarks of Apple Com-
puter Inc.
Mac2Win Software Copyright © 1990-2007, is a product of Altura Software, Inc.
This product includes software developed by the Apache Software Foundation (http://www.apache.org/).
4th Dimension includes cryptographic software written by Eric Young ([email protected])
4th Dimension includes software written by Tim Hudson ([email protected]).
Spellchecker © Copyright SYNAPSE Développement, Toulouse, France, 1994-2007.
ACROBAT © Copyright 1987-2007 Secret Commercial Adobe Systems Inc. All rights reserved. ACROBAT is a
registered trademark of Adobe Systems Inc.
All other referenced trade names are trademarks, registered trademarks, or copyrights of their respective
holders.
Contents

Developer’s Guide. . . . . . . . . . . . . . . . .5
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
4D Ajax Framework Concepts . . . . . . . . . . . . . . . . . . . 5
Localization . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Developer Hooks . . . . . . . . . . . . . . . . . . . . . . . 6
Views or Selections . . . . . . . . . . . . . . . . . . . . . . 6
Callbacks. . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Setting Preferences. . . . . . . . . . . . . . . . . . . . . . . . . 7
Language and Interface Settings . . . . . . . . . . . . . . . 7
General Settings . . . . . . . . . . . . . . . . . . . . . . . . 8
Managing User Authentication and Sessions . . . . . . . . . . . 9
Authentication Developer Hooks . . . . . . . . . . . . . . 10
Managing Data Modification . . . . . . . . . . . . . . . . . . 15
DAX_DevHook_SaveRecord . . . . . . . . . . . . . . . . . 15
DAX_DevHook_DeleteRecord . . . . . . . . . . . . . . . . 16
Creating DCS Views . . . . . . . . . . . . . . . . . . . . . . . 17
DAX_DevHook_DCS_ViewAdd . . . . . . . . . . . . . . . 17
DAX_DevHook_DCS_SetSelection . . . . . . . . . . . . . 19
DAX_DevHook_DCS_RecordSave . . . . . . . . . . . . . . 21
DAX_DevHook_DCS_RecordDelete . . . . . . . . . . . . . 23
Creating DDW Views . . . . . . . . . . . . . . . . . . . . . . 24
Creating Callbacks . . . . . . . . . . . . . . . . . . . . . . . . 25
DAX_DevHook_InstallCallBack . . . . . . . . . . . . . . . 26
Method to be executed on a Callback. . . . . . . . . . . . 26

4D Ajax Framework Developer’s Guide 3

Contents

4 4D Ajax Framework Developer’s Guide

 Developer’s Guide

Overview
4D Ajax Framework allows 4D developers to add web browsing
integration into their applications. Using Ajax technology, 4D
developers can offer the end-user a rich web 2.0 interface that can
browse, add, modify and delete records from the underlying database.
4D Ajax Framework includes a component and a full Javascript
framework that is available for integration into existing HTML pages.
Experienced 4D web developers will be able to use the DAX API
(Javascript framework) to quickly add 4D Ajax Framework objects into
their existing HTML/Javascript pages.

4D Ajax Framework Concepts

Although 4D Ajax Framework will provide full functionality without
any modifications by the developer, many 4D developers will want to
take advantage of some of the more powerful advanced options that
are available.

Localization Ajax Framework uses a localization technique that allows developers to

deploy their applications in most languages. All messages that are
displayed in the application interface and on the web front end are
retrieved from XML files located in the \Extras\Support folder. By
default these messages appear in English.
■ Localized_strings.xml
This file contains the progress, alert and confirm messages that are dis-
played in the 4D interface. Any time Ajax Framework needs to display
a message, Ajax Framework will find an appropriate translation based
on the value that was set in the variable <>DAX_Language_t (see Set-
ting Preferences below).

4D Ajax Framework Developer’s Guide 5

 

4D Ajax Framework Concepts

The developer can add new language elements by editing the XML file.
For example, if you want the " Ajax Framework Initializing" startup
message to appear in Spanish, simply add a <es> element as a child of
the <DAXInitializing> element with the message in Spanish as the
element value.
■ en_errors.xml
This file contains all of the error messages that are sent to the front
end. By default, the name of the file matches the language value set in
the variable <>DAX_Language_t ("en"). You can create an error file for
another language by duplicating the en_errors.xml file and changing
the contents of the <message> nodes.

❿ To create an error file for a different language:

1 Duplicate the en_errors.xml file.
2 Rename the duplicate file to begin with the language that you set in
<>DAX_Language_t (fr_errors.xml for example).
3 Go through the new file and translate the contents of all of the
<message> nodes to the language you are adding.

Developer Hooks Developer Hooks allow the 4D developer to override certain default
Ajax Framework behaviors and to trap various events. Use of the
Developer Hooks is optional. The only editable methods within the
Ajax Framework component are named DAX_DevHook... The only
callable methods in the Ajax Framework component are named
DAX_Dev_... Use of the various available developer hooks is discussed
later in this document.

Views or Selections A view or selection is a window that displays data or other content to
the user. The simplest example of this is the window that opens and
displays the list of records when a table name is clicked on in the
Portals sidebar. You can create various custom views within the Ajax
Framework component to be added to the list of tables that appears by
default.

Developer Created Developer Created Selections (DCS) are views that are completely array
Selections driven. The developer defines the view through 4D code and provides
arrays with the data that is used in the view. See Creating DCS Views
later in this document for more information.

6 4D Ajax Framework Developer’s Guide

 Setting Preferences

Developer Defined Developer Defined Windows (DDW) are views that can contain any
Windows HTML content. They are not generally for displaying a list of data but
instead available to display a complete web page within the front-end
user interface. A DDW can open a link to an external site such as
http://www.4d.com or call back to the developer's existing web code
with a link such as /4dcgi/mymethod. A DDW can also be sent an
HTML blob directly. This allows the developer to create a web page in
memory and deliver it to the front-end.

Callbacks Callbacks act similar to 4D's form events. A callback can be assigned to
a field within the input form and call 4D code when a particular event
occurs (currently On Load and On Data Change). For example, an
email address can be validated when a user tabs out of the email
address field and the user can be given immediate feedback if the
address is determined to be invalid. See Creating Callbacks later in this
document.

Setting Preferences
4D Ajax Framework has several global preferences that you can adjust
to your specific needs. To change the default settings, open the project
method DAX_DevHook_Preferences and edit the variable values
defined below.

Language and There are two 4D Ajax Framework language settings. The first setting
Interface Settings determines what language 4D Ajax Framework should use when
displaying information dialogs in the 4D interface during startup and
shutdown. The second determines what language 4D Ajax Framework
uses when displaying information to the front-end (web browser) user
interface.

The language used in the 4D interface is determined by the variable

<>DAX_Language_t. This value must correspond to a valid language in
the Localized_strings.xml file (see Ajax Framework Concepts above).
The default value is “en” for English.

4D Ajax Framework Developer’s Guide 7

Setting Preferences

▼ Example
<>DAX_Language_t:="en" ` set the 4D interface language to English

The language to use for the Ajax Framework front-end can be installed
on a group by group basis. To install a language for a particular group,
make a call to the project method DAX_Dev_InstallLanguage inside
the DAX_DevHook_Preferences method. By default the front-end will
use English for all groups.
▼ Example
DAX_Dev_InstallLanguage ("Admins";"en")
` set the language for Admins to English
DAX_Dev_InstallLanguage ("Group A";"fr")
` set the language for Group A to French
To suppress the startup and shutdown status messages in 4D set the
variable <>DAX_DisplayMessages_b to False. Critical error alerts will
still be displayed.
▼ Example
<>DAX_DisplayMessages_b:=False ` Turn off messages
<>DAX_DisplayMessages_b:=True ` Turn on messages

General Settings There are several general settings 4D Ajax Framework uses in
conjunction with its various features.

User's sessions automatically expire after a given period of inactivity.

You can set this time period in the variable
<>DAX_CONN_TIMEOUT_m. By default, sessions will expire after one
hour. Set the variable to ?00:00:00? to have sessions never timeout.
▼ Example
<>DAX_CONN_TIMEOUT_m:=?01:00:00?
` expire sessions after 1 hour of inactivity

The 4D Ajax Framework record locking system automatically releases a

lock after a given period of inactivity. You can set this time period in
the variable <>DAX_LOCK_TIMEOUT_m. By default a lock will expire
after five minutes. Set the variable to ?00:00:00? to have locks never
timeout .

8 4D Ajax Framework Developer’s Guide

 Managing User Authentication and Sessions

▼ Example
<>DAX_LOCK_TIMEOUT_m:=?00:05:00?
` expire locks after 5 minutes of inactivity

When a new view is created from the Admin area of the 4D Ajax
Framework front-end the related tables are displayed so data may be
combined from multiple tables. The number of relations to follow is
set in the variable <>DAX_Rel_DepthLevel_l. By default this value is set
to eight. It is recommended that this value not be increased.
▼ Example
<>DAX_Rel_DepthLevel_l:=8

4D Ajax Framework has a daemon process that runs continuously in

the background. This process periodically writes 4D Ajax Framework
preferences to disk and cleans up memory being used for user sessions
that have expired. By default this process wakes up and runs every
thirty minutes.
▼ Example
<>DAX_DAEMONDELAY_m:=?00:30:00?

Managing User Authentication and Sessions

By default 4D Ajax Framework will use the built in 4D Users and
Groups system for users login and group management. 4D Ajax
Framework also has its own internal session management system. You
can override the DAX login system, the 4D Ajax Framework login
system and session management, or just let 4D Ajax Framework handle
both for you. You cannot override session management unless you are also
overriding login.

If you already have your own login system in place, for instance a
Users table, you can hook into the 4D Ajax Framework
implementation and authorize users yourself. If you also have your
own session management system you can hook into the 4D Ajax
Framework session implementation and validate the sessions yourself
as well.

4D Ajax Framework Developer’s Guide 9

Managing User Authentication and Sessions

Authentication
Developer Hooks
DAX_DevHook_Login DAX_DevHook_Login is used by the Developer to override the 4D Ajax
Framework login system. By default 4D Ajax Framework uses the 4D
Users and Groups system to authenticate users when they login using
the 4D Ajax Framework login object. If you have your own login
system you can hook into the login process using this method and take
over user validation. If you are using the 4D Ajax Framework login
system (4D Users and Groups) you do not need to modify this method.

DAX_DevHook_Login receives six text parameters. These six

parameters are identical to the ones that are received in the On Web
Connection database method. Therefore you can call the same
authentication code you would normally call from On Web
Connection.
■ Passed Parameters:
$1 TEXT - URL that has been requested by the client
$2 TEXT - Header text from the request
$3 TEXT - Client IP Address
$4 TEXT - Server IP Address
$5 TEXT - User Name (from HTTP Authorization)
$6 TEXT - Password (from HTTP Authorization)
■ Returned Value:
$0 BOOLEAN - Did this user successfully log in?

Using the system you currently have in place you validate the user
name and password. This most likely involves querying a table for the
user name and password to authenticate the user. If you are using the
4D Ajax Framework login object on the web page you can retrieve the
user name and password using the following calls:
$userName_t:=DAX_Dev_GetWebVar ("username")
$password_t:=DAX_Dev_GetWebVar ("password")

If the user has successfully logged in, you return True from this
method and, if their login fails, you should return False.

When you are using the DAX_DevHook_Login method to validate

users yourself, you must pass 4D Ajax Framework some information
about the user.

10 4D Ajax Framework Developer’s Guide

 Managing User Authentication and Sessions

Upon Successful Login

1 You must call DAX_Dev_Session_UserName and pass the user's user
name.
2 If the user should have Admin privileges, call
DAX_Dev_Session_Admin and pass True; otherwise, pass False or
simply don't call the method.
A user with Admin privileges can make changes to what tables and
fields are displayed using the Admin object on the web page. Generally
very few users should have this ability.
3 If you are also planning on handling sessions with your own session
management system, you will need to provide the session id you will
be using for this user by calling DAX_Dev_Session_SessionID and
passing the session id you are using for this user.

Upon Failed Login If the login is not successful, you must pass an error code to Ajax
Framework. If you return False from this method and do not pass an
error code, Ajax Framework will attempt to log the user in. To set a
login error code call DAX_Dev_Session_Error and pass an appropriate
error code.

Login error codes include:

LoginPasswordMissing
LoginUsernameMissing
UserNotFound
InvalidUsernameOrPassword
▼ Successful Example:
DAX_Dev_Session_UserName ($userName_t)
DAX_Dev_Session_Admin ($isAdmin_b)
DAX_Dev_Session_SessionID ($sessionID_t)
$0:=True
▼ Failed Example:
DAX_Session_Error ("LoginPasswordMissing")
$0:=False

4D Ajax Framework Developer’s Guide 11

Managing User Authentication and Sessions

DAX_DevHook_SessionV DAX_DevHook_SessionValidate is used by the developer to override

alidate the default 4D Ajax Framework session management system. By
default 4D Ajax Framework uses an internal session management
system to authenticate users when they make various 4D Ajax
Framework requests. If you have your own session management
system, using a Sessions table for example, you can hook into the
session process using this method and take over session validation.
You must have first modified DAX_DevHook_Login and provided a
session id before using this developer hook. If you are using the default
4D Ajax Framework session management system, you do not need to
modify this method.

DAX_DevHook_SessionManagement receives six text parameters.

These six parameters are identical to the ones that are received in the
On Web Connection database method. Therefore you can call the
same validation code you would normally call from On Web
Connection.
■ Passed:
$1 TEXT - URL that has been requested by the client
$2 TEXT - Header text from the request
$3 TEXT - Client IP Address
$4 TEXT - Server IP Address
$5 TEXT - User Name (from HTTP Authorization)
$6 TEXT - Password (from HTTP Authorization)
■ Returned:
$0 BOOLEAN - Is this a valid user session?

Using whatever system you currently have in place, you validate the
user's current session. This most likely involves querying a table for the
session id. 4D Ajax Framework supplies the session id with every 4D
Ajax Framework call. You can retrieve the supplied session id with the
following call:
$sessionid_t:=DAX_Dev_GetWebVar ("sessionid")
If the session is valid, return True from this method. If the session is
not valid, return False.

When you are using the DAX_DevHook_SessionValidate method to

validate users yourself, you must pass 4D Ajax Framework some
information about the user and the session.

12 4D Ajax Framework Developer’s Guide

 Managing User Authentication and Sessions

Upon Valid Session

1 You must call DAX_Dev_Session_UserName and pass the user's user
name.
2 If the user should have Admin privileges, call
DAX_Dev_Session_Admin and pass True; otherwise, pass False or
simply don't call the method.
A user with Admin privileges can make changes to what tables and
fields are displayed using the Admin object on the web page. Generally
very few users should have this ability.
3 You must call DAX_Dev_Session_SessionID and pass the session id you
are using for this user.

Upon Failed Login If the session is not valid you must pass an error code to 4D Ajax
Framework. If you return False from this method and do not pass an
error code, 4D Ajax Framework will attempt to validate the session
itself. To set a session error code call DAX_Dev_Session_Error and pass
an appropriate error code.

Session error codes include:

SessionExpired
IllegalAccessPoint
InvalidSessionId
▼ Successful Example:
DAX_Dev_Session_UserName ($userName_t)
DAX_Dev_Session_Admin ($isAdmin_b)
DAX_Dev_Session_SessionID ($sessionID_t)
$0:=True
▼ Failed Example:
DAX_Session_Error ("InvalidSessionId")
$0:=False

DAX_DevHook_GetGrou DAX_DevHook_GetGroupsList is provided for the Developer to

psList override the default 4D Ajax Framework Groups system. By default 4D
Ajax Framework uses the 4D Users and Groups system to authenticate
users when they login using the 4D Ajax Framework login object.
Groups are then used to determine what to display to particular users.
For instance, users in Group A can be shown and allowed to edit the
table 1 Contacts, while users in Group B will never see the table. If you
have your own users and groups system in place, you can override the

4D Ajax Framework Developer’s Guide 13

Managing User Authentication and Sessions

4D Ajax Framework group system here. This method should be used in

tandem with DAX_DevHook_UserInGroup. If you use
DAX_DevHook_Login to override the login system and do not
implement your own groups, all of the users of your system will be
assigned to the "AllUsers" group and have equal access. You must
return True from this method if you implement your own solution
here.

DAX_DevHook_GetGroupsList receives two Pointer parameters. These

two pointers point to arrays that the developer should populate with
their group names and group numbers.
■ Passed:
$1 POINTER - Pointer to a Text Array to receive the group names
$2 POINTER - Pointer to a Longint Array to receive the group numbers
■ Returned:
$0 BOOLEAN - Flag indicating that you are using your own groups system
▼ Example:
READ ONLY([User_Groups])
ALL RECORDS ([User_Groups])
SELECTION TO ARRAY([User_Groups]ID;$groupIDs_p>;
[User_Groups]Group_Name;$groupNames_p->)
UNLOAD RECORD([User_Groups])

DAX_DevHook_UserInG DAX_DevHook_UserInGroup should be used in tandem with

roup DAX_DevHook_GetGroupsList as described above. You must return
True in $0 if you implement your own solution here.

DAX_DevHook_UserInGroup receives two text parameters and one

pointer parameter. The two text parameters contain the user name and
the group name. The pointer points to a boolean variable that you set
to True if the passed user is in the passed group and set to False if the
user is not.
■ Passed:
$1 TEXT - User name we are checking
$2 TEXT - Group name we are checking
$3 POINTER - Pointer to a Boolean: True this user is in this group, False
otherwise

14 4D Ajax Framework Developer’s Guide

 Managing Data Modification

■ Returned:
$0 BOOLEAN - Flag indicating that you are using your own groups system
▼ Example:
$userName_t:=$1
$groupName_t:=$2
$userInGroup_p:=$3

READ ONLY([Users])
READ ONLY([User_Groups])
QUERY([Users];[Users]User_Name=$userName_t)
RELATE ONE([Users]User_Groups_Link)
$userInGroup_p->:=([User_Groups]Group_Name=$groupName_t)
UNLOAD RECORD([Users])
UNLOAD RECORD([User_Groups])

$0:=True ` Developer is handling Users and Groups

Managing Data Modification

Whenever 4D Ajax Framework is about to save or delete a record, the
developer is given the opportunity to deny the action or handle other
related tasks as necessary via two data modification developer hooks.

DAX_DevHook_Save DAX_DevHook_SaveRecord is called anytime 4D Ajax Framework is

Record about to save a record. It allows the developer to add any necessary
internal field modifications, such as date created or modified fields, or
to handle other necessary actions such as updating related records or a
system log.

This method is always called whenever 4D Ajax Framework is about to

save a record. A pointer to the table and the record number for the
record to be saved are passed in. Developers can add any necessary
internal field modifications here. For example, if you have a
Date_Created field in your table you can set that value here. To deny
the save record return False from this method.
■ Passed:
$1 POINTER - Pointer to the table where the record is being saved
$2 LONGINT - Record number for the record that is being saved

4D Ajax Framework Developer’s Guide 15

Managing Data Modification

■ Returned:
$0 BOOLEAN - True=OK to save, False=Do not save and send an error

The record that is about to be saved is already loaded in read write

mode and the changes to its fields have already been made. Any
further processing is up to your specific needs.

The record is loaded in READ WRITE mode when this method is called,
but the record has not been saved yet. 4D Ajax Framework will expect
the record to be loaded still in READ WRITE mode after this call. If you
need to modify the selection within the table, you must first save the
record and then restore the selection in READ WRITE mode when your
code completes.

Any code you have in Triggers will execute normally.

DAX_DevHook_Dele DAX__DevHook_DeleteRecord is called anytime 4D Ajax Framework is

teRecord about to delete a record. It allows the developer to deny the deletion or
to handle other necessary actions such as deleting related records or
updating a system log.

This method is always called whenever 4D Ajax Framework is about to

delete a record. A pointer to the table and the record number for the
record to be deleted are passed in. Developers can add any necessary
handling here. For instance, if you need to have related records deleted
when this record is deleted, you can do so here. To deny the delete
record return False from this method.
■ Passed:
$1 POINTER - Pointer to the table where the record is being deleted
$2 LONGINT - Record number for the record that is being deleted
■ Returned:
$0 BOOLEAN - True=OK to delete, False=Do not delete and send an error

The record that is about to be deleted is already loaded in read write

mode. Any further processing is up to your specific needs.

The record is loaded in READ WRITE mode when this method is called.
4D Ajax Framework will expect the record to be loaded still in READ
WRITE mode after this call. If you modify the selection within the
table, you must restore the selection in READ WRITE mode when your
code completes. Any code you have in Triggers will execute normally.

16 4D Ajax Framework Developer’s Guide

 Creating DCS Views

Creating DCS Views

Developer Created Selections allow the developer to add a new item to
the list of tables (Views) that are displayed on the front-end using
arrays as the data source. The arrays can then be populated with data
from any data source the developer has access to. To the end user a
DCS view appears and acts no differently than any other table.

Since DCS does a lot of array manipulation it is highly recommended that

DCS be used only in systems that will be deployed compiled.

DAX_DevHook_DCS DAX_DevHook_DCS_ViewAdd is provided for the Developer to add

_ViewAdd custom Views to the 4D Ajax Framework web interface using arrays as
the data source. Views added with this method will be added to the
standard list of tables available on the front-end and will appear to the
end user as just another table. 4D Ajax Framework will automatically
add any Views defined in this method when the database starts up.
Using DAX_DevHook_DCS_ViewAdd is the only supported way to add
a DCS view.

When using custom views the developer must handle all of the other
DCS hooks as well:
DAX_DevHook_DCS_SetSelection
DAX_DevHook_DCS_RecordSave
DAX_DevHook_DCS_RecordDelete

Adding a custom view is done by calling

DAX_Dev_DCS_AddCustomView and passing seven parameters.
1 Name of the view to add as text. This is the name that will be
displayed to users on the web page. It is, in essence, a table name.
2 Pointer to text array of names for each column of data. This is a
pointer to a text array that contains the names of the columns for the
view. For instance, "Name", "Address", "Phone Number", etc. It is, in
essence, the field names.
3 Pointer to longint array of types for each column of data. This is a
pointer to a longint array that contains the data types for the columns
in the view. You use the standard 4D data types; for instance, Is Text, Is
Longint, etc.
4 Pointer to a boolean array to set the unique attribute.
5 Pointer to a boolean array to set the mandatory attribute.

4D Ajax Framework Developer’s Guide 17

Creating DCS Views

6 Pointer to a boolean array to set the non-enterable attribute.

7 Pointer to a boolean array to set the non-modifiable attribute.

You can add as many custom views as you like. Just make one call to
DAX_Dev_DCS_AddCustomView for each view you are adding.

Valid Date Types The following is a list of the valid data types you may use in the types
array. The types serve two purposes. The first is to let 4D Ajax
Framework know what type of value it is working with so it can make
the proper conversions when necessary (using String, Num, Date, etc.).
The second is to let the 4D Ajax Framework web front-end know what
type of display to use for field input. For example, the type 'Is Text' will
cause a multi-line text area input field to be displayed, while the type
'Is String Var' will cause a single line input field. 'Is Date' will cause a
date entry calendar to be displayed. Numerical types will cause the 4D
Ajax Framework front-end to allow only numerical values to be
entered.

The type is for an individual item, so pass standard types not array
types (i.e., don't use 'Text array' instead use 'Is Text').
Is Text
Is String Var
Is Real
Is Integer
Is LongInt
Is Date
Is Time
Is Boolean
Is Picture
▼ Example:

This example creates a view to display Customer names and the totals
from their Invoices. It is assumed we have a Customer table and a
related Invoice table. This example continues in the other DCS method
definitions.
C_TEXT($viewName_t)
C_BOOLEAN($added_b)
C_LONGINT($i)

ARRAY TEXT($names_at;3)
ARRAY LONGINT($types_al;3)
ARRAY BOOLEAN($unique_ab;3)

18 4D Ajax Framework Developer’s Guide

 Creating DCS Views

ARRAY BOOLEAN($mandatory_ab;3)
ARRAY BOOLEAN($nonEnterable_ab;3)
ARRAY BOOLEAN($nonModifiable_ab;3)

$viewName_t:="Customer Invoices"
` set the name of the view you are adding

` set the names of the columns

$names_at{1}:="First Name"
$names_at{2}:="Last Name"
$names_at{3}:="Total"

` set the data types of the columns

$types_al{1}:=Is String Var
$types_al{2}:=Is String Var
$types_al{3}:=Is Real

` set the attributes of the columns

` for simplicity the example is setting all to false
For ($i;1;Size of array($unique_ab))
$unique_ab{$i}:=False
$mandatory_ab{$i}:=False
$nonEnterable_ab{$i}:=False
$nonModifiable_ab{$i}:=False
End for
$added_b:=DAX_Dev_DCS_AddCustomView ($viewName_t;->$names_at;
->$types_al;->$unique_ab;->$mandatory_ab;
->$nonEnterable_ab;->$nonModifiable_ab)

DAX_DevHook_DCS DAX_DevHook_DCS_SetSelection is called whenever 4D Ajax

_SetSelection Framework needs the selection for a developer created view added
through the DAX_DevHook_DCS_ViewAdd method. The name of the
view that was set in DAX_DevHook_DCS_ViewAdd is passed in so the
developer knows which records to load.
■ Passed:
$1 TEXT - Name of the DCS view to load the selection for

When referring to a "record," we mean any single set of data and not
necessarily a record from a 4D table. A record can come from any data
source as long as you can identify it uniquely.

4D Ajax Framework Developer’s Guide 19

Creating DCS Views

Setting a custom view selection is done by calling

DAX_Dev_DCS_SetSelection and passing two-n pointer parameters:

The first parameter to DAX_DCS_SetSelection must be a pointer to a

longint array of record IDs. These IDs can be record numbers from a
table, an ID or Key field's values created with Sequence Number or a
similar function or any other method you have for creating a longint
identifier.

Whatever method you use, the record ID must be a value that can find
and load a particular record (data set) regardless of the current
selection. Using a simple array element number system is not
recommended and would most likely cause serious problems in a
multi-user database.

The rest of the parameters to DAX_Dev_DCS_SetSelection are pointers

to the arrays you will be using for the data. These arrays must be passed
in the same order as the column names that were defined in
DAX_DevHook_DCS_ViewAdd.

In other words, if the first element in the column names was "First
Name" the first data array passed should be the one that contains first
names. The type of arrays must be compatible with the types you set
for the columns in DAX_DevHook_DCS_ViewAdd. Compatible means
direct assignment between values is possible. So if you passed a type of
'Is Real' you cannot now pass a text array, but you can pass a longint or
integer array. similarly, if you set the column type to 'Is Text' or 'Is
String var' you can pass a text or string array interchangeably
(assuming the string is long enough to hold your values).
▼ Example:

This example continues from the example view that was created in
DAX_DevHook_DCS_ViewAdd to display Customer names and the
totals from their Invoices. This example continues in the other DCS
method definitions.
Case of
:($viewName_t="Customer Invoices")
` Declare the arrays
ARRAY LONGINT(recordIDs_al;0)
ARRAY REAL(totals_ar;0)
ARRAY TEXT(firstNames_at;0)
ARRAY TEXT(lastNames_at;0)

20 4D Ajax Framework Developer’s Guide

 Creating DCS Views

` Put the data into our arrays

ALL RECORDS([Invoice])
SELECTION TO ARRAY([Invoice];recordIDs_al;[Invoice]Total;totals_ar;
[Customer]FirstName;firstNames_at;
[Customer]LastName;lastNames_at)

` Set the selection in DAX in the order defined when we created the View
DAX_Dev_DCS_SetSelection(->recordIDs_al;->firstNames_at;
->lastNames_at;->totals_ar)

End case

DAX_DevHook_DCS DAX_DevHook_DCS_RecordSave is called whenever 4D Ajax

_RecordSave Framework is asked to save a DCS record. The name of the view that
you set in DAX_DevHook_DCS_ViewAdd and the record id for the
record to be saved are passed in. For modified records the record id is
the id you passed in as the record id in
DAX_DevHook_DCS_SetSelection; for new records the constant 'New
record' is passed in.

If you save the record, return the record id, either the same one that
was passed in (for modifying) or a new record id (for new records). If
you do not save the record, return the constant 'No current record'.
■ Passed:
$1 TEXT - Name of the DCS View where the record is being saved
$2 LONGINT - Record ID for the record that is being saved ('New record'
constant for new records)
$3 POINTER - Pointer to text array of field names for the record that is
being saved
$4 POINTER - Pointer to text array of field values for the record that is
being saved
■ Returned:
$0 LONGINT - Record ID for the record (either same as passed, ID for new
record, or 'No record loaded')

In the case of the ID being a record number, you can use Goto Record
to load the record that needs to be updated. In the case of the ID being
a unique sequence number from an ID field, you can query for the
record that needs to be updated. In other cases it will depend on what
the ID means to you as the developer.

4D Ajax Framework Developer’s Guide 21

Creating DCS Views

▼ Example:

This example continues from the example view that was created in
DAX_DevHook_DCS_ViewAdd to display Customer names and the
totals from their Invoices. This example continues in the other DCS
methods.
Case of
:($viewName_t="Customer Invoices")
If($recordNumber_l=New record)
CREATE RECORD([Invoice])

$find_l:=Find in array($addRecFieldName_p->;"First Name")

$firstName_t:=$addRecFieldValue_p->{$find_l}

$find_l:=Find in array($addRecFieldName_p->;"Last Name")

$lastName_t:=$addRecFieldValue_p->{$find_l}

QUERY([Customer];[Customer]FirstName=$firstName_t;*)
QUERY([Customer]; & ;[Customer]LastName=$lastName_t)
[Invoice]CustomerID:=[Customer]ID

Else
READ WRITE([Invoice])
GOTO RECORD([Invoice];$recordNumber_l)

If(Records in selection([Invoice])#1)
$recordNumber_l:=No current record
UNLOAD RECORD([Invoice])
End if

End if

If($recordNumber_l#No current record )

$find_l:=Find in array($addRecFieldName_p->;"Total")
[Invoice]Total:=$addRecFieldValue_p->{$find_l}
SAVE RECORD([Invoice])
$recordNumber_l:=Record number([Invoice])
UNLOAD RECORD([Invoice])
End if

End case

$0:=$recordNumber_l

22 4D Ajax Framework Developer’s Guide

 Creating DCS Views

DAX_DevHook_DCS DAX_DevHook_DCS_RecordDelete is called whenever 4D Ajax

_RecordDelete Framework is asked to delete a DCS record. The name of the view that
you set in DAX_DevHook_DCS_ViewAdd and the record id for the
record to be deleted are passed in. The record id is the id you passed in
as the record id in DAX_DevHook_DCS_SetSelection. If you delete the
record, return True. If the record is not deleted (denied), return False.
■ Passed:
$1 TEXT - Name of the DCS View where the record is being deleted
$2 LONGINT - Record ID for the record that is being deleted
■ Returned:
$0 BOOLEAN - True=Deleted, False=Not deleted and send an error

The record id is the id you passed in as the record id in

DAX_DevHook_DCS_SetSelection. The developer must use this ID to
load the data that it represents and act accordingly.

In the case of the id being a record number, you can use Goto Record
and delete the record. In the case of the id being a unique sequence
number from an id field, you can query for the record and delete the
record. In other cases it will depend on what the id means to you as
the developer.
▼ Example:

This example continues from the example view that was created in
DAX_DevHook_DCS_ViewAdd to display Customer names and the
totals from their Invoices. This example continues in the other DCS
methods.
$deleteRecordAccepted_b:=True

Case of

:($viewName_t="Customer Invoices")
If ($recordID_l>No current record )
READ WRITE([Invoice])
GOTO RECORD([Invoice];$recordID_l)
End if

4D Ajax Framework Developer’s Guide 23

Creating DDW Views

If (Records in selection([Invoice])=1)
DELETE RECORD([Invoice])
Else
$deleteRecordAccepted_b:=False
UNLOAD RECORD([Invoice])
End if

End case

$0:=$deleteRecordAccepted_b

Creating DDW Views

Developer Defined Windows (DDW) give developers the ability to add
a window with any HTML content they want on the front-end. The
developer can have the window display an HTML blob or content from
any valid URL. A DDW can display anything that can be displayed in a
web browser.

A DDW can be created at the portal level, selection level or field level.
A portal level DDW is displayed in the left sidebar of the main window.
A selection level DDW is displayed at the top of a window which
displays a selection of records with the Create, Delete, etc. buttons. For
selection level a button is also added to the detail view next to the Save
and Cancel buttons. A field level DDW causes the field data to display
as a link in a list of records and as a button next to the field value in
the detail views

Adding a DDW view is done by calling DAX_Dev_DDW_Create and

passing four parameters.
1 Object Type as Text. This is the type of object that will be displayed to
users on the web page. Valid values are either "linkstatic" or
"linkdynamic".
2 Object Title as Text. This is the title that will be displayed on the
button or as the link.
3 Method or URL as Text. This can be one of two things. The first use is
the name of the method to execute when the user clicks on the button
or link. In this case the method must return a blob that contains HTML
content to be displayed. The second use is a valid URL that points to a
resource to be loaded into the window (i.e., "http://www.4d.com" or
"/4dcgi/MyWebMethod&parameter=value").

24 4D Ajax Framework Developer’s Guide

 Creating Callbacks

4 Associated To as Text. This is the type of object with which the DDW
will be used. Valid values are "Portal" or "Other". This parameter is
optional and will default to "Other" if it is not provided.
▼ Examples:

You can add as many DDW views as you like. Just make one call to
DAX_Dev_DDW_Create for each DDW view you are adding.
■ Adding a Portal
$ddwID_l:=DAX_Dev_DDW_Create ("Linkstatic";"4D Home Page";
"http://www.4d.com/";"Portal")
■ Creating a DDW and assigning it to multiple fields

$ddwID_l:=DAX_Dev_DDW_Create ("Linkstatic";"Map It";

"MyMapMethod";"Other")
DAX_Dev_DDW_AssignToObject($ddwID_l;"Field";Table name(->[Contact]);
Field name(->[Contact]Address))
DAX_Dev_DDW_AssignToObject ($ddwID_l;"Field";
Table name(->[Company]);Field name(->[Company]Address))
■ Creating a DDW and assigning it to a Selection

$ddwID_l:=DAX_Dev_DDW_Create ("Linkstatic";"Help";"MyHelpMethod")
DAX_Dev_DDW_AssignToObject ($ddwID_l;"Selection";
Table name(->[Contact]))

In the above examples, MyHelpMethod might load a local HTML help

file into a blob and then return the blob. Or, MyMapMethod could use
the TCP commands to download map information from another site
and then return the HTML in a blob.

Creating Callbacks
Callbacks are a way for 4D to respond to certain events that occur in a
field on the front-end. When an event is triggered, the front-end will
post the event information and field value to the 4D. 4D will then
execute the method that is set to handle the event and return a
response back to the front-end. Currently 4D Ajax Framework supports
two events from the front-end: On Load (event id=1) and On Data
Change (event id=20).
1 On Load - The field object is about to be drawn in the Detail View.
2 On Data Change - The user tabbed out of the field.

4D Ajax Framework Developer’s Guide 25

Creating Callbacks

DAX_DevHook_Inst Adding a callback is done by calling DAX_Dev_SetCallBack and

allCallBack passing five parameters.
1 Event ID as Longint. This is the event that the callback will handle.
Currently On Load and On Data Change are supported.
2 Table Name as Text. This is the table name for the table that the
callback will be installed (a DCS or View name is also acceptable).
3 Field Name as Text. This is the field name for the field for which the
callback will be installed (a DCS or View field name is also acceptable)
4 Method Name as Text. This is the name of the method that will be
executed when the event triggers.
5 Modifiable as Boolean. This determines whether or not the callback
can be modified via the Admin interface on the front-end.

Method to be The method that is set to respond to a callback must return a Text
executed on a value in $0 to be used as the new value for the field that triggered the
Callback event. 4D Ajax Framework callback methods have access to six
attributes when they run:
1 Event ID as Longint. This is the event that triggered the callback.
2 Table ID as Longint. This is the table number for the edited field.
3 Table Name as Text. This is the table name for the edited field.
4 Field ID as Longint. This is the field number for the edited field.
5 Field Name as Text. This is the field name for the edited field.
6 Record ID as Longint. This is the record number (-3 for new records).
7 Value as Text. This is the value the user entered for the edited field.
8 Message as Text. Text message that will be returned to the front-end.

❿ To get the value of these attributes the developer calls

DAX_Dev_GetCallBackVar passing the following parameters:
1 Name of Attribute as Text.
This is the name of the attribute the developer wants to retrieve. Valid
attributes are "Event ID", "Table ID", "Table Name", "Field ID", "Field
Name", "Record ID", "Value, "Message"
2 Pointer to a Variable. This is a pointer to the variable that will receive
the attribute value.

26 4D Ajax Framework Developer’s Guide

 Creating Callbacks

❿ To set the "Message" attribute value the developer calls

DAX_Dev_SetCallBackVar passing the following parameters:
1 Name of Attribute as Text. This should be "Message".
2 Pointer to a Variable. This is a pointer to the variable that contains the
message value.

The message attribute is displayed at the bottom of the detail window.

For example, if you are doing email validation the message might be
set to "Invalid Email Address."

4D Ajax Framework Developer’s Guide 27

Creating Callbacks

28 4D Ajax Framework Developer’s Guide