fpWeb Tutorial: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		Originally based on: fcl-web tutorial (in PDF) by forum user [Leledumbo](https://forum.lazarus.freepascal.org/index.php?action=profile;u=7523).
2	2
3	3		## Introduction
4	4
5	5		fpWeb is a web application framework shipped by FPC in its default distribution as a part of fcl-web package. The framework itself is built on top of fcl-web features. The framework is built with RAD mind to make a good use of componentization in producing dynamic content. A Lazarus package is provided that can use the framework in a drag n drop manner for its session management and content production. This tutorial will attempt to cover basic functionality of fpWeb, so that one can build common web application with it. Note that this tutorial does NOT attempt to teach HTTP protocol, HTML, CSS, JavaScript or database manipulation as the protocol and client languages should be the prerequisites for every web application programmer and database manipulation does not differ from desktop implementation.
6	6
7	7		## Architecture (PLEASE read)
8	8
9	9		Before starting, it's necessary to know the architecture and application flow to avoid confusion when certain things don't work or work unexpectedly. So please spend some time reading this section.
10	10
11	11		### Application
12	12
13	13		Application here refers to the protocol that your app will implement. fpWeb will happily switch from CGI, FCGI, Apache module to embedded server, and more if fcl-web implements another one in the future. Each application is implemented in its own unit, so to switch from one application to another, with the exception of Apache module, one just needs to change the respective identifier in the uses clause. Currently (as of 3.0.0 / 3.1.1), they are:
14	14
15	15		- fpCGI -\> CGI
16	16		- fpFCGI -\> FastCGI
17	17		- fpApache (requires httpd as well) -\> Apache module
18	18		- fpHttpApp -\> embedded server
19	19		- microhttpapp -\> embedded server using GNU libmicrohttp library.
20	20		- fphttpsys -\> Windows system support for HTTP protocol.
21	21
22	22		Throughout this tutorial, we will use embedded server for the sake of simplicity because you don't have to deal with setting up virtual server and messing up with complicated configuration file and service management. Your app will be a single binary portable web application! Another reason would be there are more than just one web server application out there and each has different way to configure. It would be overkill to cover all of them while their documentation already does the job. Apache module is implemented as a (dynamic) library, while other protocols are normal application. Each application may have specific properties (such as port) available and meaningful only to that application. That's why if you look at fcl-web examples, .lpi / .lpr pairs for each protocol are put in their own directories, only the web modules are shared.
23	23
24	24		### Web Modules
25	25
26	26		![](/wiki-images/5/50/FpWeb-overview.png)
27	27
28	28		fpWeb applications consist of web modules which do the actual content production. A web module can contain web actions that can divide the functionality even more. For instance, an auth web module might have login and logout web actions. While an about web module might not need an action at all and serves just one content. Web module is integrated with fpTemplate that can be used for producing dynamic content from a template file. This is roughly similar to what PHP does, only the gap between logic and presentation is forced rather than suggested. Some say that fpTemplate implements passive view while PHP by default implements an active view design pattern.
29	29
30	30		## Installation
31	31
32	32		The fpWeb package for Lazarus is not installed by default (but it's shipped), to enable fpWeb:
33	33
34	34		1. Open Lazarus and choose Package-\>Install/Uninstall Package
35	35		2. In the Available for installation listbox, look for weblaz and press Install selection. Press Save and rebuild IDE and confirm with Continue
36	36		3. Let the IDE rebuild and restart itself. If everything goes well, you should now have fpWeb tab in the component palette, as shown below:
37	37
38	38
39	39
40	40		![](/wiki-images/5/55/Fpwebtutorial_inst.png)
41	41
42	42		## Specialized modules
43	43
44	44		The TFPWebModule class (used below) is a simple example of a fpWEB module that can be used for all kinds of HTTP requests.
45	45
46	46		However, fpWEB comes with some specialized modules, that have extra support for specialized tasks:
47	47
48	48		- The TSimpleFileModule class in unit fpwebfile.pp can be used to send files. You point it to a directory, and it does the rest.
49	49		- The TFPHTMLModule class in unit fphtml.pp can be used to produce HTML.
50	50		- The TProxyWebModule class in unit fpwebproxy.pp is a ready-made forwarding proxy.
51	51		- The TFPWebProviderDataModule class in unit fpwebdata.pp serves data in JSON format that can be consumed by ExtJS stores.
52	52		- The TSQLDBRestModule class in unit sqldbrestmodule.pp implements a full REST server backed by SQLDB. See more info in [[SQLDBRestBridge]].
53	53		- The TJSONRPCModule class in unit webjsonrpc.pp implements a JSON-RPC service.
54	54		- The TExtDirectModule class in unit fpextdirect.pp implements a Ext.Direct variant of a JSON-RPC service.
55	55
56	56		## Hello, World!
57	57
58	58		Let's create a simple Web Application. As commonly taught when learning programming, "Hello, World!" will be our first app.\
59	59
60	60		1\. Open up Lazarus and choose Project-\>New Project then pick HTTP server Application
61	61
62	62
63	63		![Create new HTTP server application](/wiki-images/5/57/Fpwebtutorial_create_app.png)\
64	64
65	65		2\. Another dialog shall appear for serving static files, port selection and multithreading. Just use default port 8080.
66	66
67	67
68	68		``` pascal
69	69		You may skip the static files serving (go to tips and tricks section if you want to know it more).
70	70		```
71	71
72	72		![](/wiki-images/e/e6/Fpwebtutorial_port_selection.PNG)
73	73
74	74		:IMPORTANT!:
75	75
76	76
77	77		If you choose to use threads on *nix, don't forget to add cthreads as the first unit in the .lpr's uses clause, otherwise a RTE 232 will be generated. When running from console, a message shall appear:
78	78
79	79		``` pascal
80	80		This binary has no thread support compiled in. Recompile the application with a thread-driver in the program uses clause before other units using thread.
81	81		```
82	82
83	83		3\. Since Jan 14, 2017 (or FPC 3.0.4), you may need to open the .lpr and add the following line in the main body if it's not already there:
84	84
85	85
86	86		``` pascal
87	87		Application.LegacyRouting := true;
88	88		```
89	89
90	90		reason will be explained in chapter #Routing.
91	91
92	92		4\. Whatever you choose, pick "OK" and you'll be presented in the default one module fpWeb app.\
93	93		5\. Focus the module and move to Object Inspector. Feel free to rename the module if you wish.\
94	94		6\. Choose Events tab and click the button at the right of the second column of the OnRequest row to create the event handler.
95	95
96	96
97	97		![Creating web module's OnRequest handler in the object inspector](/wiki-images/8/8d/Fpwebtutorial_on_request.png)\
98	98
99	99
100	100		You will be redirected to the source editor with the following code:
101	101
102	102		:
103	103
104	104		``` pascal
105	105		procedure TFPWebModule1.DataModuleRequest(Sender: TObject; ARequest: TRequest;
106	106		AResponse: TResponse; var Handled: Boolean);
107	107		begin
108	108		\|
109	109		end;
110	110		```
111	111
112	112
113	113		Fill in the event with:
114	114
115	115		:
116	116
117	117		``` pascal
118	118		procedure TFPWebModule1.DataModuleRequest(Sender: TObject; ARequest: TRequest;
119	119		AResponse: TResponse; var Handled: Boolean);
120	120		begin
121	121		AResponse.Content := 'Hello, World!';
122	122		Handled := true;
123	123		end;
124	124		```
125	125
126	126		7\. Then run your app (or press F9).\
127	127		8\. Open your browser and type:
128	128
129	129
130	130		<http://localhost:8080/>\
131	131
132	132		9\. You should see "Hello, World!" displayed.\
133	133
134	134		If it doesn't, check below:
135	135
136	136		- The framework does a lot of exception handling and the IDE's debugger might catch them and interrupts your app. It's OK to add most of the exceptions to the ignore list so you can concentrate more on your app flow. Keep skipping and continue until no more dialog appears and the browser shows the output.
137	137
138	138		- Handled := true is the way we tell the framework that the request has been handled. Not setting it (or setting it to false) will show error page instead. For now, this doesn't affect the request flow yet, but it will be later on. So keep it that way until the time comes to further make a good use of it.
139	139
140	140		- other track: test without a firewall loaded in RAM (as an application, as a service or deamon, or as both).
141	141
142	142		## Reading GET & POST data
143	143
144	144		A dynamic content is likely to be triggered from user input, either through forms, providing values in the URL, etc. Those data are sent along the request, which is represented in the method as ARequest parameter of type TRequest.
145	145
146	146		### Reading GET
147	147
148	148		GET data is provided as ARequest.QueryFields , which is a TStrings descendant. In short, whatever you usually do with TStrings, is applicable here such as accessing the data in a map style through the Values property.
149	149
150	150		Reusing above code, replace the method body with:
151	151
152	152		``` pascal
153	153		procedure TFPWebModule1.DataModuleRequest(Sender: TObject; ARequest: TRequest;
154	154		AResponse: TResponse; var Handled: Boolean);
155	155		var
156	156		LName: String;
157	157		begin
158	158		LName := ARequest.QueryFields.Values['Name'];
159	159		if LName = EmptyStr then
160	160		with AResponse.Contents do
161	161		begin
162	162		Add('<form action="' + ARequest.URI + '" method="GET"');
163	163		Add('<label for="name">Please tell me your name:</label>');
164	164		Add('<input type="text" name="name" id="name" />');
165	165		Add('<input type="submit" value="Send" />');
166	166		Add('</form>');
167	167		end
168	168		else
169	169		AResponse.Content := 'Hello, ' + LName + '!';
170	170		Handled := true;
171	171		end;
172	172		```
173	173
174	174		ARequest.URI is just a convenience to refer to the current URI, so even when you change your registered module or action name, this code stays the same.
175	175
176	176		Note that as in Pascal, referring to the data is done case insensitively.
177	177
178	178		Now you can try requesting /, which will display
179	179
180	180		` Please tell me your name`
181	181
182	182		and /?name=\<write anything here, e.g.: Bob\>, which will display
183	183
184	184		` Hello, Bob!`
185	185
186	186		### Reading POST
187	187
188	188		POST is actually doesn't differ much from GET, only differs in which property to access. If GET is accessed through ARequest.QueryFields , POST is accessed through ARequest.ContentFields. POST style of previous code is:
189	189
190	190		``` pascal
191	191		procedure TFPWebModule1.DataModuleRequest(Sender: TObject; ARequest: TRequest;
192	192		AResponse: TResponse; var Handled: Boolean);
193	193		var
194	194		LName: String;
195	195		begin
196	196		LName := ARequest.ContentFields.Values['Name'];
197	197		if LName = EmptyStr then
198	198		with AResponse.Contents do
199	199		begin
200	200		Add('<form action="' + ARequest.URI + '" method="POST"');
201	201		Add('<label for="name">Please tell me your name:</label>');
202	202		Add('<input type="text" name="name" id="name" />');
203	203		Add('<input type="submit" value="Send" />');
204	204		Add('</form>');
205	205		end
206	206		else
207	207		AResponse.Content := 'Hello, ' + LName + '!';
208	208		Handled := true;
209	209		end;
210	210		```
211	211
212	212		### Reading File Uploads
213	213
214	214		One exception is for reading multipart/form-data fields, i.e. files. That one is available in ARequest.Files as a TUploadedFiles instance, which is a TCollection descendant. The following is TUploadedFiles public interface which you can use to access the files:
215	215
216	216		``` pascal
217	217		TUploadedFiles = Class(TCollection)
218	218		...
219	219		public
220	220		Function First: TUploadedFile;
221	221		Function Last: TUploadedFile;
222	222		Function IndexOfFile(AName: String) : Integer;
223	223		Function FileByName(AName: String) : TUploadedFile;
224	224		Function FindFile(AName: String) : TUploadedFile;
225	225		Property Files[Index: Integer] : TUploadedFile read GetFile Write SetFile; default;
226	226		end;
227	227		```
228	228
229	229		Each TUploadedFile itself has several properties:
230	230
231	231		``` pascal
232	232		TUploadedFile = Class(TCollectionItem)
233	233		...
234	234		Public
235	235		Destructor Destroy; override;
236	236		Property FieldName: String Read FFieldName Write FFieldName;
237	237		Property FileName: String Read FFileName Write FFileName;
238	238		Property Stream: TStream Read GetStream;
239	239		Property Size: Int64 Read FSize Write FSize;
240	240		Property ContentType: String Read FContentType Write FContentType;
241	241		Property Disposition: String Read FDisposition Write FDisposition;
242	242		Property LocalFileName: String Read FLocalFileName Write FLocalFileName;
243	243		Property Description: String Read FDescription Write FDescription;
244	244		end;
245	245		```
246	246
247	247		They should be descriptive enough, with the exception of FileName and LocalFileName. FileName is the original file name as uploaded from client, LocalFileName is the file path in the server where the file is temporarily stored. Note the difference in bold terms above.
248	248
249	249		Again, reusing the same request handler:
250	250
251	251		``` pascal
252	252		procedure TFPWebModule1.DataModuleRequest(Sender: TObject; ARequest: TRequest;
253	253		AResponse: TResponse; var Handled: Boolean);
254	254		var
255	255		n: Integer;
256	256		f: TUploadedFile;
257	257		i: Integer;
258	258		begin
259	259		n := ARequest.Files.Count;
260	260		if n = 0 then
261	261		with AResponse.Contents do
262	262		begin
263	263		Add('<form id="form" action="' + ARequest.URI + '" method="POST" enctype="multipart/form-data">');
264	264		Add('<label for="name">Drag n drop or click to add file:</label>');
265	265		Add('<input type="file" name="input" />');
266	266		Add('<input type="submit" value="Send" />');
267	267		Add('</form>');
268	268		end
269	269		else
270	270		begin
271	271		f := ARequest.Files[0];
272	272		AResponse.Contents.LoadFromStream(f.Stream);
273	273		end;
274	274		Handled := true;
275	275		end;
276	276		```
277	277
278	278		drag n drop a file (preferably text, as it's will be rendered as text) to the input file field (or click the respective button) then click Send button. The file content should be displayed.
279	279
280	280		## Cookies
281	281
282	282		### Setting
283	283
284		-	<img src="cookie_session_Object_Pascal.png" title="The "cookie" concept, invented by Netscape in 1994, to allow the HTTP server to identify all its clients." width="450" alt="The "cookie" concept, invented by Netscape in 1994, to allow the HTTP server to identify all its clients." />\
	284	+	![The "cookie" concept, invented by Netscape in 1994, to allow the HTTP server to identify all its clients.](cookie_session_Object_Pascal.png "The "cookie" concept, invented by Netscape in 1994, to allow the HTTP server to identify all its clients.")\
285	285		Cookies are browser responsibility to save and keep, therefore server need to send it as part of the response in order to set one. AResponse.Cookies contains a list of cookies to be sent. It's a descendant of TCollection, respectively the contained TCookie is a descendant of TCollectionItem. Therefore, you can use TCollection way of managing items to manipulate it.
286	286
287	287		Here's an example:
288	288
289	289		``` pascal
290	290		procedure TFPWebModule1.DataModuleRequest(Sender: TObject; ARequest: TRequest;
291	291		AResponse: TResponse; var Handled: Boolean);
292	292		var
293	293		C: TCookie;
294	294		begin
295	295		C := AResponse.Cookies.Add;
296	296		C.Name := 'mycookie';
297	297		C.Value := 'somevalue';
298	298		Handled := true;
299	299		end;
300	300		```
301	301
302	302		You won't see any output in your browser. But if you use some kind of developer tools (Chrome has one built-in), you can see the response header:
303	303
304	304		![](/wiki-images/6/69/Fpwebtutorial_cookie_set.png)
305	305
306	306		Note that cookie has attributes, so Name and Value is not the only two you can set. Browse TCookie interface to see what properties are supported.
307	307
308	308		### Getting
309	309
310	310		Once you give Set-Cookie header above, subsequent request to your site will contain additional header containing the value you ask to set previously:
311	311
312	312		![](/wiki-images/9/93/Fpwebtutorial_cookie_get.png)
313	313
314	314		Fortunately, the way to read it is no different from GET & POST data. The related property is ARequest.CookieFields. To read previously set cookie:
315	315
316	316		``` pascal
317	317		procedure TFPWebModule1.DataModuleRequest(Sender: TObject; ARequest: TRequest;
318	318		AResponse: TResponse; var Handled: Boolean);
319	319		begin
320	320		AResponse.Contents.Add('<p>Cookie get: ' + ARequest.CookieFields.Values['mycookie'] + '</p>');
321	321		Handled := true;
322	322		end;
323	323		```
324	324
325	325		## Sessions
326	326
327	327		TFPWebModule is a descendant of TSessionHTTPModule, so it has session management capability. Session is module based, so each module may choose to use or not to use session management.
328	328
329	329		Session is implemented in abstract manner. By default, no implementation is provided. One sample implementation using .ini files is given in iniwebsession unit. You must have this unit in your project or implement one for session management to work. If you decide to implement one, basically you need to extend and implement abstract methods in TCustomSession and TSessionFactory classes.
330	330
331	331		### Activating
332	332
333	333		To activate session management, set CreateSession property to true. Session will be started prior to request handling. In case of a new session, OnNewSession will be called. Initialize your session variables here.
334	334
335	335		### Session Variables Manipulation
336	336
337	337		Session variables are provided as Session.Variables (nb: the Session object is the equivalent of the \$_SESSION array used in PHP). This is a string to string map like structure, so you can read / write it like:
338	338
339	339		``` pascal
340	340		Session.Variables['myvar'] := myvar; // write
341	341		...
342	342		myvar := Session.Variables['myvar']; // read
343	343		```
344	344
345	345		Setting a variable to empty string does NOT remove it. If you really want to remove a variable, call Session.RemoveVariable instead.
346	346
347	347		### Terminating
348	348
349	349		Call Session.Terminate whenever you want to terminate a session (e.g.: user logout). Session will also automatically expire if the next request comes after Session.TimeOutMinutes since last request. When session terminates, OnSessionExpired will be called. Do whatever cleanup you need there.
350	350
351	351		## Routing
352	352
353	353		Since FPC 3.0.4, a new routing mechanism has been implemented. Instead of maintaining backward compatibility, it is decided that the new routing will be the default. Thus, any old code (or new code depending on old routing) must be ported by adding:
354	354
355	355		``` pascal
356	356		Application.LegacyRouting := true;
357	357		```
358	358
359	359		in the .lpr.
360	360
361	361		### Old Mechanism
362	362
363	363		#### Using Multiple Modules
364	364
365	365		You can have multiple modules in your app. Click "File" menu, then click "New...". A dialog shall appear, select "Web Module" from the treeview.
366	366
367	367		![](/wiki-images/e/e5/Fpwebtutorial_new_module.png)
368	368
369	369		then click OK.
370	370
371	371		With multiple modules exist in your app, you can no longer request just with /. The framework will not be able to magically select which module must serve the response, so there are two ways to state which module you'd like to call:
372	372
373	373		- /\<module name\>
374	374		- /?module=\<module name\>
375	375
376	376		In the 2nd format, you can change "module" (which is the default value) to whatever valid query string key by modifying Application.ModuleVariable.
377	377
378	378		#### Using Actions
379	379
380	380		So far, we've only used web modules with single request handler. This doesn't scale much as your web app gets more and more complex. Moreover, some features might have shared properties and be better logically grouped, e.g.:
381	381
382	382		- Account module
383	383		- Login action
384	384		- Logout action
385	385		- Register action
386	386		- Product module
387	387		- Create action
388	388		- Update action
389	389		- Delete action
390	390		- Details action
391	391
392	392		##### Request Handling Flow
393	393
394	394		Before using action, it is important to know fpWeb request handling flow. Failing to do so might render your action useless because it's always your data module that handles the request. How could that be? Going back a few chapters, remember the Handled := true that we always did before? Now this is where Handled parameter comes into play.
395	395
396	396		Every requests will go through module's OnRequest first, regardless the requested action. Only if it does not set Handled to true, web action's OnRequest is executed.
397	397
398	398		In general, the request flow is:
399	399
400	400		![](/wiki-images/e/ea/Fpwebtutorial_request_flow.png)
401	401
402	402		Notice the "Our Concern" box, that's what we're going to put our attention at.
403	403
404	404		##### Add Actions to Web Modules
405	405
406	406		To add an action, select the web module then go to object inspector. In the properties tab, select Actions and click the button on the second column.
407	407
408	408		![](/wiki-images/9/95/Fpwebtutorial_manage_actions.png)
409	409
410	410		A popup window shall appear where you can add, delete and reorder actions.
411	411
412	412		![](/wiki-images/d/db/Fpwebtutorial_edit_actions.png)
413	413
414	414		Press Add, a new action shall appear in the list. Select it then go to object inspector. It will currently show properties and events of that newly created action. Rename the Name property (this will be the name you write in the URL, so give it a short, simple but descriptive name) as you wish, I will choose "Hello". Move on to events tab, do the same as OnRequest for module, click button on the right of OnRequest row to create the request handler.
415	415
416	416		![](/wiki-images/2/2e/Fpwebtutorial_action_onrequest.png)
417	417
418	418		You will be presented in the same OnRequest interface, but this one handles web action instead of web module. Whatever you can do in web module's OnRequest can be done here as well. Copy the method body from the "Hello, World!" section.
419	419
420	420		Remember to remove Handled := true from the previous web module's OnRequest body (or remove the event completely) for the action to take care of the request handling.
421	421
422	422		Run your project, and fire up your browser. Now, since the request handling is delegated to web action, you can no longer just request /, but you need /\<action name\> or \<Module's ActionVar property\>=\<action name\>. Note that \<Module's ActionVar property\> has a default value of empty string, unlike Application.ModuleVariable which has "module" as the default value. So, by default, you can only use the /\<action name\> form.
423	423
424	424		If you have multiple modules, then you have a variety of options:
425	425
426	426		- /\<module name\>/\<action name\>
427	427		- /\<module name\>?action=\<action name\>
428	428		- /\<action name\>?module=\<module name\>
429	429		- /?module=\<module name\>&action=\<action name\>
430	430
431	431		Note that as soon as a module have at least one action, /\<module or action name\> alone will by default map to /\<action name\>. To change the behavior such that it maps to /\<module name\> by default, set Application.PreferModuleName to true. In case of multiple modules, if no module name given, then the default module will handle the given action. To change the behavior such that module name must be explicitly given, set Application.AllowDefaultModule to false.
432	432
433	433		The following tables summarize what will happen based on the two properties:
434	434
435	435		<thead>
436	436
437	437		</thead>
438	438		<tbody>
439	439
440	440		</tbody>
441	441
442	442		##### Default Action
443	443
444	444		Remember the previous diagram, the "Delegate request handling to actions" is actually not so simple, but if we expand that diagram, the image will be too big to fit. So, here's the diagram of that part:
445	445
446	446		![](/wiki-images/4/44/Fpwebtutorial_request_delegation_flow.png)
447	447
448	448		Two important things from the flow: DefActionWhenUnknown and a default action. The former is a web module's property while the latter corresponds to Default property of an action. In the latter case, in case there are more than two actions having Default property set to true, the the action order (as how it's shown in the manage actions popup window) will be considered to decide which is the default action. The two properties forms what the application should do if no matching action found for a given request.
449	449
450	450		The following tables summarize what will happen based on the two properties:
451	451
452	452		<thead>
453	453
454	454		</thead>
455	455		<tbody>
456	456
457	457		</tbody>
458	458
459	459		<thead>
460	460
461	461		</thead>
462	462		<tbody>
463	463
464	464		</tbody>
465	465
466	466		In case of error response above, a stack trace shall follow, complete with line number information if you build your app with -gl. We'll see later on how to create custom handler for this (stacktrace are no good for production). But for now, make sure you understand the concept of web module and web action, especially the request flow. Play around until you think you're ready for next section.
467	467
468	468		### New Mechanism
469	469
470	470		The new mechanism is extremely flexible and works even without data modules (old mechanism only works with data modules).
471	471
472	472		A dedicated unit for this routing is provided as httproute (add this to uses clause of program / unit where you want to register routes). The unit contains a function HTTPRouter that will return singleton object responsible for application's route management and has RegisterRoute method to register your route.
473	473
474	474		#### Route Syntax
475	475
476	476		The first parameter of HTTPRouter.RegisterRoute is the route that will be matched against incoming request. It can be as simple as *** above, which means 0 or more paths or simply any paths, up to as complex as /api/v1/:resource/* which means REQUEST_URI header should start with /api/v1/** followed by something else that will be bound to variable named resource and finally ended with 0 or more paths. It will match:
477	477
478	478		- /api/v1/products
479	479		- /api/v1/products/1
480	480		- /api/v1/products/1/clone
481	481		- /api/v1/products/something/else/that/is/really/long/and/silly
482	482
483	483		but not:
484	484
485	485		- /api/v1
486	486		- /excuse/me/api/v1/products
487	487
488	488		Basically there are only 3 special characters:
489	489
490	490		- * denoting 0 or more paths
491	491
492	492		-
493	493		param denoting a part
494	494
495	495		- / denoting part separator
496	496
497	497		your route will be composed of these 3 characters, plus everything else that made up a route.
498	498
499	499		#### Registering a Route
500	500
501	501		The 2nd, 3rd or 4th parameter (depending on whether you want to handle specific HTTP method and/or pass additional data to it) of HTTPRouter.RegisterRoute is overloaded with several possibilities:
502	502
503	503		- Callback procedure
504	504
505	505		``` pascal
506	506		TRouteCallback = Procedure(ARequest: TRequest; AResponse);
507	507		```
508	508
509	509		- Callback event
510	510
511	511		``` pascal
512	512		TRouteEvent = Procedure(ARequest: TRequest; AResponse) of object;
513	513		```
514	514
515	515		- Object satisfying a (CORBA) interface
516	516
517	517		``` pascal
518	518		IRouteInterface = Interface ['{10115353-10BA-4B00-FDA5-80B69AC4CAD0}']
519	519		Procedure HandleRequest(ARequest: TRequest; AResponse: TResponse);
520	520		end;
521	521		```
522	522
523	523		- Object extending abstract router class
524	524
525	525		``` pascal
526	526		TRouteObject = Class(TObject, IRouteInterface)
527	527		Public
528	528		Procedure HandleRequest(ARequest: TRequest; AResponse: TResponse); virtual; abstract;
529	529		end;
530	530
531	531		TRouteObjectClass = Class of TRouteObject;
532	532		```
533	533
534	534		By default, if 2nd parameter is not a TRouteMethod, then all HTTP methods will match. Use one of rmUnknown, rmAll, rmGet, rmPost, rmPut, rmDelete, rmOptions, rmHead, rmTrace to match only a specific HTTP method.
535	535
536	536		Registration order matters. If there are two or more routes matching the current request, the earlier registered one will handle it.
537	537
538	538		In this new mechanism, standalone Hello, World! program can be as simple as:
539	539
540	540		``` pascal
541	541		uses
542	542		fphttpapp, httpdefs, httproute;
543	543		procedure DoHello(ARequest:TRequest; AResponse : TResponse);
544	544		begin
545	545		AResponse.Content:='<html><body><h1>Hello,World!</h1></body></html>'
546	546		end;
547	547
548	548		begin
549	549		HTTPRouter.RegisterRoute('*', @DoHello);
550	550		Application.Port := 9000;
551	551		Application.Initialize;
552	552		Application.Run;
553	553		end.
554	554		```
555	555
556	556		#### Webserver example
557	557
558	558		This is an example of a simple, cross-platform, multi-threaded web server.
559	559
560	560		``` pascal
561	561		program webserver;
562	562
563	563		{$mode objfpc}{$H+}
564	564
565	565		uses
566	566		{$ifdef UNIX}
567	567		cthreads, cmem,
568	568		{$endif}
569	569		fphttpapp, httpdefs, httproute;
570	570
571	571		procedure route1(aReq: TRequest; aResp: TResponse);
572	572		begin
573	573		aResp.content:='<html><body><h1>Route 1 The Default</h1></body></html>'
574	574		end;
575	575
576	576		procedure route2(aReq: TRequest; aResp: TResponse);
577	577		begin
578	578		aResp.content:='<html><body><h1>Route 2</h1></body></html>'
579	579		end;
580	580
581	581		begin
582	582		HTTPRouter.registerRoute('/', @route1, true);
583	583		HTTPRouter.registerRoute('/route2', @route2);
584	584		Application.port := 8080;
585	585		Application.threaded := true;
586	586		Application.initialize;
587	587		Application.run;
588	588		end.
589	589		```
590	590
591	591		To open "Route 1" type into your browser the following URL: <http://127.0.0.1:8080>
592	592
593	593		To open "Route 2" type into your browser the following URL: <http://127.0.0.1:8080/route2>
594	594
595	595		## Using Templates
596	596
597	597		fpWeb has integrated support for FPTemplate, Free Pascal's generic templating engine. It doesn't have to be used from web application context, but with integrated support things will be easier a bit. At least the memory management can be ignored as the module will take care of it.
598	598
599	599		There are two levels where one can use templates at: action and module. The full RAD support is incomplete, so you need to go down to hand coding at some points.
600	600
601	601		There are two modes of operation: non-parameterized and parameterized. The active mode is controlled by AllowTagParams property, which should be obvious enough what value refers to what mode.
602	602
603	603		Template string can be given from a file through FileName property or a direct string through Template property. Template.Template, I know it sounds weird :) If both are filled then FileName will take precedence.
604	604
605	605		The two properties: StartDelimiter and EndDelimiter define how the engine should recognize a template tag. For instance, if you have:
606	606
607	607		- StartDelimiter = '{+'
608	608		- EndDelimiter = '+}'
609	609
610	610		then a string '{+title+}' defines a template tag named 'title'. Note that spaces are significant, so '{+ title +}' defines a template tag named ' title ' instead of just 'title'.
611	611
612	612		Special for parameterized mode, additional three properties: ParamStartDelimiter, ParamEndDelimiter and ParamValueSeparator defines how the engine should recognize a template tag parameter. For instance, if you have:
613	613
614	614		- ParamStartDelimiter = '\[-'
615	615		- ParamEndDelimiter = '-\]'
616	616		- ParamValueSeparator = '='
617	617
618	618		then a string '{+data \[-p=v-\]\[-a=b-\] +}' defines a template tag named 'data' with parameter 'p' of value 'v' and parameter 'a' of value 'b'. This can be used to pass template level parameter such as expected date format, header-row-footer for customizable output presentation, name of file, etc. you decide.
619	619
620	620		As a consequence of different way of operation, the core event where the template works is different, too. Non-parameterized will use OnGetParam while the parameterized will use OnReplaceTag. The two has of course different interface:
621	621
622	622		``` pascal
623	623		Type
624	624		// OnGetParam: for simple template tag support only (ex: {Name})
625	625		TGetParamEvent = Procedure(
626	626		Sender: TObject;
627	627		Const ParamName: String;
628	628		Out AValue: String
629	629		) Of Object;
630	630		// OnReplaceTag: for tags with parameters support
631	631		TReplaceTagEvent = Procedure(
632	632		Sender: TObject;
633	633		Const TagString: String;
634	634		TagParams: TStringList;
635	635		Out ReplaceText: String
636	636		) Of Object;
637	637		```
638	638
639	639		In OnGetParam, you check for ParamName, then assign AValue accordingly. i.e., if you want tag 'title' to be replaced by 'My App', then fill in the method with:
640	640
641	641		``` pascal
642	642		// use Trim() if you want the spaces around tag to be insignificant
643	643		case Trim(ParamName) of
644	644		'title': AValue := 'My App';
645	645		else
646	646		AValue := 'UNKNOWN';
647	647		end;
648	648		```
649	649
650	650		In OnReplaceTag, you check for TagString and optionally TagParams, then assign ReplaceText accordingly. i.e., if you want tag 'datetime' to be replaced by current time with parameter 'datetimeformat' to specify how the date and time should be formatted, then fill in the method like this:
651	651
652	652		``` pascal
653	653		// use Trim() if you want the spaces around tag to be insignificant
654	654		case Trim(TagString) of
655	655		'datetime': AValue := FormatDateTime(TagParams.Values['datetimeformat'],Now);
656	656		else
657	657		AValue := 'UNKNOWN';
658	658		end;
659	659		```
660	660
661	661		### At Action Level
662	662
663	663		Create/select an action, then go to object inspector. You will see a subcomponent property named Template. This template is a normal TFPTemplate instance. Expand it and fill in the properties as explained above. Now go to Events tab, again expand Template, you will see the two events. Fill the one based on your value of AllowTagParams property.
664	664
665	665		NOTE: If your Lazarus cannot autocomplete the event, try writing the name manually in the edit box then click the ... button. This is a bug in present Lazarus which may be fixed in the future.
666	666
667	667		At this level, template with a content is not automatically set as request handler. It might change in the future, but let's deal with its current state. Fill in OnRequest event of the action, then fill it with:
668	668
669	669		``` pascal
670	670		with Actions.CurrentAction as TFPWebAction do
671	671		begin
672	672		AResponse.Content := Template.GetContent;
673	673		end;
674	674		Handled := true;
675	675		```
676	676
677	677		The cast is required since CurrentAction is of type TCustomWebAction instead of TFPWebAction. Without it, we can't access the Template property.
678	678
679	679		### At Module Level
680	680
681	681		At module level, you currently have to do it by hand coding since no RAD support is implemented. The linked property is ModuleTemplate . This is however not a regular TFPTemplate instance, but special TFPWebTemplate class that's a descendant of it.
682	682
683	683		The idea here is to have module provide a layout while the actions provide content, with the ability to provide additional variables. It's therefore a good idea to keep AllowTagParams as is and assign OnGetParam event of the module only. Do NOT assign OnGetParam of ModuleTemplate as it will never be called.
684	684
685	685		A template tag named 'content' will be replaced automatically by what content produced by action, everything else is either replaced from internal template variables or from OnGetParam.
686	686
687	687		### Using Separated Template
688	688
689	689		Despite the somewhat incomplete integration, nothing stops you from using fpTemplate (or any other templating solutions) manually, outside from the integrated support. This could even be better in some cases since it's modular.
690	690
691	691		## Using an html Producer object
692	692
693	693		Assuming that there is a TWebAction named act_get_my_html, you must ask to write in AResponse, the return of an internal bytes stream: when answering with html Producer objects solution, we must use the methods of the writer. It manages a memory stream for a purpose of rapidity. No string type here, like with the above fpTemplate solution which uses text \\ string processing as in the regular Php way. The Producer writes in AResponse with a recursive " foreach " iteration, that traverses the polymorphic objects HTML Dom tree, composed with the hierarchy THtmlCustomElement = Class(TDOMElement) Classes (see unit htmlelements.pp). So, the AResponse is written by the parameter aWriter, with the following call:
694	694
695	695		``` pascal
696	696		procedure TFPWebModule1.act_get_my_htmlRequest(Sender: TObject; ARequest: TRequest; AResponse: TResponse; var Handled: Boolean);
697	697		begin
698	698		(* ask HTMLEntityProducer1 for the content of its html DOM elements: *)
699	699		HTMLEntityProducer1.HandleRequest(ARequest, AResponse, Handled);
700	700		Handled := True;
701	701		end;
702	702		```
703	703
704	704		Said again, it's the job of the Producer to convert its internal memory stream into text in the response object: that's how this pattern was designed, although there is a text-html rendering method named ProduceContent for debugging purposes only. You can override this method if you are writing or debugging a Producer component.
705	705
706	706		Here is an example, always with an html Producer object, allowing to create a web application in the "RAD way", i.e. with the drag-drop of the HTMLEntityProducer component from the pallet:
707	707
708	708		``` pascal
709	709		procedure TFPWebModule1.HTMLEntityProducer1WriteEntity(Sender: THTMLContentProducer; aWriter: THTMLWriter);
710	710		begin
711	711
712	712		aWriter.startHeader;
713	713		aWriter.Meta('','Content-Type','text/html; charset=UTF-8');
714	714		aWriter.title('My web page');
715	715		aWriter.link('stylesheet','stylesheet.css','text/css','screen');
716	716		aWriter.EndHeader;
717	717
718	718		aWriter.Startbody;
719	719		aWriter.Startparagraph;
720	720		aWriter.heading2('Hello, world from inside §1:');
721	721		aWriter.Text('Here is text written inside the current paragraph.');
722	722		aWriter.Endparagraph;
723	723		aWriter.paragraph('This is another text written inside a self "started and ended" paragraph.');
724	724		aWriter.Startparagraph;
725	725		aWriter.heading2('Hello, world from inside §2:');
726	726		aWriter.Text('Here is the final text.');
727	727		aWriter.Image.src := 'logo.png';
728	728		AnotherProducer.WriteContent(aWriter);
729	729		aWriter.Endparagraph;
730	730		aWriter.Endbody;
731	731
732	732		end;
733	733		```
734	734
735	735		The TWebAction.ContentProducer property allows to couple a THTTPContentProducer to its web action exposed via a URI on the net.
736	736
737	737		\[ToDo: there is no official documentation about the components "RAD way" of fpWeb (html producer, html provider, html adapter, html formatter, etc)\]
738	738
739	739		## Tips and Tricks
740	740
741	741		### Returning Different HTTP Response Code
742	742
743	743		By default, fpWeb will return HTTP 200 OK to indicate successful request handling. This surely is not always the case, as user input might not be as what we expected. To do so, set AResponse.Code in your request handler to the code you want to return.
744	744
745	745		### Redirect Request to Different URL
746	746
747	747		A common flow after a successful login is to redirect user to his account page. This can be done by calling AResponse.SendRedirect in your request handler, supplying the URL to redirect request to.
748	748
749	749		### Serving Static Files (Embedded Web Server)
750	750
751	751		Remember the dialog in the #Hello, World! section after you select HTTP server Application? If you tick "Register location to serve files from" you can fill "Location" (the URI segment, must not contain any slashes) and "Directory" (physical directory in your computer, must exist at runtime) and the wizard will simply add:
752	752
753	753		``` pascal
754	754		RegisterFileLocation('<Location>','<Directory>');
755	755		```
756	756
757	757		to the beginning of your .lpr and add the unit fpwebfile to the uses clause. You can actually do this by hand anytime and also register multiple times for different locations / directories. After this you can request /\<Location\>/\<any filename under Directory\> and it will be served automatically. Note that the mimetype of the file is determined by fpmimetypes. Call MimeTypes.LoadFromFile with your mime.types file in order to give correct mimetype based on its extension. Otherwise, the file will always be served as application/octet-stream which means the browser will download it instead of interpreting it (especially important for JavaScript and CSS files).
758	758
759	759		You can grab a complete mime.types here <http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/conf/mime.types?&view=co>
760	760
761	761		In Lazarus 2.0.6 or newer you must add at the top of your program the full path of the mime.types file
762	762
763	763		``` pascal
764	764		begin
765	765		MimeTypesFile := Application.Location + 'mime.txt';
766	766		```
767	767
768	768		Take into consideration that the default path coming with the project is lib\\\$(TargetCPU)-\$(TargetOS)
769	769
770	770		For example httpproject\lib\i386-win32\mime.txt
771	771
772	772		### Centralize Management of Configuration and Modules
773	773
774	774		By default, the program file (.lpr) is the one that contains protocol unit. This limits the ability to use Application object from other contexts such as from web modules. Fortunately, it's not difficult to refactor to have what we want. We remove RegisterHTTPModule calls from web modules' units and left out the .lpr to empty main block with single unit identifier in the uses clause, we name it: brokers. The unit contains:
775	775
776	776		``` pascal
777	777		unit Brokers;
778	778
779	779		{$mode objfpc}{$H+}
780	780
781	781		interface
782	782
783	783		{ $define cgi}
784	784		{ $define fcgi}
785	785		{$define httpapp}
786	786
787	787		uses
788	788		CustWeb;
789	789
790	790		function GetApp: TCustomWebApplication; inline;
791	791
792	792		implementation
793	793
794	794		uses
795	795		{$ifdef cgi}fpcgi{$endif}
796	796		{$ifdef fcgi}fpfcgi{$endif}
797	797		{$ifdef httpapp}fphttpapp{$endif}
798	798		,webmodule1
799	799		,webmodule2
800	800		;
801	801
802	802		function GetApp: TCustomWebApplication;
803	803		begin
804	804		Result := Application;
805	805		end;
806	806
807	807		initialization
808	808		RegisterHTTPModule('wm1', TWebModule1);
809	809		RegisterHTTPModule('wm2', TWebModule2);
810	810		{$ifndef cgi}
811	811		Application.Port := 2015;
812	812		{$endif}
813	813		Application.Initialize;
814	814		Application.Run;
815	815		end.
816	816		```
817	817
818	818		This way, we can control over web module registration and also provide an API to get Application object (casted as TCustomWebApplication), while still easily switch between protocol implementations, in a single place.
819	819
820	820		### Terminating Gracefully (FastCGI / Embedded Web Server)
821	821
822	822		Instead of Ctrl+C-ing your app, there is a way for your app to terminate gracefully, doing whatever cleanup it needs, by calling Application.Terminate. You might need to use previous trick to easily access the Application object. A common implementation is to provide a specific password protected module / action that calls the Terminate method. You may choose whatever way you want, though.
823	823
824	824		### Custom Exception Handler
825	825
826	826		\[edit the May 1, 2020 =\> moved from a method pointer to a simple procedure.\]
827	827
828	828		To override the default exception handler, which prints stacktrace whenever an exception is raised (i.e.: on HTTP 404 or 500), and thus not good for production, you must assign Application.OnShowRequestException.
829	829
830	830		This is a method so you will need to provide your procedure that implements the method and assign it by using the object. i.e.: if you have MyExceptionHandler as an object of TMyExceptionHandler which has MyShowRequestException method, you can assign it by:
831	831
832	832		``` pascal
833	833		Application.OnShowRequestException := @MyExceptionHandler.MyShowRequestException;
834	834		```
835	835
836	836		don't forget to .Create() MyExceptionHandler BEFORE assigning above or you will get an EAccessViolation!
837	837
838	838		You must provide your global procedure that implements your own exception handler (in production, it is advisable to replace the call stack by an HTTP status code and its explanation). Then, you can override the default exception handler, by assigning it like this:
839	839
840	840		``` pascal
841	841		Application.OnShowRequestException := @MyShowRequestException;
842	842		```
843	843
844	844		### Pure Hand Coding (No Form Designer Required)
845	845
846	846		It's not a must to use Lazarus' form designer to write an fpWeb application. You can use pure hand coding technique to write it. The secret lies in the 3rd parameter of RegisterHTTPModule : SkipStreaming. When this parameter is set to true, fpWeb will not search for .lfm resource. Therefore everything must be manually handled: property settings, event handlers, action registration, etc.
847	847
848	848		Note that it's logical to do what's usually done through object inspector in an overriden constructor. Inside it, call the inherited constructor supplying both AOwner and CreateMode as parameters. After that you can set properties, assign event handlers, etc. Example:
849	849
850	850		``` pascal
851	851		type
852	852		THelloWorldModule = class(TFPWebModule)
853	853		constructor CreateNew(AOwner: TComponent; CreateMode: Integer); override;
854	854		procedure Request(Sender: TObject; ARequest: TRequest;
855	855		AResponse: TResponse; var Handled: Boolean);
856	856		end;
857	857
858	858		constructor THelloWorldModule.CreateNew(AOwner: TComponent; CreateMode: Integer);
859	859		begin
860	860		inherited CreateNew(AOwner,CreateMode);
861	861		OnRequest := @Request;
862	862		end;
863	863
864	864		procedure THelloWorldModule.Request(Sender: TObject; ARequest: TRequest;
865	865		AResponse: TResponse; var Handled: Boolean);
866	866		begin
867	867		AResponse.Content := 'Hello, World!';
868	868		Handled := true;
869	869		end;
870	870		```
871	871
872	872		## See also
873	873
874	874		- [Possibly same content](https://github.com/leledumbo/fpWebTutorial)
875	875		- [Lazarus for the web (tutorial)](https://www.freepascal.org/~michael/articles/#web1)
876	876		- [Lazarus for the web: Sessions and Templates (tutorial)](https://www.freepascal.org/~michael/articles/#web2) This article explains a TSQLDBSession Class that manages a SQL connection, that inherits from a web session (in order to manage the histories of web session variables, within a connection-session to a database having row-locking capabilities).
877	877		- the examples - read the text files - in your directory ...\fpc\x.x.x\source\packages\fcl-web\examples.\
878	878
879		-	~~<img src="cgi-listrecords.png" title="Screenshot copy of one of the examples" width="50" />~~
	879	+	![](/wiki-images/c/c0/Cgi-listrecords.png)
880	880
881	881		- XML or JSON, on ExtJS: if you want to use a more or less complex engine that is very "accomplished" regarding the rendering aspect of Javascript objects on the browser side, in addition to their functionalities (like ExtJS, for example, to display a db-aware grid, dynamic graphics, etc), this kind of solution very very often expects an XML or a JSON file. There are Adapter and Formatter classes (e.g. the classes TExtJSXMLWebdataInputAdaptor, TExtJSJSONDataFormatter).
882	882
883	883		Overall, the Adapter classes adapt the nodes of an incoming jSon or XML to a mapping of their TField database fields. And Formatter classes are mappers of each TField of a record to its node in jSon or XML format, before sending it out towards the browser.\
884	884		* [Web data formats in Lazarus/FPC](https://www.freepascal.org/~michael/articles/#webdata)
885	885
886	886		- [Practical GUI construction in ExtJS](https://www.freepascal.org/~michael/articles/#extjs1)
887	887		- [Mixing ExtJS webapplications and Pascal: ExtPascal](https://www.freepascal.org/~michael/articles/#extpascal)
888	888
889	889		---
890	890		From the Free Pascal wiki, page "fpWeb Tutorial", as it stood on 2023-03-17 after a change by Trev, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).

Back to history