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/embedded-content-0.html#the-source-element">&lt;source&gt;</a>
025 * element.
026 *
027 * <p>
028 * The source element specifies multiple media resources for media elements like audio and video.
029 * It allows browsers to choose the most appropriate source based on format support, bandwidth,
030 * and other factors. The source element is used inside audio and video elements to provide
031 * fallback options for different media formats.
032 *
033 * <h5 class='section'>Examples:</h5>
034 * <p class='bcode w800'>
035 *    <jk>import static</jk> org.apache.juneau.bean.html5.HtmlBuilder.*;
036 *
037 *    <jc>// Video with multiple sources</jc>
038 *    Video <jv>video</jv> = <jsm>video</jsm>()
039 *       .controls(<jk>true</jk>)
040 *       .children(
041 *          <jsm>source</jsm>().src(<js>"movie.mp4"</js>).type(<js>"video/mp4"</js>),
042 *          <jsm>source</jsm>().src(<js>"movie.webm"</js>).type(<js>"video/webm"</js>),
043 *          <jsm>source</jsm>().src(<js>"movie.ogg"</js>).type(<js>"video/ogg"</js>)
044 *       );
045 *
046 *    <jc>// Audio with multiple sources</jc>
047 *    Audio <jv>audio</jv> = <jsm>audio</jsm>()
048 *       .controls(<jk>true</jk>)
049 *       .children(
050 *          <jsm>source</jsm>().src(<js>"sound.mp3"</js>).type(<js>"audio/mpeg"</js>),
051 *          <jsm>source</jsm>().src(<js>"sound.ogg"</js>).type(<js>"audio/ogg"</js>),
052 *          <jsm>source</jsm>().src(<js>"sound.wav"</js>).type(<js>"audio/wav"</js>)
053 *       );
054 *
055 *    <jc>// Picture with multiple sources</jc>
056 *    Picture <jv>picture</jv> = <jsm>picture</jsm>(
057 *       <jsm>source</jsm>().src(<js>"image.webp"</js>).type(<js>"image/webp"</js>),
058 *       <jsm>source</jsm>().src(<js>"image.jpg"</js>).type(<js>"image/jpeg"</js>)
059 *    );
060 *
061 *    <jc>// Source with media query</jc>
062 *    Source <jv>responsive</jv> = <jsm>source</jsm>()
063 *       .src(<js>"large-image.jpg"</js>)
064 *       .media(<js>"(min-width: 800px)"</js>)
065 *       .type(<js>"image/jpeg"</js>);
066 * </p>
067 *
068 * <p>
069 * The following convenience methods are provided for constructing instances of this bean:
070 * <ul class='javatree'>
071 *    <li class='jc'>{@link HtmlBuilder}
072 *    <ul class='javatree'>
073 *       <li class='jm'>{@link HtmlBuilder#source() source()}
074 *    </ul>
075 * </ul>
076 * </p>
077 *
078 * <h5 class='section'>See Also:</h5><ul>
079 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanHtml5">juneau-bean-html5</a>
080 * </ul>
081 */
082@Marshalled(typeName = "source")
083public class Source extends HtmlElementVoid<Source> {
084
085   /**
086    * Creates an empty {@link Source} element.
087    */
088   public Source() {}
089
090   /**
091    * Creates a {@link Source} element with the specified {@link Source#src(Object)} and {@link Source#type(String)}
092    * attributes.
093    *
094    * @param src The {@link Source#src(Object)} attribute. Can be <jk>null</jk>, in which case the attribute is stored with a <jk>null</jk> value (not removed).
095    * @param type The {@link Source#type(String)} attribute. Can be <jk>null</jk> to unset the attribute.
096    */
097   public Source(Object src, String type) {
098      src(src).type(type);
099   }
100
101   /**
102    * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-source-src">src</a> attribute.
103    *
104    * <p>
105    * Address of the resource.
106    *
107    * <p>
108    * The value can be of any of the following types: {@link URI}, {@link URL}, {@link String}.
109    * Strings must be valid URIs.
110    *
111    * <p>
112    * URIs defined by {@link UriResolver} can be used for values.
113    *
114    * @param value
115    *    The new value for this attribute.
116    *    Typically a {@link URL} or {@link String}.
117    *    Can be <jk>null</jk>, in which case the attribute is stored with a <jk>null</jk> value (not removed).
118    * @return This object.
119    */
120   public Source src(Object value) {
121      attrUri("src", value);
122      return this;
123   }
124
125   /**
126    * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-source-type">type</a> attribute.
127    *
128    * <p>
129    * Specifies the MIME type of the media resource. Helps browsers determine if they can play the media
130    * and which source to use when multiple sources are provided.
131    *
132    * <p>
133    * Common values:
134    * <ul>
135    *    <li><js>"video/mp4"</js> - MP4 video</li>
136    *    <li><js>"video/webm"</js> - WebM video</li>
137    *    <li><js>"audio/mp3"</js> - MP3 audio</li>
138    *    <li><js>"audio/ogg"</js> - OGG audio</li>
139    *    <li><js>"audio/wav"</js> - WAV audio</li>
140    * </ul>
141    *
142    * @param value The MIME type of the media resource. Can be <jk>null</jk> to unset the attribute.
143    * @return This object.
144    */
145   public Source type(String value) {
146      attr("type", value);
147      return this;
148   }
149}