-
Notifications
You must be signed in to change notification settings - Fork 3
/
jforms.gtw
262 lines (182 loc) · 9.2 KB
/
jforms.gtw
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
~~LANG:FR@frman:plugins/jforms~~
As noted in [[/components/jforms/display|display jforms chapter]], you can select which
plugin will generate forms content (in HTML, javascript and so on..) sent to
clients.
You have two kind of plugins: those that build a whole form, generators, and
plugins for the 'html' generator, to generate only a control.
==== Generators plugin ====
To create a such plugin, you should of course pick a name, say "moreforms". Then:
* Create a @@F@formbuilder/moreforms@@ directory in a plugins repository.
* Create a @@F@moreforms.jformsbuilder.php@@ in it
* In it, declare a @@C@moreformsFormBuilder@@ class inheriting from
@@C@\jelix\forms\Builder\BuilderBase@@ or from @@C@\jelix\forms\Builder\HtmlBuilder@@
if you want to generate a form similaire to the default html generator.
@@C@moreformsFormBuilder@@ should implement following list of methods. Those
methods display different form parts and don't return any value (they call @@echo@@).
They are called through jForms template plugins.
After each modification of your generator, **don't forget to clear your temp directory**
(by using the command @@app:cleartemp@@ for example).
<code php>
/**
* called during the meta content processing in templates
* This method should set things on the response, like adding
* css styles, javascript links etc.
* @param \jTpl $tpl the template object
*/
abstract public function outputMetaContent($tpl);
/**
* output the header content of the form
*/
abstract public function outputHeader();
/**
* output the footer content of the form
*/
abstract public function outputFooter();
/**
* displays all the form. outputMetaContent, outputHeader and outputFooters are also called
*/
abstract public function outputAllControls();
/**
* displays the content corresponding of the given control
* @param jFormsControl $ctrl the control to display
* @param array $attributes attribute to add on the generated code (html attributes for example)
*/
abstract public function outputControl($ctrl, $attributes=array());
/**
* displays the label corresponding of the given control
* @param jFormsControl $ctrl the control to display
*/
abstract public function outputControlLabel($ctrl, $format = '', $editMode = true);
/**
* displays the value of the control (without the control)
* @param \jFormsControl $ctrl the control to display
* @param array $attributes attribute to add on the generated code (html attributes for example)
*/
abstract public function outputControlValue($ctrl, $attributes=array());
</code>
=== outputMetaContent() ===
Use the controller response object to specify CSS stylesheets, javascript files
to be included in the final response. Example:
<code php>
public function outputMetaContent($t) {
$resp= jApp::coord()->response;
if ($resp === null) {
return;
}
// si les fichiers sont dans le répertoire jelix
$www = jApp::urlJelixWWWPath();
// ou si les fichiers sont dans un répertoire à vous dans www
$www = jApp::urlBasePath();
$resp->addJSLink($www.'js/fichier.js');
$resp->addCSSLink($www.'design/fichier.css');
$resp->addAssets('my_web_assets');
//we loop on root control has they fill call the outputMetaContent recursively
foreach( $this->_form->getRootControls() as $ctrlref=>$ctrl) {
if($ctrl->type == 'hidden') continue;
if(!$this->_form->isActivated($ctrlref)) continue;
$widget = $this->getWidget($ctrl, $this->rootWidget);
$widget->outputMetaContent($resp);
}
}
</code>
This method is the first called.
=== outputHeader() ===
This one generates tags declaring your form and other useful form contents.
@@M@OutputHeader@@ opens a @@E@<form>@@ tag, optionally displays error messages,
generates hidden fields and adds some javascript.
=== outputFooter() ===
This is the last method called by template plugins. As for HTML,
@@M@outputFooter@@ closes the form tags @@E@</form>@@ and adds some javascript.
=== outputAllControls() ===
This one is called by @@{formfull}@@ template plugin. It has to generate all
controls (apart of those generated by @@outputHeader()@@ and @@outputFooter()@@).
=== outputControlLabel() ===
Called by the @@{form}@@ template block for fields labels, it generates labels tags.
As argument, it receives a @@C@jFormsControl@@ object defining the control associated.
In the HTML generator, it calls the widget plugin corresponding to the control, to display the label.
=== outputControl() ===
Called by the @@{form}@@ template block for controls, it generates control elements.
As argument, it receives a @@C@jFormsControl@@ object defining the control associated,
and the list of html attributes to add or other informations.
In the HTML generator, it calls the widget plugin corresponding to the control, to display the field.
=== outputControlValue() ===
Called by the @@{formdata}@@ template block for fields values, it only output the value
of a control.
As argument, it receives a @@C@jFormsControl@@ object defining the control associated.
In the HTML generator, it calls the widget plugin corresponding to the control, to display the value.
==== Using a generator ====
If you want to use the same generator in the whole application, you should
indicate the generator name into this configuration parameter:
<code ini>
[tplplugins]
defaultJformsBuilder = myformbuilder
</code>
If you want to use a generator only on some forms, you can indicate the generator
in the @@{form}@@ or @@{formfull}@@ template plugin:
<code html>
{formfull $form, 'mymodule~default:save', array(), 'myformbuilder'}
</code>
==== Widget plugin ====
The generator provided by Jelix is a plugin, that is itself extensible and use
other type of plugins, "formwidget", to generate controls.
A "formwidget" plugin generates the code of a specific control. You can provide
your own formwidget plugin and use it for a particular control, if you want to
have a different HTML construction.
A "formwidget" should follow the @@jelix\forms\HtmlWidget\WidgetInterface@@ interface, and so,
it should provide these methods:
* @@M@getId()@@: return the id of the HTML element
* @@M@getName()@@: return the name of the HTML element
* @@M@getValue()@@: return the value of the HTML field
* @@M@outputMetaContent($resp)@@: add the CSS and javascript link
* @@M@outputHelp()@@: displays the help of the form field
* @@M@outputLabel($format = '', $editMode = true)@@: displays the form field label
* @@M@outputControl()@@: displays the form field itself
* @@M@setAttributes($attributes)@@: set attributes to add on the HTML element
The plugin could inherits from the @@jelix\forms\HtmlWidget\WidgetBase@@ class so only few
methods are needed to be implemented.
The plugin should have a name. It should be stored into a file
@@F@plugins/formwidget/{name}/{name}.formwidget.php@@.
See all existing plugins into @@F@lib/jelix/plugins/formwidget/@@ to know more about how
it should be implemented.
Note that there is a specific widget, the "root" widget, which can generate
more HTML, in addition of HTML generated by widgets and the main generator.
It has the same name of the generator. For example, the root widget of
the HTML generator, it is the plugin @@plugins/formwidget/html/html.formwidget.php@@.
For you own html generator called for example "myhtml", it will be
@@plugins/formwidget/monhtml/monhtml.formwidget.php@@.
==== Declaring a widget plugin ====
After creating the widget class, you should declare it so it can be used.
Depending of the context, you would choose one of these solutions.
If you want to use a specific plugin in a specific form, indicate it in the
options of the generator, in the template :
<code>
{form $form, 'action', array(), 'html',
array('plugins' => array ('birthdaydate' => 'mydateplugin')) }
...
{/form}
{formfull $form, 'action', array(), 'html',
array('plugins' => array ('birthdaydate' => 'mydateplugin')) }
</code>
Here you indicate that for the control which has the name 'birthdaydate', the
widget 'mydateplugin' will be used. So it will be @@F@plugins/formwidget/mydateplugin/mydateplugin.formwidget.php@@.
If you want to use the same plugin for all forms, you should indicate into
the configuration, the plugin name to use with a specific type of control:
<code ini>
[jforms_builder_html]
;<control type> = <plugin name>
date = mydateplugin
</code>
Here, the "mydateplugin" widget will be used for all jforms date control.
If you create your own builder inheriting from the html generator, the generator
will try automatically to use widgets for which the name will be end with the builder
name: @@<controle_type>_<builder_type>@@.
So if you create a builder "htmlbootstrap", it will try to use widgets plugins
having the name ending with "_htmlbootstrap" (@@date_htmlbootstrap@@ for all date
controls for example).
And if in your generator, there are some plugins having a name which doesn't follow
the convention, you can indicate it into a property of your generator:
<code>
protected $pluginsConf = array(
'control type' => 'widget name'
);
</code>