001 // Copyright 2004, 2005 The Apache Software Foundation
002 //
003 // Licensed under the Apache License, Version 2.0 (the "License");
004 // you may not use this file except in compliance with the License.
005 // You may obtain a copy of the License at
006 //
007 // http://www.apache.org/licenses/LICENSE-2.0
008 //
009 // Unless required by applicable law or agreed to in writing, software
010 // distributed under the License is distributed on an "AS IS" BASIS,
011 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012 // See the License for the specific language governing permissions and
013 // limitations under the License.
014
015 package org.apache.tapestry.components;
016
017 import org.apache.tapestry.IComponent;
018 import org.apache.tapestry.IMarkupWriter;
019 import org.apache.tapestry.IRequestCycle;
020 import org.apache.tapestry.engine.ILink;
021
022 /**
023 * A component that renders an HTML <a> element. It exposes some
024 * properties to the components it wraps. This is basically to facilitate the
025 * {@link org.apache.tapestry.html.Rollover} component.
026 *
027 * @author Howard Lewis Ship
028 */
029
030 public interface ILinkComponent extends IComponent
031 {
032
033 /**
034 * Returns the desired scheme (i.e., "http" or "https") for the link, or
035 * null to not output a specific scheme (in which case the URL will fall
036 * under the incoming request's scheme).
037 *
038 * @return The scheme portion of the url to be generated.
039 * @since 4.0
040 */
041
042 String getScheme();
043
044 /**
045 * Returns the desired port (i.e., "80" or "443") for the link, or null to
046 * not output a specific port (in which case the URL will fall under the
047 * incoming request's port).
048 *
049 * @return The http port to use.
050 * @since 4.1
051 */
052
053 Integer getPort();
054
055 /**
056 * Returns whether this service link component is enabled or disabled.
057 *
058 * @return True if disabled, false otherwise.
059 * @since 0.2.9
060 */
061
062 boolean isDisabled();
063
064 /**
065 * Returns the anchor defined for this link, or null for no anchor.
066 *
067 * @return The <code>#anchorid</code> portion of the url to be generated - if any.
068 * @since 3.0
069 */
070
071 String getAnchor();
072
073 /**
074 * Returns the name of the target window or frame for this link, or null if
075 * current window or frame is to be used.
076 *
077 * @return The <code>target="_this"</code> portion of the link to be generated - if any.
078 * @since 4.0
079 */
080 String getTarget();
081
082 /**
083 * Adds a new event handler. When the event occurs, the JavaScript function
084 * specified is executed. Multiple functions can be specified, in which case
085 * all of them are executed.
086 * <p>
087 * This was created for use by {@link org.apache.tapestry.html.Rollover} to
088 * set mouse over and mouse out handlers on the {@link ILinkComponent} that
089 * wraps it, but can be used for many other things as well.
090 *
091 * @param type
092 * The type of event to add.
093 * @param functionName
094 * The name of the client side javascript function to generate.
095 *
096 * @since 0.2.9
097 * @deprecated To be removed in Tapestry 4.1.4.
098 */
099
100 void addEventHandler(LinkEventType type, String functionName);
101
102 /**
103 * Invoked by the {@link org.apache.tapestry.link.ILinkRenderer} (if the
104 * link is not disabled) to provide a
105 * {@link org.apache.tapestry.engine.EngineServiceLink} that the renderer
106 * can convert into a URL.
107 *
108 * @param cycle
109 * The current request.
110 * @return A {@link ILink} instance representing the link information for this component.
111 */
112
113 ILink getLink(IRequestCycle cycle);
114
115 /**
116 * Invoked (by the {@link org.apache.tapestry.link.ILinkRenderer}) to make
117 * the link render any additional attributes. These are informal parameters,
118 * plus any attributes related to events. This is only invoked for
119 * non-disabled links.
120 *
121 * @param writer
122 * Markup writer to write content to.
123 * @param cycle
124 * The current request.
125 * @since 3.0
126 */
127
128 void renderAdditionalAttributes(IMarkupWriter writer, IRequestCycle cycle);
129 }