001: // Copyright 2006, 2007 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:
015: package org.apache.tapestry.internal.structure;
016:
017: import org.apache.tapestry.Block;
018: import org.apache.tapestry.ComponentResources;
019: import org.apache.tapestry.ComponentResourcesCommon;
020: import org.apache.tapestry.internal.InternalComponentResources;
021: import org.apache.tapestry.internal.InternalComponentResourcesCommon;
022: import org.apache.tapestry.internal.services.Instantiator;
023: import org.apache.tapestry.model.ParameterModel;
024: import org.apache.tapestry.runtime.Component;
025: import org.apache.tapestry.runtime.ComponentEvent;
026: import org.apache.tapestry.runtime.RenderQueue;
027: import org.apache.tapestry.services.PersistentFieldManager;
028:
029: /**
030: * Extended version of {@link org.apache.tapestry.internal.structure.PageElement} for elements that
031: * are, in fact, components (rather than just static markup).
032: */
033: public interface ComponentPageElement extends ComponentResourcesCommon,
034: InternalComponentResourcesCommon, PageElement, BodyPageElement {
035: /**
036: * Returns the core component associated with this page element (as opposed to any mixins
037: * attached to the component).
038: */
039: Component getComponent();
040:
041: /** Returns the resources associated with the core component. */
042: InternalComponentResources getComponentResources();
043:
044: /** Returns the page which contains this component. */
045: Page getContainingPage();
046:
047: /**
048: * Containing component (or null for the root component of a page).
049: */
050: ComponentPageElement getContainerElement();
051:
052: /**
053: * Used during the construction of a page. Adds a page element as part of the template for this
054: * page element. A page element will eventually render by sequentially rendering these elements.
055: * A page elements template is really just the outermost portions of the component's template
056: * ... where a template contains elements that are all components, those components will receive
057: * portions of the template as their body.
058: */
059: void addToTemplate(PageElement element);
060:
061: /**
062: * Used during the contruction of a page to add a non-anonymous Block to the component.
063: *
064: * @see ComponentResourcesCommon#getBlock(String)
065: */
066: void addBlock(String blockId, Block block);
067:
068: /**
069: * Adds a component to its container. The embedded component's id must be unique within the
070: * container (after the id is converted to lower case).
071: */
072: void addEmbeddedElement(ComponentPageElement child);
073:
074: /**
075: * Adds a mixin.
076: *
077: * @param instantiator
078: * used to instantiate an instance of the mixin
079: */
080: void addMixin(Instantiator instantiator);
081:
082: /**
083: * Retrieves a component page element by its id. The search is caseless.
084: *
085: * @param id
086: * used to locate the element
087: * @return the page element
088: * @throws IllegalArgumentException
089: * if no component exists with the given id
090: */
091: ComponentPageElement getEmbeddedElement(String id);
092:
093: /** Invoked when the component should render its body. */
094: void enqueueBeforeRenderBody(RenderQueue queue);
095:
096: /**
097: * Asks each mixin and component to {@link Component#handleComponentEvent(ComponentEvent)},
098: * returning true if any handler was found.
099: *
100: * @param event
101: * to be handled
102: * @return true if a handler was found
103: */
104: boolean handleEvent(ComponentEvent event);
105:
106: /**
107: * Searches the component (and its mixins) for a formal parameter matching the given name. If
108: * found, the {@link ParameterModel#getDefaultBindingPrefix() default binding prefix} is
109: * returned. Otherwise the parameter is an informal parameter, and null is returned.
110: *
111: * @param parameterName
112: * the name of the parameter, possibly qualified with the mixin class name
113: * @return the default binding prefix, or null
114: */
115: String getDefaultBindingPrefix(String parameterName);
116:
117: /**
118: * Posts a change to a persistent field. If the component is still loading, then this change is
119: * ignored. Otherwise, it is propogated, via the
120: * {@link Page#persistFieldChange(ComponentResources, String, Object) page} to the
121: * {@link PersistentFieldManager#postChange(String, ComponentResources, String, Object) PersistentFieldManager}.
122: */
123: void persistFieldChange(ComponentResources resources,
124: String fieldName, Object newValue);
125: }
|