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