Sometimes it is necessary to make calls from an application to code that is external to the application or component library code. In order to do so, you must first create an external interface that provides the compiler with information about how the external code should be used. An external interface is a set of declarations that differ slightly from normal declarations and contains no implementation code for the external declarations. Regular declarations and external declarations can be mixed together in the same source unit.

For client applications, external code will include JavaScript code or the built-in classes available as part of the a browser's DOM (Document Object Model) class hierarchy. The DOM is the core framework in a browser that allows any JavaScript code to create and manipulate elements in an HTML or XML document, as well as parts of the browser itself. A fairly complete external interface to the DOM is in the WebDOM unit that is included as part of the client component library.


For server applications, external code is the native code surfaced as intrinsic functions/procedures in the run-time, as well as any external native Delphi code that is made available to the application code using native external module(s). Please see the Web Server Applications topic for more information on native external modules and the Creating a New External Module Interface Unit topic for more information on how to automatically generate the external interface for a native external module.


Please see the Using the Project Manager topic for more information on including external JavaScript source files with client applications and native external modules with server applications.

External Declarations

---

External declarations are marked as such by including the special external keyword before the declaration. The syntax for all declarations is:

{ Enumerated type declaration }

external <Type Name> = (<Member>[, Member]) [module <Native External Module>];   

{ Class type declaration }
   
external <Class Name> [emit <External Type Name>]|[module <Native External Module>] = class[(<Class Name>)]
   [public]
      property <Property Name>:<Type Name> read [write]; [default;]
   end;

{ Function/procedure declarations }

external procedure <Function/Procedure Name>([<Parameter>[, <Parameter>]])[: <Type Name>] [module <Native External Module>];

{ Variable declarations }

var external <Variable Name>: <Type Name> [module <Native External Module>];

The following are the rules and restrictions for external declarations:

• Because JavaScript is the target language for external code in client applications and is case-sensitive, all external declarations for client applications 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, themselves. All application and component library 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.



• Constant declarations are not discoverable in external JavaScript code or native external modules and are not considered part of an external interface. If there are any special constant declarations required in the external interface, they will need to be added manually.



• The ancestor class for all external class type declarations is the TExternalObject class, not the TObject class that is used with non-external class type declarations. If the ancestor class name is not explicitly specified, then the TExternalObject class is implicitly used as the ancestor class.



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



• You can use the emit clause with client external interfaces 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 classes that are nested within namespaces. For example, Google Maps integration requires the following emit clause:
  
  

  external TGoogleMapOptions emit google.maps.MapOptions = class




• The module clause is required for external interfaces to native external modules in server applications. The clause tells the compiler which native external module contains the corresponding implementation for the declaration.



• External class type declarations contain only public member declarations. The public scope keyword is optional for external class type declarations and can be omitted.



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



• External class instances do not necessarily follow the same instantiation rules regarding the initialization of 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.

The following is an example class type declaration from the WebDOM unit included with the component library for client applications:

external THTMLImageElement emit HTMLImageElement = class(THTMLElement)
   public
      { Properties }
      property alt: String read write;
      property height: Integer read;
      property isMap: Boolean read write;
      property longDesc: String read write;
      property name: String read write;
      property naturalHeight: Integer read;
      property naturalWidth: Integer read;
      property src: String read write;
      property useMap: String read write;
      property width: Integer read;
   end;

The following is an example class type declaration from the example extclasstype native external module included with the component library for server applications:

external TVehicle module extclasstype = class(TExternalObject)
   public
      { Properties }
      property VIN: String read write;
      property VehicleType: TVehicleType read write;
      property Make: String read write;
      property Model: String read write;
      property Year: Integer read write;
      { Methods }
      function EstimateValue(ACondition: TVehicleCondition): Integer;
   end;