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/sections.html#the-article-element">&lt;article&gt;</a>
023 * element.
024 *
025 * <p>
026 * The article element represents a self-contained composition in a document, page, application, or site,
027 * which is intended to be independently distributable or reusable. It is used for content that could
028 * stand alone, such as blog posts, news articles, forum posts, or other independent pieces of content.
029 * Each article should have its own heading structure and can contain other semantic elements.
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 blog post article</jc>
036 *    Article <jv>blogPost</jv> = <jsm>article</jsm>(
037 *       <jsm>header</jsm>(
038 *          <jsm>h1</jsm>(<js>"How to Use HTML5 Semantic Elements"</js>),
039 *          <jsm>p</jsm>(<js>"Published on "</js>, <jsm>time</jsm>(<js>"2024-01-15"</js>, <js>"January 15, 2024"</js>))
040 *       ),
041 *       <jsm>p</jsm>(<js>"HTML5 introduced several semantic elements that help structure content..."</js>),
042 *       <jsm>footer</jsm>(
043 *          <jsm>p</jsm>(<js>"Author: John Doe"</js>),
044 *          <jsm>address</jsm>(<js>"Contact: john@example.com"</js>)
045 *       )
046 *    );
047 *
048 *    <jc>// News article</jc>
049 *    Article <jv>newsArticle</jv> = <jsm>article</jsm>(
050 *       <jsm>header</jsm>(
051 *          <jsm>h1</jsm>(<js>"Breaking: New Technology Released"</js>),
052 *          <jsm>p</jsm>(<js>"By Jane Smith, Technology Reporter"</js>)
053 *       ),
054 *       <jsm>p</jsm>(<js>"A revolutionary new technology was announced today..."</js>),
055 *       <jsm>section</jsm>(
056 *          <jsm>h2</jsm>(<js>"Technical Details"</js>),
057 *          <jsm>p</jsm>(<js>"The technology works by..."</js>)
058 *       )
059 *    );
060 *
061 *    <jc>// Forum post</jc>
062 *    Article <jv>forumPost</jv> = <jsm>article</jsm>(
063 *       <jsm>header</jsm>(
064 *          <jsm>h3</jsm>(<js>"Question about CSS Grid"</js>),
065 *          <jsm>p</jsm>(<js>"Posted by "</js>, <jsm>strong</jsm>(<js>"user123"</js>), <js>" on "</js>, <jsm>time</jsm>(<js>"2024-01-14"</js>, <js>"yesterday"</js>))
066 *       ),
067 *       <jsm>p</jsm>(<js>"I'm having trouble with CSS Grid layout..."</js>),
068 *       <jsm>footer</jsm>(
069 *          <jsm>p</jsm>(<js>"Tags: "</js>, <jsm>a</jsm>(<js>"/tag/css"</js>, <js>"CSS"</js>), <js>", "</js>, <jsm>a</jsm>(<js>"/tag/grid"</js>, <js>"Grid"</js>))
070 *       )
071 *    ).class_(<js>"forum-post"</js>);
072 *
073 *    <jc>// Product review</jc>
074 *    Article <jv>review</jv> = <jsm>article</jsm>(
075 *       <jsm>header</jsm>(
076 *          <jsm>h1</jsm>(<js>"Review: Amazing Widget Pro"</js>),
077 *          <jsm>p</jsm>(<js>"Rating: "</js>, <jsm>strong</jsm>(<js>"5/5 stars"</js>))
078 *       ),
079 *       <jsm>p</jsm>(<js>"After using the Amazing Widget Pro for a month..."</js>),
080 *       <jsm>section</jsm>(
081 *          <jsm>h2</jsm>(<js>"Pros"</js>),
082 *          <jsm>ul</jsm>(
083 *             <jsm>li</jsm>(<js>"Easy to use"</js>),
084 *             <jsm>li</jsm>(<js>"Great performance"</js>),
085 *             <jsm>li</jsm>(<js>"Excellent support"</js>)
086 *          )
087 *       )
088 *    );
089 *
090 *    <jc>// Article with multiple sections</jc>
091 *    Article <jv>multiSection</jv> = <jsm>article</jsm>(
092 *       <jsm>header</jsm>(<jsm>h1</jsm>(<js>"Complete Guide to Web Development"</js>)),
093 *       <jsm>section</jsm>(
094 *          <jsm>h2</jsm>(<js>"Introduction"</js>),
095 *          <jsm>p</jsm>(<js>"Web development encompasses many technologies..."</js>)
096 *       ),
097 *       <jsm>section</jsm>(
098 *          <jsm>h2</jsm>(<js>"Frontend Development"</js>),
099 *          <jsm>p</jsm>(<js>"Frontend development focuses on..."</js>)
100 *       ),
101 *       <jsm>section</jsm>(
102 *          <jsm>h2</jsm>(<js>"Backend Development"</js>),
103 *          <jsm>p</jsm>(<js>"Backend development handles..."</js>)
104 *       )
105 *    );
106 * </p>
107 *
108 * <p>
109 * The following convenience methods are provided for constructing instances of this bean:
110 * <ul class='javatree'>
111 *    <li class='jc'>{@link HtmlBuilder}
112 *    <ul class='javatree'>
113 *       <li class='jm'>{@link HtmlBuilder#article() article()}
114 *       <li class='jm'>{@link HtmlBuilder#article(Object...) article(Object...)}
115 *    </ul>
116 * </ul>
117 *
118 * <h2 class='section'>See Also:</h2><ul>
119 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanHtml5">juneau-bean-html5</a>
120 * </ul>
121 */
122@Marshalled(typeName = "article")
123public class Article extends HtmlElementMixed<Article> {
124
125   /**
126    * Creates an empty {@link Article} element.
127    */
128   public Article() {}
129
130   /**
131    * Creates an {@link Article} element with the specified child nodes.
132    *
133    * @param children The child nodes. Must not be <jk>null</jk>.
134    */
135   public Article(Object...children) {
136      children(children);
137   }
138
139   /**
140    * Adds a footer node to this element.
141    *
142    * @param children The children inside the footer node. Must not be <jk>null</jk>.
143    * @return This object.
144    */
145   public Article footer(Object...children) {
146      super.child(HtmlBuilder.footer(children));
147      return this;
148   }
149
150   /**
151    * Adds a header node to this element.
152    *
153    * @param children The children inside the header node. Must not be <jk>null</jk>.
154    * @return This object.
155    */
156   public Article header(Object...children) {
157      super.child(HtmlBuilder.header(children));
158      return this;
159   }
160
161   /**
162    * Adds a link node to this element.
163    *
164    * @param value The link node to add to this article. Can be <jk>null</jk> (a <jk>null</jk> entry is added to the children list).
165    * @return This object.
166    */
167   public Article link(Link value) {
168      super.child(value);
169      return this;
170   }
171
172   /**
173    * Adds a section node to this element.
174    *
175    * @param value The section node to add to this article. Can be <jk>null</jk> (a <jk>null</jk> entry is added to the children list).
176    * @return This object.
177    */
178   public Article section(Section value) {
179      super.child(value);
180      return this;
181   }
182
183}