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 * <h5 class='section'>Examples:</h5> 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 * </p> 067 * 068 * <h5 class='section'>See Also:</h5><ul> 069 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanHtml5">juneau-bean-html5</a> 070 * </ul> 071 */ 072@Marshalled(typeName = "option") 073public class Option extends HtmlElementText<Option> { 074 075 /** 076 * Creates an empty {@link Option} element. 077 */ 078 public Option() {} 079 080 /** 081 * Creates an {@link Option} element with the specified {@link Option#text(Object)} attribute. 082 * 083 * @param text The {@link Option#text(Object)} attribute. Can be <jk>null</jk> to leave the text unset. 084 */ 085 public Option(Object text) { 086 text(text); 087 } 088 089 /** 090 * Creates an {@link Option} element with the specified {@link Option#value(Object)} attribute and 091 * {@link Option#text(Object)} node. 092 * 093 * @param value The {@link Option#value(Object)} attribute. Can be <jk>null</jk> to unset the attribute. 094 * @param text The {@link Option#text(Object)} node. Can be <jk>null</jk> to leave the text unset. 095 */ 096 public Option(Object value, Object text) { 097 value(value).text(text); 098 } 099 100 /** 101 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-option-disabled">disabled</a> attribute. 102 * 103 * <p> 104 * Whether the form control is disabled. 105 * 106 * <p> 107 * This attribute uses deminimized values: 108 * <ul> 109 * <li><jk>false</jk> - Attribute is not added</li> 110 * <li><jk>true</jk> - Attribute is added as <js>"disabled"</js></li> 111 * <li>Other values - Passed through as-is</li> 112 * </ul> 113 * 114 * @param value 115 * The new value for this attribute. 116 * Typically a {@link Boolean} or {@link String}. 117 * Can be <jk>null</jk> to unset the attribute. 118 * @return This object. 119 */ 120 public Option disabled(Object value) { 121 attr("disabled", deminimize(value, "disabled")); 122 return this; 123 } 124 125 /** 126 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-option-label">label</a> attribute. 127 * 128 * <p> 129 * Specifies the user-visible label for the option. This label is displayed in the select element 130 * and can be different from the option's value. 131 * 132 * <p> 133 * The label should be user-friendly and descriptive of what the option represents. 134 * 135 * @param value The user-visible label for the option. Can be <jk>null</jk> to unset the attribute. 136 * @return This object. 137 */ 138 public Option label(String value) { 139 attr("label", value); 140 return this; 141 } 142 143 /** 144 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-option-selected">selected</a> attribute. 145 * 146 * <p> 147 * Whether the option is selected by default. 148 * 149 * <p> 150 * This attribute uses deminimized values: 151 * <ul> 152 * <li><jk>false</jk> - Attribute is not added</li> 153 * <li><jk>true</jk> - Attribute is added as <js>"selected"</js></li> 154 * <li>Other values - Passed through as-is</li> 155 * </ul> 156 * 157 * @param value 158 * The new value for this attribute. 159 * Typically a {@link Boolean} or {@link String}. 160 * Can be <jk>null</jk> to unset the attribute. 161 * @return This object. 162 */ 163 public Option selected(Object value) { 164 attr("selected", deminimize(value, "selected")); 165 return this; 166 } 167 168 /** 169 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-option-value">value</a> attribute. 170 * 171 * <p> 172 * Value to be used for form submission. 173 * 174 * @param value 175 * The new value for this attribute. 176 * Typically a {@link Number} or {@link String}. 177 * Can be <jk>null</jk> to unset the attribute. 178 * @return This object. 179 */ 180 public Option value(Object value) { 181 attr("value", value); 182 return this; 183 } 184}