Generating client wrappers

Even if it feasible to write the client code by hand, your mORMot server is able to create the source code needed for client access, via a dedicated method-based service, and set of Mustache-based templates - see Mustache template engine.

The following templates are available in the CrossPlatformtemplates folder:

Unit Name Compiler Target
CrossPlatform.pas.mustache Delphi / FPC SynCrossPlatform* units
Delphi.pas.mustache Delphi Win32/Win64 mORMot units
SmartMobileStudio.pas.mustache Smart Mobile Studio 2.1

In the future, other wrappers may be added. And you can write your own, which could be included within the framework source! Your input is warmly welcome, especially if you want to write a template for Java or C# client. The generated data context already contains the data types corresponding to those compilers: e.g. a mORMot's RawUTF8 field or parameter could be identified as "typeCS":"string" or "typeJava":"String" in addition to "typeDelphi":"RawUTF8" and "typePascal":"string".

Publishing the code generator

By default, and for security reasons, the code generation is not embedded to your mORMot RESTful server. In fact, the mORMotWrapper.pas unit will link both mORMot.pas and SynMustache.pas units, and use Mustache templates to generate code for a given TSQLRestServer instance.

We will start from the interface-based service Sample code as defined in the
"SQLite3- Interface based services" folder.
After some minor modifications, we copied the server source code into
"SQLite3- CrossPlatform ClientsProject14ServerHttpWrapper.dpr":

program Project14ServerHttpWrapper;

{$APPTYPE CONSOLE}

uses
  SysUtils,
  Classes,
  SynCommons,
  mORMot,
  mORMotHttpServer,
  mORMotWrappers,
  Project14Interface in '..\14 - Interface based services\Project14Interface.pas';

type
  TServiceCalculator = class(TInterfacedObject, ICalculator)
  public
    function Add(n1,n2: integer): integer;
  end;

function TServiceCalculator.Add(n1, n2: integer): integer;
begin
  result := n1+n2;
end;

var
  aModel: TSQLModel;
  aServer: TSQLRestServer;
  aHTTPServer: TSQLHttpServer;
begin
  // create a Data Model
  aModel := TSQLModel.Create([],ROOT_NAME);
  try
    // initialize a TObjectList-based database engine
    aServer := TSQLRestServerFullMemory.Create(aModel,'test.json',false,true);
    try
      // add the http://localhost:888/root/wrapper code generation web page
      AddToServerWrapperMethod(aServer,
        ['..\..\..\CrossPlatform\templates','..\..\..\..\CrossPlatform\templates']);
      // register our ICalculator service on the server side
      aServer.ServiceRegister(TServiceCalculator,[TypeInfo(ICalculator)],sicShared);
      // launch the HTTP server
      aHTTPServer := TSQLHttpServer.Create(PORT_NAME,[aServer],'+',useHttpApiRegisteringURI);
      try
        aHTTPServer.AccessControlAllowOrigin := '*'; // for AJAX requests to work
        writeln(#10'Background server is running.');
        writeln('You can test http://localhost:',PORT_NAME,'/wrapper');
        writeln(#10'Press [Enter] to close the server.'#10);
        readln;
      finally
        aHTTPServer.Free;
      end;
    finally
      aServer.Free;
    end;
  finally
    aModel.Free;
  end;
end.

As you can see, we just added a reference to the mORMotWrappers unit, and a call to AddToServerWrapperMethod() in order to publish the available code generators.

Now, if you run the Project14ServerHttpWrapper server, and point your favorite browser to http://localhost:888/root/wrapper you will see the following page:

Client Wrappers

Available Templates:

* CrossPlatform
mORMotClient.pas - download as file - see as text - see template

* Delphi
mORMotClient.pas - download as file - see as text - see template

* SmartMobileStudio
mORMotClient.pas - download as file - see as text - see template

You can also retrieve the corresponding template context.

Each of the *.mustache template available in the specified folder is listed here. Links above will allow downloading a client source code unit, or displaying it as text in the browser. The template can also be displayed un-rendered, for reference. As true Mustache templates, the source code files are generated from a data context, which can be displayed, as JSON, from the "template context" link. It may help you when debugging your own templates. Note that if you modify and save a .mustache template file, just re-load the "see as text" browser page and your modification is taken in account immediately (you do not need to restart the server).

Generated source code will follow the template name, and here will always be downloaded as mORMotClient.pas. Of course, you can change the unit name for your end-user application. It could be even mandatory if the same client would access to several mORMot servers at once, which could be the case in a Service-Oriented Architecture (SOA) project.

Just ensure that you will never change the mORMotClient.pas generated content by hand. If necessary, you can create and customize your own Mustache template, to be used for your exact purpose. By design, such automated code generation will require to re-create the client unit each time the server ORM or SOA structure is modified. In fact, as stated in the mORMotClient.pas comment, any manual modification of this file may be lost after regeneration. You have been warned!

If you feel that the current templates have some issues or need some enhancements, you are very welcome to send us your change requests on our forums. Once you are used at it, Mustache templates are fairly easy to work with. Similarly, if you find out that some information is missing in the generated data context, e.g. for a new platform or language, we would be pleased to enhance the official mORMotWrapper.pas process.

Visit our source code repository

There is nothing better than some real files.

You can take a look at the following files in our source code repository:

Enjoy!