1 /*
2 * Copyright 2007 The Kuali Foundation
3 *
4 * Licensed under the Educational Community License, Version 1.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/ecl1.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.modifier;
17
18 import org.kuali.rice.krad.uif.view.View;
19 import org.kuali.rice.krad.uif.component.Component;
20 import org.kuali.rice.krad.uif.component.Configurable;
21 import org.kuali.rice.krad.uif.component.Ordered;
22
23 import java.io.Serializable;
24 import java.util.Set;
25
26 /**
27 * Provides modification functionality for a <code>Component</code>
28 *
29 * <p>
30 * <code>ComponentModifier</code> instances are configured by the component's
31 * dictionary definition. They can be used to provide dynamic initialization
32 * behavior for a certain type of component or all components based on the
33 * getSupportedComponents method. In addition they can do dynamic generation of
34 * new <code>Component</code> instances, or replacement of the components or
35 * their properties.
36 * </p>
37 *
38 * <p>
39 * Modifiers provide for more usability and flexibility of component
40 * configuration. For instance if a <code>Group</code> definition is already
41 * configured that is close to what the developer needs, but they need to make
42 * global changes of the group, then can invoke or create a
43 * <code>ComponentModifier</code> for the group to apply those changes. The
44 * configuration can then inherit the exiting group definition and then specify
45 * the modifier to run with the component's componentModifiers property.
46 * </p>
47 *
48 * @author Kuali Rice Team (rice.collab@kuali.org)
49 */
50 public interface ComponentModifier extends Configurable, Serializable, Ordered {
51
52 /**
53 * Should be called to initialize the ComponentModifier
54 *
55 * <p>
56 * This is where component modifiers can set defaults and setup other necessary
57 * state. The initialize method should only be called once per layout
58 * manager lifecycle and is invoked within the initialize phase of the view
59 * lifecylce.
60 * </p>
61 *
62 * <p>
63 * Note if the component modifier holds nested components, they should be initialized
64 * in this method by calling the view helper service
65 * </p>
66 *
67 * @param view - View instance the component modifier is a part of
68 * @parma model - object instance containing the view data
69 * @param component - Component the modifier is configured on
70 * @see org.kuali.rice.krad.uif.service.ViewHelperService#performInitialization
71 */
72 public void performInitialization(View view, Object model, Component component);
73
74 /**
75 * Invoked within the configured phase of the component lifecycle. This is
76 * where the <code>ComponentModifier</code> should perform its work against
77 * the given <code>Component</code> instance
78 *
79 * @param view - the view instance to which the component belongs
80 * @param model - top level object containing the view data
81 * @param component - the component instance to modify
82 * @see org.kuali.rice.krad.uif.modifier.ComponentModifier.performModification
83 * (View, Component)
84 */
85 public void performModification(View view, Object model, Component component);
86
87 /**
88 * <code>Set</code> of <code>Component</code> classes that may be sent to
89 * the modifier
90 *
91 * <p>
92 * If an empty or null list is returned, it is assumed the modifier supports
93 * all components. The returned set will be used by the dictionary
94 * validation
95 * </p>
96 *
97 * @return Set component classes
98 */
99 public Set<Class<? extends Component>> getSupportedComponents();
100
101 /**
102 * Indicates what phase of the component lifecycle the
103 * <code>ComponentModifier</code> should be invoked in (INITIALIZE,
104 * APPLY_MODEL, or FINALIZE)
105 *
106 * @return String view lifecycle phase
107 * @see org.kuali.rice.krad.uif.UifConstants.ViewPhases
108 */
109 public String getRunPhase();
110
111 /**
112 * Conditional expression to evaluate for determining whether the component
113 * modifier should be run. If the expression evaluates to true the modifier
114 * will be executed, otherwise it will not be executed
115 *
116 * @return String el expression that should evaluate to boolean
117 */
118 public String getRunCondition();
119
120 /**
121 * @see org.springframework.core.Ordered#getOrder()
122 */
123 public int getOrder();
124
125 /**
126 * @see org.kuali.rice.krad.uif.component.Ordered#setOrder(int)
127 */
128 public void setOrder(int order);
129
130 }