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-time-element">&lt;time&gt;</a>
023 * element.
024 *
025 * <p>
026 * The time element represents a specific point in time or a duration. It provides a machine-readable
027 * way to mark up dates and times in HTML, making it easier for search engines, screen readers, and
028 * other tools to understand and process temporal information. The element can contain human-readable
029 * text while providing a machine-readable datetime attribute.
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 date</jc>
036 *    Time <jv>date</jv> = <jsm>time</jsm>(<js>"January 15, 2024"</js>)
037 *       .datetime(<js>"2024-01-15"</js>);
038 *
039 *    <jc>// Date and time</jc>
040 *    Time <jv>datetime</jv> = <jsm>time</jsm>(<js>"2:30 PM on January 15, 2024"</js>)
041 *       .datetime(<js>"2024-01-15T14:30:00Z"</js>);
042 *
043 *    <jc>// Relative time</jc>
044 *    Time <jv>relative</jv> = <jsm>time</jsm>(<js>"yesterday"</js>)
045 *       .datetime(<js>"2024-01-15"</js>);
046 *
047 *    <jc>// Duration</jc>
048 *    Time <jv>duration</jv> = <jsm>time</jsm>(<js>"2 hours and 30 minutes"</js>)
049 *       .datetime(<js>"PT2H30M"</js>);
050 *
051 *    <jc>// Time with styling</jc>
052 *    Time <jv>styled</jv> = <jsm>time</jsm>(<js>"Event Date: January 15, 2024"</js>)
053 *       .datetime(<js>"2024-01-15"</js>)
054 *       .class_(<js>"event-date"</js>);
055 *
056 *    <jc>// Time with timezone</jc>
057 *    Time <jv>timezone</jv> = <jsm>time</jsm>(<js>"2:30 PM EST on January 15, 2024"</js>)
058 *       .datetime(<js>"2024-01-15T14:30:00-05:00"</js>);
059 * </p>
060 *
061 * <p>
062 * The following convenience methods are provided for constructing instances of this bean:
063 * <ul class='javatree'>
064 *    <li class='jc'>{@link HtmlBuilder}
065 *    <ul class='javatree'>
066 *       <li class='jm'>{@link HtmlBuilder#time() time()}
067 *       <li class='jm'>{@link HtmlBuilder#time(Object...) time(Object...)}
068 *    </ul>
069 * </ul>
070 * </p>
071 *
072 * <h5 class='section'>See Also:</h5><ul>
073 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanHtml5">juneau-bean-html5</a>
074 * </ul>
075 */
076@Marshalled(typeName = "time")
077public class Time extends HtmlElementMixed<Time> {
078
079   /**
080    * Creates an empty {@link Time} element.
081    */
082   public Time() {}
083
084   /**
085    * Creates a {@link Time} element with the specified {@link Time#children(Object[])} nodes.
086    *
087    * @param children The {@link Time#children(Object[])} nodes. Must not be <jk>null</jk>.
088    */
089   public Time(Object...children) {
090      children(children);
091   }
092
093   /**
094    * <a class="doclink" href="https://www.w3.org/TR/html5/text-level-semantics.html#attr-time-datetime">datetime</a>
095    * attribute.
096    *
097    * <p>
098    * Specifies the machine-readable value of the time element. This provides a standardized
099    * format for the date and time that can be processed by computers.
100    *
101    * <p>
102    * The value should be a valid date-time string in ISO 8601 format.
103    *
104    * @param value The machine-readable date and time value. Can be <jk>null</jk> to unset the attribute.
105    * @return This object.
106    */
107   public Time datetime(String value) {
108      attr("datetime", value);
109      return this;
110   }
111}