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-option-element"><option></a> 023 * element. 024 * 025 * <p> 026 * The option element represents an option in a select element or a suggestion in a datalist element. 027 * It defines a choice that users can select from a dropdown menu or autocomplete list. The value 028 * attribute specifies the value to be submitted, while the text content provides the display text. 029 * 030 * <h2 class='section'>Examples:</h2> 031 * <p class='bcode w800'> 032 * <jk>import static</jk> org.apache.juneau.bean.html5.HtmlBuilder.*; 033 * 034 * <jc>// Simple option</jc> 035 * Option <jv>option1</jv> = <jsm>option</jsm>(<js>"red"</js>, <js>"Red"</js>); 036 * 037 * <jc>// Selected option</jc> 038 * Option <jv>option2</jv> = <jsm>option</jsm>(<js>"blue"</js>, <js>"Blue"</js>) 039 * .selected(<jk>true</jk>); 040 * 041 * <jc>// Disabled option</jc> 042 * Option <jv>option3</jv> = <jsm>option</jsm>(<js>"gray"</js>, <js>"Gray"</js>) 043 * .disabled(<jk>true</jk>); 044 * 045 * <jc>// Option with label</jc> 046 * Option <jv>option4</jv> = <jsm>option</jsm>(<js>"green"</js>, <js>"Green"</js>) 047 * .label(<js>"Green Color"</js>); 048 * 049 * <jc>// Options in a select</jc> 050 * Select <jv>select1</jv> = <jsm>select</jsm>(<js>"color"</js>, 051 * <jsm>option</jsm>(<js>"red"</js>, <js>"Red"</js>), 052 * <jsm>option</jsm>(<js>"green"</js>, <js>"Green"</js>), 053 * <jsm>option</jsm>(<js>"blue"</js>, <js>"Blue"</js>) 054 * ); 055 * </p> 056 * 057 * <p> 058 * The following convenience methods are provided for constructing instances of this bean: 059 * <ul class='javatree'> 060 * <li class='jc'>{@link HtmlBuilder} 061 * <ul class='javatree'> 062 * <li class='jm'>{@link HtmlBuilder#option() option()} 063 * <li class='jm'>{@link HtmlBuilder#option(Object) option(Object)} 064 * </ul> 065 * </ul> 066 * 067 * <h2 class='section'>See Also:</h2><ul> 068 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanHtml5">juneau-bean-html5</a> 069 * </ul> 070 */ 071@Marshalled(typeName = "option") 072public class Option extends HtmlElementText<Option> { 073 074 /** 075 * Creates an empty {@link Option} element. 076 */ 077 public Option() {} 078 079 /** 080 * Creates an {@link Option} element with the specified {@link Option#text(Object)} attribute. 081 * 082 * @param text The {@link Option#text(Object)} attribute. Can be <jk>null</jk> to leave the text unset. 083 */ 084 public Option(Object text) { 085 text(text); 086 } 087 088 /** 089 * Creates an {@link Option} element with the specified {@link Option#value(Object)} attribute and 090 * {@link Option#text(Object)} node. 091 * 092 * @param value The {@link Option#value(Object)} attribute. Can be <jk>null</jk> to unset the attribute. 093 * @param text The {@link Option#text(Object)} node. Can be <jk>null</jk> to leave the text unset. 094 */ 095 public Option(Object value, Object text) { 096 value(value).text(text); 097 } 098 099 /** 100 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-option-disabled">disabled</a> attribute. 101 * 102 * <p> 103 * Whether the form control is disabled. 104 * 105 * <p> 106 * This attribute uses deminimized values: 107 * <ul> 108 * <li><jk>false</jk> - Attribute is not added</li> 109 * <li><jk>true</jk> - Attribute is added as <js>"disabled"</js></li> 110 * <li>Other values - Passed through as-is</li> 111 * </ul> 112 * 113 * @param value 114 * The new value for this attribute. 115 * Typically a {@link Boolean} or {@link String}. 116 * Can be <jk>null</jk> to unset the attribute. 117 * @return This object. 118 */ 119 public Option disabled(Object value) { 120 attr("disabled", deminimize(value, "disabled")); 121 return this; 122 } 123 124 /** 125 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-option-label">label</a> attribute. 126 * 127 * <p> 128 * Specifies the user-visible label for the option. This label is displayed in the select element 129 * and can be different from the option's value. 130 * 131 * <p> 132 * The label should be user-friendly and descriptive of what the option represents. 133 * 134 * @param value The user-visible label for the option. Can be <jk>null</jk> to unset the attribute. 135 * @return This object. 136 */ 137 public Option label(String value) { 138 attr("label", value); 139 return this; 140 } 141 142 /** 143 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-option-selected">selected</a> attribute. 144 * 145 * <p> 146 * Whether the option is selected by default. 147 * 148 * <p> 149 * This attribute uses deminimized values: 150 * <ul> 151 * <li><jk>false</jk> - Attribute is not added</li> 152 * <li><jk>true</jk> - Attribute is added as <js>"selected"</js></li> 153 * <li>Other values - Passed through as-is</li> 154 * </ul> 155 * 156 * @param value 157 * The new value for this attribute. 158 * Typically a {@link Boolean} or {@link String}. 159 * Can be <jk>null</jk> to unset the attribute. 160 * @return This object. 161 */ 162 public Option selected(Object value) { 163 attr("selected", deminimize(value, "selected")); 164 return this; 165 } 166 167 /** 168 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-option-value">value</a> attribute. 169 * 170 * <p> 171 * Value to be used for form submission. 172 * 173 * @param value 174 * The new value for this attribute. 175 * Typically a {@link Number} or {@link String}. 176 * Can be <jk>null</jk> to unset the attribute. 177 * @return This object. 178 */ 179 public Option value(Object value) { 180 attr("value", value); 181 return this; 182 } 183}