001/* Attribute containing information and methods for web elements, 002 * for example, HTML tags and content, as in 003 * <div> This is some HTML content </div> 004 005 Copyright (c) 2011-2018 The Regents of the University of California. 006 All rights reserved. 007 Permission is hereby granted, without written agreement and without 008 license or royalty fees, to use, copy, modify, and distribute this 009 software and its documentation for any purpose, provided that the above 010 copyright notice and the following two paragraphs appear in all copies 011 of this software. 012 013 IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY 014 FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES 015 ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF 016 THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF 017 SUCH DAMAGE. 018 019 THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES, 020 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 021 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE 022 PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF 023 CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, 024 ENHANCEMENTS, OR MODIFICATIONS. 025 026 PT_COPYRIGHT_VERSION_2 027 COPYRIGHTENDKEY 028 029 */ 030package ptolemy.vergil.basic.export.web; 031 032import ptolemy.kernel.util.IllegalActionException; 033import ptolemy.kernel.util.NameDuplicationException; 034import ptolemy.kernel.util.NamedObj; 035import ptolemy.kernel.util.StringAttribute; 036 037/////////////////////////////////////////////////////////////////// 038//// WebElement 039/** 040 * Attribute containing information and methods for web elements, 041 * for example, HTML tags and content, as in 042 * <div> This is some HTML content </div> 043 * 044 * The full name including the _elementName is used as WebElement's web id. 045 * In an HTML page, elements that have ids are required to have globally 046 * unique ids. The _webName field is used for the WebElement's web name. 047 * Elements can have non-unique web names - this is done for example for radio 048 * buttons on web forms. 049 * http://solidlystated.com/scripting/html-difference-between-id-and-name/ 050 * http://stackoverflow.com/questions/1363693/do-input-field-names-have-to-be-unique-across-forms 051 * 052 * @author Elizabeth Latronico 053 * @version $Id$ 054 * @since Ptolemy II 10.0 055 * @Pt.ProposedRating Red (ltrnc) 056 * @Pt.AcceptedRating Red (ltrnc) 057 */ 058 059// FIXME: How to make this non-persistent? Don't want to save these with the 060// model. 061public class WebElement extends StringAttribute { 062 063 /** Create an instance of this parameter. 064 * @param container The container. 065 * @param name The name. 066 * @exception IllegalActionException If the superclass throws it. 067 * @exception NameDuplicationException If the superclass throws it. 068 */ 069 public WebElement(NamedObj container, String name) 070 throws IllegalActionException, NameDuplicationException { 071 super(container, name); 072 073 setParent(""); 074 setWebName(""); 075 } 076 077 /////////////////////////////////////////////////////////////////// 078 //// public methods //// 079 080 /** Factory method for creating WebElements. Checks if there is an 081 * existing WebElement with the same id (Ptolemy name). If so, return it; 082 * if not create a new one. Sets persistent to false. Static so that any 083 * WebExportable may call it. 084 * 085 * @param container The container object for the WebElement 086 * @param id The Ptolemy name for the WebElement (WebElement uses this as a 087 * unique id) 088 * @param webName The web name of this WebElement 089 * @return The WebElement that was created (or that previously existed) 090 * with persistent set to false 091 * @exception IllegalActionException if the WebAttribute cannot be created 092 * (perhaps another Attribute exists with the requested name) 093 */ 094 public static WebElement createWebElement(NamedObj container, String id, 095 String webName) throws IllegalActionException { 096 WebElement webElement; 097 098 try { 099 if (id != null && container.getAttribute(id) == null) { 100 webElement = new WebElement(container, id); 101 webElement.setPersistent(false); 102 } 103 } catch (NameDuplicationException e) { 104 throw new IllegalActionException(container, 105 "Cannot create web content. Duplicate id (Ptolemy name) for" 106 + "WebElement: " + id); 107 } 108 109 webElement = (WebElement) container.getAttribute(id, WebElement.class); 110 if (webElement == null) { 111 throw new NullPointerException( 112 "Could not get the WebElement attribute \"" + id 113 + "\" from \"" + container.getFullName() + "\""); 114 } else { 115 webElement.setWebName(webName); 116 webElement.setPersistent(false); 117 webElement.setVisibility(NONE); 118 return webElement; 119 } 120 } 121 122 /** Return the name of the desired parent element, or the empty string if 123 * none. 124 * 125 * @return The name of the desired parent element, or the empty string if 126 * none. 127 * @see #setParent(String) 128 */ 129 public String getParent() { 130 return _parent; 131 } 132 133 /** Return the web name of this element; for example, "myElement" in 134 * <div name="myElement"/> in HTML. 135 * 136 * @return The web name of this element; for example, "myElement" in 137 * <div name="myElement"/> in HTML. 138 * @see #setWebName(String) 139 */ 140 public String getWebName() { 141 return _webName; 142 } 143 144 /** Set the name of the desired parent element. Can also be a special 145 * constant for tags that do not typically have names, like <head/> and 146 * <body/>. 147 * 148 * @param parent The name or special constant of the parent element. 149 * @see #getParent() 150 */ 151 public void setParent(String parent) { 152 _parent = parent; 153 } 154 155 /** Set the web name of this element; for example, "myElement" in 156 * <div name="myElement"/> in HTML. 157 * 158 * @param webName The web name of this element; for example, "myElement" in 159 * <div name="myElement"/> in HTML. 160 * @see #getWebName() 161 */ 162 public void setWebName(String webName) { 163 _webName = webName; 164 } 165 166 /////////////////////////////////////////////////////////////////// 167 //// public variables //// 168 169 /** A special constant indicating that the <body/> element should 170 * be the parent. 171 * The <head/> and <body/> tags of an HTML document do not typically 172 * have names. For example, almost no one writes <head name="head">, 173 * it's only <head/>. Therefore, the WebExporter will not be able to use 174 * the name to find the parent element. 175 */ 176 public static final String BODY = "body"; 177 178 /** A special constant indicating that the <head/> element should 179 * be the parent. 180 * The <head/> and <body/> tags of an HTML document do not typically 181 * have names. For example, almost no one writes <head name="head">, 182 * it's only <head/>. Therefore, the WebExporter will not be able to use 183 * the name to find the parent element. 184 */ 185 public static final String HEAD = "head"; 186 187 /** Special constants for backwards compatibility to Export to Web. 188 189 * Parameter specifying the position into which to export HTML text. 190 * The parameter offers the following possibilities: 191 * <ul> 192 * <li><b>end</b>: Put the text at the end of the HTML file. 193 * <li><b>head</b>: Put the text in the head section. 194 * <li><b>start</b>: Put the text at the start of the body section. 195 * <li><i>anything_else</i>: Put the text in a div of this name. 196 * </ul> 197 * The default is "start". 198 */ 199 200 /** Special constant indicating to put content in a div with the name 201 * "start" which occurs at the beginning of the HTML body. 202 */ 203 public static final String START = "start"; 204 205 /** Special constant indicating to put content in a div with the name 206 * "end" which occurs at the end of the HTML body. 207 */ 208 public static final String END = "end"; 209 210 /////////////////////////////////////////////////////////////////// 211 //// private variables //// 212 213 /** The name of the desired parent element of this element, if any. 214 * For example, if we have the element name "result" 215 * <div name="result"> </div> that we want as the parent: 216 * <div name="result"> <div name="thisElement"> </div> </div> 217 * Please see {@link ptolemy.vergil.basic.export.web.HTMLTextPosition} for some 218 * more examples. If there is no parent element, _position is set to 219 * the empty string. 220 */ 221 private String _parent; 222 223 /** The desired name of this element in the web file, for example, 224 * "myElement" in <div name="myElement"></div>. 225 */ 226 private String _webName; 227 228}