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 * <h5 class='section'>Examples:</h5>
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 * </p>
069 *
070 * <h5 class='section'>See Also:</h5><ul>
071 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanHtml5">juneau-bean-html5</a>
072 * </ul>
073 */
074@Marshalled(typeName = "output")
075public class Output extends HtmlElementMixed<Output> {
076
077   /**
078    * Creates an empty {@link Output} element.
079    */
080   public Output() {}
081
082   /**
083    * Creates an {@link Output} element with the specified {@link Output#name(String)} attribute.
084    *
085    * @param name The {@link Output#name(String)} attribute. Can be <jk>null</jk> to unset the attribute.
086    */
087   public Output(String name) {
088      name(name);
089   }
090
091   /**
092    * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-output-for">for</a> attribute.
093    *
094    * <p>
095    * Specifies the IDs of form controls from which the output value was calculated.
096    * This creates a programmatic relationship between the output and its source controls.
097    *
098    * <p>
099    * Multiple IDs can be specified as a space-separated list.
100    *
101    * @param value The IDs of the form controls that contribute to this output. Can be <jk>null</jk> to unset the attribute.
102    * @return This object.
103    */
104   @SuppressWarnings({
105      "java:S100" // Method name uses underscore suffix to avoid Java keyword conflict
106   })
107   public Output for_(String value) {
108      attr("for", value);
109      return this;
110   }
111
112   /**
113    * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fae-form">form</a> attribute.
114    *
115    * <p>
116    * Associates the output element with a form element by specifying the form's ID. This allows the output
117    * to be placed outside the form element while still being part of the form.
118    *
119    * <p>
120    * The value should match the ID of a form element in the same document.
121    *
122    * @param value The ID of the form element to associate with this output. Can be <jk>null</jk> to unset the attribute.
123    * @return This object.
124    */
125   public Output form(String value) {
126      attr("form", value);
127      return this;
128   }
129
130   /**
131    * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fe-name">name</a> attribute.
132    *
133    * <p>
134    * Specifies the name of the output element. This name is used when the form is submitted and
135    * can be used to access the element via the form.elements API.
136    *
137    * <p>
138    * The name should be unique within the form and should not contain spaces or special characters.
139    *
140    * @param value The name of the output element for submission and API access. Can be <jk>null</jk> to unset the attribute.
141    * @return This object.
142    */
143   public Output name(String value) {
144      attr("name", value);
145      return this;
146   }
147
148}