pas2js designtime: what changed

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

Old	New		Line
1	1		# Designtime support for Pas2JS Components
2	2
3	3		The pas2jscomponents.lpk package that comes with lazarus installs design-time support for pas2js webwidgets and design-time editing of components.
4	4
5	5		## Installed functionality
6	6
7	7		- there is a new file type 'HTML Fragment', this is akin to a 'Form' or 'Frame'.
8	8		- There are several components that allow you to interact with the HTML.
9	9		- THTMLElementActionList
10	10		- TBootstrapModal
11	11		- TBootstrapToastWidget
12	12		- TTemplateLoader
13	13		- TSQLDBRestConnection
14	14		- TSQLDBRestDataset
15	15		- TDBBootstraptableWidget
16	16		- TDBLoopTableWidget
17	17		- TDBSelectWidget
18	18
19	19		The package also installs support for parsing HTML files and loading HTML id attributes from the html. Properties that need a HTML element ID, will display a dropdown with the discovered ID attributes.
20	20
21	21		## HTML Fragment
22	22
23	23		The HTML fragment is the HTML equivalent of a form in a native LCL application. An application can contain multiple HTML fragments, which can be shown at the same time or separately.
24	24
25	25		You can add a new HTML fragment with the File-New dialog:
26	26
27	27		![](/wiki-images/1/1c/Htmlfragment.png)
28	28
29	29		This will start a new form, which looks like a datamodule in the IDE.
30	30
31	31		After dropping some components on it, it will look for example like this in the designer:
32	32
33	33		![](/wiki-images/9/9f/Fragment-design.png)
34	34
35	35		The object inspector can be used to manipulate the properties, just as for a regular form.
36	36
37		-	~~` Note: `\~~
38		-	~~` You must add ``-JRjs`` to the custom compiler options of your project to include the form data in the application.`\~~
39		-	~~` Additionally, the ``p2jsres`` unit must be added to the uses clause of your program, so the resource data can be loaded when the program is run.`~~
	37	+	``` pascal
	38	+	Note:
	39	+	You must add -JRjs to the custom compiler options of your project to include the form data in the application.
	40	+	Additionally, the p2jsres unit must be added to the uses clause of your program, so the resource data can be loaded when the program is run.
	41	+	```
