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 * <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 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 *
067 * <h2 class='section'>See Also:</h2><ul>
068 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanHtml5">juneau-bean-html5</a>
069 * </ul>
070 */
071@Marshalled(typeName = "param")
072public class Param extends HtmlElementVoid<Param> {
073
074   /**
075    * Creates an empty {@link Param} element.
076    */
077   public Param() {}
078
079   /**
080    * Creates a {@link Param} element with the specified {@link Param#name(String)} and {@link Param#value(Object)}
081    * attributes.
082    *
083    * @param name The {@link Param#name(String)} attribute. Can be <jk>null</jk> to unset the attribute.
084    * @param value The {@link Param#value(Object)} attribute. Can be <jk>null</jk> to unset the attribute.
085    */
086   public Param(String name, Object value) {
087      name(name).value(value);
088   }
089
090   /**
091    * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-param-name">name</a> attribute.
092    *
093    * <p>
094    * Specifies the name of the parameter. This name is used by the parent object element
095    * to identify the parameter and its associated value.
096    *
097    * <p>
098    * The name should be meaningful and correspond to the expected parameter name
099    * for the embedded content.
100    *
101    * @param value The name of the parameter. Can be <jk>null</jk> to unset the attribute.
102    * @return This object.
103    */
104   public Param name(String value) {
105      attr("name", value);
106      return this;
107   }
108
109   /**
110    * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-param-value">value</a>
111    * attribute.
112    *
113    * <p>
114    * Value of parameter.
115    *
116    * @param value
117    *    The new value for this attribute.
118    *    Typically a {@link Number} or {@link String}.
119    *    Can be <jk>null</jk> to unset the attribute.
120    * @return This object.
121    */
122   public Param value(Object value) {
123      attr("value", value);
124      return this;
125   }
126}