1 /**
2 * Copyright 2005-2012 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 org.kuali.rice.krad.datadictionary.uif.UifDictionaryBean;
19 import org.kuali.rice.krad.datadictionary.validator.ErrorReport;
20 import org.kuali.rice.krad.datadictionary.validator.TracerToken;
21 import org.kuali.rice.krad.uif.modifier.ComponentModifier;
22 import org.kuali.rice.krad.uif.view.View;
23 import org.kuali.rice.krad.uif.widget.Tooltip;
24
25 import java.io.Serializable;
26 import java.util.ArrayList;
27 import java.util.List;
28 import java.util.Map;
29
30 /**
31 * Component defines basic properties and methods that all rendering element implement
32 *
33 * <p>
34 * All classes of the UIF that are used as a rendering element implement the
35 * component interface. All components within the framework have the
36 * following structure:
37 * <ul>
38 * <li>Dictionary Configuration/Composition</li>
39 * <li>Java Class (the Component implementation</li>
40 * <li>>JSP Template Renderer</li>
41 * </ul>
42 * </p>
43 * <p>
44 * There are three basic types of components:
45 * <ul>
46 * <li>Container Components: {@code View}, {@code Group}</li>
47 * <li>Field Components: {@code Field}</li>
48 * <li>Widget Components: {@code Widget}</li>
49 * </ul>
50 * </p>
51 *
52 * @author Kuali Rice Team (rice.collab@kuali.org)
53 * @see org.kuali.rice.krad.uif.container.Container
54 * @see org.kuali.rice.krad.uif.field.Field
55 * @see org.kuali.rice.krad.uif.widget.Widget
56 */
57 public interface Component extends UifDictionaryBean, Serializable, Ordered, ScriptEventSupport {
58
59 /**
60 * The unique id (within a given tree) for the component
61 *
62 * <p>
63 * The id will be used by renderers to set the HTML element id. This gives a way to find various elements
64 * for scripting. If the id is not given, a default will be generated by the framework
65 * </p>
66 *
67 * @return String id
68 */
69 String getId();
70
71 /**
72 * Setter for the unique id (within a given tree) for the component
73 *
74 * @param id - string to set as the component id
75 */
76 void setId(String id);
77
78 /**
79 * Holds the id for the component that can be used to request new instances of that component from the
80 * {@link org.kuali.rice.krad.uif.util.ComponentFactory}
81 *
82 * <p>
83 * During component refreshes the component is reinitialized and the lifecycle is performed again to
84 * reflect the component state based on the latest updates (data, other component state). Since the lifecycle
85 * is only performed on the component, a new instance with configured initial state needs to be retrieved. Some
86 * component instances, such as those that are nested or created in code, cannot be obtained from the spring
87 * factory. For those the initial state is captured during the perform initialize phase and the factory id
88 * generated for referencing retrieving that configuration during a refresh
89 * </p>
90 *
91 * @return String bean id for component
92 */
93 String getBaseId();
94
95 /**
96 * Setter for the base id that backs the component instance
97 *
98 * @param baseId
99 */
100 void setBaseId(String baseId);
101
102 /**
103 * The name for the component type
104 *
105 * <p>
106 * This is used within the rendering layer to pass the component instance into the template. The component instance
107 * is exported under the name given by this method.
108 * </p>
109 *
110 * @return String type name
111 */
112 String getComponentTypeName();
113
114 /**
115 * The path to the JSP file that should be called to render the component
116 *
117 * <p>
118 * The path should be relative to the web root. An attribute will be available to the component to use under the
119 * name given by the method {@code getComponentTypeName}. Based on the component type, additional attributes could
120 * be available for use. See the component documentation for more information on such attributes.
121 * </p>
122 *
123 * <p>
124 * e.g. '/krad/WEB-INF/jsp/tiles/component.jsp'
125 * </p>
126 *
127 * @return String representing the template path
128 */
129 String getTemplate();
130
131 /**
132 * Setter for the components template
133 *
134 * @param template
135 */
136 void setTemplate(String template);
137
138 /**
139 * The component title
140 *
141 * <p>
142 * Depending on the component can be used in various ways. For example with a Container component the title is
143 * used to set the header text. For components like controls other other components that render an HTML element it
144 * is used to set the HTML title attribute.
145 * </p>
146 *
147 * @return String title for component
148 */
149 String getTitle();
150
151 /**
152 * Setter for the component's title
153 *
154 * @param title
155 */
156 void setTitle(String title);
157
158 /**
159 * Initializes the component
160 *
161 * <p>
162 * Where components can set defaults and setup other necessary state. The initialize method should only be called
163 * once per component lifecycle and is invoked within the initialize phase of the view lifecylce.
164 * </p>
165 *
166 * @param view - view instance in which the component belongs
167 * @param model - object instance containing the view data
168 * @see org.kuali.rice.krad.uif.service.ViewHelperService#performInitialization(org.kuali.rice.krad.uif.view.View,
169 * Object)
170 */
171 void performInitialization(View view, Object model);
172
173 /**
174 * Called after the initialize phase to perform conditional logic based on the model data
175 *
176 * <p>
177 * Where components can perform conditional logic such as dynamically generating new fields or setting field state
178 * based on the given data
179 * </p>
180 *
181 * @param view - view instance to which the component belongs
182 * @param model - Top level object containing the data (could be the form or a
183 * top level business object, dto)
184 */
185 void performApplyModel(View view, Object model, Component parent);
186
187 /**
188 * The last phase before the view is rendered
189 *
190 * <p>
191 * Here final preparations can be made based on the updated view state.
192 * </p>
193 *
194 * @param view - view instance that should be finalized for rendering
195 * @param model - top level object containing the data
196 * @param parent - parent component
197 */
198 void performFinalize(View view, Object model, Component parent);
199
200 /**
201 * List of components that are contained within the component and should be sent through
202 * the lifecycle
203 *
204 * <p>
205 * Used by {@code ViewHelperService} for the various lifecycle callbacks
206 * </p>
207 *
208 * @return List<Component> child components
209 */
210 List<Component> getComponentsForLifecycle();
211
212 /**
213 * List of components that are maintained by the component as prototypes for creating other component instances
214 *
215 * <p>
216 * Prototypes are held for configuring how a component should be created during the lifecycle. An example of this
217 * are the fields in a collection group that are created for each collection record. They only participate in the
218 * initialize phase.
219 * </p>
220 *
221 * @return List<Component> child component prototypes
222 */
223 List<Component> getComponentPrototypes();
224
225 /**
226 * List of components that are contained within the List of {@code PropertyReplacer} in component
227 *
228 * <p>
229 * Used to get all the nested components in the property replacers.
230 * </p>
231 *
232 * @return List<Component> {@code PropertyReplacer} child components
233 */
234 List<Component> getPropertyReplacerComponents();
235
236 /**
237 * {@code ComponentModifier} instances that should be invoked to
238 * initialize the component
239 *
240 * <p>
241 * These provide dynamic initialization behavior for the component and are
242 * configured through the components definition. Each initializer will get
243 * invoked by the initialize method.
244 * </p>
245 *
246 * @return List of component modifiers
247 * @see org.kuali.rice.krad.uif.service.ViewHelperService#performInitialization(org.kuali.rice.krad.uif.view.View,
248 * Object)
249 */
250 List<ComponentModifier> getComponentModifiers();
251
252 /**
253 * Setter for the components List of {@code ComponentModifier}
254 * instances
255 *
256 * @param componentModifiers
257 */
258 void setComponentModifiers(List<ComponentModifier> componentModifiers);
259
260 /**
261 * Indicates whether the component should be rendered in the UI
262 *
263 * <p>
264 * If set to false, the corresponding component template will not be invoked
265 * (therefore nothing will be rendered to the UI).
266 * </p>
267 *
268 * @return boolean true if the component should be rendered, false if it
269 * should not be
270 */
271 boolean isRender();
272
273 /**
274 * Setter for the components render indicator
275 *
276 * @param render
277 */
278 void setRender(boolean render);
279
280 /**
281 * Indicates whether the component should be hidden in the UI
282 *
283 * <p>
284 * How the hidden data is maintained depends on the views persistence mode.
285 * If the mode is request, the corresponding data will be rendered to the UI
286 * but not visible. If the mode is session, the data will not be rendered to
287 * the UI but maintained server side.
288 * </p>
289 *
290 * <p>
291 * For a {@code Container} component, the hidden setting will apply to
292 * all contained components (making a section hidden makes all fields within
293 * the section hidden)
294 * </p>
295 *
296 * @return boolean true if the component should be hidden, false if it
297 * should be visible
298 */
299 boolean isHidden();
300
301 /**
302 * Setter for the hidden indicator
303 *
304 * @param hidden
305 */
306 void setHidden(boolean hidden);
307
308 /**
309 * Indicates whether the component can be edited
310 *
311 * <p>
312 * When readOnly the controls and widgets of {@code Field} components
313 * will not be rendered. If the Field has an underlying value it will be
314 * displayed readOnly to the user.
315 * </p>
316 *
317 * <p>
318 * For a {@code Container} component, the readOnly setting will apply
319 * to all contained components (making a section readOnly makes all fields
320 * within the section readOnly).
321 * </p>
322 *
323 * @return boolean true if the component should be readOnly, false if is
324 * allows editing
325 */
326 boolean isReadOnly();
327
328 /**
329 * Setter for the read only indicator
330 *
331 * @param readOnly
332 */
333 void setReadOnly(boolean readOnly);
334
335 /**
336 * Indicates whether the component is required
337 *
338 * <p>
339 * At the general component level required means there is some action the
340 * user needs to take within the component. For example, within a section it
341 * might mean the fields within the section should be completed. At a field
342 * level, it means the field should be completed. This provides the ability
343 * for the renderers to indicate the required action.
344 * </p>
345 *
346 * @return boolean true if the component is required, false if it is not
347 * required
348 */
349 Boolean getRequired();
350
351 /**
352 * Setter for the required indicator
353 *
354 * @param required
355 */
356 void setRequired(Boolean required);
357
358 /**
359 * CSS style string to be applied to the component
360 *
361 * <p>
362 * Any style override or additions can be specified with this attribute.
363 * This is used by the renderer to set the style attribute on the
364 * corresponding element.
365 * </p>
366 *
367 * <p>
368 * e.g. 'color: #000000;text-decoration: underline;'
369 * </p>
370 *
371 * @return String css style string
372 */
373 String getStyle();
374
375 /**
376 * Setter for the components style
377 *
378 * @param style
379 */
380 void setStyle(String style);
381
382 /**
383 * CSS style class(s) to be applied to the component
384 *
385 * <p>
386 * Declares style classes for the component. Multiple classes are specified
387 * with a space delimiter. This is used by the renderer to set the class
388 * attribute on the corresponding element. The class(s) declared must be
389 * available in the common style sheets or the style sheets specified for
390 * the view
391 * </p>
392 *
393 * @return List<String> css style classes to appear on the 'class' attribute
394 */
395 List<String> getCssClasses();
396
397 /**
398 * Setter for the components style classes
399 *
400 * @param styleClasses
401 */
402 void setCssClasses(List<String> styleClasses);
403
404 /**
405 * Adds a single style to the list of styles on this component
406 *
407 * @param styleClass
408 */
409 void addStyleClass(String styleClass);
410
411 /**
412 * Appends to the inline style set on a component
413 *
414 * @param itemStyle
415 */
416 void appendToStyle(String itemStyle);
417
418 /**
419 * Number of places the component should take up horizontally in the
420 * container
421 *
422 * <p>
423 * All components belong to a {@code Container} and are placed using a
424 * {@code LayoutManager}. This property specifies how many places
425 * horizontally the component should take up within the container. This is
426 * only applicable for table based layout managers. Default is 1
427 * </p>
428 *
429 * TODO: this should not be on component interface since it only applies if
430 * the layout manager supports it, need some sort of layoutOptions map for
431 * field level options that depend on the manager
432 *
433 * @return int number of columns to span
434 */
435 int getColSpan();
436
437 /**
438 * Setter for the components column span
439 *
440 * @param colSpan
441 */
442 void setColSpan(int colSpan);
443
444 /**
445 * Number of places the component should take up vertically in the container
446 *
447 * <p>
448 * All components belong to a {@code Container} and are placed using a
449 * {@code LayoutManager}. This property specifies how many places
450 * vertically the component should take up within the container. This is
451 * only applicable for table based layout managers. Default is 1
452 * </p>
453 *
454 * TODO: this should not be on component interface since it only applies if
455 * the layout manager supports it, need some sort of layoutOptions map for
456 * field level options that depend on the manager
457 *
458 * @return int number of rows to span
459 */
460 int getRowSpan();
461
462 /**
463 * Setter for the component row span
464 *
465 * @param rowSpan
466 */
467 void setRowSpan(int rowSpan);
468
469 /**
470 * Context map for the component
471 *
472 * <p>
473 * Any el statements configured for the components properties (e.g.
474 * title="@{foo.property}") are evaluated using the el context map. This map
475 * will get populated with default objects like the model, view, and request
476 * from the {@code ViewHelperService}. Other components can push
477 * further objects into the context so that they are available for use with
478 * that component. For example, {@code Field} instances that are part
479 * of a collection line as receive the current line instance
480 * </p>
481 *
482 * <p>
483 * Context map also provides objects to methods that are invoked for
484 * {@code GeneratedField} instances
485 * </p>
486 *
487 * <p>
488 * The Map key gives the name of the variable that can be used within
489 * expressions, and the Map value gives the object instance for which
490 * expressions containing the variable should evaluate against
491 * </p>
492 *
493 * <p>
494 * NOTE: Calling getContext().putAll() will skip updating any configured property replacers for the
495 * component. Instead you should call #pushAllToContext
496 * </p>
497 *
498 * @return Map<String, Object> context
499 */
500 Map<String, Object> getContext();
501
502 /**
503 * Setter for the context Map
504 *
505 * @param context
506 */
507 void setContext(Map<String, Object> context);
508
509 /**
510 * Places the given object into the context Map for the component with the
511 * given name
512 *
513 * <p>
514 * Note this also will push context to property replacers configured on the component.
515 * To place multiple objects in the context, you should use #pushAllToContext since that
516 * will call this method for each and update property replacers. Using {@link #getContext().putAll()}
517 * will bypass property replacers.
518 * </p>
519 *
520 * @param objectName - name the object should be exposed under in the context map
521 * @param object - object instance to place into context
522 */
523 void pushObjectToContext(String objectName, Object object);
524
525 /**
526 * Places each entry of the given Map into the context for the component
527 *
528 * <p>
529 * Note this will call #pushObjectToContext for each entry which will update any configured property
530 * replacers as well. This should be used in place of getContext().putAll()
531 * </p>
532 *
533 * @param objects - Map<String, Object> objects to add to context, where the entry key will be the context key
534 * and the entry value will be the context value
535 */
536 void pushAllToContext(Map<String, Object> objects);
537
538 /**
539 * gets a list of {@code PropertyReplacer} instances
540 *
541 * <p>They will be evaluated
542 * during the view lifecycle to conditionally set properties on the
543 * {@code Component} based on expression evaluations</p>
544 *
545 * @return List<PropertyReplacer> replacers to evaluate
546 */
547 List<PropertyReplacer> getPropertyReplacers();
548
549 /**
550 * Setter for the components property substitutions
551 *
552 * @param propertyReplacers
553 */
554 void setPropertyReplacers(List<PropertyReplacer> propertyReplacers);
555
556 /**
557 * The options that are passed through to the Component renderer
558 *
559 * <p>
560 * The Map key is the option name, with the Map value as the option value. See
561 * documentation on the particular widget render for available options.
562 * </p>
563 *
564 * @return Map<String, String> options
565 */
566 Map<String, String> getTemplateOptions();
567
568 /**
569 * Setter for the template's options
570 *
571 * @param templateOptions
572 */
573 void setTemplateOptions(Map<String, String> templateOptions);
574
575 /**
576 * Builds a string from the underlying <code>Map</code> of template options that will export that options as a
577 * JavaScript Map for use in js and jQuery plugins
578 *
579 * <p>
580 * See documentation on the particular component render for available options.
581 * </p>
582 *
583 * @return String options
584 */
585 String getTemplateOptionsJSString();
586
587 /**
588 * Setter for the template's options
589 *
590 * @param templateOptionsJSString
591 */
592 void setTemplateOptionsJSString(String templateOptionsJSString);
593
594 /**
595 * Order of a component within a List of other components
596 *
597 * <p>Lower numbers are placed higher up in the list, while higher numbers are placed
598 * lower in the list</p>
599 *
600 * @return int ordering number
601 * @see org.springframework.core.Ordered#getOrder()
602 */
603 int getOrder();
604
605 /**
606 * Setter for the component's order
607 *
608 * @param order
609 */
610 void setOrder(int order);
611
612 /**
613 * The Tooltip widget that renders a tooltip with additional information about the element on
614 * specified trigger event
615 *
616 * @return Tooltip
617 */
618 Tooltip getToolTip();
619
620 /**
621 * Setter for the component tooltip widget instance
622 *
623 * @param toolTip
624 */
625 void setToolTip(Tooltip toolTip);
626
627 /**
628 * The name of the method that should be invoked for finalizing the component
629 * configuration (full method name, without parameters or return type)
630 *
631 * <p>
632 * Note the method can also be set with the finalizeMethodInvoker
633 * targetMethod property. If the method is on the configured
634 * {@code ViewHelperService}, only this property needs to be configured
635 * </p>
636 *
637 * <p>
638 * The model backing the view will be passed as the first argument method and then
639 * the {@code Component} instance as the second argument. If any additional method
640 * arguments are declared with the finalizeMethodAdditionalArguments, they will then
641 * be passed in the order declared in the list
642 * </p>
643 *
644 * <p>
645 * If the component is selfRendered, the finalize method can return a string which
646 * will be set as the component's renderOutput. The selfRendered indicator will also
647 * be set to true on the component.
648 * </p>
649 *
650 * @return String method name
651 */
652 String getFinalizeMethodToCall();
653
654 /**
655 * The List of Object instances that should be passed as arguments to the finalize method
656 *
657 * <p>
658 * These arguments are passed to the finalize method after the standard model and component
659 * arguments. They are passed in the order declared in the list
660 * </p>
661 *
662 * @return List<Object> additional method arguments
663 */
664 List<Object> getFinalizeMethodAdditionalArguments();
665
666 /**
667 * {@code MethodInvokerConfig} instance for the method that should be invoked
668 * for finalizing the component configuration
669 *
670 * <p>
671 * MethodInvoker can be configured to specify the class or object the method
672 * should be called on. For static method invocations, the targetClass
673 * property can be configured. For object invocations, that targetObject
674 * property can be configured
675 * </p>
676 *
677 * <p>
678 * If the component is selfRendered, the finalize method can return a string which
679 * will be set as the component's renderOutput. The selfRendered indicator will also
680 * be set to true on the component.
681 * </p>
682 *
683 * @return MethodInvokerConfig instance
684 */
685 MethodInvokerConfig getFinalizeMethodInvoker();
686
687 /**
688 * Indicates whether the component contains its own render output (through
689 * the renderOutput property)
690 *
691 * <p>
692 * If self rendered is true, the corresponding template for the component
693 * will not be invoked and the renderOutput String will be written to the
694 * response as is.
695 * </p>
696 *
697 * @return boolean true if component is self rendered, false if not (renders
698 * through template)
699 */
700 boolean isSelfRendered();
701
702 /**
703 * Setter for the self render indicator
704 *
705 * @param selfRendered
706 */
707 void setSelfRendered(boolean selfRendered);
708
709 /**
710 * Rendering output for the component that will be sent as part of the
711 * response (can contain static text and HTML)
712 *
713 * @return String render output
714 */
715 String getRenderedHtmlOutput();
716
717 /**
718 * Setter for the component's render output
719 *
720 * @param renderOutput
721 */
722 void setRenderedHtmlOutput(String renderOutput);
723
724 /**
725 * Disables the storage of the component in session (when the framework determines it needs to be due to a
726 * refresh condition)
727 *
728 * <p>
729 * When the framework determines there is a condition on the component that requires it to keep around between
730 * posts, it will store the component instance in session. This flag can be set to disable this behavior (which
731 * would require custom application logic to support behavior such as refresh)
732 * </p>
733 *
734 * @return boolean true if the component should not be stored in session, false if session storage is allowed
735 */
736 boolean isDisableSessionPersistence();
737
738 /**
739 * Setter for disabling storage of the component in session
740 *
741 * @param disableSessionPersistence
742 */
743 void setDisableSessionPersistence(boolean disableSessionPersistence);
744
745 /**
746 * Indicates whether the component should be stored with the session view regardless of configuration
747 *
748 * <p>
749 * By default the framework nulls out any components that do not have a refresh condition or are needed for
750 * collection processing. This can be a problem if custom application code is written to refresh a component
751 * without setting the corresponding component flag. In this case this property can be set to true to force the
752 * framework to keep the component in session. Defaults to false
753 * </p>
754 *
755 * @return boolean true if the component should be stored in session, false if not
756 */
757 boolean isForceSessionPersistence();
758
759 /**
760 * Setter for the indicator to force persistence of the component in session
761 *
762 * @param persistInSession
763 */
764 void setForceSessionPersistence(boolean persistInSession);
765
766 /**
767 * Security object that indicates what authorization (permissions) exist for the component
768 *
769 * @return ComponentSecurity instance
770 */
771 ComponentSecurity getComponentSecurity();
772
773 /**
774 * Setter for the components security object
775 *
776 * @param componentSecurity
777 */
778 void setComponentSecurity(ComponentSecurity componentSecurity);
779
780 /**
781 * Spring EL expression, which when evaluates to true, makes this component visible
782 *
783 * @return the SpEl expression string
784 */
785 String getProgressiveRender();
786
787 /**
788 * Setter for progressiveRender Spring EL expression
789 *
790 * @param progressiveRender the progressiveRender to set
791 */
792 void setProgressiveRender(String progressiveRender);
793
794 /**
795 * Spring EL expression, which when evaluates to true, causes this component to be refreshed
796 *
797 * @return the SpEl expression string
798 */
799 String getConditionalRefresh();
800
801 /**
802 * Setter for conditionalRefresh Spring EL expression
803 *
804 * @param conditionalRefresh the conditionalRefresh to set
805 */
806 void setConditionalRefresh(String conditionalRefresh);
807
808 /**
809 * List of control names (ids) extracted from {@link #getProgressiveRender()}
810 *
811 * @return the list of control names
812 */
813 List<String> getProgressiveDisclosureControlNames();
814
815 /**
816 * A JavaScript expression constructed from {@link #getConditionalRefresh()}
817 *
818 * <p>The script can be executed on the client to determine if the original exp was satisfied before
819 * interacting with the server.</p>
820 *
821 * @return the JS script
822 */
823 String getProgressiveDisclosureConditionJs();
824
825 /**
826 * A JavaScript expression constructed from {@link #getProgressiveRender()}
827 *
828 * <p>The script can be executed on the client to determine if the original exp was satisfied before
829 * interacting with the server.</p>
830 *
831 * @return the JS script
832 */
833 String getConditionalRefreshConditionJs();
834
835 /**
836 * The list of control names (ids) extracted from {@link #getConditionalRefresh()}
837 *
838 * @return the list of control names
839 */
840 List<String> getConditionalRefreshControlNames();
841
842 /**
843 * Indicates whether the component will be stored on the client, but hidden, after the first retrieval
844 *
845 * <p>
846 * The component will not be rendered hidden after first retrieval if this flag is set to true. The component will
847 * then be fetched via an ajax call when it should be rendered.
848 * </p>
849 *
850 * @return the progressiveRenderViaAJAX
851 */
852 boolean isProgressiveRenderViaAJAX();
853
854 /**
855 * Setter for the progressiveRenderViaAJAX flag
856 *
857 * @param progressiveRenderViaAJAX the progressiveRenderViaAJAX to set
858 */
859 void setProgressiveRenderViaAJAX(boolean progressiveRenderViaAJAX);
860
861 /**
862 * Determines whether the component will always be retrieved from the server and shown
863 *
864 * <p>
865 * If true, when the progressiveRender condition is satisfied, the component
866 * will always be retrieved from the server and shown(as opposed to being
867 * stored on the client, but hidden, after the first retrieval as is the
868 * case with the progressiveRenderViaAJAX option). <b>By default, this is
869 * false, so components with progressive render capabilities will always be
870 * already within the client html and toggled to be hidden or visible.</b> </p>
871 *
872 * @return the progressiveRenderAndRefresh
873 */
874 boolean isProgressiveRenderAndRefresh();
875
876 /**
877 * Setter for the progressiveRenderAndRefresh flag
878 *
879 * @param progressiveRenderAndRefresh the progressiveRenderAndRefresh to set
880 */
881 void setProgressiveRenderAndRefresh(boolean progressiveRenderAndRefresh);
882
883 /**
884 * Specifies a property by name that when its value changes will automatically perform
885 * a refresh on this component
886 *
887 * <p>
888 * This can be a comma
889 * separated list of multiple properties that require this component to be
890 * refreshed when any of them change. <Br>DO NOT use with progressiveRender
891 * unless it is know that progressiveRender condition will always be
892 * satisfied before one of these fields can be changed.
893 * </p>
894 *
895 * @return List property names that should trigger a refresh when their values change
896 */
897 List<String> getRefreshWhenChangedPropertyNames();
898
899 /**
900 * Setter for the list of property names that trigger a refresh
901 *
902 * @param refreshWhenChangedPropertyNames
903 */
904 void setRefreshWhenChangedPropertyNames(List<String> refreshWhenChangedPropertyNames);
905
906 /**
907 * Returns a list of componentIds which will be also be refreshed when this component is refreshed
908 * <p>
909 * This will be a comma separated list of componentIds that need to be refreshed when a refresh
910 * condition has been set on this component.
911 * </p>
912 * @return List<String>
913 */
914 public List<String> getAdditionalComponentsToRefresh();
915
916 /**
917 * Setter for alsoRefreshComponents
918 *
919 * @param additionalComponentsToRefresh
920 */
921 public void setAdditionalComponentsToRefresh(List<String> additionalComponentsToRefresh);
922
923 /**
924 * Returns a string for representing the list of additional components to be refreshed as
925 * a JavaScript value
926 *
927 * @return String representation of the list of componentIds for the components that need to be refreshed
928 */
929 public String getAdditionalComponentsToRefreshJs();
930
931 /**
932 * Indicates the component can be refreshed by an action
933 *
934 * <p>
935 * This is set by the framework for configured ajax action buttons, should not be set in
936 * configuration
937 * </p>
938 *
939 * @return boolean true if the component is refreshed by an action, false if not
940 */
941 boolean isRefreshedByAction();
942
943 /**
944 * Setter for the refreshed by action indicator
945 *
946 * <p>
947 * This is set by the framework for configured ajax action buttons, should not be set in
948 * configuration
949 * </p>
950 *
951 * @param refreshedByAction
952 */
953 void setRefreshedByAction(boolean refreshedByAction);
954
955 /**
956 * Indicates whether data contained within the component should be reset (set to default) when the
957 * component is refreshed
958 *
959 * @return boolean true if data should be refreshed, false if data should remain as is
960 */
961 boolean isResetDataOnRefresh();
962
963 /**
964 * Setter for the reset data on refresh indicator
965 *
966 * @param resetDataOnRefresh
967 */
968 void setResetDataOnRefresh(boolean resetDataOnRefresh);
969
970 /**
971 * Time in seconds after which the component is automatically refreshed
972 *
973 * @return time in seconds
974 */
975 int getRefreshTimer();
976
977 /**
978 * Setter for refreshTimer
979 *
980 * @param refreshTimer
981 */
982 void setRefreshTimer(int refreshTimer);
983
984 /**
985 * Add a data attribute to the dataAttributes map
986 *
987 * @param key
988 * @param value
989 */
990 void addDataAttribute(String key, String value);
991
992 Map<String, String> getDataAttributes();
993
994 /**
995 * The DataAttributes that will be written to the html and/or through script to be consumed by jQuery
996 *
997 * <p>The attributes that are complex objects (contain {}) they will be written through script.
998 * The attributes that are simple (contain no objects) will be written directly to the html of the
999 * component using standard data-.</p>
1000 * <p>Either way they can be access through .data() call in jQuery.</p>
1001 *
1002 * @param dataAttributes
1003 */
1004 void setDataAttributes(Map<String, String> dataAttributes);
1005
1006 /**
1007 * A JavaScript script that will add data to this component by the element which matches its id
1008 *
1009 * <p>
1010 * This will return script for only the complex data elements (containing {})</p>
1011 *
1012 * @return jQuery data script for adding complex data attributes
1013 */
1014 String getComplexDataAttributesJs();
1015
1016 /**
1017 * The string that can be put into a the tag of a component to add data attributes inline
1018 *
1019 * <p>
1020 * This does not include the complex attributes which contain {}</p>
1021 *
1022 * @return html string for data attributes for the simple attributes
1023 */
1024 String getSimpleDataAttributes();
1025
1026 /**
1027 * A JavaScript script that will add data to this component by the element which matches its id
1028 *
1029 * <p>This will return script for all the complex data elements.
1030 * This method is useful for controls that are implemented as spring form tags</p>
1031 *
1032 * @return jQuery data script for adding all data attributes
1033 */
1034 String getAllDataAttributesJs();
1035
1036 /**
1037 * Validates different requirements of component compiling a series of reports detailing information on errors
1038 * found in the component. Used by the RiceDictionaryValidator.
1039 *
1040 * @param tracer Record of component's location
1041 * @return A list of ErrorReports detailing errors found within the component and referenced within it
1042 */
1043 ArrayList<ErrorReport> completeValidation(TracerToken tracer);
1044 }