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 org.apache.wiki.api.core.Context;
022import org.apache.wiki.api.exceptions.PluginException;
023import org.apache.wiki.api.plugin.Plugin;
024
025import java.util.HashMap;
026import java.util.Map;
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 implements Plugin {
060
061    /**
062     *  {@inheritDoc}
063     */
064    @Override
065    public String execute( final Context ctx, final Map< String, String > params ) throws PluginException {
066        final String formName = params.get( FormElement.PARAM_FORM );
067        if( formName == null || formName.trim().length() == 0 ) {
068            return "";
069        }
070
071        FormInfo info = ctx.getVariable( FormElement.FORM_VALUES_CARRIER );
072
073        if( info == null || !formName.equals( info.getName() ) ) {
074            info = new FormInfo();
075            ctx.setVariable( FormElement.FORM_VALUES_CARRIER, info );
076        }
077
078        //
079        //  Create a copy for the context.  Unfortunately we need to create slightly modified copy, because otherwise on next
080        //  invocation this might be coming from a cache; so we can't modify the original param string.
081        //
082        info.setName( formName );
083        final Map< String, String > hm = new HashMap<>();
084        hm.putAll( params );
085        hm.remove( FormElement.PARAM_FORM );
086        info.addSubmission( hm );
087        
088        return "";
089    }
090}