Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.tapestry5.internal.structure
Class ComponentPageElementImpl

    java.lang.Object
      org.apache.tapestry5.ioc.BaseLocatable
          org.apache.tapestry5.internal.structure.ComponentPageElementImpl

All Implemented Interfaces:
  ComponentResourcesCommon, InternalComponentResourcesCommon, BodyPageElement, ComponentPageElement, Locatable, RenderCommand

    public class ComponentPageElementImpl

extends BaseLocatable
implements ComponentPageElement

Implements `RenderCommand` and represents a component within an overall page. Much of a component page element's behavior is delegated to user code, via a `Component` instance.

Once instantiated, a ComponentPageElement should be registered as a lifecycle listener. This could be done inside the constructors, but that tends to complicate unit tests, so its done by `PageElementFactoryImpl`. There's still a bit of refactoring in this class (and its many inner classes) that can improve overall efficiency.

Modified for Tapestry 5.2 to adjust for the no-pooling approach (shared instances with externalized mutable state).

Constructor Summary
`ComponentPageElementImpl(Page page, Instantiator instantiator, ComponentPageElementResources elementResources, Request request, SymbolSource symbolSource)` Constructor for the root component of a page.

Method Summary
`void` | `addBlock(java.lang.String blockId, Block block)` Used during the contruction of a page to add a non-anonymous Block to the component.
`void` | `addMixin(java.lang.String mixinId, Instantiator instantiator, java.lang.String... order)` Adds a mixin.
`void` | `addToBody(RenderCommand element)` Used during the construction of the page.
`void` | `addToTemplate(RenderCommand element)` Used during the construction of a page.
`void` | `bindMixinParameter(java.lang.String mixinId, java.lang.String parameterName, Binding binding)`
`void` | `bindParameter(java.lang.String parameterName, Binding binding)` Used during construction of the page to identify the binding for a particular parameter.
`Link` | `createActionLink(java.lang.String eventType, boolean forForm, java.lang.Object... context)` Creates a component event request link as a callback for this component.
`Link` | `createEventLink(java.lang.String eventType, java.lang.Object... context)` Creates a component event request link as a callback for this component.
`Link` | `createFormEventLink(java.lang.String eventType, java.lang.Object... context)` Creates a component event request link as a callback for this component.
`Link` | `createPageLink(java.lang.Class pageClass, boolean override, java.lang.Object... context)` Creates a page render request link to render a specific page.
`Link` | `createPageLink(java.lang.String pageName, boolean override, java.lang.Object... context)` Creates a page render request link to render a specific page.
`protected RenderPhaseEvent` | `createRenderEvent(RenderQueue queue)`
`boolean` | `dispatchEvent(ComponentEvent event)` Asks each mixin and component to `Component.dispatchComponentEvent(ComponentEvent)`, returning true if any handler was found.
`void` | `enqueueBeforeRenderBody(RenderQueue queue)` Invoked when the component should render its body.
`Block` | `findBlock(java.lang.String id)` As with `ComponentResourcesCommon.getBlock(String)`, but returns null if the block is not found.
`Binding` | `getBinding(java.lang.String parameterName)` Returns the binding for the given parameter name, or null.
`Block` | `getBlock(java.lang.String id)` Returns a block from the component's template, referenced by its id.
`Block` | `getBody()` Returns the body of this component as a (possibly empty) block.
`java.lang.String` | `getCompleteId()` Returns a string consisting of the logical name of the containing page, and the `nested id` of this component, separated by a colon.
`Component` | `getComponent()` Returns the core component associated with this page element (as opposed to any mixins attached to the component).
`InternalComponentResources` | `getComponentResources()` Returns the resources associated with the core component.
`ComponentPageElement` | `getContainerElement()` Containing component (or null for the root component of a page).
`Page` | `getContainingPage()` Returns the page which contains this component.
`java.lang.String` | `getElementName(java.lang.String defaultElementName)` Returns the name of element that represents the component in its template, or the provided default element name if the element was a component type (in the Tapestry namespace).
`ComponentPageElement` | `getEmbeddedElement(java.lang.String embeddedId)` Retrieves a component page element by its id.
`org.slf4j.Logger` | `getEventLogger()` Returns a logger used to for logging event dispatch and event method invocation.
`java.lang.String` | `getId()` Returns the simple (or local) id of the component.
`java.util.Map<java.lang.String,Binding>` | `getInformalParameterBindings()` Constructs a map linking informal parameters to the corresponding bindings.
`java.util.Locale` | `getLocale()` Returns the locale for the page containing this component.
`org.slf4j.Logger` | `getLogger()` Returns the log instance associated with the component (which is based on the component or mixin's class name).
`Component` | `getMixinByClassName(java.lang.String mixinClassName)` Returns the mixin instance for the fully qualfied mixin class name.
`ComponentResources` | `getMixinResources(java.lang.String mixinId)` Returns the `ComponentResources` for a mixin attached to this component element.
`java.lang.String` | `getNestedId()` Return a string consisting the concatinated ids of all containing components, separated by periods.
`java.lang.String` | `getPageName()` Returns the logical name of the page containing this component.
`ComponentResourceSelector` | `getResourceSelector()` Returns the selector used when constructing the component and its containing page.
`boolean` | `hasBody()` Returns true if the element has a body and false otherwise.
`boolean` | `isLoaded()` Returns true if the component has finished loading.
`boolean` | `isRendering()` Returns true if the component is currently rendering, false otherwise.
`ComponentPageElement` | `newChild(java.lang.String id, java.lang.String nestedId, java.lang.String completeId, java.lang.String elementName, Instantiator instantiator, Location location)` Creates a new child component of the invoked component.
`void` | `render(MarkupWriter writer, RenderQueue queue)` Pushes the SetupRender phase state onto the queue.
`java.lang.String` | `toString()`
`boolean` | `triggerContextEvent(java.lang.String eventType, EventContext context, ComponentEventCallback callback)` Triggers a component event.
`boolean` | `triggerEvent(java.lang.String eventType, java.lang.Object[] contextValues, ComponentEventCallback callback)` A convienience for invoking `ComponentResourcesCommon.triggerContextEvent(String, EventContext , ComponentEventCallback)`.

Methods inherited from class org.apache.tapestry5.ioc.BaseLocatable
`getLocation`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Methods inherited from interface org.apache.tapestry5.ioc.Locatable
`getLocation`

Constructor Detail

### ComponentPageElementImpl

    public ComponentPageElementImpl(Page page,
                                    Instantiator instantiator,
                                    ComponentPageElementResources elementResources,
                                    Request request,
                                    SymbolSource symbolSource)

  Constructor for the root component of a page.

Method Detail

### newChild

    public ComponentPageElement newChild(java.lang.String id,
                                         java.lang.String nestedId,
                                         java.lang.String completeId,
                                         java.lang.String elementName,
                                         Instantiator instantiator,
                                         Location location)

  Description copied from interface: `ComponentPageElement`
  Creates a new child component of the invoked component. The new element will be added as an embedded element of its container.

  Specified by:
    `newChild` in interface `ComponentPageElement`
  Parameters:
    `id` - simple id of the new component
    `elementName` - name of the component's element in its container's template
    `instantiator` - used to create a component instance, and access the component's model
    `location` - location of the element within its container's template @return the new component

### addMixin

    public void addMixin(java.lang.String mixinId,
                         Instantiator instantiator,
                         java.lang.String... order)

  Description copied from interface: `ComponentPageElement`
  Adds a mixin.

  Specified by:
    `addMixin` in interface `ComponentPageElement`
  Parameters:
    `mixinId` - a unique id for the mixin, the last term of the mixin's class name
    `instantiator` - used to instantiate an instance of the mixin
    `order` - Ordering strings used to determine the order of mixin execution.

### bindMixinParameter

    public void bindMixinParameter(java.lang.String mixinId,
                                   java.lang.String parameterName,
                                   Binding binding)

  Specified by:
    `bindMixinParameter` in interface `ComponentPageElement`
  Parameters:
    `mixinId` - id of previously added mixin
    `parameterName` - simple (unqualified) name of parameter
    `binding` - binding for parameter

### getBinding

    public Binding getBinding(java.lang.String parameterName)

  Description copied from interface: `InternalComponentResourcesCommon`
  Returns the binding for the given parameter name, or null.

  Specified by:
    `getBinding` in interface `InternalComponentResourcesCommon`
  Parameters:
    `parameterName` - name of component parameter
  Returns:
    binding if bound, or null

### bindParameter

    public void bindParameter(java.lang.String parameterName,
                              Binding binding)

  Description copied from interface: `InternalComponentResourcesCommon`
  Used during construction of the page to identify the binding for a particular parameter.

  Specified by:
    `bindParameter` in interface `InternalComponentResourcesCommon`

### addToBody

    public void addToBody(RenderCommand element)

  Description copied from interface: `BodyPageElement`
  Used during the construction of the page. Adds a page element as part of the body of the component. The body of a component is defined as the portion of the container's template directly enclosed by component's start and end elements.

  Specified by:
    `addToBody` in interface `BodyPageElement`

### addToTemplate

    public void addToTemplate(RenderCommand element)

  Description copied from interface: `ComponentPageElement`
  Used during the construction of a page. Adds a page element as part of the template for this page element. A page element will eventually render by sequentially rendering these elements. A page elements template is really just the outermost portions of the component's template ... where a template contains elements that are all components, those components will receive portions of the template as their body.

  Specified by:
    `addToTemplate` in interface `ComponentPageElement`

### enqueueBeforeRenderBody

    public void enqueueBeforeRenderBody(RenderQueue queue)

  Description copied from interface: `ComponentPageElement`
  Invoked when the component should render its body.

  Specified by:
    `enqueueBeforeRenderBody` in interface `ComponentPageElement`

### getCompleteId

    public java.lang.String getCompleteId()

  Description copied from interface: `ComponentResourcesCommon`
  Returns a string consisting of the logical name of the containing page, and the `nested id` of this component, separated by a colon. I.e., "MyPage:foo.bar.baz". For a page, returns just the page's name.

  This value is often used to obtain an equivalent component instance in a later request.

  Specified by:
    `getCompleteId` in interface `ComponentResourcesCommon`
  See Also:
    `ComponentSource.getComponent(String)`

### getComponent

    public Component getComponent()

  Description copied from interface: `ComponentPageElement`
  Returns the core component associated with this page element (as opposed to any mixins attached to the component).

  Specified by:
    `getComponent` in interface `ComponentPageElement`

### getComponentResources

    public InternalComponentResources getComponentResources()

  Description copied from interface: `ComponentPageElement`
  Returns the resources associated with the core component.

  Specified by:
    `getComponentResources` in interface `ComponentPageElement`

### getContainerElement

    public ComponentPageElement getContainerElement()

  Description copied from interface: `ComponentPageElement`
  Containing component (or null for the root component of a page).

  Specified by:
    `getContainerElement` in interface `ComponentPageElement`

### getContainingPage

    public Page getContainingPage()

  Description copied from interface: `ComponentPageElement`
  Returns the page which contains this component.

  Specified by:
    `getContainingPage` in interface `ComponentPageElement`

### getEmbeddedElement

    public ComponentPageElement getEmbeddedElement(java.lang.String embeddedId)

  Description copied from interface: `ComponentPageElement`
  Retrieves a component page element by its id. The search is caseless.

  Specified by:
    `getEmbeddedElement` in interface `ComponentPageElement`
  Parameters:
    `embeddedId` - used to locate the element
  Returns:
    the page element

### getId

    public java.lang.String getId()

  Description copied from interface: `ComponentResourcesCommon`
  Returns the simple (or local) id of the component. The id will be unique within the component's immediate container. For a page's root component, the value null is returned.

  Specified by:
    `getId` in interface `ComponentResourcesCommon`

### getLogger

    public org.slf4j.Logger getLogger()

  Description copied from interface: `ComponentResourcesCommon`
  Returns the log instance associated with the component (which is based on the component or mixin's class name).

  Specified by:
    `getLogger` in interface `ComponentResourcesCommon`
  See Also:
    `ComponentModel.getLogger()`

### getMixinByClassName

    public Component getMixinByClassName(java.lang.String mixinClassName)

  Description copied from interface: `InternalComponentResourcesCommon`
  Returns the mixin instance for the fully qualfied mixin class name.

  Specified by:
    `getMixinByClassName` in interface `InternalComponentResourcesCommon`
  Parameters:
    `mixinClassName` - fully qualified class name
  Returns:
    IllegalArgumentException if no such mixin is associated with the core component

### getMixinResources

    public ComponentResources getMixinResources(java.lang.String mixinId)

  Description copied from interface: `ComponentPageElement`
  Returns the `ComponentResources` for a mixin attached to this component element. Mixin ids are the simple names of the mixin class.

  Specified by:
    `getMixinResources` in interface `ComponentPageElement`
  Parameters:
    `mixinId` - the mixin id (case insensitive)
  Returns:
    the resources for the component

### getNestedId

    public java.lang.String getNestedId()

  Description copied from interface: `ComponentResourcesCommon`
  Return a string consisting the concatinated ids of all containing components, separated by periods. In addition, nested ids are always all lower case. I.e., "foo.bar.baz". Returns null for the root component of a page.

  Specified by:
    `getNestedId` in interface `ComponentResourcesCommon`

### dispatchEvent

    public boolean dispatchEvent(ComponentEvent event)

  Description copied from interface: `ComponentPageElement`
  Asks each mixin and component to `Component.dispatchComponentEvent(ComponentEvent)`, returning true if any handler was found.

  Specified by:
    `dispatchEvent` in interface `ComponentPageElement`
  Parameters:
    `event` - to be handled
  Returns:
    true if a handler was found

### isLoaded

    public boolean isLoaded()

  Description copied from interface: `InternalComponentResourcesCommon`
  Returns true if the component has finished loading. Initially, this value will be false.

  Specified by:
    `isLoaded` in interface `InternalComponentResourcesCommon`
  See Also:
    `PageLifecycleListener.containingPageDidLoad()`

### isRendering

    public boolean isRendering()

  Description copied from interface: `ComponentResourcesCommon`
  Returns true if the component is currently rendering, false otherwise. This is most often used to determine if parameter values should be cached.

  Specified by:
    `isRendering` in interface `ComponentResourcesCommon`

### render

    public final void render(MarkupWriter writer,
                             RenderQueue queue)

  Pushes the SetupRender phase state onto the queue.

  Specified by:
    `render` in interface `RenderCommand`

### toString

    public java.lang.String toString()

  Overrides:
    `toString` in class `java.lang.Object`

### triggerEvent

    public boolean triggerEvent(java.lang.String eventType,
                                java.lang.Object[] contextValues,
                                ComponentEventCallback callback)

  Description copied from interface: `ComponentResourcesCommon`
  A convienience for invoking `ComponentResourcesCommon.triggerContextEvent(String, EventContext , ComponentEventCallback)`. Wraps the context values into an `EventContext`.

  Specified by:
    `triggerEvent` in interface `ComponentResourcesCommon`
  Parameters:
    `eventType` - event type (as determined from the request, or otherwise by design)
    `contextValues` - Values that may be provided to the event handler method as method parameters, or null if no context values are available
    `callback` - the handler to be informed of the result, or null if the event is a notification that does not support return values from event handler methods (the value true is allowed even if the handler is null).
  Returns:
    true if any event handler was invoked (even if no event handler method returns a non-null value)
  See Also:
    `OnEventWorker`, `OnEvent`

### triggerContextEvent

    public boolean triggerContextEvent(java.lang.String eventType,
                                       EventContext context,
                                       ComponentEventCallback callback)

  Description copied from interface: `ComponentResourcesCommon`
  Triggers a component event. A search for an event handling method will occur, first in the component, then its container, and so on. When a matching event handler method is located, it is invoked. If the method returns a value, the value is passed to the callback (if callback is null, then it is an error for a method to return a non-null value).

  Resolution of event type to event handler methods is case insensitive.

  Specified by:
    `triggerContextEvent` in interface `ComponentResourcesCommon`
  Parameters:
    `eventType` - event type (as determined from the request, or otherwise by design)
    `context` - the context (as extracted from the request, or provided by the triggering component); these values may be provided to event handler methods via their parameters (may not be null)
    `callback` - the handler to be informed of the result, or null if the event is a notification that does not support return values from event handler methods (the value true is allowed even if the handler is null).
  Returns:
    true if any event handler was invoked (even if no event handler method returns a non-null value)
  See Also:
    `OnEventWorker`, `OnEvent`

### getLocale

    public java.util.Locale getLocale()

  Description copied from interface: `ComponentResourcesCommon`
  Returns the locale for the page containing this component.

  Specified by:
    `getLocale` in interface `ComponentResourcesCommon`
  See Also:
    `ComponentResourcesCommon.getResourceSelector()`

### getElementName

    public java.lang.String getElementName(java.lang.String defaultElementName)

  Description copied from interface: `ComponentResourcesCommon`
  Returns the name of element that represents the component in its template, or the provided default element name if the element was a component type (in the Tapestry namespace).

  Specified by:
    `getElementName` in interface `ComponentResourcesCommon`
  Parameters:
    `defaultElementName` - element name to return if the element name is not known (may be null)
  Returns:
    the element name

### getBlock

    public Block getBlock(java.lang.String id)

  Description copied from interface: `ComponentResourcesCommon`
  Returns a block from the component's template, referenced by its id.

  Specified by:
    `getBlock` in interface `ComponentResourcesCommon`
  Parameters:
    `id` - the id of the block (case insensitive)
  Returns:
    the identified Block
  See Also:
    `ComponentResourcesCommon.findBlock(String)`

### findBlock

    public Block findBlock(java.lang.String id)

  Description copied from interface: `ComponentResourcesCommon`
  As with `ComponentResourcesCommon.getBlock(String)`, but returns null if the block is not found.

  Specified by:
    `findBlock` in interface `ComponentResourcesCommon`
  Parameters:
    `id` - the id of the block (case insensitive)
  Returns:
    the block, or null

### addBlock

    public void addBlock(java.lang.String blockId,
                         Block block)

  Description copied from interface: `ComponentPageElement`
  Used during the contruction of a page to add a non-anonymous Block to the component.

  Specified by:
    `addBlock` in interface `ComponentPageElement`
  See Also:
    `ComponentResourcesCommon.getBlock(String)`

### getPageName

    public java.lang.String getPageName()

  Description copied from interface: `ComponentResourcesCommon`
  Returns the logical name of the page containing this component. This is the short name (it often appears in URLs)

  Specified by:
    `getPageName` in interface `ComponentResourcesCommon`
  Returns:
    the logical name of the page which contains this component

### hasBody

    public boolean hasBody()

  Description copied from interface: `ComponentResourcesCommon`
  Returns true if the element has a body and false otherwise. Only components may have a body; pages and mixins will return false.

  Specified by:
    `hasBody` in interface `ComponentResourcesCommon`

### getBody

    public Block getBody()

  Description copied from interface: `ComponentResourcesCommon`
  Returns the body of this component as a (possibly empty) block. When invoked on a mixin, returns the containing component's body.

  Specified by:
    `getBody` in interface `ComponentResourcesCommon`

### getInformalParameterBindings

    public java.util.Map<java.lang.String,Binding> getInformalParameterBindings()

  Description copied from interface: `InternalComponentResourcesCommon`
  Constructs a map linking informal parameters to the corresponding bindings.

  Specified by:
    `getInformalParameterBindings` in interface `InternalComponentResourcesCommon`
  Returns:
    map, possible empty

### getEventLogger

    public org.slf4j.Logger getEventLogger()

  Description copied from interface: `ComponentPageElement`
  Returns a logger used to for logging event dispatch and event method invocation.

  Specified by:
    `getEventLogger` in interface `ComponentPageElement`

### createEventLink

    public Link createEventLink(java.lang.String eventType,
                                java.lang.Object... context)

  Description copied from interface: `ComponentResourcesCommon`
  Creates a component event request link as a callback for this component. The event type and context (as well as the page name and nested component id) will be encoded into a URL. A request for the URL will ComponentResourcesCommon.triggerEvent(String, Object[], org.apache.tapestry5.ComponentEventCallback) trigger} the named event on the component.

  Specified by:
    `createEventLink` in interface `ComponentResourcesCommon`
  Parameters:
    `eventType` - the type of event to be triggered. Event types should be Java identifiers (contain only letters, numbers and the underscore).
    `context` - additional objects to be encoded into the path portion of the link; each is converted to a string and URI encoded
  Returns:
    link object for the callback

### createActionLink

    public Link createActionLink(java.lang.String eventType,
                                 boolean forForm,
                                 java.lang.Object... context)

  Description copied from interface: `ComponentResourcesCommon`
  Creates a component event request link as a callback for this component. The event type and context (as well as the page name and nested component id) will be encoded into a URL. A request for the URL will ComponentResourcesCommon.triggerEvent(String, Object[], org.apache.tapestry5.ComponentEventCallback) trigger} the named event on the component.

  Specified by:
    `createActionLink` in interface `ComponentResourcesCommon`
  Parameters:
    `eventType` - the type of event to be triggered. Event types should be Java identifiers (contain only letters, numbers and the underscore).
    `forForm` - if true, the link will be used as the eventType for an HTML form submission, which may affect what information is encoded into the link
    `context` - additional objects to be encoded into the path portion of the link; each is converted to a string and URI encoded
  Returns:
    link object for the callback

