/packages/fcl-web/src/webdata/readme.txt

  1FPC WebData architecture
  2========================
  3
  4The aim of this set of components is to be able to easily send data 
  5to a webapplication, and to handle updates of this data, all in a
  6webserver module.
  7
  8The following components are used
  9
 10- TFPWebDataProvider
 11  The central component, forming a bridge between TDataset and web content.
 12
 13- TCustomWebdataInputAdaptor
 14    A class that transforms the input of a web request to something that
 15    TFPWebDataProvider understands. Example implementations are provided 
 16    for ExtJS, XML and JSON.
 17
 18- TWebdataInputAdaptor
 19   A descendent of TCustomWebdataInputAdaptor that allows to select the
 20   input format from a list of known formats.
 21
 22- TCustomHTTPDataContentProducer
 23    This class produces the response for the webapplication. It is an
 24    abstract class: descendents need to be made for the various expected
 25    outputs. Example implementations are provided for ExtJS, XML and JSON.
 26
 27- THTTPDataContentProducer
 28   A descendent of TCustomHTTPDataContentProducer that allows to select the
 29   output format from a list of known formats.
 30
 31- TFPWebProviderDataModule
 32   A THTTPSessionDatamodule descendent that can be used to handle data
 33   requests from a webclient. It functions as a container for
 34   TFPWebDataProvider components, InputAdaptors and Content producers.
 35
 36   A module is registered in the Lazarus IDE package under File/New.
 37
 38Typically, one will do the following
 39 - Create a TFPWebProviderDataModule from the IDE.
 40 - Drop some dataset components on it, and set them up for use with some
 41   datasources
 42 - For each dataset, drop a TFPWebDataProvider component on the module, 
 43   and connect it to the datasource. The name of this component is exposed
 44   to the client.
 45 - Drop a suitable input adaptor.
 46 
 47The data can then typically be read through the URL:
 48baseurl/modulename/providername/read
 49Or updated through the URLs
 50baseurl/modulename/providername/update
 51baseurl/modulename/providername/create
 52baseurl/modulename/providername/delete
 53where baseurl is the base URL for the web-application.
 54
 55Large applications: factory support
 56For large-scale applications with lots of different datasets, there is
 57support for registering dataproviders in a central factory system:
 58
 59The WebDataProviderManager function returns an instance of
 60TFPWebDataProviderManager.
 61
 62It must be used to register WebDataProvider names and classes:
 63
 64Function RegisterProvider(Const AProviderName : String; AClass : TFPCustomWebDataProviderClass) : TWebDataProviderDef; overload;
 65
 66The first form registers a class: an instance of this class will
 67be created by the factory whenever a provider of name AProviderName is
 68requested.
 69
 70The TFPWebProviderDataModule class is aware of the WebDataProviderManager
 71factory class, and will look there for a TFPCustomWebDataProvider instance
 72if none is found in the webmodule instance itself and the
 73'UseProviderManager' property is 'True'.
 74
 75The WebDataProviderManager factory can also Register a complete datamodule:
 76
 77Procedure RegisterDatamodule(Const AClass : TDatamoduleClass);
 78
 79This will register all WebDataProvider instances on the datamodule:
 80An instance will be created, all  TFPCustomWebDataProvider instances
 81will be registered with their component names. 
 82When a provider belonging to such a datamodule is requested, then
 83the module will be created, and the requested TFPCustomWebDataProvider 
 84instance is returned. 
 85
 86A provider instance can be requested with the following factory methods:
 87
 88Function GetProvider(Const ADef : TWebDataProviderDef; AOwner : TComponent;out AContainer : TComponent): TFPCustomWebDataProvider; 
 89Function GetProvider(Const AProviderName : String; AOwner : TComponent; Out AContainer : TComponent): TFPCustomWebDataProvider;
 90
 91The result is the provider instance. All instances are created using a
 92container module: either this is the module class used in RegisterDatamodule
 93or a vanilla TDatamodule class. This instance is returned in AContainer.
 94
 95The container must be freed by the caller.
 96
 97In practise, this means that one creates a datamodule, drops some
 98TFPWebDataProvider instances on it, and adds the following call
 99to the initialization section of the unit:
100
101WebDataProviderManager.RegisterDatamodule(TMyDataModule);
102
103The TFPWebProviderDataModule that handles web requests will then be able
104to handle requests for the TFPWebDataProvider instances on the datamodule.
105
106Note that the RegisterDataModule routine will create an instance of the
107datamodule to get a list of provider components (it uses the component.name
108property). The WebDataProviderManager's 'registering' property will be set 
109to true: this way one can avoid connecting to a database during registration.
110
111The WebDataProviderManager also handles the registration of inputadataptors
112and output contents producers.
113
114