    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}