4D Ajax Framework 1.1 ADDENDUM

Transcription

1 ADDENDUM The 4D Ajax Framework has undergone significant enhancement in version 1.1, with new features added, enhancements made to existing features, performance improvement, as well as bug fixes. This document details the new features and major changes for the 4D Ajax Framework. Additional information on these features can be found at the 4D Web 2.0 Pack wiki, New in Version 1.1 New Selection Object: Data / Image Matrix Two new objects were added to the 4D Ajax Framework - Data Matrix and Image Matrix. Internally they are the same object, but vary slightly based on parameters. Both objects allow you to organize and integrate different data types and fields into a user-friendly display. We drew our inspiration for these objects from the Outlook Contacts interface, but these objects can be used to organize many other kinds of data, including graphics, documents, videos, and more. As Administrator, you can define your selection to be displayed as Data Matrix or Picture Matrix. In conjunction with a picture field, you can display your selection as an image gallery. Click on the SetUp button to define the view. You can display or choose any available picture fields, select any field as title and display or not other fields next to the picture. However, a picture field is not required to use these window types. Available Layouts: There are 2 main layouts for the matrix objects: Browse (top/bottom) and Detail (left/right). Browse layout displays data in the form of thumbnails. It is the default layout when selecting the Image Matrix for a selection. With this matrix type, only two fields value can be displayed in the matrix cell. Addendum 1

2 The first picture field in the selection The first non-picture field in the selection. 2 Addendum

3 New in Version 1.1 Detail layout displays data in a form of a label. Once the Data Matrix is set to a selection, the selection is displayed with the Left-Detail layout by default. Addendum 3

4 If the selection has no picture field or the picture field is invisible, the Left-Detail and Right-Detail layout will appear the same way. Changing the Number of Cells Displayed The matrix objects also give the end user the ability to increase or decrease the number of cells in each matrix window. Click the "Less" button at the top of the window if you want to decrease the number of cells in the matrix window. Click "More" to increase the number of cells. 4 Addendum

5 New in Version 1.1 Changing the Default Layout The user can overwrite the default layout at any time while they are in the same login session. Any changes made by the user will be overwritten the next time the user logs in. To view the setup option, click on the "Setup" button at the top of the matrix window to display or hide the layout option bar. The Header field will always be displayed, but the Image field is not required. To deselect the picture, select "None" from the Image dropdown list. Data Matrix API Summary Here are some key commands in the new Data Matrix API. Create a new object: mydatamatrix = new datamatrix(targetnode, selectionname, header, imagefield, contents, zoomcontents, layout, margin, zoomlevel, scrollmode, forcerows, forcecolumns, allowcellmouseinteraction); Reapply settings (will use the existing object and resubmit those same settings to be used when a new object is created): mydatamatrix.reinit(selectionname, header, imagefield, contents, zoom- Contents, layout, margin, zoomlevel, scrollmode, forcerows, forcecolumns, allowcellmouseinteraction); Hibernate and wake up will suspend object operations (such as automatic data update) or resume them: mydatamatrix.hibernate(); mydatamatrix.wakeup(); ZoomCell will magnify the cell up to the size of the entire object: mydatamatrix.zoomcell(cellref); Customize toolbar to show or hide parts of the toolbar: mydatamatrix.customize(showtoolbar, showauxtoolbar, useeditor, createbtn, deletebtn, zoombtn, setupbtn, displaybtn, layoutbtn, searchbtn, headerdropdown, ImageDropdown, sortdropdown); Addendum 5

6 For full customization and API documentation, please refer to: Choice Lists 4D Ajax Framework version 1.1 introduces a new 'choice lists' feature. When a choice list is assigned to a field, the browser will display the input for that field as a pop-up menu (instead of a text entry area). To assign a choice list to a field: 1 Define a list in the 4D list Editor. 2 Open the Structure window and double-click on the field you wish to assign the list to. 3 In the Inspector window select the Choices & Help tab. 4 Place a check in the checkbox Allow Choice List. 5 Select your list from the pop-up menu and click the Apply button. You can use the developer hook DAX_DevHook_ListContents (defined elsewhere in this document) to modify the contents of the list before it is sent to the browser. You can also define an empty list in the List Editor and use the developer hook to define the full contents of the list. Note: Only flat lists are supported. Hierarchical lists are not supported by this feature; only the first level of the list will be visible in the pop-up menu if used. Preset Queries 4D Ajax Framework version 1.1 introduces a new 'preset queries' feature. Preset queries are queries formulated by the 4D Developer for the purpose of presenting information in an organized manner once users log on. It allows the admin to filter the data before the users can access it. The Query Manager in the administrative control panel allows the developer to create or edit the preset queries for his application. Unlike 6 Addendum

