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

https://github.com/slibre/freepascal · Plain Text · 114 lines · 83 code · 31 blank · 0 comment · 0 complexity · 30b12823dbaf20309f9f2c34989c3ad5 MD5 · raw file

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