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/text-level-semantics.html#the-data-element">&lt;data&gt;</a>
023 * element.
024 *
025 * <p>
026 * The data element represents its contents, along with a machine-readable form of those contents in
027 * the value attribute. It is used to provide both human-readable and machine-readable versions of
028 * the same data, making it easier for scripts and other automated systems to process the information
029 * while still displaying meaningful content to users. The value attribute should contain the
030 * machine-readable version of the data.
031 *
032 * <h5 class='section'>Examples:</h5>
033 * <p class='bcode w800'>
034 *    <jk>import static</jk> org.apache.juneau.bean.html5.HtmlBuilder.*;
035 *
036 *    <jc>// Simple data element</jc>
037 *    Data <jv>simple</jv> = <jsm>data</jsm>(<js>"12345"</js>, <js>"Product #12345"</js>);
038 *
039 *    <jc>// Data with styling</jc>
040 *    Data <jv>styled</jv> = <jsm>data</jsm>(<js>"USD"</js>, <js>"US Dollar"</js>)
041 *       .class_(<js>"currency"</js>);
042 *
043 *    <jc>// Data in a sentence</jc>
044 *    P <jv>sentence</jv> = <jsm>p</jsm>(
045 *       <js>"Price: "</js>,
046 *       <jsm>data</jsm>(<js>"29.99"</js>, <js>"$29.99"</js>),
047 *       <js>" per item"</js>
048 *    );
049 *
050 *    <jc>// Data with complex content</jc>
051 *    Data <jv>complex</jv> = <jsm>data</jsm>(<js>"2024-01-15"</js>,
052 *       <js>"January 15, 2024"</js>,
053 *       <jsm>span</jsm>().class_(<js>"date"</js>).children(<js>" (Monday)"</js>)
054 *    );
055 *
056 *    <jc>// Data with multiple attributes</jc>
057 *    Data <jv>multiple</jv> = <jsm>data</jsm>(<js>"SKU-12345"</js>, <js>"SKU: 12345"</js>)
058 *       .class_(<js>"product-sku"</js>)
059 *       .title(<js>"Product SKU"</js>);
060 *
061 *    <jc>// Data with ID</jc>
062 *    Data <jv>withId</jv> = <jsm>data</jsm>(<js>"user-123"</js>, <js>"User ID: 123"</js>)
063 *       .id(<js>"user-id"</js>)
064 *       .children(<js>"User ID: 123"</js>);
065 *
066 *    <jc>// Data with styling</jc>
067 *    Data <jv>styled2</jv> = <jsm>data</jsm>(<js>"active"</js>, <js>"Active"</js>)
068 *       .style(<js>"color: green; font-weight: bold;"</js>);
069 * </p>
070 *
071 * <p>
072 * The following convenience methods are provided for constructing instances of this bean:
073 * <ul class='javatree'>
074 *    <li class='jc'>{@link HtmlBuilder}
075 *    <ul class='javatree'>
076 *       <li class='jm'>{@link HtmlBuilder#data() data()}
077 *       <li class='jm'>{@link HtmlBuilder#data(String, Object) data(String, Object)}
078 *    </ul>
079 * </ul>
080 * </p>
081 *
082 * <h5 class='section'>See Also:</h5><ul>
083 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanHtml5">juneau-bean-html5</a>
084 * </ul>
085 */
086@Marshalled(typeName = "data")
087public class Data extends HtmlElementMixed<Data> {
088
089   /**
090    * Creates an empty {@link Data} element.
091    */
092   public Data() {}
093
094   /**
095    * Creates a {@link Data} element with the specified {@link Data#value(Object)} attribute and child node.
096    *
097    * @param value The {@link Data#value(Object)} attribute. Can be <jk>null</jk> to unset the attribute.
098    * @param child The child node. Can be <jk>null</jk> (a <jk>null</jk> entry is added to the children list).
099    */
100   public Data(String value, Object child) {
101      value(value).child(child);
102   }
103
104   /**
105    * <a class="doclink" href="https://www.w3.org/TR/html5/text-level-semantics.html#attr-data-value">value</a>
106    * attribute.
107    *
108    * <p>
109    * Machine-readable value.
110    *
111    * @param value
112    *    The new value for this attribute.
113    *    Typically a {@link Number} or {@link String}.
114    *    Can be <jk>null</jk> to unset the attribute.
115    * @return This object.
116    */
117   public Data value(Object value) {
118      attr("value", value);
119      return this;
120   }
121}