maint-5-2/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/FormInjector.java

// Copyright 2008, 2009, 2010 The Apache Software Foundation
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package org.apache.tapestry5.corelib.components;

import java.io.IOException;

import org.apache.tapestry5.*;
import org.apache.tapestry5.annotations.Environmental;
import org.apache.tapestry5.annotations.Events;
import org.apache.tapestry5.annotations.Parameter;
import org.apache.tapestry5.annotations.RequestParameter;
import org.apache.tapestry5.annotations.SupportsInformalParameters;
import org.apache.tapestry5.corelib.data.InsertPosition;
import org.apache.tapestry5.corelib.internal.ComponentActionSink;
import org.apache.tapestry5.corelib.internal.HiddenFieldPositioner;
import org.apache.tapestry5.corelib.internal.InternalFormSupport;
import org.apache.tapestry5.dom.Element;
import org.apache.tapestry5.internal.services.PageRenderQueue;
import org.apache.tapestry5.internal.services.RequestConstants;
import org.apache.tapestry5.ioc.annotations.Inject;
import org.apache.tapestry5.ioc.util.IdAllocator;
import org.apache.tapestry5.json.JSONObject;
import org.apache.tapestry5.services.ClientBehaviorSupport;
import org.apache.tapestry5.services.ClientDataEncoder;
import org.apache.tapestry5.services.ComponentSource;
import org.apache.tapestry5.services.Environment;
import org.apache.tapestry5.services.FormSupport;
import org.apache.tapestry5.services.Heartbeat;
import org.apache.tapestry5.services.HiddenFieldLocationRules;
import org.apache.tapestry5.services.PartialMarkupRenderer;
import org.apache.tapestry5.services.PartialMarkupRendererFilter;
import org.apache.tapestry5.services.javascript.JavaScriptSupport;
import org.slf4j.Logger;

/**
 * A way to add new content to an existing Form. The FormInjector emulates its tag from the template (or uses a
 * <div>). When triggered, new content is obtained from the application and is injected before or after the
 * element.
 * <p/>
 * On the client side, a new function, trigger(), is added to the element. Invoking this client-side function will
 * trigger the FormInjector; a request is sent to the server, new content is generated, and the new content is placed
 * before or after (per configuration) the existing FormInjector element.
 */
@SupportsInformalParameters
@Events(EventConstants.ACTION)
public class FormInjector implements ClientElement
{
    public static final String INJECT_EVENT = "inject";

    /**
     * @deprecated Use {@link RequestConstants#FORM_CLIENTID_PARAMETER} instead
     */
    public static final String FORM_CLIENTID_PARAMETER = RequestConstants.FORM_CLIENTID_PARAMETER;

    /**
     * @deprecated Use {@link RequestConstants#FORM_COMPONENTID_PARAMETER} instead
     */
    public static final String FORM_COMPONENTID_PARAMETER = RequestConstants.FORM_COMPONENTID_PARAMETER;

    /**
     * The context for the link (optional parameter). This list of values will be converted into strings and included in
     * the URI. The strings will be coerced back to whatever their values are and made available to event handler
     * methods.
     */
    @Parameter
    private Object[] context;

    @Parameter(defaultPrefix = BindingConstants.LITERAL, value = "above")
    private InsertPosition position;

    /**
     * Name of a function on the client-side Tapestry.ElementEffect object that is invoked to make added content
     * visible. Leaving as null uses the default function, "highlight".
     */
    @Parameter(defaultPrefix = BindingConstants.LITERAL)
    private String show;

    /**
     * The element name to render, which is normally the element name used to represent the FormInjector component in
     * the template, or "div".
     */
    @Parameter(defaultPrefix = BindingConstants.LITERAL)
    private String element;

    @Environmental
    private JavaScriptSupport javascriptSupport;

    @Environmental
    private FormSupport formSupport;

    @Environmental
    private ClientBehaviorSupport clientBehaviorSupport;

    @SuppressWarnings("unchecked")
    @Environmental
    private TrackableComponentEventCallback eventCallback;

    @Inject
    private PageRenderQueue pageRenderQueue;

    private String clientId;

    @Inject
    private ComponentResources resources;

    private Element clientElement;

    String defaultElement()
    {
        return resources.getElementName("div");
    }

    void beginRender(MarkupWriter writer)
    {
        clientId = javascriptSupport.allocateClientId(resources);

        clientElement = writer.element(element, "id", clientId);

        resources.renderInformalParameters(writer);

        // Now work on the JavaScript side of things.

        Link link = resources.createEventLink(INJECT_EVENT, context);

        link.addParameter(RequestConstants.FORM_CLIENTID_PARAMETER, formSupport.getClientId());
        link.addParameter(RequestConstants.FORM_COMPONENTID_PARAMETER, formSupport.getFormComponentId());

        clientBehaviorSupport.addFormInjector(clientId, link, position, show);
    }

    void afterRender(MarkupWriter writer)
    {
        writer.end();

        // Add the class name to the rendered client element. This allows nested elements to locate
        // the containing FormInjector element.

        clientElement.addClassName("t-forminjector");
    }

    /**
     * Returns the unique client-side id of the rendered element.
     */
    public String getClientId()
    {
        return clientId;
    }

    /**
     * Invoked via an Ajax request. Triggers an action event and captures the return value. The return value from the
     * event notification is what will ultimately render (typically, its a Block).
     */
    void onInject(EventContext context) throws IOException
    {
        resources.triggerContextEvent(EventConstants.ACTION, context, eventCallback);

        if (!eventCallback.isAborted())
            return;

        // Before rendering, allocate a unique element id and record it into the JSON reply.

        PartialMarkupRendererFilter filter = new PartialMarkupRendererFilter()
        {
            public void renderMarkup(MarkupWriter writer, JSONObject reply, PartialMarkupRenderer renderer)
            {
                clientId = javascriptSupport.allocateClientId(resources);

                reply.put("elementId", clientId);

                renderer.renderMarkup(writer, reply);
            }
        };

        pageRenderQueue.addPartialMarkupRendererFilter(filter);
    }
}