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