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-input-element"><input></a> 025 * element. 026 * 027 * <p> 028 * The input element represents a form control that allows users to input data. It is a void element 029 * that can take many different forms depending on the type attribute, including text fields, checkboxes, 030 * radio buttons, file uploads, and more. The input element is one of the most versatile and commonly 031 * used form controls in HTML. 032 * 033 * <h5 class='section'>Examples:</h5> 034 * <p class='bcode w800'> 035 * <jk>import static</jk> org.apache.juneau.bean.html5.HtmlBuilder.*; 036 * 037 * <jc>// Text input field</jc> 038 * Input <jv>input1</jv> = <jsm>input</jsm>(<js>"text"</js>) 039 * .name(<js>"username"</js>) 040 * .placeholder(<js>"Enter your username"</js>) 041 * .required(<jk>true</jk>); 042 * 043 * <jc>// Email input with validation</jc> 044 * Input <jv>input2</jv> = <jsm>input</jsm>(<js>"email"</js>) 045 * .name(<js>"email"</js>) 046 * .placeholder(<js>"your@email.com"</js>) 047 * .autocomplete(<js>"email"</js>); 048 * 049 * <jc>// File upload input</jc> 050 * Input <jv>input3</jv> = <jsm>input</jsm>(<js>"file"</js>) 051 * .name(<js>"avatar"</js>) 052 * .accept(<js>"image/*"</js>) 053 * .multiple(<jk>true</jk>); 054 * 055 * <jc>// Checkbox input</jc> 056 * Input <jv>input4</jv> = <jsm>input</jsm>(<js>"checkbox"</js>) 057 * .name(<js>"subscribe"</js>) 058 * .value(<js>"yes"</js>) 059 * .checked(<jk>true</jk>); 060 * 061 * <jc>// Password input with pattern</jc> 062 * Input <jv>input5</jv> = <jsm>input</jsm>(<js>"password"</js>) 063 * .name(<js>"password"</js>) 064 * .pattern(<js>".{8,}"</js>) 065 * .title(<js>"Password must be at least 8 characters"</js>); 066 * </p> 067 * 068 * <p> 069 * The following convenience methods are provided for constructing instances of this bean: 070 * <ul class='javatree'> 071 * <li class='jc'>{@link HtmlBuilder} 072 * <ul class='javatree'> 073 * <li class='jm'>{@link HtmlBuilder#input() input()} 074 * <li class='jm'>{@link HtmlBuilder#input(String) input(String)} 075 * </ul> 076 * </ul> 077 * </p> 078 * 079 * <h5 class='section'>See Also:</h5><ul> 080 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanHtml5">juneau-bean-html5</a> 081 * </ul> 082 */ 083@Marshalled(typeName = "input") 084public class Input extends HtmlElementVoid<Input> { 085 086 /** 087 * Creates an empty {@link Input} element. 088 */ 089 public Input() {} 090 091 /** 092 * Creates an {@link Input} element with the specified {@link Input#type(String)} attribute. 093 * 094 * @param type The {@link Input#type(String)} attribute. Can be <jk>null</jk> to unset the attribute. 095 */ 096 public Input(String type) { 097 type(type); 098 } 099 100 /** 101 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-accept">accept</a> attribute. 102 * 103 * <p> 104 * Specifies which file types the file input should accept. Used with <c>type="file"</c>. 105 * 106 * <p> 107 * Examples: 108 * <ul> 109 * <li><js>"image/*"</js> - Accept all image files</li> 110 * <li><js>".pdf,.doc,.docx"</js> - Accept specific file extensions</li> 111 * <li><js>"image/png,image/jpeg"</js> - Accept specific MIME types</li> 112 * </ul> 113 * 114 * @param value File type restrictions for file uploads. Can be <jk>null</jk> to unset the attribute. 115 * @return This object. 116 */ 117 public Input accept(String value) { 118 attr("accept", value); 119 return this; 120 } 121 122 /** 123 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-alt">alt</a> attribute. 124 * 125 * <p> 126 * Alternative text for image submit buttons. Used with <c>type="image"</c> to provide 127 * accessible text when the image cannot be displayed. 128 * 129 * @param value Alternative text for image submit buttons. Can be <jk>null</jk> to unset the attribute. 130 * @return This object. 131 */ 132 public Input alt(String value) { 133 attr("alt", value); 134 return this; 135 } 136 137 /** 138 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fe-autocomplete">autocomplete</a> attribute. 139 * 140 * <p> 141 * Controls whether the browser can automatically complete the input field. 142 * 143 * <p> 144 * Common values: 145 * <ul> 146 * <li><js>"on"</js> - Allow autocomplete (default)</li> 147 * <li><js>"off"</js> - Disable autocomplete</li> 148 * <li><js>"name"</js> - Full name</li> 149 * <li><js>"email"</js> - Email address</li> 150 * <li><js>"username"</js> - Username or login</li> 151 * <li><js>"current-password"</js> - Current password</li> 152 * <li><js>"new-password"</js> - New password</li> 153 * <li><js>"tel"</js> - Telephone number</li> 154 * <li><js>"url"</js> - URL</li> 155 * <li><js>"address-line1"</js> - Street address</li> 156 * <li><js>"country"</js> - Country name</li> 157 * <li><js>"postal-code"</js> - Postal code</li> 158 * </ul> 159 * 160 * @param value Autocomplete hint for the input field. Can be <jk>null</jk> to unset the attribute. 161 * @return This object. 162 */ 163 public Input autocomplete(String value) { 164 attr("autocomplete", value); 165 return this; 166 } 167 168 /** 169 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fe-autofocus">autofocus</a> attribute. 170 * 171 * <p> 172 * Automatically focuses the form control when the page loads. 173 * Only one element per page should have this attribute. 174 * 175 * @param value 176 * The new value for this attribute. 177 * Typically a {@link Boolean} or {@link String}. 178 * Can be <jk>null</jk> to unset the attribute. 179 * @return This object. 180 */ 181 public Input autofocus(Object value) { 182 attr("autofocus", value); 183 return this; 184 } 185 186 /** 187 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-checked">checked</a> attribute. 188 * 189 * <p> 190 * Whether the command or control is checked. 191 * 192 * <p> 193 * This attribute uses deminimized values: 194 * <ul> 195 * <li><jk>false</jk> - Attribute is not added</li> 196 * <li><jk>true</jk> - Attribute is added as <js>"checked"</js></li> 197 * <li>Other values - Passed through as-is</li> 198 * </ul> 199 * 200 * @param value 201 * The new value for this attribute. 202 * Typically a {@link Boolean} or {@link String}. 203 * Can be <jk>null</jk> to unset the attribute. 204 * @return This object. 205 */ 206 public Input checked(Object value) { 207 attr("checked", deminimize(value, "checked")); 208 return this; 209 } 210 211 /** 212 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fe-dirname">dirname</a> attribute. 213 * 214 * <p> 215 * Specifies the name of a hidden form field that will be submitted along with the input value, 216 * containing the text direction (ltr or rtl) of the input content. 217 * 218 * <p> 219 * This is useful for forms that need to preserve text direction information when submitted. 220 * The hidden field will contain either "ltr" or "rtl" based on the input's direction. 221 * 222 * @param value The name of the hidden field for directionality information. Can be <jk>null</jk> to unset the attribute. 223 * @return This object. 224 */ 225 public Input dirname(String value) { 226 attr("dirname", value); 227 return this; 228 } 229 230 /** 231 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fe-disabled">disabled</a> attribute. 232 * 233 * <p> 234 * Whether the form control is disabled. 235 * 236 * <p> 237 * This attribute uses deminimized values: 238 * <ul> 239 * <li><jk>false</jk> - Attribute is not added</li> 240 * <li><jk>true</jk> - Attribute is added as <js>"disabled"</js></li> 241 * <li>Other values - Passed through as-is</li> 242 * </ul> 243 * 244 * @param value 245 * The new value for this attribute. 246 * Typically a {@link Boolean} or {@link String}. 247 * Can be <jk>null</jk> to unset the attribute. 248 * @return This object. 249 */ 250 public Input disabled(Object value) { 251 attr("disabled", deminimize(value, "disabled")); 252 return this; 253 } 254 255 /** 256 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fae-form">form</a> attribute. 257 * 258 * <p> 259 * Associates the input with a form element by specifying the form's ID. This allows the input 260 * to be placed outside the form element while still being part of the form. 261 * 262 * <p> 263 * The value should match the ID of a form element in the same document. 264 * 265 * @param value The ID of the form element to associate with this input. Can be <jk>null</jk> to unset the attribute. 266 * @return This object. 267 */ 268 public Input form(String value) { 269 attr("form", value); 270 return this; 271 } 272 273 /** 274 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-formaction">formaction</a> attribute. 275 * 276 * <p> 277 * URL to use for form submission. 278 * 279 * @param value The new value for this attribute. Can be <jk>null</jk> to unset the attribute. 280 * @return This object. 281 */ 282 public Input formaction(String value) { 283 attr("formaction", value); 284 return this; 285 } 286 287 /** 288 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-formenctype">formenctype</a> attribute. 289 * 290 * <p> 291 * Form data set encoding type to use for form submission. 292 * 293 * @param value The new value for this attribute. Can be <jk>null</jk> to unset the attribute. 294 * @return This object. 295 */ 296 public Input formenctype(String value) { 297 attr("formenctype", value); 298 return this; 299 } 300 301 /** 302 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-formmethod">formmethod</a> attribute. 303 * 304 * <p> 305 * HTTP method to use for form submission. 306 * 307 * @param value The new value for this attribute. Can be <jk>null</jk> to unset the attribute. 308 * @return This object. 309 */ 310 public Input formmethod(String value) { 311 attr("formmethod", value); 312 return this; 313 } 314 315 /** 316 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-formnovalidate">formnovalidate</a> 317 * attribute. 318 * 319 * <p> 320 * Bypass form control validation for form submission. 321 * 322 * @param value The new value for this attribute. Can be <jk>null</jk> to unset the attribute. 323 * @return This object. 324 */ 325 public Input formnovalidate(String value) { 326 attr("formnovalidate", value); 327 return this; 328 } 329 330 /** 331 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-formtarget">formtarget</a> attribute. 332 * 333 * <p> 334 * Browsing context for form submission. 335 * 336 * @param value The new value for this attribute. Can be <jk>null</jk> to unset the attribute. 337 * @return This object. 338 */ 339 public Input formtarget(String value) { 340 attr("formtarget", value); 341 return this; 342 } 343 344 /** 345 * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-dim-height">height</a> 346 * attribute. 347 * 348 * <p> 349 * Vertical dimension. 350 * 351 * @param value 352 * The new value for this attribute. 353 * Typically a {@link Number} or {@link String}. 354 * Can be <jk>null</jk> to unset the attribute. 355 * @return This object. 356 */ 357 public Input height(Object value) { 358 attr("height", value); 359 return this; 360 } 361 362 /** 363 * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-input-inputmode">inputmode</a> 364 * attribute. 365 * 366 * <p> 367 * Provides a hint to browsers about the type of virtual keyboard to display on mobile devices. 368 * 369 * <p> 370 * Possible values: 371 * <ul> 372 * <li><js>"none"</js> - No virtual keyboard</li> 373 * <li><js>"text"</js> - Standard text keyboard (default)</li> 374 * <li><js>"tel"</js> - Numeric keypad for telephone numbers</li> 375 * <li><js>"url"</js> - Keyboard optimized for URLs</li> 376 * <li><js>"email"</js> - Keyboard optimized for email addresses</li> 377 * <li><js>"numeric"</js> - Numeric keypad</li> 378 * <li><js>"decimal"</js> - Numeric keypad with decimal point</li> 379 * <li><js>"search"</js> - Keyboard optimized for search</li> 380 * </ul> 381 * 382 * @param value The input modality hint for mobile keyboards. Can be <jk>null</jk> to unset the attribute. 383 * @return This object. 384 */ 385 public Input inputmode(String value) { 386 attr("inputmode", value); 387 return this; 388 } 389 390 /** 391 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-list">list</a> attribute. 392 * 393 * <p> 394 * References a <c><datalist></c> element that provides predefined options 395 * for the input field. Creates a dropdown with autocomplete suggestions. 396 * 397 * @param value The ID of a datalist element (without the # prefix). Can be <jk>null</jk> to unset the attribute. 398 * @return This object. 399 */ 400 public Input list(String value) { 401 attr("list", value); 402 return this; 403 } 404 405 /** 406 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-max">max</a> attribute. 407 * 408 * <p> 409 * Maximum value. 410 * 411 * @param value 412 * The new value for this attribute. 413 * Typically a {@link Number} or {@link String}. 414 * Can be <jk>null</jk> to unset the attribute. 415 * @return This object. 416 */ 417 public Input max(Object value) { 418 attr("max", value); 419 return this; 420 } 421 422 /** 423 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-maxlength">maxlength</a> attribute. 424 * Maximum length of value. 425 * 426 * @param value The new value for this attribute. Can be <jk>null</jk> to unset the attribute. 427 * Typically a {@link Number} or {@link String}. 428 * @return This object. 429 */ 430 public Input maxlength(Object value) { 431 attr("maxlength", value); 432 return this; 433 } 434 435 /** 436 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-min">min</a> attribute. 437 * 438 * <p> 439 * Minimum value. 440 * 441 * @param value 442 * The new value for this attribute. 443 * Typically a {@link Number} or {@link String}. 444 * Can be <jk>null</jk> to unset the attribute. 445 * @return This object. 446 */ 447 public Input min(Object value) { 448 attr("min", value); 449 return this; 450 } 451 452 /** 453 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-minlength">minlength</a> attribute. 454 * 455 * <p> 456 * Minimum length of value. 457 * 458 * @param value 459 * The new value for this attribute. 460 * Typically a {@link Number} or {@link String}. 461 * Can be <jk>null</jk> to unset the attribute. 462 * @return This object. 463 */ 464 public Input minlength(Object value) { 465 attr("minlength", value); 466 return this; 467 } 468 469 /** 470 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-multiple">multiple</a> attribute. 471 * 472 * <p> 473 * Whether to allow multiple values. 474 * 475 * <p> 476 * This attribute uses deminimized values: 477 * <ul> 478 * <li><jk>false</jk> - Attribute is not added</li> 479 * <li><jk>true</jk> - Attribute is added as <js>"multiple"</js></li> 480 * <li>Other values - Passed through as-is</li> 481 * </ul> 482 * 483 * @param value 484 * The new value for this attribute. 485 * Typically a {@link Boolean} or {@link String}. 486 * Can be <jk>null</jk> to unset the attribute. 487 * @return This object. 488 */ 489 public Input multiple(Object value) { 490 attr("multiple", deminimize(value, "multiple")); 491 return this; 492 } 493 494 /** 495 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fe-name">name</a> attribute. 496 * 497 * <p> 498 * Name of form control to use for form submission and in the form.elements API. 499 * 500 * @param value The new value for this attribute. Can be <jk>null</jk> to unset the attribute. 501 * @return This object. 502 */ 503 public Input name(String value) { 504 attr("name", value); 505 return this; 506 } 507 508 /** 509 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-pattern">pattern</a> attribute. 510 * 511 * <p> 512 * Specifies a regular expression that the input's value must match for the form to be valid. 513 * Works with the <c>title</c> attribute to provide user feedback. 514 * 515 * @param value A regular expression pattern (e.g., <js>"[0-9]{3}-[0-9]{3}-[0-9]{4}"</js> for phone numbers). Can be <jk>null</jk> to unset the attribute. 516 * @return This object. 517 */ 518 public Input pattern(String value) { 519 attr("pattern", value); 520 return this; 521 } 522 523 /** 524 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-placeholder">placeholder</a> attribute. 525 * 526 * <p> 527 * Provides a hint to the user about what to enter in the input field. 528 * The placeholder text appears when the field is empty and disappears when the user starts typing. 529 * 530 * @param value Hint text to display in the empty input field. Can be <jk>null</jk> to unset the attribute. 531 * @return This object. 532 */ 533 public Input placeholder(String value) { 534 attr("placeholder", value); 535 return this; 536 } 537 538 /** 539 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-readonly">readonly</a> attribute. 540 * 541 * <p> 542 * Whether to allow the value to be edited by the user. 543 * 544 * @param value If <jk>true</jk>, adds <c>readonly="readonly"</c>. Can be <jk>null</jk> to unset the attribute. 545 * @return This object. 546 */ 547 public Input readonly(boolean value) { 548 if (value) 549 value("value"); 550 return this; 551 } 552 553 /** 554 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-readonly">readonly</a> attribute. 555 * 556 * <p> 557 * Makes the input field read-only, preventing user modification while still allowing 558 * the value to be submitted with the form. 559 * 560 * @param value If <jk>true</jk>, makes the input read-only. Can be <jk>null</jk> to unset the attribute. 561 * @return This object. 562 */ 563 public Input readonly(Object value) { 564 attr("readonly", value); 565 return this; 566 } 567 568 /** 569 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-readonly">required</a> attribute. 570 * 571 * <p> 572 * Indicates that the input field must be filled out before the form can be submitted. 573 * Browsers will show validation messages for empty required fields. 574 * 575 * @param value If <jk>true</jk>, makes the input required for form submission. Can be <jk>null</jk> to unset the attribute. 576 * @return This object. 577 */ 578 public Input required(Object value) { 579 attr("required", value); 580 return this; 581 } 582 583 /** 584 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-size">size</a> attribute. 585 * 586 * <p> 587 * Size of the control. 588 * 589 * @param value 590 * The new value for this attribute. 591 * Typically a {@link Number} or {@link String}. 592 * Can be <jk>null</jk> to unset the attribute. 593 * @return This object. 594 */ 595 public Input size(Object value) { 596 attr("size", value); 597 return this; 598 } 599 600 /** 601 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-src">src</a> attribute. 602 * 603 * <p> 604 * Address of the resource. 605 * 606 * @param value 607 * The new value for this attribute. 608 * Typically a {@link URL} or {@link String}. 609 * Can be <jk>null</jk> to unset the attribute. 610 * @return This object. 611 */ 612 public Input src(Object value) { 613 attr("src", value); 614 return this; 615 } 616 617 /** 618 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-step">step</a> attribute. 619 * 620 * <p> 621 * Granularity to be matched by the form control's value. 622 * 623 * @param value The new value for this attribute. Can be <jk>null</jk> to unset the attribute. 624 * @return This object. 625 */ 626 public Input step(String value) { 627 attr("step", value); 628 return this; 629 } 630 631 /** 632 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-type">type</a> attribute. 633 * 634 * <p> 635 * Specifies the type of form control to display. 636 * 637 * <p> 638 * Common values: 639 * <ul> 640 * <li><js>"text"</js> - Single-line text input (default)</li> 641 * <li><js>"password"</js> - Password input (characters are masked)</li> 642 * <li><js>"email"</js> - Email address input with validation</li> 643 * <li><js>"number"</js> - Numeric input with spinner controls</li> 644 * <li><js>"tel"</js> - Telephone number input</li> 645 * <li><js>"url"</js> - URL input with validation</li> 646 * <li><js>"search"</js> - Search input field</li> 647 * <li><js>"date"</js> - Date picker</li> 648 * <li><js>"time"</js> - Time picker</li> 649 * <li><js>"datetime-local"</js> - Date and time picker</li> 650 * <li><js>"checkbox"</js> - Checkbox input</li> 651 * <li><js>"radio"</js> - Radio button input</li> 652 * <li><js>"file"</js> - File upload input</li> 653 * <li><js>"submit"</js> - Submit button</li> 654 * <li><js>"button"</js> - Generic button</li> 655 * <li><js>"reset"</js> - Reset form button</li> 656 * <li><js>"hidden"</js> - Hidden input field</li> 657 * </ul> 658 * 659 * @param value The input type for the form control. Can be <jk>null</jk> to unset the attribute. 660 * @return This object. 661 */ 662 public Input type(String value) { 663 attr("type", value); 664 return this; 665 } 666 667 /** 668 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-value">value</a> attribute. 669 * 670 * <p> 671 * Value of the form control. 672 * 673 * @param value 674 * The new value for this attribute. 675 * Typically a {@link Number} or {@link String}. 676 * Can be <jk>null</jk> to unset the attribute. 677 * @return This object. 678 */ 679 public Input value(Object value) { 680 attr("value", value); 681 return this; 682 } 683 684 /** 685 * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-dim-width">width</a> attribute. 686 * 687 * <p> 688 * Horizontal dimension. 689 * 690 * @param value 691 * The new value for this attribute. 692 * Typically a {@link Number} or {@link String}. 693 * Can be <jk>null</jk> to unset the attribute. 694 * @return This object. 695 */ 696 public Input width(Object value) { 697 attr("width", value); 698 return this; 699 } 700}