    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}