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.WikiContext;
022import org.apache.wiki.api.plugin.WikiPlugin;
023
024/**
025 */
026public abstract class FormElement
027    implements WikiPlugin
028{
029    /**
030     * In order to make the form-to-handler parameter transfer easier,
031     * we prefix all user-specified FORM element names with HANDLERPARAM_PREFIX
032     * the HTML output. This lets us differentiate user-defined FormHandler
033     * parameters from Form parameters.
034     * The submit handler must then use MapUtil.requestToMap() to
035     * strip them before executing the handler itself.
036     */
037    public static final String HANDLERPARAM_PREFIX = "nbf_";
038
039    /**
040     * The submit servlet may decide to store a FormInfo with user-entered
041     * form values in the Session. It should use this name, and this class
042     * checks for it to pre-fill fields from a previous form submit.
043     */
044    public static final String FORM_VALUES_CARRIER = "nbpf_values";
045
046    /**
047     *   Show values.  Value is <tt>{@value}</tt>.
048     */
049    public static final String HIDE_SUCCESS = "onsuccess";
050
051    // Parameter names:
052    /** Plugin parameter, optional, indicates servlet to post to. */
053    public static final String PARAM_SUBMITHANDLER = "submit";
054    /** Plugin parameter, mandatory, indicates what form element to insert. */
055    public static final String PARAM_ELEMENT    = "element";
056    /** 
057     * Plugin parameter, mandatory in output element, indicates
058     * WikiPlugin to use to handle form submitted data.
059     */
060    public static final String PARAM_HANDLER    = "handler";
061    /** Plugin parameter, mandatory in open/output: name of the form. */
062    public static final String PARAM_FORM       = "form";
063    /** Plugin parameter, mandatory in input elements: name of an element. */
064    public static final String PARAM_INPUTNAME  = "name";
065    /** Plugin parameter, optional: default value for an input. */
066    public static final String PARAM_VALUE      = "value";
067    /** Experimental: hide the form if it was submitted successfully. */ 
068    public static final String PARAM_HIDEFORM   = "hide";
069
070    /** If set to 'handler' in output element, the handler plugin is
071     * called even on first invocation (no submit). The plugin can
072     * then place values into its parameter map, and these are seen by
073     * subsequent Form elements. (Store a value in the plugin with the
074     * same key as an input element, and the value will be visible in
075     * the initial form.)
076     */
077    public static final String PARAM_POPULATE = "populate";
078    /** HTTP parameter, inserted as hidden variable into the generated form. */
079    public static final String PARAM_FORMNAMEHIDDEN   = "formname";
080
081    // Key to store the form info container in the context by:
082    //public static final String CONTEXT_FORMINFO = "FormPluginInfo";
083
084    /**
085     * Utility method stores a FormInfo object into the WikiContext.
086     * 
087     * @param ctx The Context to store it in
088     * @param info The FormInfo to store.
089     */
090    protected void storeFormInfo( WikiContext ctx, FormInfo info )
091    {
092        ctx.setVariable( FORM_VALUES_CARRIER, info );
093    }
094
095    /**
096     * Attempts to retrieve information on the currently handled
097     * form from the WikiContext.
098     * 
099     * @param ctx The Context
100     * @return The FormInfo from the context
101     */
102    protected FormInfo getFormInfo( WikiContext ctx )
103    {
104        return ( FormInfo )ctx.getVariable( FORM_VALUES_CARRIER );
105    }
106}