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 org.apache.juneau.marshall.*; 020 021/** 022 * DTO for an HTML <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#the-textarea-element"><textarea></a> 023 * element. 024 * 025 * <p> 026 * The textarea element represents a multiline text input control. It allows users to enter and edit 027 * text over multiple lines, making it suitable for longer text content such as comments, descriptions, 028 * or messages. The textarea element supports various attributes for controlling its size, behavior, 029 * and validation. 030 * 031 * <h5 class='section'>Examples:</h5> 032 * <p class='bcode w800'> 033 * <jk>import static</jk> org.apache.juneau.bean.html5.HtmlBuilder.*; 034 * 035 * <jc>// Basic textarea</jc> 036 * Textarea <jv>basic</jv> = <jsm>textarea</jsm>(<js>"comments"</js>) 037 * .rows(4) 038 * .cols(50); 039 * 040 * <jc>// Textarea with placeholder and validation</jc> 041 * Textarea <jv>validated</jv> = <jsm>textarea</jsm>(<js>"description"</js>) 042 * .placeholder(<js>"Enter a description..."</js>) 043 * .required(<jk>true</jk>) 044 * .minlength(10) 045 * .maxlength(500); 046 * 047 * <jc>// Textarea with initial content</jc> 048 * Textarea <jv>withContent</jv> = <jsm>textarea</jsm>(<js>"message"</js>) 049 * .text(<js>"Default message text"</js>); 050 * 051 * <jc>// Textarea with styling and behavior</jc> 052 * Textarea <jv>styled</jv> = <jsm>textarea</jsm>(<js>"feedback"</js>) 053 * .class_(<js>"large-textarea"</js>) 054 * .rows(6) 055 * .cols(60) 056 * .placeholder(<js>"Please provide your feedback..."</js>) 057 * .wrap(<js>"hard"</js>); 058 * 059 * <jc>// Disabled textarea</jc> 060 * Textarea <jv>disabled</jv> = <jsm>textarea</jsm>(<js>"readonly"</js>) 061 * .disabled(true) 062 * .text("This textarea is disabled"); 063 * 064 * // Textarea with form association 065 * Textarea external = new Textarea() 066 * .name="external" 067 * .form="myForm" 068 * .placeholder="This textarea is outside the form"; 069 * </p> 070 * 071 * <p> 072 * The following convenience methods are provided for constructing instances of this bean: 073 * <ul class='javatree'> 074 * <li class='jc'>{@link HtmlBuilder} 075 * <ul class='javatree'> 076 * <li class='jm'>{@link HtmlBuilder#textarea() textarea()} 077 * <li class='jm'>{@link HtmlBuilder#textarea(String, String) textarea(String, String)} 078 * </ul> 079 * </ul> 080 * </p> 081 * 082 * <h5 class='section'>See Also:</h5><ul> 083 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanHtml5">juneau-bean-html5</a> 084 * </ul> 085 */ 086@Marshalled(typeName = "textarea") 087public class Textarea extends HtmlElementRawText<Textarea> { 088 089 /** 090 * Creates an empty {@link Textarea} element. 091 */ 092 public Textarea() {} 093 094 /** 095 * Creates a {@link Textarea} element with the specified {@link Textarea#name(String)} attribute and 096 * {@link Textarea#text(Object)} node. 097 * 098 * @param name The {@link Textarea#name(String)} attribute. Can be <jk>null</jk> to unset the attribute. 099 * @param text The {@link Textarea#text(Object)} node. Can be <jk>null</jk> to leave the text unset. 100 */ 101 public Textarea(String name, String text) { 102 name(name).text(text); 103 } 104 105 /** 106 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fe-autocomplete">autocomplete</a> attribute. 107 * 108 * <p> 109 * Specifies whether the browser should automatically complete the form field based on user's previous input. 110 * 111 * <p> 112 * Possible values: 113 * <ul> 114 * <li><js>"on"</js> - Allow autocomplete (default)</li> 115 * <li><js>"off"</js> - Disable autocomplete</li> 116 * <li><js>"name"</js> - Autocomplete for name fields</li> 117 * <li><js>"email"</js> - Autocomplete for email fields</li> 118 * <li><js>"username"</js> - Autocomplete for username fields</li> 119 * <li><js>"current-password"</js> - Autocomplete for current password</li> 120 * <li><js>"new-password"</js> - Autocomplete for new password</li> 121 * </ul> 122 * 123 * @param value Autocomplete behavior for the form field. Can be <jk>null</jk> to unset the attribute. 124 * @return This object. 125 */ 126 public Textarea autocomplete(String value) { 127 attr("autocomplete", value); 128 return this; 129 } 130 131 /** 132 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fe-autofocus">autofocus</a> attribute. 133 * 134 * <p> 135 * Automatically focus the form control when the page is loaded. 136 * 137 * @param value 138 * The new value for this attribute. 139 * Typically a {@link Boolean} or {@link String}. 140 * Can be <jk>null</jk> to unset the attribute. 141 * @return This object. 142 */ 143 public Textarea autofocus(Object value) { 144 attr("autofocus", value); 145 return this; 146 } 147 148 /** 149 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-textarea-cols">cols</a> attribute. 150 * 151 * <p> 152 * Specifies the visible width of the textarea in characters. This is a hint for the browser 153 * and may not be exactly followed depending on the font and styling. 154 * 155 * @param value The visible width of the textarea in characters. Can be <jk>null</jk> to unset the attribute. 156 * @return This object. 157 */ 158 public Textarea cols(Object value) { 159 attr("cols", value); 160 return this; 161 } 162 163 /** 164 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fe-dirname">dirname</a> attribute. 165 * 166 * <p> 167 * Specifies the name of a hidden form field that will be submitted along with the textarea value, 168 * containing the text direction (ltr or rtl) of the textarea content. 169 * 170 * <p> 171 * This is useful for forms that need to preserve text direction information when submitted. 172 * The hidden field will contain either "ltr" or "rtl" based on the textarea's direction. 173 * 174 * @param value The name of the hidden field for directionality information. Can be <jk>null</jk> to unset the attribute. 175 * @return This object. 176 */ 177 public Textarea dirname(String value) { 178 attr("dirname", value); 179 return this; 180 } 181 182 /** 183 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fe-disabled">disabled</a> attribute. 184 * 185 * <p> 186 * Whether the form control is disabled. 187 * 188 * <p> 189 * This attribute uses deminimized values: 190 * <ul> 191 * <li><jk>false</jk> - Attribute is not added</li> 192 * <li><jk>true</jk> - Attribute is added as <js>"disabled"</js></li> 193 * <li>Other values - Passed through as-is</li> 194 * </ul> 195 * 196 * @param value 197 * The new value for this attribute. 198 * Typically a {@link Boolean} or {@link String}. 199 * Can be <jk>null</jk> to unset the attribute. 200 * @return This object. 201 */ 202 public Textarea disabled(Object value) { 203 attr("disabled", deminimize(value, "disabled")); 204 return this; 205 } 206 207 /** 208 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fae-form">form</a> attribute. 209 * 210 * <p> 211 * Associates the textarea with a form element by specifying the form's ID. This allows the textarea 212 * to be placed outside the form element while still being part of the form submission. 213 * 214 * <p> 215 * The value should match the ID of a form element in the same document. 216 * 217 * @param value The ID of the form element to associate with this textarea. Can be <jk>null</jk> to unset the attribute. 218 * @return This object. 219 */ 220 public Textarea form(String value) { 221 attr("form", value); 222 return this; 223 } 224 225 /** 226 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#inputmode">inputmode</a> attribute. 227 * 228 * <p> 229 * Provides a hint to browsers about the type of virtual keyboard to display on mobile devices. 230 * 231 * <p> 232 * Possible values: 233 * <ul> 234 * <li><js>"none"</js> - No virtual keyboard</li> 235 * <li><js>"text"</js> - Standard text keyboard (default)</li> 236 * <li><js>"tel"</js> - Telephone number keyboard</li> 237 * <li><js>"url"</js> - URL keyboard with .com key</li> 238 * <li><js>"email"</js> - Email keyboard with @ key</li> 239 * <li><js>"numeric"</js> - Numeric keyboard</li> 240 * <li><js>"decimal"</js> - Decimal number keyboard</li> 241 * <li><js>"search"</js> - Search keyboard</li> 242 * </ul> 243 * 244 * @param value The type of virtual keyboard to display. Can be <jk>null</jk> to unset the attribute. 245 * @return This object. 246 */ 247 public Textarea inputmode(String value) { 248 attr("inputmode", value); 249 return this; 250 } 251 252 /** 253 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-textarea-maxlength">maxlength</a> attribute. 254 * 255 * <p> 256 * Maximum length of value. 257 * 258 * @param value 259 * The new value for this attribute. 260 * Typically a {@link Number} or {@link String}. 261 * Can be <jk>null</jk> to unset the attribute. 262 * @return This object. 263 */ 264 public Textarea maxlength(Object value) { 265 attr("maxlength", value); 266 return this; 267 } 268 269 /** 270 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-textarea-minlength">minlength</a> attribute. 271 * 272 * <p> 273 * Minimum length of value. 274 * 275 * @param value 276 * The new value for this attribute. 277 * Typically a {@link Number} or {@link String}. 278 * Can be <jk>null</jk> to unset the attribute. 279 * @return This object. 280 */ 281 public Textarea minlength(Object value) { 282 attr("minlength", value); 283 return this; 284 } 285 286 /** 287 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fe-name">name</a> attribute. 288 * 289 * <p> 290 * Specifies the name of the form control. This name is used when the form is submitted and 291 * can be used to access the element via the form.elements API. 292 * 293 * <p> 294 * The name should be unique within the form and should not contain spaces or special characters. 295 * 296 * @param value The name of the form control for submission and API access. Can be <jk>null</jk> to unset the attribute. 297 * @return This object. 298 */ 299 public Textarea name(String value) { 300 attr("name", value); 301 return this; 302 } 303 304 /** 305 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-textarea-placeholder">placeholder</a> 306 * attribute. 307 * 308 * <p> 309 * Provides a hint to the user about what to enter in the textarea. The placeholder text is displayed 310 * when the textarea is empty and disappears when the user starts typing. 311 * 312 * <p> 313 * The placeholder should be a brief, helpful description of the expected input. 314 * 315 * @param value The placeholder text to display when the textarea is empty. Can be <jk>null</jk> to unset the attribute. 316 * @return This object. 317 */ 318 public Textarea placeholder(String value) { 319 attr("placeholder", value); 320 return this; 321 } 322 323 /** 324 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-textarea-readonly">readonly</a> attribute. 325 * 326 * <p> 327 * Whether to allow the value to be edited by the user. 328 * 329 * @param value 330 * The new value for this attribute. 331 * Typically a {@link Boolean} or {@link String}. 332 * Can be <jk>null</jk> to unset the attribute. 333 * @return This object. 334 */ 335 public Textarea readonly(Object value) { 336 attr("readonly", value); 337 return this; 338 } 339 340 /** 341 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-textarea-required">required</a> attribute. 342 * 343 * <p> 344 * Whether the control is required for form submission. 345 * 346 * @param value 347 * The new value for this attribute. 348 * Typically a {@link Boolean} or {@link String}. 349 * Can be <jk>null</jk> to unset the attribute. 350 * @return This object. 351 */ 352 public Textarea required(Object value) { 353 attr("required", value); 354 return this; 355 } 356 357 /** 358 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-textarea-rows">rows</a> attribute. 359 * 360 * <p> 361 * Specifies the visible height of the textarea in lines. This is a hint for the browser 362 * and may not be exactly followed depending on the font and styling. 363 * 364 * @param value The visible height of the textarea in lines. Can be <jk>null</jk> to unset the attribute. 365 * @return This object. 366 */ 367 public Textarea rows(Number value) { 368 attr("rows", value); 369 return this; 370 } 371 372 /** 373 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-textarea-wrap">wrap</a> attribute. 374 * 375 * <p> 376 * Specifies how the text in the textarea should be wrapped when the form is submitted. 377 * 378 * <p> 379 * Possible values: 380 * <ul> 381 * <li><js>"soft"</js> - Text is wrapped in the display but not in the submitted value (default)</li> 382 * <li><js>"hard"</js> - Text is wrapped in both display and submitted value</li> 383 * <li><js>"off"</js> - Text is not wrapped</li> 384 * </ul> 385 * 386 * @param value How the text should be wrapped for form submission. Can be <jk>null</jk> to unset the attribute. 387 * @return This object. 388 */ 389 public Textarea wrap(String value) { 390 attr("wrap", value); 391 return this; 392 } 393}