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 java.net.*;
020
021import org.apache.juneau.marshall.*;
022
023/**
024 * DTO for an HTML <a class="doclink" href="https://www.w3.org/TR/html5/document-metadata.html#the-base-element">&lt;base&gt;</a>
025 * element.
026 *
027 * <p>
028 * The base element specifies the base URL for all relative URLs in a document. It also specifies
029 * the default target for all links and forms in the document. Only one base element is allowed
030 * per document and it must be placed in the head section.
031 *
032 * <h2 class='section'>Examples:</h2>
033 * <p class='bcode w800'>
034 *    <jc>// Set base URL for all relative links</jc>
035 *    Base <jv>base1</jv> = <jsm>base</jsm>().href(<js>"https://example.com/docs/"</js>);
036 *
037 *    <jc>// Set default target for all links</jc>
038 *    Base <jv>base2</jv> = <jsm>base</jsm>().target(<js>"_blank"</js>);
039 *
040 *    <jc>// Set both base URL and default target</jc>
041 *    Base <jv>base3</jv> = <jsm>base</jsm>().href(<js>"https://example.com/"</js>).target(<js>"_self"</js>);
042 * </p>
043 *
044 * <p>
045 * The following convenience methods are provided for constructing instances of this bean:
046 * <ul class='javatree'>
047 *    <li class='jc'>{@link HtmlBuilder}
048 *    <ul class='javatree'>
049 *       <li class='jm'>{@link HtmlBuilder#base() base()}
050 *    </ul>
051 * </ul>
052 *
053 * <h2 class='section'>See Also:</h2><ul>
054 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanHtml5">juneau-bean-html5</a>
055 * </ul>
056 */
057@Marshalled(typeName = "base")
058public class Base extends HtmlElementVoid<Base> {
059
060   /**
061    * Creates an empty {@link Base} element.
062    */
063   public Base() {}
064
065   /**
066    * Creates a {@link Base} element with the specified {@link Base#href(Object)} attribute.
067    *
068    * @param value The {@link Base#href(Object)} attribute. Can be <jk>null</jk>, in which case the attribute is stored with a <jk>null</jk> value (not removed).
069    */
070   public Base(Object value) {
071      href(value);
072   }
073
074   /**
075    * <a class="doclink" href="https://www.w3.org/TR/html5/document-metadata.html#attr-base-href">href</a> attribute.
076    *
077    * <p>
078    * Document base URL.
079    *
080    * <p>
081    * The value can be of any of the following types: {@link URI}, {@link URL}, {@link String}.
082    * Strings must be valid URIs.
083    *
084    * <p>
085    * URIs defined by {@link UriResolver} can be used for values.
086    *
087    * @param value
088    *    The new value for this attribute.
089    *    Typically a {@link URL} or {@link String}.
090    *    Can be <jk>null</jk>, in which case the attribute is stored with a <jk>null</jk> value (not removed).
091    * @return This object.
092    */
093   public Base href(Object value) {
094      attrUri("href", value);
095      return this;
096   }
097
098   /**
099    * <a class="doclink" href="https://www.w3.org/TR/html5/document-metadata.html#attr-base-target">target</a>
100    * attribute.
101    *
102    * <p>
103    * Specifies the default target for all links and forms in the document.
104    *
105    * <p>
106    * Common values:
107    * <ul>
108    *    <li><js>"_blank"</js> - Open in a new window/tab</li>
109    *    <li><js>"_self"</js> - Open in the same frame (default)</li>
110    *    <li><js>"_parent"</js> - Open in the parent frame</li>
111    *    <li><js>"_top"</js> - Open in the full body of the window</li>
112    *    <li><js>"framename"</js> - Open in a named frame</li>
113    * </ul>
114    *
115    * @param value The default target for links and forms. Can be <jk>null</jk> to unset the attribute.
116    * @return This object.
117    */
118   public Base target(String value) {
119      attr("target", value);
120      return this;
121   }
122
123}