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-q-element">&lt;q&gt;</a>
023 * element.
024 *
025 * <p>
026 * The q element represents a short inline quotation. It is used for short quotes that are part
027 * of the surrounding text, as opposed to blockquote which is used for longer, standalone quotations.
028 * The cite attribute can be used to provide a link to the source of the quotation.
029 *
030 * <h2 class='section'>Examples:</h2>
031 * <p class='bcode w800'>
032 *    <jk>import static</jk> org.apache.juneau.bean.html5.HtmlBuilder.*;
033 *
034 *    <jc>// Simple inline quotation</jc>
035 *    Q <jv>q1</jv> = <jsm>q</jsm>(<js>"To be or not to be, that is the question."</js>);
036 *
037 *    <jc>// Quotation with citation</jc>
038 *    Q <jv>q2</jv> = <jsm>q</jsm>(<js>"The only way to do great work is to love what you do."</js>)
039 *       .cite(<js>"https://example.com/source"</js>);
040 *
041 *    <jc>// Quotation in a paragraph</jc>
042 *    P <jv>p1</jv> = <jsm>p</jsm>(
043 *       <js>"As Shakespeare once said, "</js>,
044 *       <jsm>q</jsm>(<js>"All the world's a stage"</js>),
045 *       <js>" and we are merely players."</js>
046 *    );
047 *
048 *    <jc>// Quotation with styling</jc>
049 *    Q <jv>q3</jv> = <jsm>q</jsm>(<js>"Innovation distinguishes between a leader and a follower."</js>)
050 *       .class_(<js>"highlighted-quote"</js>)
051 *       .cite(<js>"https://example.com/author"</js>);
052 * </p>
053 *
054 * <p>
055 * The following convenience methods are provided for constructing instances of this bean:
056 * <ul class='javatree'>
057 *    <li class='jc'>{@link HtmlBuilder}
058 *    <ul class='javatree'>
059 *       <li class='jm'>{@link HtmlBuilder#q() q()}
060 *       <li class='jm'>{@link HtmlBuilder#q(Object...) q(Object...)}
061 *    </ul>
062 * </ul>
063 *
064 * <h2 class='section'>See Also:</h2><ul>
065 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanHtml5">juneau-bean-html5</a>
066 * </ul>
067 */
068@Marshalled(typeName = "q")
069public class Q extends HtmlElementMixed<Q> {
070
071   /**
072    * Creates an empty {@link Q} element.
073    */
074   public Q() {}
075
076   /**
077    * Creates a {@link Q} element with the specified child nodes.
078    *
079    * @param children The child nodes. Must not be <jk>null</jk>.
080    */
081   public Q(Object...children) {
082      children(children);
083   }
084
085   /**
086    * <a class="doclink" href="https://www.w3.org/TR/html5/text-level-semantics.html#attr-q-cite">cite</a> attribute.
087    *
088    * <p>
089    * Specifies the URL of the source document or message from which the quotation was taken.
090    * This provides context and attribution for the quoted content.
091    *
092    * <p>
093    * The URL should point to the original source of the quoted material.
094    *
095    * @param value The URL of the source document for the quotation. Can be <jk>null</jk> to unset the attribute.
096    * @return This object.
097    */
098   public Q cite(String value) {
099      attr("cite", value);
100      return this;
101   }
102}