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/tabular-data.html#the-th-element">&lt;th&gt;</a>
023 * element.
024 *
025 * <p>
026 * The th element represents a header cell in a table. It is used to contain header information
027 * for a column or row, providing context and meaning to the data cells (td) in the table. The th
028 * element supports various attributes for accessibility, spanning multiple columns or rows, and
029 * defining the relationship between header and data cells.
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 header cell</jc>
036 *    Th <jv>simple</jv> = <jsm>th</jsm>(<js>"Name"</js>);
037 *
038 *    <jc>// Header cell with scope</jc>
039 *    Th <jv>scoped</jv> = <jsm>th</jsm>(<js>"Age"</js>)
040 *       .scope(<js>"col"</js>);
041 *
042 *    <jc>// Header cell spanning multiple columns</jc>
043 *    Th <jv>colspan</jv> = <jsm>th</jsm>(<js>"Contact Information"</js>)
044 *       .colspan(2);
045 *
046 *    <jc>// Header cell with abbreviation</jc>
047 *    Th <jv>abbreviated</jv> = <jsm>th</jsm>(<js>"Quantity"</js>)
048 *       .abbr(<js>"Qty"</js>);
049 *
050 *    <jc>// Header cell with sorting</jc>
051 *    Th <jv>sorted</jv> = <jsm>th</jsm>(<js>"Price"</js>)
052 *       .sorted(<js>"asc"</js>);
053 *
054 *    <jc>// Header cell with styling</jc>
055 *    Th <jv>styled</jv> = <jsm>th</jsm>(<js>"Status"</js>)
056 *       .class_(<js>"header-cell"</js>);
057 *
058 *    <jc>// Header cell with complex content</jc>
059 *    Th <jv>complex</jv> = <jsm>th</jsm>(
060 *       .children(
061 *          new Strong().children("Total"),
062 *          " ",
063 *          new Small().children("(USD)")
064 *       );
065 * </p>
066 *
067 * <h5 class='section'>See Also:</h5><ul>
068 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanHtml5">juneau-bean-html5</a>
069 * </ul>
070 */
071@Marshalled(typeName = "th")
072public class Th extends HtmlElementMixed<Th> {
073
074   /**
075    * Creates an empty {@link Th} element.
076    */
077   public Th() {}
078
079   /**
080    * Creates a {@link Th} element with the specified child nodes.
081    *
082    * @param children The child nodes. Must not be <jk>null</jk>.
083    */
084   public Th(Object...children) {
085      children(children);
086   }
087
088   /**
089    * <a class="doclink" href="https://www.w3.org/TR/html5/tabular-data.html#attr-th-abbr">abbr</a> attribute.
090    *
091    * <p>
092    * Specifies an alternative, abbreviated label for the header cell. This is used by screen readers
093    * and other assistive technologies when referencing the cell in other contexts.
094    *
095    * <p>
096    * The abbreviation should be shorter than the full header text but still meaningful.
097    *
098    * @param value The abbreviated label for the header cell. Can be <jk>null</jk> to unset the attribute.
099    * @return This object.
100    */
101   public Th abbr(String value) {
102      attr("abbr", value);
103      return this;
104   }
105
106   /**
107    * <a class="doclink" href="https://www.w3.org/TR/html5/tabular-data.html#attr-tdth-colspan">colspan</a> attribute.
108    *
109    * <p>
110    * Number of columns that the cell is to span.
111    *
112    * @param value
113    *    The new value for this attribute.
114    *    Typically a {@link Number} or {@link String}.
115    *    Can be <jk>null</jk> to unset the attribute.
116    * @return This object.
117    */
118   public Th colspan(Object value) {
119      attr("colspan", value);
120      return this;
121   }
122
123   /**
124    * <a class="doclink" href="https://www.w3.org/TR/html5/tabular-data.html#attr-tdth-headers">headers</a> attribute.
125    *
126    * <p>
127    * Specifies the IDs of header cells that apply to this table cell. This creates a programmatic
128    * relationship between the cell and its headers for accessibility purposes.
129    *
130    * <p>
131    * Multiple IDs can be specified as a space-separated list.
132    *
133    * @param value The IDs of header cells that apply to this cell. Can be <jk>null</jk> to unset the attribute.
134    * @return This object.
135    */
136   public Th headers(String value) {
137      attr("headers", value);
138      return this;
139   }
140
141   /**
142    * <a class="doclink" href="https://www.w3.org/TR/html5/tabular-data.html#attr-tdth-rowspan">rowspan</a> attribute.
143    *
144    * <p>
145    * Number of rows that the cell is to span.
146    *
147    * @param value
148    *    The new value for this attribute.
149    *    Typically a {@link Number} or {@link String}.
150    *    Can be <jk>null</jk> to unset the attribute.
151    * @return This object.
152    */
153   public Th rowspan(Object value) {
154      attr("rowspan", value);
155      return this;
156   }
157
158   /**
159    * <a class="doclink" href="https://www.w3.org/TR/html5/tabular-data.html#attr-th-scope">scope</a> attribute.
160    *
161    * <p>
162    * Specifies which cells the header cell applies to. This helps define the relationship
163    * between header and data cells for accessibility.
164    *
165    * <p>
166    * Possible values:
167    * <ul>
168    *    <li><js>"row"</js> - Header applies to all cells in the same row</li>
169    *    <li><js>"col"</js> - Header applies to all cells in the same column</li>
170    *    <li><js>"rowgroup"</js> - Header applies to all cells in the same row group</li>
171    *    <li><js>"colgroup"</js> - Header applies to all cells in the same column group</li>
172    * </ul>
173    *
174    * @param value Which cells the header cell applies to. Can be <jk>null</jk> to unset the attribute.
175    * @return This object.
176    */
177   public Th scope(String value) {
178      attr("scope", value);
179      return this;
180   }
181
182   /**
183    * <a class="doclink" href="https://www.w3.org/TR/html5/tabular-data.html#attr-th-sorted">sorted</a> attribute.
184    *
185    * <p>
186    * Specifies the sort direction and ordinality of the column. This indicates how the table
187    * is currently sorted and which column is the primary sort key.
188    *
189    * <p>
190    * Common values:
191    * <ul>
192    *    <li><js>"asc"</js> - Column is sorted in ascending order</li>
193    *    <li><js>"desc"</js> - Column is sorted in descending order</li>
194    *    <li><js>"asc 1"</js> - Column is the primary sort key in ascending order</li>
195    *    <li><js>"desc 1"</js> - Column is the primary sort key in descending order</li>
196    * </ul>
197    *
198    * @param value The sort direction and ordinality of the column. Can be <jk>null</jk> to unset the attribute.
199    * @return This object.
200    */
201   public Th sorted(String value) {
202      attr("sorted", value);
203      return this;
204   }
205}