001// Licensed under the Apache License, Version 2.0 (the "License");
002// you may not use this file except in compliance with the License.
003// You may obtain a copy of the License at
004//
005//     http://www.apache.org/licenses/LICENSE-2.0
006//
007// Unless required by applicable law or agreed to in writing, software
008// distributed under the License is distributed on an "AS IS" BASIS,
009// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
010// See the License for the specific language governing permissions and
011// limitations under the License.
012
013package org.apache.tapestry5.internal.structure;
014
015import java.util.Set;
016
017import org.apache.tapestry5.Binding;
018import org.apache.tapestry5.Block;
019import org.apache.tapestry5.ComponentResources;
020import org.apache.tapestry5.ComponentResourcesCommon;
021import org.apache.tapestry5.commons.Location;
022import org.apache.tapestry5.internal.InternalComponentResources;
023import org.apache.tapestry5.internal.InternalComponentResourcesCommon;
024import org.apache.tapestry5.internal.services.Instantiator;
025import org.apache.tapestry5.ioc.annotations.IncompatibleChange;
026import org.apache.tapestry5.runtime.Component;
027import org.apache.tapestry5.runtime.ComponentEvent;
028import org.apache.tapestry5.runtime.RenderCommand;
029import org.apache.tapestry5.runtime.RenderQueue;
030import org.slf4j.Logger;
031
032/**
033 * Defines an element of a {@link org.apache.tapestry5.internal.structure.Page} that is a full {@link org.apache.tapestry5.runtime.Component},
034 * including the possibility of its own template and mixins. This is distinct from other {@linkplain org.apache.tapestry5.runtime.RenderCommand renderable}
035 * elements of the page, which represent fixed or dynamic text, or markup element that may have dynamic attribute values.
036 */
037public interface ComponentPageElement extends ComponentResourcesCommon, InternalComponentResourcesCommon, RenderCommand, BodyPageElement
038{
039    /**
040     * Returns the core component associated with this page element (as opposed to any mixins attached to the
041     * component).
042     */
043    Component getComponent();
044
045    /**
046     * Returns the resources associated with the core component.
047     */
048    InternalComponentResources getComponentResources();
049
050    /**
051     * Returns the page which contains this component.
052     */
053    Page getContainingPage();
054
055    /**
056     * Containing component (or null for the root component of a page).
057     */
058    ComponentPageElement getContainerElement();
059
060    /**
061     * Used during the construction of a page. Adds a page element as part of the template for this page element. A page
062     * element will eventually render by sequentially rendering these elements. A page elements template is really just
063     * the outermost portions of the component's template ... where a template contains elements that are all
064     * components, those components will receive portions of the template as their body.
065     */
066    void addToTemplate(RenderCommand element);
067
068    /**
069     * Used during the contruction of a page to add a non-anonymous Block to the component.
070     *
071     * @see ComponentResourcesCommon#getBlock(String)
072     */
073    void addBlock(String blockId, Block block);
074
075    /**
076     * Adds a mixin.
077     *
078     * @param mixinId
079     *         a unique id for the mixin, the last term of the mixin's class name
080     * @param instantiator
081     *         used to instantiate an instance of the mixin
082     * @param order
083     *         Ordering strings used to determine the order of mixin execution.
084     */
085    void addMixin(String mixinId, Instantiator instantiator, String... order);
086
087    /**
088     * @param mixinId
089     *         id of previously added mixin
090     * @param parameterName
091     *         simple (unqualified) name of parameter
092     * @param binding
093     *         binding for parameter
094     * @since 5.1.0.0
095     */
096    void bindMixinParameter(String mixinId, String parameterName, Binding binding);
097
098    /**
099     * Retrieves a component page element by its id. The search is caseless.
100     *
101     * @param id
102     *         used to locate the element
103     * @return the page element
104     * @throws IllegalArgumentException
105     *         if no component exists with the given id
106     */
107    ComponentPageElement getEmbeddedElement(String id);
108    
109    /**
110     * Returns the ids of all embedded elements defined within the component.
111     * @since 5.8.3
112     */
113    @IncompatibleChange(release = "5.8.3", details = "Added method")
114    Set<String> getEmbeddedElementIds();
115
116    /**
117     * Returns the {@link org.apache.tapestry5.ComponentResources} for a mixin attached to this component element. Mixin
118     * ids are the simple names of the mixin class.
119     *
120     * @param mixinId
121     *         the mixin id (case insensitive)
122     * @return the resources for the component
123     * @throws IllegalArgumentException
124     *         if no mixin with the given id exists
125     */
126    ComponentResources getMixinResources(String mixinId);
127
128    /**
129     * Invoked when the component should render its body.
130     */
131    void enqueueBeforeRenderBody(RenderQueue queue);
132
133    /**
134     * Asks each mixin and component to {@link Component#dispatchComponentEvent(ComponentEvent)}, returning true if any
135     * handler was found.
136     *
137     * @param event
138     *         to be handled
139     * @return true if a handler was found
140     */
141    boolean dispatchEvent(ComponentEvent event);
142
143    /**
144     * Creates a new child component of the invoked component.  The new element will be added as an embedded element of
145     * its container.
146     *
147     * @param id
148     *         simple id of the new component
149     * @param nestedId
150     * @param completeId
151     * @param elementName
152     *         name of the component's element in its container's template
153     * @param instantiator
154     *         used to create a component instance, and access the component's model
155     * @param location
156     *         location of the element within its container's template @return the new component
157     */
158    ComponentPageElement newChild(String id, String nestedId, String completeId, String elementName,
159                                  Instantiator instantiator,
160                                  Location location);
161
162    /**
163     * Returns a logger used to for logging event dispatch and event method invocation.
164     */
165    Logger getEventLogger();
166}