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 * <h5 class='section'>Examples:</h5> 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 * </p> 077 * 078 * <h5 class='section'>See Also:</h5><ul> 079 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanHtml5">juneau-bean-html5</a> 080 * </ul> 081 */ 082@Marshalled(typeName = "form") 083public class Form extends HtmlElementMixed<Form> { 084 085 /** 086 * Creates an empty {@link Form} element. 087 */ 088 public Form() {} 089 090 /** 091 * Creates a {@link Form} element with the specified {@link Form#action(String)} attribute. 092 * 093 * @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). 094 */ 095 public Form(String action) { 096 action(action); 097 } 098 099 /** 100 * Creates an {@link Form} element with the specified {@link Form#action(String)} attribute and child nodes. 101 * 102 * @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). 103 * @param children The child nodes. Must not be <jk>null</jk>. 104 */ 105 public Form(String action, Object...children) { 106 action(action).children(children); 107 } 108 109 /** 110 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-form-accept-charset">accept-charset</a> 111 * attribute. 112 * 113 * <p> 114 * Specifies the character encodings that are accepted for form submission. Multiple encodings 115 * can be specified as a space-separated list. 116 * 117 * <p> 118 * Common values: 119 * <ul> 120 * <li><js>"UTF-8"</js> - Unicode UTF-8 encoding (default)</li> 121 * <li><js>"ISO-8859-1"</js> - Latin-1 encoding</li> 122 * <li><js>"UTF-8 ISO-8859-1"</js> - Multiple encodings</li> 123 * </ul> 124 * 125 * @param value The character encodings accepted for form submission. Can be <jk>null</jk> to unset the attribute. 126 * @return This object. 127 */ 128 public Form acceptcharset(String value) { 129 attr("accept-charset", value); 130 return this; 131 } 132 133 /** 134 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-action">action</a> attribute. 135 * 136 * <p> 137 * URL to use for form submission. 138 * 139 * <p> 140 * The value can be of any of the following types: {@link URI}, {@link URL}, {@link String}. 141 * Strings must be valid URIs. 142 * 143 * <p> 144 * URIs defined by {@link UriResolver} can be used for values. 145 * 146 * @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). 147 * @return This object. 148 */ 149 public Form action(String value) { 150 attrUri("action", value); 151 return this; 152 } 153 154 /** 155 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-form-autocomplete">autocomplete</a> 156 * attribute. 157 * 158 * <p> 159 * Sets the default autocomplete behavior for all form controls within this form. 160 * Individual controls can override this setting. 161 * 162 * <p> 163 * Possible values: 164 * <ul> 165 * <li><js>"on"</js> - Allow autocomplete (default)</li> 166 * <li><js>"off"</js> - Disable autocomplete</li> 167 * </ul> 168 * 169 * @param value The default autocomplete behavior for form controls. Can be <jk>null</jk> to unset the attribute. 170 * @return This object. 171 */ 172 public Form autocomplete(String value) { 173 attr("autocomplete", value); 174 return this; 175 } 176 177 /** 178 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-enctype">enctype</a> attribute. 179 * 180 * <p> 181 * Specifies how form data should be encoded when submitted to the server. 182 * 183 * <p> 184 * Possible values: 185 * <ul> 186 * <li><js>"application/x-www-form-urlencoded"</js> - Default encoding (default)</li> 187 * <li><js>"multipart/form-data"</js> - Used for file uploads</li> 188 * <li><js>"text/plain"</js> - Plain text encoding</li> 189 * </ul> 190 * 191 * @param value The encoding type for form data submission. Can be <jk>null</jk> to unset the attribute. 192 * @return This object. 193 */ 194 public Form enctype(String value) { 195 attr("enctype", value); 196 return this; 197 } 198 199 /** 200 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-method">method</a> attribute. 201 * 202 * <p> 203 * Specifies the HTTP method to use when submitting the form. 204 * 205 * <p> 206 * Possible values: 207 * <ul> 208 * <li><js>"get"</js> - Form data is sent as URL parameters (default)</li> 209 * <li><js>"post"</js> - Form data is sent in the request body</li> 210 * <li><js>"dialog"</js> - Used for forms within dialog elements</li> 211 * </ul> 212 * 213 * @param value The HTTP method for form submission. Can be <jk>null</jk> to unset the attribute. 214 * @return This object. 215 */ 216 public Form method(String value) { 217 attr("method", value); 218 return this; 219 } 220 221 /** 222 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-form-name">name</a> attribute. 223 * 224 * <p> 225 * Specifies the name of the form. This name can be used to access the form via the 226 * document.forms API and for form submission. 227 * 228 * <p> 229 * The name should be unique within the document and should not contain spaces or special characters. 230 * 231 * @param value The name of the form for API access and submission. Can be <jk>null</jk> to unset the attribute. 232 * @return This object. 233 */ 234 public Form name(String value) { 235 attr("name", value); 236 return this; 237 } 238 239 /** 240 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-novalidate">novalidate</a> attribute. 241 * 242 * <p> 243 * Disables form validation, allowing the form to be submitted even if validation fails. 244 * 245 * @param value If <jk>true</jk>, disables form validation. Can be <jk>null</jk> to unset the attribute. 246 * @return This object. 247 */ 248 public Form novalidate(Boolean value) { 249 attr("novalidate", value); 250 return this; 251 } 252 253 /** 254 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-target">target</a> attribute. 255 * 256 * <p> 257 * Specifies where to display the response after form submission. 258 * 259 * <p> 260 * Possible values: 261 * <ul> 262 * <li><js>"_self"</js> - Load in the same frame (default)</li> 263 * <li><js>"_blank"</js> - Load in a new window or tab</li> 264 * <li><js>"_parent"</js> - Load in the parent frame</li> 265 * <li><js>"_top"</js> - Load in the full body of the window</li> 266 * <li>Frame name - Load in the named frame</li> 267 * </ul> 268 * 269 * @param value Where to display the form submission response. Can be <jk>null</jk> to unset the attribute. 270 * @return This object. 271 */ 272 public Form target(String value) { 273 attr("target", value); 274 return this; 275 } 276 277}