### createFormEventLink

    public Link createFormEventLink(java.lang.String eventType,
                                    java.lang.Object... context)

  Description copied from interface: `ComponentResourcesCommon`
  Creates a component event request link as a callback for this component. The event type and context (as well as the page name and nested component id) will be encoded into a URL. A request for the URL will ComponentResourcesCommon.triggerEvent(String, Object[], org.apache.tapestry5.ComponentEventCallback) trigger} the named event on the component. This is only used for form submission events, as extra data may be encoded in the form as hidden fields.

  Specified by:
    `createFormEventLink` in interface `ComponentResourcesCommon`
  Parameters:
    `eventType` - the type of event to be triggered. Event types should be Java identifiers (contain only letters, numbers and the underscore).
    `context` - additional objects to be encoded into the path portion of the link; each is converted to a string and URI encoded
  Returns:
    link object for the callback

### createPageLink

    public Link createPageLink(java.lang.String pageName,
                               boolean override,
                               java.lang.Object... context)

  Description copied from interface: `ComponentResourcesCommon`
  Creates a page render request link to render a specific page.

  Specified by:
    `createPageLink` in interface `ComponentResourcesCommon`
  Parameters:
    `pageName` - the logical name of the page to link to
    `override` - if true, the context is used even if empty (normally, the target page is allowed to passivate, providing a context, when the provided context is empty)
    `context` - the activation context for the page. If omitted, the activation context is obtained from the target page
  Returns:
    link for a render request to the targetted page

### createPageLink

    public Link createPageLink(java.lang.Class pageClass,
                               boolean override,
                               java.lang.Object... context)

  Description copied from interface: `ComponentResourcesCommon`
  Creates a page render request link to render a specific page. Using a page class, rather than a page name, is more refactoring safe (in the even the page is renamed or moved).

  Specified by:
    `createPageLink` in interface `ComponentResourcesCommon`
  Parameters:
    `pageClass` - identifies the page to link to
    `override` - if true, the context is used even if empty (normally, the target page is allowed to passivate, providing a context, when the provided context is empty)
    `context` - the activation context for the page. If omitted, the activation context is obtained from the target page
  Returns:
    link for a render request to the targetted page

### createRenderEvent

    protected RenderPhaseEvent createRenderEvent(RenderQueue queue)

### getResourceSelector

    public ComponentResourceSelector getResourceSelector()

  Description copied from interface: `ComponentResourcesCommon`
  Returns the selector used when constructing the component and its containing page.

  Specified by:
    `getResourceSelector` in interface `ComponentResourcesCommon`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2003-2012 The Apache Software Foundation.