4D Live Window Addendum 1.1

Size: px

Start display at page:

Download "4D Live Window Addendum 1.1"

Jennifer Powers
5 years ago
Views:

1 Version 1.1 enhances the feature set to allow users to add HTML to a 4D window to present data and respond with interactive content on user clicks. Main enhancements Control of Context Menu/New Window Callback to 4D before/during/after a click Callback to 4D on load error Get/SetContent with different encodings Evaluation of Javascript functions on Windows Platform differences Mac OS/Windows uses the native HTML engine of the operating system (Safari / Internet Explorer), so the behavior/feature set will be different. For the new features in version 1.1 this is specially: Web_SetContent operates slowly on Windows, it is much faster to write the document temporarily on hard disk and open this file. Actually, the execution of JavaScript is only possible on Windows; the commands are disabled on Mac OS. On Mac OS, can display PDF documents without the need of additional browser plug-ins, like Adobe Acrobat Reader. The Acrobat Reader installer modifies Safari to allow it to call Acrobat Reader, but does this modification only for Safari, not for other applications using the Safari engine, like. As a result Mac OS computers with an installed Acrobat Reader browser plug-in cannot display PDF anymore with. 1

2 It is possible to disable the PDF Browser plug-in (while Adobe Acrobat Reader is still useable). To do so the administrator needs to remove the bundle \Library\Internet Plug-Ins\AdobePDFViewer.plugin. This disables it in Safari, too. On Windows, the Acrobat Reader browser plug-in must be installed for MS Internet Explorer to enable to display PDF. Modified with Version 1.1 Windows: The plug-in does not appear with a 3D border anymore. This gives you the choice to use 4D form's property to select none, plain or 3D border. Windows: By default, opening new windows in MS Internet Explorer instances is disabled. This behaviour can be controlled with the new option Web_kOpenWindow in Web_SetPreferences. Windows and Mac OS: To display an empty document, use Web_SetURL to navigate to "About:blank Modified commands in Version 1.1 Web_SetPreferences Web_SetPreferences(Area; Selector; NumValue; StringValue) error code Selector Longint Preferences Selector NumValue Longint Numerical value to set StringValue Alpha String Value to set The command Web_SetPreferences allows the user to change the behavior of the plug-in. Version 1.0 only supports Selectors 1-2. Selector Code Usage Web_kResize 1 0=Disable Resizing; 1=Enable Resizing Web_kVisible 2 0=Hide the Browser; 1=Show the Browser Web_kOpenWindow 3 0=Disable New Window, 1=Launch MS IE Web_kContextMenu 4 0=Disable/1=Enable (default) 2

3 Modified commands in Version 1.1 Selector Code Usage Web_kNavigate 5 Call Method on Before/During/After Navigate Web_kError 6 Call Method on URL Load Error Web_kNavigatorFilter 7 Filter to Cancel for Navigations (User Clicks) Web_kSetUserAgent 8 Set User Agent (Mac only) Web_kResize Mac OS only: If the plug-in area is resized, some web sites (like maps.google.com) act on the resize by using JavaScript to change the position of some elements. This may lead to a crash if the site was already displayed. To avoid this crash the developer should set the browser area to a fixed size (not resizable). In any case the browser area is not automatically resized on Mac OS except for the first display (opening a window before loading a web site). If you display HTML content (or PDF images) without JavaScript, you may enable the resize functionality by using this option. In this case you should not allow the end user to enter a URL manually. Note: Using this option has no result on Windows. Web_kVisible The 4D Command SET VISIBLE does not fully hide the browser because the browser responds directly to events such as mouse-over or Java Script triggered redraws. So it is necessary to hide/show the browser area by using both commands SET VISIBLE and Web_SetPreferences. Web_kOpenWindow On Windows it is possible to allow the embedded MS Internet Explorer to open a new MS Internet Explorer instance (window) for some events (like JavaScript or user action). This was the default behavior in version 1.0. In version 1.1, by default it is disabled, but can be enabled using this parameter. Web_kContextMenu By default, both platforms show a context menu on a right mouse click. This feature allows disabling the menu. Using this parameter works for all plug-in areas, not just for the current one. 3

