pas2js designtime: what changed

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

Title: pas2js designtime

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

Back to history