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 * <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 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 *
071 * <h2 class='section'>See Also:</h2><ul>
072 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanHtml5">juneau-bean-html5</a>
073 * </ul>
074 */
075@Marshalled(typeName = "time")
076public class Time extends HtmlElementMixed<Time> {
077
078   /**
079    * Creates an empty {@link Time} element.
080    */
081   public Time() {}
082
083   /**
084    * Creates a {@link Time} element with the specified {@link Time#children(Object[])} nodes.
085    *
086    * @param children The {@link Time#children(Object[])} nodes. Must not be <jk>null</jk>.
087    */
088   public Time(Object...children) {
089      children(children);
090   }
091
092   /**
093    * <a class="doclink" href="https://www.w3.org/TR/html5/text-level-semantics.html#attr-time-datetime">datetime</a>
094    * attribute.
095    *
096    * <p>
097    * Specifies the machine-readable value of the time element. This provides a standardized
098    * format for the date and time that can be processed by computers.
099    *
100    * <p>
101    * The value should be a valid date-time string in ISO 8601 format.
102    *
103    * @param value The machine-readable date and time value. Can be <jk>null</jk> to unset the attribute.
104    * @return This object.
105    */
106   public Time datetime(String value) {
107      attr("datetime", value);
108      return this;
109   }
110}