4 Web_kNavigate This selector is useful for displaying a progress dialog or status text. It is also needed for evaluating JavaScript functions, which cannot be used before the load is fully done. Pass in the parameter StringValue the name of a 4D method to be called on navigation events. The parameter NumValue allows to specify on which events the methods will be called, this allows filtering unneeded events. The same method will be called for all events; it is not possible to specify different methods. Following calls overwrite the callback. Pass value 0 and an empty method name to disable the function. Possible Events: 1 Before Called for each click/javascript navigation 2 After Called as soon as a page is fully loaded/displayed 4 Progress Called several times during loading a page The events can be combined (added), for example: 7 = all, 3 = Before+After, no Progress Use a negative number (-1, -7) to cancel all navigations, except page loads through Web_SetURL. If the user (or a JavaScript function) navigates to another page, it is canceled but the 4D method is called. This allows the 4D method to still use Web_SetURL to follow the click, to modify the URL or ignore it. The selector Web_kNavigateFilter allows canceling only clicks with a special keyword. This method should be fast, it can be called several times per second. Similar to a 4D form method calls are not "stacked, so if the method is too slow it may miss calls. In practice this does not matter, if a process event is missed the next one (or the After) event still displays your progress bar correctly. The 4D method must have the following parameters declared: $1 Longint Area ID $2 Text URL $3 Text Post Data $4 Longint Progress $5 Longint Progress Max 4

5 Modified commands in Version 1.1 In the event Before $4/Progress is set to 0, in the event After to -1. This parameter allows you to detect for which event the method is called. Other values are used during loading the page, like 5000/ To get a progress percentage (like 98%) use this formula: $ratio := $4*100/$5 The method may be called outside the context of the current form, this means you cannot use GET OBJECT RECT or MOVE OBJECT for form objects. Also modifications of form variables may not be displayed automatically. There may also occur a problem with the 4D Debugger window. If you debug the called method, the debugger window may not be closed correctly, because the callback runs outside the form scope. To solve this issue, the callback method should end with: CALL PROCESS(Current Process) Don't forget to enable the Outside Call attribute for the form. This makes sure that the debugger window is closed correctly and modified variables are redrawn. To modify form objects it is a good idea to do this inside the Outside Call form method event. Web_kError Allows the developer to install a callback for page loading errors. The method is called if loading of a page wasn t successful. The parameter NumValue is unused; StringValue specifies the 4D method name. Pass "" to disable the callback. The 4D method must have the following parameters declared: $1 Longint Area ID $2 Text URL $3 Longint Error Code The error code depends on the HTTP server, such as 404 for Page not found. Platform notes: Mac OS: If an error occurs, the default behavior is to display nothing Windows: It displays the standard MS Internet Explorer error page. 5

6 This command allows a developer to display a 4D error window or a custom html error page (using Web_SetURL for a local document). Web_kNavigateFilter If Web_Navigate defines that a new navigate has to be cancelled, this command allows a developer to define when to cancel. If the parameter StringValue is empty (default), all navigates are cancelled, else the passed name works as a content filter, like "/4DCall/ cancels only clicks, if the URL contain /4DCall/. This allows a developer to build interactive systems. For example, a click on a list of records displayed in an HTML table will open a new 4D window with a 4D input form. Web_kSetUserAgent Used to modify the User Agent string sent to a web server on Mac OS. The default string is a combination of the current WebKit version (system depending) and the product name: Mozilla/5.0 (Macintosh; U; PPC Mac OS X; en) AppleWebKit/412.7 (KHTML, like Gecko) This attribute allows you to overwrite the product name, and replace it with a browser name (like Safari). Pass "Safari/412.5 to modify the user agent to: Mozilla/5.0 (Macintosh; U; PPC Mac OS X; en) AppleWebKit/412.7 (KHTML, like Gecko) Safari/412.5 "Spoofing the user agent to Safari may be needed on some sites, which behave in a different way depending on the browser. They should check for AppleWebKit, but most (like sites using Microsoft WPF/E and Google Maps) check for the word "Safari. Function result If the call was successful it returns 0. Otherwise it was an error. Example The following example disables the context menu $err := Web_SetPreferences(mybrowser; Web_kContextMenu; 0; "") 6

7 Modified commands in Version 1.1 Web_GetContent Web_GetContent(Area; Content; CharacterEncoding) error code Content Blob Page Content as blob CharacterEncoding Longint Requested Encoding The command Web_GetContent returns the content of the main frame as blob. Starting with version 1.1 the command may return the blob in a specified character encoding, while version 1.0 always returned ANSI encoding on Windows and MacRoman on Mac OS. Possible values for CharacterEncoding: 0 like version MacRoman 2 Windows (ANSI) 3 UTF-8 4 UTF-16 Function result If the call was successful it returns 0. Otherwise it was an error. 7

