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.marshall.*; 022 023/** 024 * DTO for an HTML <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#the-form-element"><form></a> 025 * element. 026 * 027 * <p> 028 * The form element represents a document section containing interactive controls for submitting 029 * information to a web server. It groups form controls together and defines how the data should 030 * be submitted, including the target URL, HTTP method, and encoding type. 031 * 032 * <h2 class='section'>Examples:</h2> 033 * <p class='bcode w800'> 034 * <jc>// Simple contact form</jc> 035 * Form <jv>form1</jv> = <jsm>form</jsm>() 036 * .action(<js>"/contact"</js>) 037 * .method(<js>"post"</js>) 038 * .children( 039 * <jsm>input</jsm>(<js>"text"</js>).name(<js>"name"</js>).placeholder(<js>"Your Name"</js>), 040 * <jsm>input</jsm>(<js>"email"</js>).name(<js>"email"</js>).placeholder(<js>"Your Email"</js>), 041 * <jsm>textarea</jsm>().name(<js>"message"</js>).placeholder(<js>"Your Message"</js>), 042 * <jsm>button</jsm>().type(<js>"submit"</js>).text(<js>"Send Message"</js>) 043 * ); 044 * 045 * <jc>// File upload form</jc> 046 * Form <jv>form2</jv> = <jsm>form</jsm>() 047 * .action(<js>"/upload"</js>) 048 * .method(<js>"post"</js>) 049 * .enctype(<js>"multipart/form-data"</js>) 050 * .children( 051 * <jsm>input</jsm>(<js>"file"</js>).name(<js>"file"</js>).accept(<js>"image/*"</js>), 052 * <jsm>button</jsm>().type(<js>"submit"</js>).text(<js>"Upload"</js>) 053 * ); 054 * 055 * <jc>// Form with validation</jc> 056 * Form <jv>form3</jv> = <jsm>form</jsm>() 057 * .action(<js>"/register"</js>) 058 * .method(<js>"post"</js>) 059 * .novalidate(<jk>false</jk>) 060 * .children( 061 * <jsm>input</jsm>(<js>"email"</js>).name(<js>"email"</js>).required(<jk>true</jk>), 062 * <jsm>input</jsm>(<js>"password"</js>).name(<js>"password"</js>).required(<jk>true</jk>), 063 * <jsm>button</jsm>().type(<js>"submit"</js>).text(<js>"Register"</js>) 064 * ); 065 * </p> 066 * 067 * <p> 068 * The following convenience methods are provided for constructing instances of this bean: 069 * <ul class='javatree'> 070 * <li class='jc'>{@link HtmlBuilder} 071 * <ul class='javatree'> 072 * <li class='jm'>{@link HtmlBuilder#form() form()} 073 * <li class='jm'>{@link HtmlBuilder#form(String, Object...) form(String, Object...)} 074 * </ul> 075 * </ul> 076 * 077 * <h2 class='section'>See Also:</h2><ul> 078 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanHtml5">juneau-bean-html5</a> 079 * </ul> 080 */ 081@Marshalled(typeName = "form") 082public class Form extends HtmlElementMixed<Form> { 083 084 /** 085 * Creates an empty {@link Form} element. 086 */ 087 public Form() {} 088 089 /** 090 * Creates a {@link Form} element with the specified {@link Form#action(String)} attribute. 091 * 092 * @param action The {@link Form#action(String)} attribute. Can be <jk>null</jk>, in which case the attribute is stored with a <jk>null</jk> value (not removed). 093 */ 094 public Form(String action) { 095 action(action); 096 } 097 098 /** 099 * Creates an {@link Form} element with the specified {@link Form#action(String)} attribute and child nodes. 100 * 101 * @param action The {@link Form#action(String)} attribute. Can be <jk>null</jk>, in which case the attribute is stored with a <jk>null</jk> value (not removed). 102 * @param children The child nodes. Must not be <jk>null</jk>. 103 */ 104 public Form(String action, Object...children) { 105 action(action).children(children); 106 } 107 108 /** 109 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-form-accept-charset">accept-charset</a> 110 * attribute. 111 * 112 * <p> 113 * Specifies the character encodings that are accepted for form submission. Multiple encodings 114 * can be specified as a space-separated list. 115 * 116 * <p> 117 * Common values: 118 * <ul> 119 * <li><js>"UTF-8"</js> - Unicode UTF-8 encoding (default)</li> 120 * <li><js>"ISO-8859-1"</js> - Latin-1 encoding</li> 121 * <li><js>"UTF-8 ISO-8859-1"</js> - Multiple encodings</li> 122 * </ul> 123 * 124 * @param value The character encodings accepted for form submission. Can be <jk>null</jk> to unset the attribute. 125 * @return This object. 126 */ 127 public Form acceptcharset(String value) { 128 attr("accept-charset", value); 129 return this; 130 } 131 132 /** 133 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-action">action</a> attribute. 134 * 135 * <p> 136 * URL to use for form submission. 137 * 138 * <p> 139 * The value can be of any of the following types: {@link URI}, {@link URL}, {@link String}. 140 * Strings must be valid URIs. 141 * 142 * <p> 143 * URIs defined by {@link UriResolver} can be used for values. 144 * 145 * @param value The new value for this attribute. Can be <jk>null</jk>, in which case the attribute is stored with a <jk>null</jk> value (not removed). 146 * @return This object. 147 */ 148 public Form action(String value) { 149 attrUri("action", value); 150 return this; 151 } 152 153 /** 154 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-form-autocomplete">autocomplete</a> 155 * attribute. 156 * 157 * <p> 158 * Sets the default autocomplete behavior for all form controls within this form. 159 * Individual controls can override this setting. 160 * 161 * <p> 162 * Possible values: 163 * <ul> 164 * <li><js>"on"</js> - Allow autocomplete (default)</li> 165 * <li><js>"off"</js> - Disable autocomplete</li> 166 * </ul> 167 * 168 * @param value The default autocomplete behavior for form controls. Can be <jk>null</jk> to unset the attribute. 169 * @return This object. 170 */ 171 public Form autocomplete(String value) { 172 attr("autocomplete", value); 173 return this; 174 } 175 176 /** 177 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-enctype">enctype</a> attribute. 178 * 179 * <p> 180 * Specifies how form data should be encoded when submitted to the server. 181 * 182 * <p> 183 * Possible values: 184 * <ul> 185 * <li><js>"application/x-www-form-urlencoded"</js> - Default encoding (default)</li> 186 * <li><js>"multipart/form-data"</js> - Used for file uploads</li> 187 * <li><js>"text/plain"</js> - Plain text encoding</li> 188 * </ul> 189 * 190 * @param value The encoding type for form data submission. Can be <jk>null</jk> to unset the attribute. 191 * @return This object. 192 */ 193 public Form enctype(String value) { 194 attr("enctype", value); 195 return this; 196 } 197 198 /** 199 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-method">method</a> attribute. 200 * 201 * <p> 202 * Specifies the HTTP method to use when submitting the form. 203 * 204 * <p> 205 * Possible values: 206 * <ul> 207 * <li><js>"get"</js> - Form data is sent as URL parameters (default)</li> 208 * <li><js>"post"</js> - Form data is sent in the request body</li> 209 * <li><js>"dialog"</js> - Used for forms within dialog elements</li> 210 * </ul> 211 * 212 * @param value The HTTP method for form submission. Can be <jk>null</jk> to unset the attribute. 213 * @return This object. 214 */ 215 public Form method(String value) { 216 attr("method", value); 217 return this; 218 } 219 220 /** 221 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-form-name">name</a> attribute. 222 * 223 * <p> 224 * Specifies the name of the form. This name can be used to access the form via the 225 * document.forms API and for form submission. 226 * 227 * <p> 228 * The name should be unique within the document and should not contain spaces or special characters. 229 * 230 * @param value The name of the form for API access and submission. Can be <jk>null</jk> to unset the attribute. 231 * @return This object. 232 */ 233 public Form name(String value) { 234 attr("name", value); 235 return this; 236 } 237 238 /** 239 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-novalidate">novalidate</a> attribute. 240 * 241 * <p> 242 * Disables form validation, allowing the form to be submitted even if validation fails. 243 * 244 * @param value If <jk>true</jk>, disables form validation. Can be <jk>null</jk> to unset the attribute. 245 * @return This object. 246 */ 247 public Form novalidate(Boolean value) { 248 attr("novalidate", value); 249 return this; 250 } 251 252 /** 253 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-target">target</a> attribute. 254 * 255 * <p> 256 * Specifies where to display the response after form submission. 257 * 258 * <p> 259 * Possible values: 260 * <ul> 261 * <li><js>"_self"</js> - Load in the same frame (default)</li> 262 * <li><js>"_blank"</js> - Load in a new window or tab</li> 263 * <li><js>"_parent"</js> - Load in the parent frame</li> 264 * <li><js>"_top"</js> - Load in the full body of the window</li> 265 * <li>Frame name - Load in the named frame</li> 266 * </ul> 267 * 268 * @param value Where to display the form submission response. Can be <jk>null</jk> to unset the attribute. 269 * @return This object. 270 */ 271 public Form target(String value) { 272 attr("target", value); 273 return this; 274 } 275 276}