7 New in Version 1.1 saved queries, a user cannot delete preset queries; these can only be deleted from the control panel. When a preset query is assigned to a selection, the browser will add a tab to the data view window that will display the result of the preset query. Each query will tell the browser to create a tab in the data view window. These tabs can be reordered in the query manager and the default 'all records' tab can be hidden. This preference can be set for each selection. When multiple tab controls are displayed, two new tabs Previous and Next will appear to assist you in navigating. Preset queries can be created: from scratch from a template Addendum 7

8 as a dynamic query Creating a query from scratch In order to create a preset query from scratch, you will need to assign it to a selection and specify its name (the name will need to be unique for that selection). You will then need to set or not a sorting order and sorting field. A maximum number of records can also be preset. This allows you to create Top N type queries (such as top 10 customers). You will then need to assign conditions to your query. Conditions can be static (with a static value) or dynamic if the 'is a method' attribute is checked (with a value that will be generated by the specified method) 8 Addendum

9 New in Version 1.1 Creating a query from a template You will have to specify the selection and the field you want to associate the queries with. Templates can generate several queries at once. The templates are defined in an XML document in the extras/support folder and can be customized by the developer to meet his application needs. Creating a query as a dynamic query Dynamic queries allow the developer to create dynamic tabs. If a dynamic query is associated with a field, a tab will be created in the data view window for each unique value of the specified field. The browser will automatically update these tabs in order to reflect the changes of the data. Addendum 9

10 DAX_DevHook _QueryAdd 4D Ajax Framework version 1.1 also introduces a new Developer Hook to programmatically create a new preset query. This hook is DAX_DevHook_QueryAdd. DAX_DevHook_QueryAdd is used by the developer to create preset queries and assign them to a selection. These saved queries then appear as tabs in a Grid view. For instance you could create a saved query for each letter of the alphabet and assign it to the last name field of a Contacts table. Then the user would see 26 tabs that each return the results for the associated letter. Adding a custom query is done by calling DAX_Dev_QueryCreate and passing nine (9) parameters: Passed Parameters $1 TEXT - Name of the Query to Add $2 TEXT - Name of the selection (table ) the Query is for $3 TEXT - Name of the field to use for sorting $4 TEXT - Sort order to use. It must be either 'asc' or 'desc' (for ascending or descending). $5 POINTER - Pointer to a Text Array to set the line links. Determines if multiple lines are processed as AND or OR. The values must be either 'and' or 'or' $6 POINTER - Pointer to a Text Array to set the query field names. This is an array of field names that are to be used for the query $7 POINTER - Pointer to a Text Array to set the query operators. This is an array of operators that are to be used for the query $8 POINTER - Pointer to a Text Array to set the query conditions. This is an array of conditions (value to search for) that are to be used f or the query $9 POINTER - Pointer to a Boolean Array to set the condition is method flag. This is a Boolean array that indicates if the condition is to be treated as text or is the name of a method that is to be executed. If it is a method, the method must return a text value. Example C_TEXT($queryName_t;$tableName_t;$sortFieldName_t;$sortOrder_t) C_BOOLEAN($added_b) C_LONGINT($size_l) $queryname_t:="atestquery" 10 Addendum

11 New in Version 1.1 $tablename_t:="album" ` Table name(->[album]) $sortfieldname_t:="album_name" ` Field name(->[album]album_name) $sortorder_t:="asc" $size_l:=3 ARRAY TEXT($links_at;$size_l) ARRAY TEXT($fields_at;$size_l) ARRAY TEXT($operators_at;$size_l) ARRAY TEXT($conditions_at;$size_l) ARRAY BOOLEAN($flags_ab;$size_l) $links_at{1}:="or" $fields_at{1}:="album_name" $operators_at{1}:="starts With" $conditions_at{1}:="a" $flags_ab{1}:=false $links_at{2}:="or" $fields_at{2}:="album_name" $operators_at{2}:="starts With" $conditions_at{2}:="b" $flags_ab{2}:=false $links_at{3}:="or" $fields_at{3}:="album_name" $operators_at{3}:="starts With" $conditions_at{3}:="c" $flags_ab{3}:=false $added_b:=dax_dev_querycreate($queryname_t;$tablename_t; $sortfieldname_t;$sortorder_t;->$links_at;->$fields_at; ->$operators_at;->$conditions_at;->$flags_ab) DAX_DevHook _QueryFilter DAX_DevHook_QueryFilter is used by the developer to change the selection when it is about to be sent to the browser. This method is always called whenever 4D Ajax Framework is about to display a selection. A pointer to a longint array of table numbers and a pointer to a text array of set names are passed. The developer can then remove records that are not valid. For instance, if you have a 'Deleted' flag field, you could remove all of the records that are flagged as deleted. DAX_DevHook_QueryFilter receives two pointer parameters: Passed Parameters $1 POINTER - Pointer to a longint array of Table Numbers $2 POINTER - Pointer to a Text array of Set Names Addendum 11

