001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.bean.html5;
018
019import java.net.*;
020
021import org.apache.juneau.*;
022import org.apache.juneau.annotation.*;
023import org.apache.juneau.internal.*;
024
025/**
026 * DTO for an HTML <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#the-form-element">&lt;form&gt;</a>
027 * element.
028 *
029 * <p>
030 * The form element represents a document section containing interactive controls for submitting
031 * information to a web server. It groups form controls together and defines how the data should
032 * be submitted, including the target URL, HTTP method, and encoding type.
033 *
034 * <h5 class='section'>Examples:</h5>
035 * <p class='bcode w800'>
036 *    <jc>// Simple contact form</jc>
037 *    Form <jv>form1</jv> = <jsm>form</jsm>()
038 *       .action(<js>"/contact"</js>)
039 *       .method(<js>"post"</js>)
040 *       .children(
041 *          <jsm>input</jsm>(<js>"text"</js>).name(<js>"name"</js>).placeholder(<js>"Your Name"</js>),
042 *          <jsm>input</jsm>(<js>"email"</js>).name(<js>"email"</js>).placeholder(<js>"Your Email"</js>),
043 *          <jsm>textarea</jsm>().name(<js>"message"</js>).placeholder(<js>"Your Message"</js>),
044 *          <jsm>button</jsm>().type(<js>"submit"</js>).text(<js>"Send Message"</js>)
045 *       );
046 * 
047 *    <jc>// File upload form</jc>
048 *    Form <jv>form2</jv> = <jsm>form</jsm>()
049 *       .action(<js>"/upload"</js>)
050 *       .method(<js>"post"</js>)
051 *       .enctype(<js>"multipart/form-data"</js>)
052 *       .children(
053 *          <jsm>input</jsm>(<js>"file"</js>).name(<js>"file"</js>).accept(<js>"image/*"</js>),
054 *          <jsm>button</jsm>().type(<js>"submit"</js>).text(<js>"Upload"</js>)
055 *       );
056 * 
057 *    <jc>// Form with validation</jc>
058 *    Form <jv>form3</jv> = <jsm>form</jsm>()
059 *       .action(<js>"/register"</js>)
060 *       .method(<js>"post"</js>)
061 *       .novalidate(<jk>false</jk>)
062 *       .children(
063 *          <jsm>input</jsm>(<js>"email"</js>).name(<js>"email"</js>).required(<jk>true</jk>),
064 *          <jsm>input</jsm>(<js>"password"</js>).name(<js>"password"</js>).required(<jk>true</jk>),
065 *          <jsm>button</jsm>().type(<js>"submit"</js>).text(<js>"Register"</js>)
066 *       );
067 * </p>
068 *
069 * <p>
070 * The following convenience methods are provided for constructing instances of this bean:
071 * <ul class='javatree'>
072 *    <li class='jc'>{@link HtmlBuilder}
073 *    <ul class='javatree'>
074 *       <li class='jm'>{@link HtmlBuilder#form() form()}
075 *       <li class='jm'>{@link HtmlBuilder#form(Object, Object...) form(Object, Object...)}
076 *    </ul>
077 * </ul>
078 * </p>
079 *
080 * <h5 class='section'>See Also:</h5><ul>
081 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanHtml5">juneau-bean-html5</a>
082 * </ul>
083 */
084@Bean(typeName="form")
085public class Form extends HtmlElementMixed {
086
087   /**
088    * Creates an empty {@link Form} element.
089    */
090   public Form() {}
091
092   /**
093    * Creates a {@link Form} element with the specified {@link Form#action(String)} attribute.
094    *
095    * @param action The {@link Form#action(String)} attribute.
096    */
097   public Form(String action) {
098      action(action);
099   }
100
101   /**
102    * Creates an {@link Form} element with the specified {@link Form#action(String)} attribute and child nodes.
103    *
104    * @param action The {@link Form#action(String)} attribute.
105    * @param children The child nodes.
106    */
107   public Form(String action, Object...children) {
108      action(action).children(children);
109   }
110
111   /**
112    * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-form-accept-charset">accept-charset</a>
113    * attribute.
114    *
115    * <p>
116    * Specifies the character encodings that are accepted for form submission. Multiple encodings
117    * can be specified as a space-separated list.
118    *
119    * <p>
120    * Common values:
121    * <ul>
122    *    <li><js>"UTF-8"</js> - Unicode UTF-8 encoding (default)</li>
123    *    <li><js>"ISO-8859-1"</js> - Latin-1 encoding</li>
124    *    <li><js>"UTF-8 ISO-8859-1"</js> - Multiple encodings</li>
125    * </ul>
126    *
127    * @param acceptcharset The character encodings accepted for form submission.
128    * @return This object.
129    */
130   public Form acceptcharset(String value) {
131      attr("accept-charset", value);
132      return this;
133   }
134
135   /**
136    * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-action">action</a> attribute.
137    *
138    * <p>
139    * URL to use for form submission.
140    *
141    * <p>
142    * The value can be of any of the following types: {@link URI}, {@link URL}, {@link String}.
143    * Strings must be valid URIs.
144    *
145    * <p>
146    * URIs defined by {@link UriResolver} can be used for values.
147    *
148    * @param action The new value for this attribute.
149    * @return This object.
150    */
151   public Form action(String value) {
152      attrUri("action", value);
153      return this;
154   }
155
156   /**
157    * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-form-autocomplete">autocomplete</a>
158    * attribute.
159    *
160    * <p>
161    * Sets the default autocomplete behavior for all form controls within this form.
162    * Individual controls can override this setting.
163    *
164    * <p>
165    * Possible values:
166    * <ul>
167    *    <li><js>"on"</js> - Allow autocomplete (default)</li>
168    *    <li><js>"off"</js> - Disable autocomplete</li>
169    * </ul>
170    *
171    * @param autocomplete The default autocomplete behavior for form controls.
172    * @return This object.
173    */
174   public Form autocomplete(String value) {
175      attr("autocomplete", value);
176      return this;
177   }
178
179   /**
180    * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-enctype">enctype</a> attribute.
181    *
182    * <p>
183    * Specifies how form data should be encoded when submitted to the server.
184    *
185    * <p>
186    * Possible values:
187    * <ul>
188    *    <li><js>"application/x-www-form-urlencoded"</js> - Default encoding (default)</li>
189    *    <li><js>"multipart/form-data"</js> - Used for file uploads</li>
190    *    <li><js>"text/plain"</js> - Plain text encoding</li>
191    * </ul>
192    *
193    * @param enctype The encoding type for form data submission.
194    * @return This object.
195    */
196   public Form enctype(String value) {
197      attr("enctype", value);
198      return this;
199   }
200
201   /**
202    * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-method">method</a> attribute.
203    *
204    * <p>
205    * Specifies the HTTP method to use when submitting the form.
206    *
207    * <p>
208    * Possible values:
209    * <ul>
210    *    <li><js>"get"</js> - Form data is sent as URL parameters (default)</li>
211    *    <li><js>"post"</js> - Form data is sent in the request body</li>
212    *    <li><js>"dialog"</js> - Used for forms within dialog elements</li>
213    * </ul>
214    *
215    * @param method The HTTP method for form submission.
216    * @return This object.
217    */
218   public Form method(String value) {
219      attr("method", value);
220      return this;
221   }
222
223   /**
224    * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-form-name">name</a> attribute.
225    *
226    * <p>
227    * Specifies the name of the form. This name can be used to access the form via the
228    * document.forms API and for form submission.
229    *
230    * <p>
231    * The name should be unique within the document and should not contain spaces or special characters.
232    *
233    * @param name The name of the form for API access and submission.
234    * @return This object.
235    */
236   public Form name(String value) {
237      attr("name", value);
238      return this;
239   }
240
241   /**
242    * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-novalidate">novalidate</a> attribute.
243    *
244    * <p>
245    * Disables form validation, allowing the form to be submitted even if validation fails.
246    *
247    * @param novalidate If <jk>true</jk>, disables form validation.
248    * @return This object.
249    */
250   public Form novalidate(Boolean value) {
251      attr("novalidate", value);
252      return this;
253   }
254
255   /**
256    * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-target">target</a> attribute.
257    *
258    * <p>
259    * Specifies where to display the response after form submission.
260    *
261    * <p>
262    * Possible values:
263    * <ul>
264    *    <li><js>"_self"</js> - Load in the same frame (default)</li>
265    *    <li><js>"_blank"</js> - Load in a new window or tab</li>
266    *    <li><js>"_parent"</js> - Load in the parent frame</li>
267    *    <li><js>"_top"</js> - Load in the full body of the window</li>
268    *    <li>Frame name - Load in the named frame</li>
269    * </ul>
270    *
271    * @param target Where to display the form submission response.
272    * @return This object.
273    */
274   public Form target(String value) {
275      attr("target", value);
276      return this;
277   }
278
279   //-----------------------------------------------------------------------------------------------------------------
280   // Overridden methods
281   //-----------------------------------------------------------------------------------------------------------------
282   @Override /* Overridden from HtmlElement */
283   public Form _class(String value) {  // NOSONAR - Intentional naming.
284      super._class(value);
285      return this;
286   }
287
288   @Override /* Overridden from HtmlElement */
289   public Form accesskey(String value) {
290      super.accesskey(value);
291      return this;
292   }
293
294   @Override /* Overridden from HtmlElement */
295   public Form contenteditable(Object value) {
296      super.contenteditable(value);
297      return this;
298   }
299
300   @Override /* Overridden from HtmlElement */
301   public Form dir(String value) {
302      super.dir(value);
303      return this;
304   }
305
306   @Override /* Overridden from HtmlElement */
307   public Form hidden(Object value) {
308      super.hidden(value);
309      return this;
310   }
311
312   @Override /* Overridden from HtmlElement */
313   public Form id(String value) {
314      super.id(value);
315      return this;
316   }
317
318   @Override /* Overridden from HtmlElement */
319   public Form lang(String value) {
320      super.lang(value);
321      return this;
322   }
323
324   @Override /* Overridden from HtmlElement */
325   public Form onabort(String value) {
326      super.onabort(value);
327      return this;
328   }
329
330   @Override /* Overridden from HtmlElement */
331   public Form onblur(String value) {
332      super.onblur(value);
333      return this;
334   }
335
336   @Override /* Overridden from HtmlElement */
337   public Form oncancel(String value) {
338      super.oncancel(value);
339      return this;
340   }
341
342   @Override /* Overridden from HtmlElement */
343   public Form oncanplay(String value) {
344      super.oncanplay(value);
345      return this;
346   }
347
348   @Override /* Overridden from HtmlElement */
349   public Form oncanplaythrough(String value) {
350      super.oncanplaythrough(value);
351      return this;
352   }
353
354   @Override /* Overridden from HtmlElement */
355   public Form onchange(String value) {
356      super.onchange(value);
357      return this;
358   }
359
360   @Override /* Overridden from HtmlElement */
361   public Form onclick(String value) {
362      super.onclick(value);
363      return this;
364   }
365
366   @Override /* Overridden from HtmlElement */
367   public Form oncuechange(String value) {
368      super.oncuechange(value);
369      return this;
370   }
371
372   @Override /* Overridden from HtmlElement */
373   public Form ondblclick(String value) {
374      super.ondblclick(value);
375      return this;
376   }
377
378   @Override /* Overridden from HtmlElement */
379   public Form ondurationchange(String value) {
380      super.ondurationchange(value);
381      return this;
382   }
383
384   @Override /* Overridden from HtmlElement */
385   public Form onemptied(String value) {
386      super.onemptied(value);
387      return this;
388   }
389
390   @Override /* Overridden from HtmlElement */
391   public Form onended(String value) {
392      super.onended(value);
393      return this;
394   }
395
396   @Override /* Overridden from HtmlElement */
397   public Form onerror(String value) {
398      super.onerror(value);
399      return this;
400   }
401
402   @Override /* Overridden from HtmlElement */
403   public Form onfocus(String value) {
404      super.onfocus(value);
405      return this;
406   }
407
408   @Override /* Overridden from HtmlElement */
409   public Form oninput(String value) {
410      super.oninput(value);
411      return this;
412   }
413
414   @Override /* Overridden from HtmlElement */
415   public Form oninvalid(String value) {
416      super.oninvalid(value);
417      return this;
418   }
419
420   @Override /* Overridden from HtmlElement */
421   public Form onkeydown(String value) {
422      super.onkeydown(value);
423      return this;
424   }
425
426   @Override /* Overridden from HtmlElement */
427   public Form onkeypress(String value) {
428      super.onkeypress(value);
429      return this;
430   }
431
432   @Override /* Overridden from HtmlElement */
433   public Form onkeyup(String value) {
434      super.onkeyup(value);
435      return this;
436   }
437
438   @Override /* Overridden from HtmlElement */
439   public Form onload(String value) {
440      super.onload(value);
441      return this;
442   }
443
444   @Override /* Overridden from HtmlElement */
445   public Form onloadeddata(String value) {
446      super.onloadeddata(value);
447      return this;
448   }
449
450   @Override /* Overridden from HtmlElement */
451   public Form onloadedmetadata(String value) {
452      super.onloadedmetadata(value);
453      return this;
454   }
455
456   @Override /* Overridden from HtmlElement */
457   public Form onloadstart(String value) {
458      super.onloadstart(value);
459      return this;
460   }
461
462   @Override /* Overridden from HtmlElement */
463   public Form onmousedown(String value) {
464      super.onmousedown(value);
465      return this;
466   }
467
468   @Override /* Overridden from HtmlElement */
469   public Form onmouseenter(String value) {
470      super.onmouseenter(value);
471      return this;
472   }
473
474   @Override /* Overridden from HtmlElement */
475   public Form onmouseleave(String value) {
476      super.onmouseleave(value);
477      return this;
478   }
479
480   @Override /* Overridden from HtmlElement */
481   public Form onmousemove(String value) {
482      super.onmousemove(value);
483      return this;
484   }
485
486   @Override /* Overridden from HtmlElement */
487   public Form onmouseout(String value) {
488      super.onmouseout(value);
489      return this;
490   }
491
492   @Override /* Overridden from HtmlElement */
493   public Form onmouseover(String value) {
494      super.onmouseover(value);
495      return this;
496   }
497
498   @Override /* Overridden from HtmlElement */
499   public Form onmouseup(String value) {
500      super.onmouseup(value);
501      return this;
502   }
503
504   @Override /* Overridden from HtmlElement */
505   public Form onmousewheel(String value) {
506      super.onmousewheel(value);
507      return this;
508   }
509
510   @Override /* Overridden from HtmlElement */
511   public Form onpause(String value) {
512      super.onpause(value);
513      return this;
514   }
515
516   @Override /* Overridden from HtmlElement */
517   public Form onplay(String value) {
518      super.onplay(value);
519      return this;
520   }
521
522   @Override /* Overridden from HtmlElement */
523   public Form onplaying(String value) {
524      super.onplaying(value);
525      return this;
526   }
527
528   @Override /* Overridden from HtmlElement */
529   public Form onprogress(String value) {
530      super.onprogress(value);
531      return this;
532   }
533
534   @Override /* Overridden from HtmlElement */
535   public Form onratechange(String value) {
536      super.onratechange(value);
537      return this;
538   }
539
540   @Override /* Overridden from HtmlElement */
541   public Form onreset(String value) {
542      super.onreset(value);
543      return this;
544   }
545
546   @Override /* Overridden from HtmlElement */
547   public Form onresize(String value) {
548      super.onresize(value);
549      return this;
550   }
551
552   @Override /* Overridden from HtmlElement */
553   public Form onscroll(String value) {
554      super.onscroll(value);
555      return this;
556   }
557
558   @Override /* Overridden from HtmlElement */
559   public Form onseeked(String value) {
560      super.onseeked(value);
561      return this;
562   }
563
564   @Override /* Overridden from HtmlElement */
565   public Form onseeking(String value) {
566      super.onseeking(value);
567      return this;
568   }
569
570   @Override /* Overridden from HtmlElement */
571   public Form onselect(String value) {
572      super.onselect(value);
573      return this;
574   }
575
576   @Override /* Overridden from HtmlElement */
577   public Form onshow(String value) {
578      super.onshow(value);
579      return this;
580   }
581
582   @Override /* Overridden from HtmlElement */
583   public Form onstalled(String value) {
584      super.onstalled(value);
585      return this;
586   }
587
588   @Override /* Overridden from HtmlElement */
589   public Form onsubmit(String value) {
590      super.onsubmit(value);
591      return this;
592   }
593
594   @Override /* Overridden from HtmlElement */
595   public Form onsuspend(String value) {
596      super.onsuspend(value);
597      return this;
598   }
599
600   @Override /* Overridden from HtmlElement */
601   public Form ontimeupdate(String value) {
602      super.ontimeupdate(value);
603      return this;
604   }
605
606   @Override /* Overridden from HtmlElement */
607   public Form ontoggle(String value) {
608      super.ontoggle(value);
609      return this;
610   }
611
612   @Override /* Overridden from HtmlElement */
613   public Form onvolumechange(String value) {
614      super.onvolumechange(value);
615      return this;
616   }
617
618   @Override /* Overridden from HtmlElement */
619   public Form onwaiting(String value) {
620      super.onwaiting(value);
621      return this;
622   }
623
624   @Override /* Overridden from HtmlElement */
625   public Form spellcheck(Object value) {
626      super.spellcheck(value);
627      return this;
628   }
629
630   @Override /* Overridden from HtmlElement */
631   public Form style(String value) {
632      super.style(value);
633      return this;
634   }
635
636   @Override /* Overridden from HtmlElement */
637   public Form tabindex(Object value) {
638      super.tabindex(value);
639      return this;
640   }
641
642   @Override /* Overridden from HtmlElement */
643   public Form title(String value) {
644      super.title(value);
645      return this;
646   }
647
648   @Override /* Overridden from HtmlElement */
649   public Form translate(Object value) {
650      super.translate(value);
651      return this;
652   }
653
654   @Override /* Overridden from HtmlElementMixed */
655   public Form child(Object value) {
656      super.child(value);
657      return this;
658   }
659
660   @Override /* Overridden from HtmlElementMixed */
661   public Form children(Object...value) {
662      super.children(value);
663      return this;
664   }
665}