1 /**
2 * Copyright 2005-2013 The Kuali Foundation
3 *
4 * Licensed under the Educational Community License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.opensource.org/licenses/ecl2.php
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.kuali.rice.krad.uif.component;
17
18 import java.lang.annotation.Documented;
19 import java.lang.annotation.ElementType;
20 import java.lang.annotation.Retention;
21 import java.lang.annotation.RetentionPolicy;
22 import java.lang.annotation.Target;
23
24 /**
25 * Annotation that can be used on <code>Component</code> properties to indicate the property
26 * value should be exposed in the client and populated back from the client
27 *
28 * <p>
29 * Some components have state that can be altered on the client without making a server call. An
30 * example of this is the open state for an <code>Disclosure</code>. When the View is refreshed
31 * from the server, the refreshed state needs to reflect the last state before the refresh was made. The
32 * framework supports this exposure of state in the client and syncing of the client state to the server
33 * component by means of this annotation.
34 *
35 * During the finalize phase, values for properties that contain this annotation will be pulled and added
36 * to the ViewState object that is exposed through JavaScript. The property name/value pair is associated
37 * with the component id on the ViewState object so that the state can be updated when the view is refreshed.
38 *
39 * Properties exposed client side can also be accessed and updated by custom script.
40 * e.g.
41 * var componentState = ViewState['componentId']; // or ViewState.componentId
42 * var propertyValue = componentState['propertyName'];
43 * </p>
44 *
45 * <p>
46 * The property will be exposed client side with the identifier given by {@link #variableName()}. If not specified,
47 * the name of the property for which the annotation applies will be used
48 * </p>
49 *
50 * @author Kuali Rice Team (rice.collab@kuali.org)
51 */
52 @Target({ElementType.FIELD})
53 @Retention(RetentionPolicy.RUNTIME)
54 @Documented
55 public @interface ClientSideState {
56
57 /**
58 * Identifier to expose the client side variable as, can be left blank in which case
59 * the name of the property the annotation is associated with will be used
60 *
61 * @return String client side variable name
62 */
63 public String variableName() default "";
64
65 }