40	42
41	43		The HTML for the fragment can be loaded in 3 ways:
42	44
43	45		- Set the UseProjectHTMLFile property to True if you will only use the main html file of your project. No additional HTML will be loaded.
44	46		- Set the TemplateName property to the name of a template to load.
45	47		- Set the HTMLFilename property to the name of a HTML file to load. It will be loaded using the global template loader in unit rtl.TemplateLoader
46	48
47	49		The ParentID property determines under what HTML element in the main HTML page the HTML fragment will be loaded.
48	50
49	51		The following events exist:
50	52
51	53		- OnAllowUnrender is called when you wish to show another HTML fragment instead of this one. It is equivalent to OnCloseQuery in an LCL form.
52	54		- OnCreate Called when the fragment is created. note that the HTML is not yet available.
53	55		- OnDestroy Called when the fragment is destroyed.
54	56		- OnHTMLLoaded Called when the HTML fragment has been loaded from the server.
55	57		- OnRendered Called when the HTML fragment has been inserted in the DOM.
56	58		- OnUnRendered Called when the HTML fragment has been removed from the DOM.
57	59
58	60		## Installed components
59	61
60	62		The pas2jscomponents package also installs some components.
61	63
62	64		### THTMLElementActionList
63	65
64	66		The THTMLElementActionList component is similar to the Action list in design-time concept, but works differently at runtime: You can associate a THTMLElementAction with every element in the HTML fragment's HTML that has an ID, or you can use a CSS selector to let an action respresent a series of HTML Elements.
65	67
66	68		You don't need to create these actions manually. In the context menu there is an item "Create actions for HTML tags"
67	69
68	70		![](/wiki-images/3/3f/Htmlelementactionlist.png)
69	71
70	72		This menu will pop up a wizard that finds all elements for which no action exists yet, and proposes to create an action:
71	73
72	74		![](/wiki-images/e/e7/Createhtmlactions.png)
73	75
74	76		If you check the Use Data-Aware Actions checkbox, then DB-Aware actions will be used. These can be used as button actions (to navigate in the data, insert/post/delete etc. etc)
75	77
76	78		The action editor works similar to the LCL action list editor:
77	79
78	80		![](/wiki-images/1/17/Elementactioneditor.png)
79	81
80	82		The main properties of an action are:
81	83
82	84		- ElementID the ID of the element you want to control.
83	85		- CSSSelector A css selector for thes element you want to control in case of multiple elements (e.g. to get all rows in a table use \#tableid tr)
84	86		- Events a set of events to listen for. When the event is triggered, the OnExecute event handler is executed.
85	87		- CustomEvents a space separated list of HTML to listen for, for events that do not appear in Events
86	88		- PreventDefault can be set to True to prevent the default HTML action from happening.
87	89		- StopPropagation can be set to True to prevent the event from bubbling, i.e. propagating to parent elements.
88	90
89	91		### TBootstrapModal
90	92
91	93		A component (similar to the LCL Dialog components) to show a modal dialog using Bootstrap. (you need to include the various bootstrap files in your project HTML file)
92	94
93	95		The following properties exist:
94	96
95	97		- ShowOnRender set to True if you wish to show the modal as soon as it is rendered (meaning, the HTML was generated).
96	98		- BackDrop show a backdrop shadow over the rest of the HTML page.
97	99		- KeyBoard Allow keyboard actions
98	100		- Focus set focus to the modal.
99	101		- Template the HTML for the modal.
100	102		- TemplateName the name of a template in TempateLoader containing the modal HTML.
101	103		- TemplateLoader a custom template loader. If not set, a global template loader is used.
102	104		- References a collection of CSS Selectors which can be used to get a reference to elements in the modal. These can be used to retrieve entered values during the OnHide event handler..
103	105
104	106		The following events exist:
105	107
106	108		- OnHide event triggered when the modal is hidden.
107	109
108	110		### TBootstrapToastWidget
109	111
110	112		The TBootstrapToastWidget allow you to show a small Toast message.
111	113
112	114		It can show a toast embedded in the HTML file, or the HTML can be generated from the properties
113	115
114	116		- Header a string with the HTML for the header tag.
115	117		- SmallHeader a string with the HTML for the sub (smaller) header tag.
116	118		- Body a string with the HTML for body of the modal.
117	119		- HeaderImage an URL for the header image.
118	120		- CloseButton set to True to add a close button to the dialog.
119	121		- Contextual an enumerated which allows you to select one of the primary bootstrap color schemes.
120	122		- HideDelay a number of milliseconds before the toast automatically disappears when AutoHide is True.
121	123		- AutoHide set to True to let the toast disappear automatically after HideDelay milliseconds.
122	124		- Animate set to True to animate showing and hiding of the modal.
123	125		- MinWidth minimum width for the modal.
124	126		- UnrenderOnHide if set to True the HTML of the toast will be removed from the DOM when the toast is hidden.
125	127
126	128		The following event exists:
127	129
128	130		- OnHide triggered when the toast is hidden.
129	131
130	132		### TTemplateLoader
131	133
132	134		This component can be used to load HTML fragments (in fact, any file) when the webapplication is run.
133	135
134	136		When loaded, the templates are available in a named array Templates where the index is the name of a template. The list of templates to load can be specified in the PreloadTemplates property, a collection.
135	137
136	138		The following properties exist:
137	139
138	140		- BaseURL all filenames for templates are relative to this URL.
139	141		- CheckResources When loading a template, check if a resource with the same name as the template exists. If yes, load the template from the resource.
140	142		- PreloadTemplates List of templates to load as soon as the component is loaded from the form file.
141	143
142	144		The following events exist:
143	145
144	146		- OnLoad triggered when a template is loaded. The name of the loaded template is passed to the event handler.
145	147		- OnLoadFail triggered when a template fails to load. The name of the loaded template is passed to the event handler.
146	148
147	149		Because the loading happens asynchronous, the following method is useful:
148	150
149	151		``` pascal
150	152		Procedure IfTemplate(const aName : String; aEvent : TTemplateNotifyEvent);
151	153		```
152	154
153	155		this method will check if template aName is loaded, and calls aEvent if it is. If it is not yet loaded, it will wait till the template is loaded and then call the event.
154	156
155	157		Additional templates can be loaded with the following 2 calls:
156	158
157	159		``` pascal
158	160		Procedure LoadTemplate(Const aName,aURL : String; aOnSuccess : TTemplateNotifyEvent = Nil; AOnFail : TTemplateErrorNotifyEvent= Nil);
159	161		Procedure LoadTemplates(Const Templates : Array of String; aOnSuccess : TTemplateNotifyEvent = Nil; AOnFail : TTemplateErrorNotifyEvent= nil);
160	162		```
161	163
162	164		These methods will load a template, even if it was already loaded before. In case of the array, there must be an even number of elements, the odd elements are template names and the even elements are corresponding filenames.
163	165
164	166		### TSQLDBRestConnection
165	167
166	168		### TSQLDBRestDataset
167	169
168	170		### TDBBootstraptableWidget
169	171
170	172		A widget that renders a bootstrap-table table based on a dataset.
171	173
172	174		[Bootstrap-Table can be downloaded here](https://bootstrap-table.com/)
173	175
174	176		It renders a read-only table with paging and search options, based on the properties set, and the data from a dataset:
175	177
176	178		The component has the following properties:
177	179
178	180		- StylingClasses a set of properties that affect how a column with a button is rendered. See below for the list of properties.
179	181		- Columns A column with the columns to render in the table.
180	182		- DataSource a reference to the dataset for which to render the table. The table is rendered when the dataset opens, it is unrendered when the dataset closes.
181	183		- Options a set of general options for the table behaviour.
182	184		- ViewOptions a set of options that determine the look-and-feel of the table.
183	185		- PaginationOptions a set of options that govern the pagination mechanism of the table.
184	186		- SearchOptions a set of options that control the search mechanism of the table.
185	187		- SortOptions a set of options that control the sorting mechanism of the table.
186	188		- DisplayReadOnly set all edit/delete buttons readonly.
187	189		- AfterBodyDraw event triggered after the table body has been rendered.
188	190
189	191		For each column to be rendered the following properties can be set:
190	192
191	193		- FieldName: The Fieldname for this column
192	194		- Title: The Title for this column
193	195		- RenderMode: The Render mode for the column: text, number, checkbox, button custom render
194	196		- ButtonType: When rendermode is rmButton, what button must be rendered.
195	197		- ButtonIconClass: When buttontype is btCustom, use the following class (in \<i class=""\>\</i\>)
196	198		- OnTransformValue: Event called when rendermode is rmTransformValue
197	199		- OnCustomFormat: EVent called when rendermode is rmCustom
198	200		- Width: Column Width (in WidthUnits units)
199	201		- WidthUnits: Column Width (in CSS units)
200	202		- CSSClassName: a CSS Class name applied on cells for this column
201	203		- CheckBoxClassName: CSS Class name for this column if there is a check box.
202	204		- Visible: Visible column or not ?
203	205		- Searchable: A boolean that Indicates whether the column is searchable
204	206		- Sortable: A boolean that Indicates whether the column is sortable
205	207		- ButtonURL: string URL to use when the button is clicked
206	208		- ButtonURLTarget: link element target attribute.
207	209
208	210		The TStylingClasses has the following properties:
209	211
210	212		- CheckBoxClass a space-separated list of classes to apply to a checkbox column.
211	213		- ButtonClass a space-separated list of classes to apply to a button column.
212	214		- InfoClass a space-separated list of classes to apply to a info button column.
213	215		- EditClas a space-separated list of classes to apply to a edit button column.
214	216		- ReadonlyEditClass a space-separated list of classes to apply to a read-only edit column.
215	217		- DeleteClass a space-separated list of classes to apply to a delete button column.
216	218
217	219		### TDBLoopWidget
218	220
219	221		A widget that renders a HTML template for every record in a dataset. The HTML templates can contain placeholders in the form which will be replaced with the field value of the dataset for that record.
220	222
221	223		The Groups collection can be used to make groups based on the values in the dataset: when the group value changes, a new group is started and the header template for the group is rendered. When a group ended, a footer template is rendered for that group.
222	224
223	225		The following properties exist:
224	226
225	227		- HeaderTemplate The header template is rendered before starting the loop.
226	228		- ItemTemplate The Item template is rendered for each record in the dataset.
227	229		- FooterTemplate The footer template is rendered before starting the loop.
228	230		- OnGetValue event called to get the value of a placeholder.
229	231		- References use CSS selectors to get references to the nodes in the rendered content;
230	232		- Datasource a reference to the data for which to render the loop.
231	233		- OnFormatField an event to get a custom formatted version of a field.
232	234		- Groups a collection of groups for which an expression, a footer and header template can be specified.
233	235		- OnGetGroupValue to get a custom value for a group expression.
234	236
235	237		### TDBSelectWidget
236	238
237	239		A widget which renders a html SELECT element based on data in a dataset.
238	240
239	241		The following properties are available:
240	242
241	243		- Datasource a reference to the data from which to generate the SELECT element.
242	244		- ItemField the field whose value is used to create an OPTION element in the SELECT.
243	245		- ValueField when set, the field whose value is used to set the value attribute of an OPTION element in the select.
244	246		- NullIsNotValue if a field is null, no value is generated.
245	247		- SelectedIndex set the selected item index.
246	248		- Multiple allow multiselect.
247	249
248	250		---
249	251		From the Free Pascal wiki, page "pas2js designtime", as it stood on 2022-05-28 after a change by FTurtle, 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).
250	252		Category: Pas2js

Back to history