8 New commands in version 1.1 All commands require a displayed form (using Dialog, Modify Record, etc) with an external area ". The first parameter of the commands is the variable of the external area. Web_Refresh Web_Refresh(Area) error code The command Web Refresh calls the Refresh Function of the browser, which reloads the currently displayed content. Function result If the call was successful it returns 0. Otherwise it was an error. Web_Stop Web_Stop(Area) error code The command Web_Stop calls the Stop function of the browser, aborting all current load operations. Function result If the call was successful it returns 0. Otherwise it was an error. Web_SetContent Web_SetContent(Area; Content; CharacterEncoding) error code Content Blob Page Content as blob CharacterEncoding Longint Document Encoding The command Web_SetContent sets the main frame with the content of the blob. 8

9 JavaScript commands The blob must contain HTML content, other formats are not supported (like images). 1 MacRoman 2 Windows (ANSI) 3 UTF-8 4 UTF-16 To use the command on a new created browser area, first call Web_SetURL(area; about:blank ) to initialize the HTML area. Platform notes: Windows: Even if the plug-in has displayed a valid URL, after using this command it handles the content as content which has minimum security access rights, for example it cannot execute JavaScript. Although the command handles everything in memory, it is not really fast. Usually it is faster to write a document to disk and then load (or reload) it. Function result If the call was successful it returns 0. Otherwise it was an error. JavaScript commands These commands allow 4D to execute or evaluate JavaScript commands and functions. Using JavaScript, a 4D developer can print or modify the content of the plug-in area. It is possible to modify it in an interactive way, similar to an Ajax site, which modifies only parts of a page and not the whole page. Another example is using the DOM tree to read the content of a web page, like a catalog, and to import the data in 4D. It is even possible to insert JavaScript functions into a foreign web page to add functionality. Important: JavaScript cannot be executed before the page is fully loaded. Therefore we recommend, before using the JavaScript commands, to check using a callback with the commands Web_SetPreferences and Web_kNavigate. There are two commands to execute JavaScript, with or without returning a result. Web_JavaScriptReturn expects the name of an existing JavaScript function with up to 5 parameters and it returns a result. 9

10 Web_JavaScriptExecute can execute any valid JavaScript text, which can declare a new JavaScript function and call one or several functions or all together, but does not return any results. By combining both commands, it is possible to declare a new JavaScript for a remotely loaded web page, and then execute it to fetch data from the web page. Web JavaScript Execute Web_ JavaScriptExecute (Area; Script) error code Script Text JavaScript The command Web_JavaScriptExecute allows the developer to execute JavaScript code. It does not return a result (see Web_JavaScriptReturn for details). The parameter Script can contain the name of an existing JavaScript function or a new JavaScript function, allowing you to "inject code into displayed web pages. Web JavaScript Return Web_ JavaScriptReturn (Area; Function; Result; {Parameter1; Parameter2; Parameter3; Parameter4; Parameter5}) error code Function Text Name of an existing JavaScript function Result Text Result of JavaScript function Parameter1 Text Optional Parameter 1 Parameter2 Text Optional Parameter 2 Parameter3 Text Optional Parameter 3 Parameter4 Text Optional Parameter 4 Parameter5 Text Optional Parameter 5 The command Web_JavaScriptReturn permits executing an existing JavaScript function with up to 5 parameters, returning the result. 10

11 Error Codes The parameter Function must name an existing JavaScript function, otherwise the error is returned. The JavaScript function can be "injected using Web_JavaScriptExecute before using this command. Parameters for this function can be passed (up to 5 parameters). The routine always expects and returns parameters as text, even if the JavaScript function uses other variable types. Error Codes All commands of the plug-in return 0, if the call was successful. Possible error codes are: The specified area is not a area Invalid parameter passed Internal error JavaScript error JavaScript called before page was completely loaded 11

Troubleshooting for Onboarding (PeopleFluent)

Troubleshooting for Onboarding Paperwork (PeopleFluent) When you click the Begin button on the Home Page it will look as if nothing happened, but if you scroll to the bottom of the page the first form