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