001 // Copyright 2006, 2007, 2008, 2009, 2011 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.tapestry5.internal.structure;
016
017 import org.apache.tapestry5.Binding;
018 import org.apache.tapestry5.Block;
019 import org.apache.tapestry5.ComponentResources;
020 import org.apache.tapestry5.ComponentResourcesCommon;
021 import org.apache.tapestry5.internal.InternalComponentResources;
022 import org.apache.tapestry5.internal.InternalComponentResourcesCommon;
023 import org.apache.tapestry5.internal.services.Instantiator;
024 import org.apache.tapestry5.ioc.Location;
025 import org.apache.tapestry5.runtime.Component;
026 import org.apache.tapestry5.runtime.ComponentEvent;
027 import org.apache.tapestry5.runtime.RenderCommand;
028 import org.apache.tapestry5.runtime.RenderQueue;
029 import org.slf4j.Logger;
030
031 /**
032 * Defines an element of a page that is a component elements that are, in fact, components (rather than just static
033 * markup).
034 */
035 public interface ComponentPageElement extends ComponentResourcesCommon, InternalComponentResourcesCommon, RenderCommand, BodyPageElement
036 {
037 /**
038 * Returns the core component associated with this page element (as opposed to any mixins attached to the
039 * component).
040 */
041 Component getComponent();
042
043 /**
044 * Returns the resources associated with the core component.
045 */
046 InternalComponentResources getComponentResources();
047
048 /**
049 * Returns the page which contains this component.
050 */
051 Page getContainingPage();
052
053 /**
054 * Containing component (or null for the root component of a page).
055 */
056 ComponentPageElement getContainerElement();
057
058 /**
059 * Used during the construction of a page. Adds a page element as part of the template for this page element. A page
060 * element will eventually render by sequentially rendering these elements. A page elements template is really just
061 * the outermost portions of the component's template ... where a template contains elements that are all
062 * components, those components will receive portions of the template as their body.
063 */
064 void addToTemplate(RenderCommand element);
065
066 /**
067 * Used during the contruction of a page to add a non-anonymous Block to the component.
068 *
069 * @see ComponentResourcesCommon#getBlock(String)
070 */
071 void addBlock(String blockId, Block block);
072
073 /**
074 * Adds a mixin.
075 *
076 * @param mixinId a unique id for the mixin, the last term of the mixin's class name
077 * @param instantiator used to instantiate an instance of the mixin
078 * @param order Ordering strings used to determine the order of mixin execution.
079 */
080 void addMixin(String mixinId, Instantiator instantiator, String... order);
081
082 /**
083 * @param mixinId id of previously added mixin
084 * @param parameterName simple (unqualified) name of parameter
085 * @param binding binding for parameter
086 * @since 5.1.0.0
087 */
088 void bindMixinParameter(String mixinId, String parameterName, Binding binding);
089
090 /**
091 * Retrieves a component page element by its id. The search is caseless.
092 *
093 * @param id used to locate the element
094 * @return the page element
095 * @throws IllegalArgumentException if no component exists with the given id
096 */
097 ComponentPageElement getEmbeddedElement(String id);
098
099 /**
100 * Returns the {@link org.apache.tapestry5.ComponentResources} for a mixin attached to this component element. Mixin
101 * ids are the simple names of the mixin class.
102 *
103 * @param mixinId the mixin id (case insensitive)
104 * @return the resources for the component
105 * @throws IllegalArgumentException if no mixin with the given id exists
106 */
107 ComponentResources getMixinResources(String mixinId);
108
109 /**
110 * Invoked when the component should render its body.
111 */
112 void enqueueBeforeRenderBody(RenderQueue queue);
113
114 /**
115 * Asks each mixin and component to {@link Component#dispatchComponentEvent(ComponentEvent)}, returning true if any
116 * handler was found.
117 *
118 * @param event to be handled
119 * @return true if a handler was found
120 */
121 boolean dispatchEvent(ComponentEvent event);
122
123 /**
124 * Creates a new child component of the invoked component. The new element will be added as an embedded element of
125 * its container.
126 *
127 * @param id simple id of the new component
128 * @param nestedId
129 * @param completeId
130 * @param elementName name of the component's element in its container's template
131 * @param instantiator used to create a component instance, and access the component's model
132 * @param location location of the element within its container's template @return the new component
133 */
134 ComponentPageElement newChild(String id, String nestedId, String completeId, String elementName,
135 Instantiator instantiator,
136 Location location);
137
138 /**
139 * Returns a logger used to for logging event dispatch and event method invocation.
140 */
141 Logger getEventLogger();
142 }