Icon External Interfaces

Sometimes it is necessary to make calls from an application to external code such as 3rd party JavaScript code or the built-in classes available as part of the web browser's DOM (Document Object Model) class hierarchy. The DOM is the core framework in a modern web browser that allows any JavaScript code to create and manipulate elements in an HTML or XML document, as well as parts of the web browser itself. Elevate Web Builder includes a fairly complete external interface to the DOM in the WebDOM unit that is part of the runtime code included with the product.

The Elevate Web Builder compiler requires that an external interface be declared for any external DOM classes or JavaScript code before such classes or code can be used in an application. External interfaces are only interfaces and do not include any type of implementation. Using external interfaces will ensure that the benefits of compile-time type checking are applied to external code as well as the Object Pascal code in the application, thus allowing for more reliable applications.

Please see the Modifying Project Options and Using the Project Manager topics for more information on including external JavaScript source files with an application.

External Declarations
You must include the WebDOM unit in the uses clause of the interface section of the unit in which any external class declarations are included. The WebDOM unit is necessary for obtaining certain base class declarations.

Any constant, variable, type, class, procedure, or function can be declared as external. For example, the DOM in the web browser includes a global variable called "window" that is an instance of the Window DOM class. Elevate Web Builder represents both in the WebDOM unit as follows:


   external TWindow emit Window = class
         { Properties }
         property closed: Boolean read;
         property defaultStatus: String read write;
         property document: TDocument read;
         property event: TEvent read; // IE-only
         property frames: TWindowList read;
         property history: THistory read;
         property innerHeight: Integer read; // Supported by IE9 or higher
         property innerWidth: Integer read; // Supported by IE9 or higher
         property localStorage: TStorage read;
         property location: TLocation read;
         property name: String read write;
         property navigator: TNavigator read;
         property opener: TWindow read;
         property orientation: Integer read; // Mobile platforms only
         property outerHeight: Integer read; // Not supported by IE
         property outerWidth: Integer read; // Not supported by IE
         property pageXOffset: Integer read; // Not supported by IE
         property pageYOffset: Integer read; // Not supported by IE
         property parent: TWindow read;
         property screen: TScreen read;
         property screenLeft: Integer read; // IE-only
         property screenTop: Integer read; // IE-only
         property screenX: Integer read; // Not supported by IE
         property screenY: Integer read; // Not supported by IE
         property sessionStorage: TStorage read;
         property status: String read write;
         property top: TWindow read;
         property window: TWindow read;
         { Events }
         property onblur: TEventHandler read write;
         property onerror: TErrorEventHandler read write;
         property onfocus: TEventHandler read write;
         property onload: TEventHandler read write;
         property onresize: TEventHandler read write;
         property onunload: TEventHandler read write;
         { Methods }
         procedure addEventListener(const type: String; listener: TEventHandler;
                                    useCapture: Boolean);
         procedure alert(const message: String);
         procedure blur;
         procedure cancelAnimationFrame(animationId: Integer);
         procedure clearInterval(intervalId: Integer);
         procedure clearTimeout(timeoutId: Integer);
         procedure close;
         function confirm(const question: String): Boolean;
         procedure detachEvent(const type: String; handler: TEventHandler);
         procedure focus;
         function getComputedStyle(elt: TDOMElement; const pseudoElt: String): TCSS2Properties;
         procedure moveBy(dx, dy: Integer);
         procedure moveTo(x, y: Integer);
         function open(const url: String; const name: String=''; const features: String='';
                       replace: Boolean=False): TWindow;
         procedure print;
         function prompt(const message: String; default: String): String;
         procedure removeEventListener(const type: String; listener: TEventHandler;
                                       useCapture: Boolean);
         function requestAnimationFrame(callback: TAnimationHandler): Integer;
         procedure resizeBy(dw, dh: Integer);
         procedure resizeTo(w, h: Integer);
         procedure scrollBy(dx, dy: Integer);
         procedure scrollTo(x, y: Integer);
         function setInterval(code: TIntervalHandler; intervalId: Integer): Integer;
         function setTimeout(code: TIntervalHandler; intervalId: Integer): Integer;
   external window: TWindow;

Warning Because JavaScript is case-sensitive, all external declarations are case-sensitive and must match the required case of the external Javascript declarations for the same entities. This only applies to the external declarations. All Object Pascal code that calls the external code can still use any case desired, and the compiler will automatically make sure that the proper case is used in the emitted code for the application.

The rules and exceptions for external declarations are:
  • External class declarations cannot contain private or protected members, only public members.

  • External class instances do not necessarily follow the same instantiation rules regarding member variables. Non-external classes are guaranteed to have all of their member variables initialized to appropriate values, but this is not necessarily true for external classes.

  • External classes can still be created with the Create method and freed with the Free method, but internally the compiler will emit slightly different code than it does for non-external classes.

  • External classes can only inherit from other external classes, and non-external classes can only inherit from non-external classes.

  • The read and write clauses for properties in external class declarations do not refer to any member variables or methods.

  • You can use the emit clause to control the class name/namespace used when the compiler emits references to the class when creating new instances. This is useful when instantiating JavaScript objects that are nested within namespaces. For example, Google Maps integration requires the following emit clause:

    external TGoogleMapOptions emit google.maps.MapOptions = class