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-output-element">&lt;output&gt;</a>
023 * element.
024 *
025 * <p>
026 * The output element represents the result of a calculation or user action. It is typically used
027 * to display the result of form calculations, such as the sum of two numbers or the result of
028 * a mathematical operation. The for attribute can be used to associate the output with specific
029 * form controls that contribute to the calculation.
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>// Simple output element</jc>
036 *    Output <jv>output1</jv> = <jsm>output</jsm>(<js>"0"</js>)
037 *       .name(<js>"result"</js>);
038 *
039 *    <jc>// Output with form association</jc>
040 *    Output <jv>output2</jv> = <jsm>output</jsm>(<js>"0"</js>)
041 *       .name(<js>"sum"</js>)
042 *       .for_(<js>"num1 num2"</js>);
043 *
044 *    <jc>// Output in a calculation form</jc>
045 *    Form <jv>calcForm</jv> = <jsm>form</jsm>(
046 *       <jsm>input</jsm>(<js>"number"</js>).name(<js>"num1"</js>).id(<js>"num1"</js>).value(<js>"0"</js>),
047 *       <jsm>span</jsm>(<js>" + "</js>),
048 *       <jsm>input</jsm>(<js>"number"</js>).name(<js>"num2"</js>).id(<js>"num2"</js>).value(<js>"0"</js>),
049 *       <jsm>span</jsm>(<js>" = "</js>),
050 *       <jsm>output</jsm>(<js>"0"</js>).name(<js>"sum"</js>).for_(<js>"num1 num2"</js>)
051 *    );
052 *
053 *    <jc>// Output with styling</jc>
054 *    Output <jv>output3</jv> = <jsm>output</jsm>(<js>"Ready for calculation"</js>)
055 *       .name(<js>"display"</js>)
056 *       .class_(<js>"result-display"</js>);
057 * </p>
058 *
059 * <p>
060 * The following convenience methods are provided for constructing instances of this bean:
061 * <ul class='javatree'>
062 *    <li class='jc'>{@link HtmlBuilder}
063 *    <ul class='javatree'>
064 *       <li class='jm'>{@link HtmlBuilder#output() output()}
065 *       <li class='jm'>{@link HtmlBuilder#output(String) output(String)}
066 *    </ul>
067 * </ul>
068 *
069 * <h2 class='section'>See Also:</h2><ul>
070 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanHtml5">juneau-bean-html5</a>
071 * </ul>
072 */
073@Marshalled(typeName = "output")
074public class Output extends HtmlElementMixed<Output> {
075
076   /**
077    * Creates an empty {@link Output} element.
078    */
079   public Output() {}
080
081   /**
082    * Creates an {@link Output} element with the specified {@link Output#name(String)} attribute.
083    *
084    * @param name The {@link Output#name(String)} attribute. Can be <jk>null</jk> to unset the attribute.
085    */
086   public Output(String name) {
087      name(name);
088   }
089
090   /**
091    * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-output-for">for</a> attribute.
092    *
093    * <p>
094    * Specifies the IDs of form controls from which the output value was calculated.
095    * This creates a programmatic relationship between the output and its source controls.
096    *
097    * <p>
098    * Multiple IDs can be specified as a space-separated list.
099    *
100    * @param value The IDs of the form controls that contribute to this output. Can be <jk>null</jk> to unset the attribute.
101    * @return This object.
102    */
103   @SuppressWarnings({
104      "java:S100" // Method name uses underscore suffix to avoid Java keyword conflict
105   })
106   public Output for_(String value) {
107      attr("for", value);
108      return this;
109   }
110
111   /**
112    * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fae-form">form</a> attribute.
113    *
114    * <p>
115    * Associates the output element with a form element by specifying the form's ID. This allows the output
116    * to be placed outside the form element while still being part of the form.
117    *
118    * <p>
119    * The value should match the ID of a form element in the same document.
120    *
121    * @param value The ID of the form element to associate with this output. Can be <jk>null</jk> to unset the attribute.
122    * @return This object.
123    */
124   public Output form(String value) {
125      attr("form", value);
126      return this;
127   }
128
129   /**
130    * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fe-name">name</a> attribute.
131    *
132    * <p>
133    * Specifies the name of the output element. This name is used when the form is submitted and
134    * can be used to access the element via the form.elements API.
135    *
136    * <p>
137    * The name should be unique within the form and should not contain spaces or special characters.
138    *
139    * @param value The name of the output element for submission and API access. Can be <jk>null</jk> to unset the attribute.
140    * @return This object.
141    */
142   public Output name(String value) {
143      attr("name", value);
144      return this;
145   }
146
147}