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/embedded-content-0.html#the-param-element">&lt;param&gt;</a>
023 * element.
024 *
025 * <p>
026 * The param element defines parameters for an object element. It provides configuration data
027 * to the embedded content, such as Flash applications or other plugins. The name attribute
028 * specifies the parameter name, and the value attribute provides the parameter value.
029 *
030 * <h5 class='section'>Examples:</h5>
031 * <p class='bcode w800'>
032 *    <jk>import static</jk> org.apache.juneau.bean.html5.HtmlBuilder.*;
033 *
034 *    <jc>// Simple parameter</jc>
035 *    Param <jv>param1</jv> = <jsm>param</jsm>()
036 *       .name(<js>"autoplay"</js>)
037 *       .value(<js>"true"</js>);
038 *
039 *    <jc>// Parameter with constructor</jc>
040 *    Param <jv>param2</jv> = <jk>new</jk> Param(<js>"quality"</js>, <js>"high"</js>);
041 *
042 *    <jc>// Parameters in an object</jc>
043 *    Object_ <jv>object1</jv> = <jsm>object_</jsm>()
044 *       .data(<js>"video.swf"</js>)
045 *       .type(<js>"application/x-shockwave-flash"</js>)
046 *       .children(
047 *          <jk>new</jk> Param(<js>"autoplay"</js>, <js>"false"</js>),
048 *          <jk>new</jk> Param(<js>"loop"</js>, <js>"true"</js>),
049 *          <jk>new</jk> Param(<js>"quality"</js>, <js>"high"</js>)
050 *       );
051 *
052 *    <jc>// Parameter with special characters</jc>
053 *    Param <jv>param3</jv> = <jsm>param</jsm>()
054 *       .name(<js>"config"</js>)
055 *       .value(<js>"width=800&amp;height=600&amp;theme=dark"</js>);
056 * </p>
057 *
058 * <p>
059 * The following convenience methods are provided for constructing instances of this bean:
060 * <ul class='javatree'>
061 *    <li class='jc'>{@link HtmlBuilder}
062 *    <ul class='javatree'>
063 *       <li class='jm'>{@link HtmlBuilder#param() param()}
064 *    </ul>
065 * </ul>
066 * </p>
067 *
068 * <h5 class='section'>See Also:</h5><ul>
069 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanHtml5">juneau-bean-html5</a>
070 * </ul>
071 */
072@Marshalled(typeName = "param")
073public class Param extends HtmlElementVoid<Param> {
074
075   /**
076    * Creates an empty {@link Param} element.
077    */
078   public Param() {}
079
080   /**
081    * Creates a {@link Param} element with the specified {@link Param#name(String)} and {@link Param#value(Object)}
082    * attributes.
083    *
084    * @param name The {@link Param#name(String)} attribute. Can be <jk>null</jk> to unset the attribute.
085    * @param value The {@link Param#value(Object)} attribute. Can be <jk>null</jk> to unset the attribute.
086    */
087   public Param(String name, Object value) {
088      name(name).value(value);
089   }
090
091   /**
092    * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-param-name">name</a> attribute.
093    *
094    * <p>
095    * Specifies the name of the parameter. This name is used by the parent object element
096    * to identify the parameter and its associated value.
097    *
098    * <p>
099    * The name should be meaningful and correspond to the expected parameter name
100    * for the embedded content.
101    *
102    * @param value The name of the parameter. Can be <jk>null</jk> to unset the attribute.
103    * @return This object.
104    */
105   public Param name(String value) {
106      attr("name", value);
107      return this;
108   }
109
110   /**
111    * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-param-value">value</a>
112    * attribute.
113    *
114    * <p>
115    * Value of parameter.
116    *
117    * @param value
118    *    The new value for this attribute.
119    *    Typically a {@link Number} or {@link String}.
120    *    Can be <jk>null</jk> to unset the attribute.
121    * @return This object.
122    */
123   public Param value(Object value) {
124      attr("value", value);
125      return this;
126   }
127}