12 By default $1 is assigned to the local variable $settableids_p and $2 is assigned to the local variable $setnames_p. For every table in the $settableids_p array there is a corresponding Set in the $setnames_p array. If you need to modify the selection you should: 1 Use Set ($setnames_p{$index}->) 2 Modify the selection 3 Update the set by clearing and recreating it (or using Union, Intersection, etc.) Note: The passed sets must still exist after this call. If you use CLEAR SET, be sure to use CREATE SET with an identical set name. Example For ($i;1;size of array($settableids_p->)) Case of : ($settableids_p->{$i}=table(->[my_table])) USE SET($setTableIDs_p->{$i}) CLEAR SET($setNames_p->{$i}) QUERY SELECTION([My_Table];[My_Table]My_Field="My_Value") CREATE SET([My_Table];$setNames_p->{$i}) End case End for DAX_DevHook _ListContents DAX_DevHook_ListContents is provided for the Developer to override a list before it is sent to the browser. Every time the 4D Ajax Framework is about to send a list to the browser the developer is given the opportunity to modify the list. This allows you to remove items from the list or create the list completely in code. The list itself is assigned to a field using the structure editor and the field properties inspector. Simply assign a list defined in the Lists editor to a field using the Choices & Help tab. Note that you can create an empty list in the List editor and assign it to the field and then create the list in code using this hook. DAX_DevHook_ListContents receives two parameters. Passed Parameters $1 TEXT - Name of the list that has been requested $2 POINTER - Pointer to a Text array containing the list items 12 Addendum

13 New in Version 1.1 By default $1 is assigned to the local variable $list_t and $2 is assigned to the local variable $listitems_p. This method receives the name of the list and the contents that will be returned to the browser. For every list you wish to modify, create a case to catch it and then add the code that is necessary for your situation. This might consist of removing items from the list or creating the complete list from scratch. Example Case of ` EXAMPLE - remove a value from the list :($list_t="my_list") C_LONGINT($find_l) $find_l:=find in array($listitems_p->;"remove_value") If ($find_l#-1) DELETE ELEMENT($listItems_p->;$find_l;1) End if ` EXAMPLE - Completely create the list :($list_t="another_list") READ ONLY([My_Table]) ALL RECORDS([My_Table]) DISTINCT VALUES([My_Table]List_Items;$listItems_p->) UNLOAD RECORD([My_Table]) End case Data Filler This command populates a designated area on the web page with the contents from a designated record. Data Filler is integrated with the other 4DAF objects. Data Filler API Summary placerecorddata populates a specific HTML area with record data. For 4DAF objects, only the first two parameters are used. For generic calls, specify the html area, table, and record id. placerecorddata (html area to populate, 4DAF record, table, record id); Data Filler Example This sample code will populate the data filler area with a selected row in the data grid. Addendum 13

14 HTML code <div id="recorddetail"> Field1: <input class="4daf_[table]field1" /> Image Field: <img class="4daf_[tablename]imagefield" /> </div> JavaScript code // on data window row click, populate 'recorddetail' area with clicked record mydatawindow.grid.grid.onrowselect.onrowselected = function (rowref) { placerecorddata($('recorddetail'), rowref); } For full customization and API documentation, please visit: Modified in Version 1.1 DAX_Dev_SetCall BackExeStatus A method named DAX_Dev_SetCallBackExeStatus has been added to version 1.1 to further control callbacks. This method sets a flag to let the browser know if the Call Back method's execution is successful. It must be executed for every callback execution. In each of your Call Back methods, add a call to DAX_Dev_SetCallBackExeStatus with a LONGINT parameter of either 1 for success or 0 for failure. Example DAX_Dev_SetCallBackExeStatus(1) 14 Addendum

15 Modified in Version 1.1 Boolean Formatting: Checkbox A new format option for Boolean is 'checkbox', which will display the Boolean value as a checkbox in data views. This format can be set in field list in Admin window. Note that a Boolean will always be displayed as checkbox in the editor, regardless of the format used. Data Grid: Save Column Width Users set as administrators now have the ability to save the current column width in a data grid that will be used every time that data grid is displayed. These settings are saved on the back-end. To save column widths, click on the 'save column width' button on data window title bar. Performance Optimization Application performance has been improved tremendously in version 1.1. This is due to both a refactoring of the grid component, and to the addition of compression to the CSS and JavaScript files sent to the browser. A more thorough discussion on the compression technique can be found in the Daxipedia here: In addition, since we no longer need pre-caching to maintain speed, applications developed using this feature can remove it without any noticeable loss of performance. Addendum 15