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
015package org.apache.tapestry5.internal.structure;
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.internal.InternalComponentResources;
022import org.apache.tapestry5.internal.InternalComponentResourcesCommon;
023import org.apache.tapestry5.internal.services.Instantiator;
024import org.apache.tapestry5.ioc.Location;
025import org.apache.tapestry5.runtime.Component;
026import org.apache.tapestry5.runtime.ComponentEvent;
027import org.apache.tapestry5.runtime.RenderCommand;
028import org.apache.tapestry5.runtime.RenderQueue;
029import 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 */
035public 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}