001/* 
002    Licensed to the Apache Software Foundation (ASF) under one
003    or more contributor license agreements.  See the NOTICE file
004    distributed with this work for additional information
005    regarding copyright ownership.  The ASF licenses this file
006    to you under the Apache License, Version 2.0 (the
007    "License"); you may not use this file except in compliance
008    with the License.  You may obtain a copy of the License at
009
010       http://www.apache.org/licenses/LICENSE-2.0
011
012    Unless required by applicable law or agreed to in writing,
013    software distributed under the License is distributed on an
014    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015    KIND, either express or implied.  See the License for the
016    specific language governing permissions and limitations
017    under the License.  
018 */
019package org.apache.wiki.forms;
020
021import java.util.HashMap;
022import java.util.Map;
023
024import org.apache.wiki.WikiContext;
025import org.apache.wiki.api.exceptions.PluginException;
026import org.apache.wiki.api.plugin.WikiPlugin;
027
028/**
029 * FormSet is a companion WikiPlugin for Form. 
030 * 
031 * <p>The mandatory 'form' parameter specifies which form the variable
032 * applies to.  Any other parameters are put directly into a FormInfo
033 * object that will be available to a Form plugin called 'form'
034 * (presumably invoked later on the same WikiPage).
035 * 
036 * <p>If the name of a FormSet parameter is the same as the name of
037 * a Form plugin input element later on the same page, the Form will
038 * consider the given value the default for the form field. (However,
039 * the handler for the Form is free to use the value as it wishes, and
040 * even override it.)
041 *
042 * <p>If the name of a parameter is not present in Form input fields,
043 * the parameter is presumably meant for sending initial information
044 * to the Form handler. If this is the case, you may want to specify the
045 * <i>populate=''</i> in the Form <i>open</i> element, otherwise the
046 * form won't be displayed on the first invocation.
047 *  
048 * <p>This object looks for a FormInfo object named
049 * FORM_VALUES_CARRIER in the WikiContext. If found, it checks that
050 * its name matches the 'form' parameter, and if it does, adds the
051 * plugin parameters to the FormInfo. If the names don't match, the
052 * old FormInfo is discarded and a new one is created. Only one
053 * FormInfo is supported at a time. A practical consequence of this is
054 * that a FormSet invocation only applies to the Form plugins that
055 * follow it; any further Forms need new FormSet calls.
056 *
057 * @see FormInfo
058 */
059public class FormSet
060    implements WikiPlugin
061{    
062    /**
063     *  {@inheritDoc}
064     */
065    public String execute( WikiContext ctx, Map< String, String > params )
066        throws PluginException
067    {
068        String formName = params.get( FormElement.PARAM_FORM );
069        if( formName == null || formName.trim().length() == 0 )
070        {
071            return "";
072        }
073
074        FormInfo info = (FormInfo)ctx.getVariable( FormElement.FORM_VALUES_CARRIER );
075
076        if( info == null || formName.equals( info.getName() ) == false )
077        {
078            info = new FormInfo();
079            ctx.setVariable( FormElement.FORM_VALUES_CARRIER, info );
080        }
081
082        //
083        //  Create a copy for the context.  Unfortunately we need to 
084        //  create slightly modified copy, because otherwise on next
085        //  invocation this might be coming from a cache; so we can't
086        //  modify the original param string.
087        //
088        info.setName( formName );
089        Map< String, String > hm = new HashMap< String, String >();
090        hm.putAll( params );
091        
092        hm.remove( FormElement.PARAM_FORM );
093        info.addSubmission( hm );
094        
095        return "";
096    }
097}