1 /**
2 * Copyright 2005-2015 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.ValidationTrace;
20 import org.kuali.rice.krad.uif.layout.CssGridSizes;
21 import org.kuali.rice.krad.uif.lifecycle.RunComponentModifiersTask;
22 import org.kuali.rice.krad.uif.lifecycle.ViewLifecycleUtils;
23 import org.kuali.rice.krad.uif.modifier.ComponentModifier;
24 import org.kuali.rice.krad.uif.util.LifecycleElement;
25 import org.kuali.rice.krad.uif.widget.Tooltip;
26
27 import java.io.Serializable;
28 import java.util.List;
29 import java.util.Map;
30
31 /**
32 * Component defines basic properties and methods that all rendering element implement
33 *
34 * <p>
35 * All classes of the UIF that are used as a rendering element implement the
36 * component interface. All components within the framework have the
37 * following structure:
38 * <ul>
39 * <li>Dictionary Configuration/Composition</li>
40 * <li>Java Class (the Component implementation</li>
41 * <li>>JSP Template Renderer</li>
42 * </ul>
43 * </p>
44 * <p>
45 * There are three basic types of components:
46 * <ul>
47 * <li>Container Components: {@code View}, {@code Group}</li>
48 * <li>Field Components: {@code Field}</li>
49 * <li>Widget Components: {@code Widget}</li>
50 * </ul>
51 * </p>
52 *
53 * @author Kuali Rice Team (rice.collab@kuali.org)
54 * @see org.kuali.rice.krad.uif.container.Container
55 * @see org.kuali.rice.krad.uif.field.Field
56 * @see org.kuali.rice.krad.uif.widget.Widget
57 */
58 public interface Component extends UifDictionaryBean, LifecycleElement, Serializable, Ordered, ScriptEventSupport {
59
60 /**
61 * The name for the component type
62 *
63 * <p>
64 * This is used within the rendering layer to pass the component instance into the template. The component instance
65 * is exported under the name given by this method.
66 * </p>
67 *
68 * @return String type name
69 */
70 String getComponentTypeName();
71
72 /**
73 * Indicates whether the component has been fully rendered.
74 *
75 * @return True if the component has fully rendered, false if not.
76 */
77 boolean isRendered();
78
79 /**
80 * Invoked by the view lifecycle after expressions are evaluated at the apply model phase.
81 *
82 * <p>
83 * In general, this method is preferred to {@link #performApplyModel(Object, LifecycleElement)}
84 * for populating model data via code, since it is called before client-side state is synchronize.
85 * </p>
86 */
87 void afterEvaluateExpression();
88
89 /**
90 * Set the view lifecycle processing status for this component, explicitly.
91 *
92 * @param status The view status for this component.
93 */
94 void setViewStatus(String status);
95
96 /**
97 * The path to the JSP file that should be called to render the component
98 *
99 * <p>
100 * The path should be relative to the web root. An attribute will be available to the component to use under the
101 * name given by the method {@code getComponentTypeName}. Based on the component type, additional attributes could
102 * be available for use. See the component documentation for more information on such attributes.
103 * </p>
104 *
105 * <p>
106 * e.g. '/krad/WEB-INF/jsp/tiles/component.jsp'
107 * </p>
108 *
109 * @return String representing the template path
110 */
111 String getTemplate();
112
113 /**
114 * Setter for the components template
115 *
116 * @param template
117 */
118 void setTemplate(String template);
119
120 /**
121 * Gets additional templates that will be required during the rendering of this component.
122 *
123 * <p>
124 * If a parent or sibling component is referred to by this component's template,
125 * include that component's template here to ensure that it has been compiled already during
126 * bottom-up inline rendering.
127 * </p>
128 *
129 * @return additional templates required during rendering
130 */
131 List<String> getAdditionalTemplates();
132
133 /**
134 * The name for which the template can be invoked by
135 *
136 * <p>
137 * Whether the template name is needed depends on the underlying rendering engine being used. In the example of
138 * Freemarker, the template points to the actual source file, which then loads a macro. From then on the macro is
139 * simply invoked to execute the template
140 * </p>
141 *
142 * <p>
143 * e.g. 'uif_text'
144 * </p>
145 *
146 * @return template name
147 */
148 public String getTemplateName();
149
150 /**
151 * Setter for the name of the template (a name which can be used to invoke)
152 *
153 * @param templateName
154 */
155 public void setTemplateName(String templateName);
156
157 /**
158 * The component title
159 *
160 * <p>
161 * Depending on the component can be used in various ways. For example with a Container component the title is
162 * used to set the header text. For components like controls other other components that render an HTML element it
163 * is used to set the HTML title attribute.
164 * </p>
165 *
166 * @return String title for component
167 */
168 String getTitle();
169
170 /**
171 * Setter for the component's title
172 *
173 * @param title
174 */
175 void setTitle(String title);
176
177 /**
178 * List of components that are contained within the List of {@code PropertyReplacer} in component
179 *
180 * <p>
181 * Used to get all the nested components in the property replacers.
182 * </p>
183 *
184 * @return List<Component> {@code PropertyReplacer} child components
185 */
186 List<Component> getPropertyReplacerComponents();
187
188 /**
189 * {@code ComponentModifier} instances that should be invoked to
190 * initialize the component
191 *
192 * <p>
193 * These provide dynamic initialization behavior for the component and are
194 * configured through the components definition. Each initializer will get
195 * invoked by the initialize method.
196 * </p>
197 *
198 * @return List of component modifiers
199 * @see RunComponentModifiersTask
200 */
201 List<ComponentModifier> getComponentModifiers();
202
203 /**
204 * Setter for the components List of {@code ComponentModifier}
205 * instances
206 *
207 * @param componentModifiers
208 */
209 void setComponentModifiers(List<ComponentModifier> componentModifiers);
210
211 /**
212 * When true, this component will render as a placeholder component instead of rendering normally because the
213 * content will be later retrieved through manually ajax retrieval calls in the js
214 *
215 * <p>This flag does not imply any automation, there must be a js call invoked for the content to be retrieved
216 * by the server, but this does mark it with a placeholder component which KRAD js uses during these calls.
217 * This placeholder component is used for ajax retrievals. In particular, this flag is useful for use in
218 * combination with the <b>showLightboxComponent</b> js function which will automatically retrieve the
219 * real content of a component through ajax if a placeholder component is detected. This allows for the full
220 * content to only be retrieved when the lightbox is first opened.
221 * When this flag is set to true, the forceSessionPersistence
222 * flag is set to true AUTOMATICALLY because it is implied that this component will be retrieved by an ajax call
223 * in the future. This may also be useful for direct custom calls to <b>retrieveComponent</b> function,
224 * as well, which also relies on the placeholder being present.</p>
225 *
226 * @return true if this component is being rendered as a placeholder for use in replacement during and ajax call,
227 * false otherwise
228 */
229 public boolean isRetrieveViaAjax();
230
231 /**
232 * When true, this component will render as a placeholder component instead of rendering normally because the
233 * content will be later retrieved through manually ajax retrieval calls in the js
234 *
235 * @param useAjaxCallForContent
236 */
237 public void setRetrieveViaAjax(boolean useAjaxCallForContent);
238
239 /**
240 * Indicates whether the component should be hidden in the UI
241 *
242 * <p>
243 * How the hidden data is maintained depends on the views persistence mode.
244 * If the mode is request, the corresponding data will be rendered to the UI
245 * but not visible. If the mode is session, the data will not be rendered to
246 * the UI but maintained server side.
247 * </p>
248 *
249 * <p>
250 * For a {@code Container} component, the hidden setting will apply to
251 * all contained components (making a section hidden makes all fields within
252 * the section hidden)
253 * </p>
254 *
255 * @return boolean true if the component should be hidden, false if it
256 * should be visible
257 */
258 boolean isHidden();
259
260 /**
261 * Setter for the hidden indicator
262 *
263 * @param hidden
264 */
265 void setHidden(boolean hidden);
266
267 /**
268 * Indicates whether the component can be edited
269 *
270 * <p>
271 * When readOnly the controls and widgets of {@code Field} components
272 * will not be rendered. If the Field has an underlying value it will be
273 * displayed readOnly to the user.
274 * </p>
275 *
276 * <p>
277 * For a {@code Container} component, the readOnly setting will apply
278 * to all contained components (making a section readOnly makes all fields
279 * within the section readOnly).
280 * </p>
281 *
282 * @return boolean true if the component should be readOnly, false if is
283 * allows editing
284 */
285 Boolean getReadOnly();
286
287 /**
288 * Setter for the read only indicator
289 *
290 * @param readOnly
291 */
292 void setReadOnly(Boolean readOnly);
293
294 /**
295 * Indicates whether the component should be cleared on copy
296 *
297 * <p>
298 * By default this property is false. ReadOnly components are cleared on a copy operation.
299 * If set this prevents the component from being cleared.
300 * </p>
301 * @return
302 */
303 Boolean getCanCopyOnReadOnly();
304
305 /**
306 * Setter for the canCopyOnReadOnly indicator
307 *
308 * @param canCopyOnReadOnly
309 */
310 void setCanCopyOnReadOnly(Boolean canCopyOnReadOnly);
311 /**
312 * Indicates whether the component is required
313 *
314 * <p>
315 * At the general component level required means there is some action the
316 * user needs to take within the component. For example, within a section it
317 * might mean the fields within the section should be completed. At a field
318 * level, it means the field should be completed. This provides the ability
319 * for the renderers to indicate the required action.
320 * </p>
321 *
322 * @return boolean true if the component is required, false if it is not
323 * required
324 */
325 Boolean getRequired();
326
327 /**
328 * Setter for the required indicator
329 *
330 * @param required
331 */
332 void setRequired(Boolean required);
333
334 /**
335 * Horizontal alignment of the component within its container
336 *
337 * <p>
338 * All components belong to a <code>Container</code> and are placed using a
339 * <code>LayoutManager</code>. This property specifies how the component
340 * should be aligned horizontally within the container. During the finalize
341 * phase the CSS text-align style will be created for the align setting.
342 * </p>
343 *
344 * @return String horizontal align
345 * @see org.kuali.rice.krad.uif.CssConstants.TextAligns
346 */
347 public String getAlign();
348
349 /**
350 * Sets the components horizontal alignment
351 *
352 * @param align
353 */
354 public void setAlign(String align);
355
356 /**
357 * Vertical alignment of the component within its container
358 *
359 * <p>
360 * All components belong to a <code>Container</code> and are placed using a
361 * <code>LayoutManager</code>. This property specifies how the component
362 * should be aligned vertically within the container. During the finalize
363 * phase the CSS vertical-align style will be created for the valign
364 * setting.
365 * </p>
366 *
367 * @return String vertical align
368 * @see org.kuali.rice.krad.uif.CssConstants.VerticalAligns
369 */
370 public String getValign();
371
372 /**
373 * Setter for the component's vertical align
374 *
375 * @param valign
376 */
377 public void setValign(String valign);
378
379 /**
380 * Width the component should take up in the container
381 *
382 * <p>
383 * All components belong to a <code>Container</code> and are placed using a
384 * <code>LayoutManager</code>. This property specifies a width the component
385 * should take up in the Container. This is not applicable for all layout
386 * managers. During the finalize phase the CSS width style will be created
387 * for the width setting.
388 * </p>
389 *
390 * <p>
391 * e.g. '30%', '55px'
392 * </p>
393 *
394 * @return String width string
395 */
396 public String getWidth();
397
398 /**
399 * Setter for the components width
400 *
401 * @param width
402 */
403 public void setWidth(String width);
404
405 /**
406 * CSS style string to be applied to the component
407 *
408 * <p>
409 * Any style override or additions can be specified with this attribute.
410 * This is used by the renderer to set the style attribute on the
411 * corresponding element.
412 * </p>
413 *
414 * <p>
415 * e.g. 'color: #000000;text-decoration: underline;'
416 * </p>
417 *
418 * @return String css style string
419 */
420 String getStyle();
421
422 /**
423 * Setter for the components style
424 *
425 * @param style
426 */
427 void setStyle(String style);
428
429 public List<String> getLibraryCssClasses();
430
431 public void setLibraryCssClasses(List<String> libraryCssClasses);
432
433 /**
434 * CSS style class(s) to be applied to the component
435 *
436 * <p>
437 * Declares style classes for the component. Multiple classes are specified
438 * with a space delimiter. This is used by the renderer to set the class
439 * attribute on the corresponding element. The class(s) declared must be
440 * available in the common style sheets or the style sheets specified for
441 * the view
442 * </p>
443 *
444 * @return List<String> css style classes to appear on the 'class' attribute
445 */
446 List<String> getCssClasses();
447
448 /**
449 * Setter for the components style classes
450 *
451 * @param styleClasses
452 */
453 void setCssClasses(List<String> styleClasses);
454
455 /**
456 * Convenience property for adding css class names to the end of the list of cssClasses that may already exist on
457 * this Component (this is to avoid explicitly having to set list merge in the bean definition)
458 *
459 * @return the additionalCssClasses
460 */
461 List<String> getAdditionalCssClasses();
462
463 /**
464 * Set the additionalCssClasses
465 *
466 * @param styleClasses
467 */
468 void setAdditionalCssClasses(List<String> styleClasses);
469
470 /**
471 * Adds a single style to the list of styles on this component
472 *
473 * @param styleClass
474 */
475 void addStyleClass(String styleClass);
476
477 /**
478 * Appends to the inline style set on a component
479 *
480 * @param itemStyle
481 */
482 void appendToStyle(String itemStyle);
483
484 /**
485 * Number of places the component should take up horizontally in the
486 * container; when using a CssGridLayoutManager this is converted to the appropriate medium size.
487 *
488 * <p>
489 * All components belong to a {@code Container} and are placed using a
490 * {@code LayoutManager}. This property specifies how many places
491 * horizontally the component should take up within the container. This is
492 * only applicable for table based layout managers. Default is 1
493 * </p>
494 *
495 * TODO: this should not be on component interface since it only applies if
496 * the layout manager supports it, need some sort of layoutOptions map for
497 * field level options that depend on the manager
498 *
499 * @return int number of columns to span
500 */
501 int getColSpan();
502
503 /**
504 * Setter for the components column span
505 *
506 * @param colSpan
507 */
508 void setColSpan(int colSpan);
509
510 /**
511 * Number of places the component should take up vertically in the container
512 *
513 * <p>
514 * All components belong to a {@code Container} and are placed using a
515 * {@code LayoutManager}. This property specifies how many places
516 * vertically the component should take up within the container. This is
517 * only applicable for table based layout managers. Default is 1
518 * </p>
519 *
520 * TODO: this should not be on component interface since it only applies if
521 * the layout manager supports it, need some sort of layoutOptions map for
522 * field level options that depend on the manager
523 *
524 * @return int number of rows to span
525 */
526 int getRowSpan();
527
528 /**
529 * Setter for the component row span
530 *
531 * @param rowSpan
532 */
533 void setRowSpan(int rowSpan);
534
535 /**
536 * The cellCssClasses property defines the classes that will be placed on the corresponding td (or th) elements
537 * relating to this component when used in a table backed layout. This property has no effect on other layouts.
538 *
539 * @return the css classes to apply to the wrapping td (or th) element for this component
540 */
541 public List<String> getWrapperCssClasses();
542
543 /**
544 * Set the cellCssClasses property which defines the classes that will be placed on the corresponding td (or th)
545 * relating to this component when used in a table backed layout. This property has no effect on other layouts.
546 *
547 * @param cellCssClasses
548 */
549 public void setWrapperCssClasses(List<String> cellCssClasses);
550
551 /**
552 * Add a cell css class to the cell classes list
553 *
554 * @param cssClass the name of the class to add
555 */
556 public void addWrapperCssClass(String cssClass);
557
558 /**
559 * CSS style string to be applied to the cell containing the component (only applies within
560 * table based layouts)
561 *
562 * <p>
563 * e.g. 'align: right;'
564 * </p>
565 *
566 * @return String css style string
567 */
568 public String getWrapperStyle();
569
570 /**
571 * Setter for the cell style attribute
572 *
573 * @param cellStyle
574 */
575 public void setWrapperStyle(String cellStyle);
576
577 /**
578 * Width setting for the cell containing the component (only applies within table based
579 * layouts)
580 *
581 * @return String width ('25%', '155px')
582 */
583 public String getCellWidth();
584
585 /**
586 * Setter for the containing cell width
587 *
588 * @param cellWidth
589 */
590 public void setCellWidth(String cellWidth);
591
592 /**
593 * CssGridSizes represent the size (width) the content's div "cell" will take up in the "row" at each screen
594 * size (extra small, small, medium, large) when using a group backed by a CssGridLayoutManager.
595 *
596 * <p>
597 * This object is NOT used by other layouts.
598 * For specifics of how css grids work, refer to the krad guide and bootstrap css grid documentation.
599 * </p>
600 *
601 * @return
602 */
603 public CssGridSizes getCssGridSizes();
604
605 /**
606 * @see org.kuali.rice.krad.uif.component.Component#getCssGridSizes()
607 */
608 public void setCssGridSizes(CssGridSizes cssGridSizes);
609
610 /**
611 * Context map for the component
612 *
613 * <p>
614 * Any el statements configured for the components properties (e.g.
615 * title="@{foo.property}") are evaluated using the el context map. This map
616 * will get populated with default objects like the model, view, and request
617 * from the {@code ViewHelperService}. Other components can push
618 * further objects into the context so that they are available for use with
619 * that component. For example, {@code Field} instances that are part
620 * of a collection line as receive the current line instance
621 * </p>
622 *
623 * <p>
624 * Context map also provides objects to methods that are invoked for
625 * {@code GeneratedField} instances
626 * </p>
627 *
628 * <p>
629 * The Map key gives the name of the variable that can be used within
630 * expressions, and the Map value gives the object instance for which
631 * expressions containing the variable should evaluate against
632 * </p>
633 *
634 * <p>
635 * NOTE: Calling getContext().putAll() will skip updating any configured property replacers for the
636 * component. Instead you should call #pushAllToContextDeep
637 * </p>
638 *
639 * @return Map<String, Object> context
640 */
641 Map<String, Object> getContext();
642
643 /**
644 * Setter for the context Map
645 *
646 * @param context
647 */
648 void setContext(Map<String, Object> context);
649
650 /**
651 * gets a list of {@code PropertyReplacer} instances
652 *
653 * <p>They will be evaluated
654 * during the view lifecycle to conditionally set properties on the
655 * {@code Component} based on expression evaluations</p>
656 *
657 * @return List<PropertyReplacer> replacers to evaluate
658 */
659 List<PropertyReplacer> getPropertyReplacers();
660
661 /**
662 * Setter for the components property substitutions
663 *
664 * @param propertyReplacers
665 */
666 void setPropertyReplacers(List<PropertyReplacer> propertyReplacers);
667
668 /**
669 * The options that are passed through to the Component renderer
670 *
671 * <p>
672 * The Map key is the option name, with the Map value as the option value. See
673 * documentation on the particular widget render for available options.
674 * </p>
675 *
676 * @return Map<String, String> options
677 */
678 Map<String, String> getTemplateOptions();
679
680 /**
681 * Setter for the template's options
682 *
683 * @param templateOptions
684 */
685 void setTemplateOptions(Map<String, String> templateOptions);
686
687 /**
688 * Builds a string from the underlying <code>Map</code> of template options that will export that options as a
689 * JavaScript Map for use in js and jQuery plugins
690 *
691 * <p>
692 * See documentation on the particular component render for available options.
693 * </p>
694 *
695 * @return String options
696 */
697 String getTemplateOptionsJSString();
698
699 /**
700 * Setter for the template's options
701 *
702 * @param templateOptionsJSString
703 */
704 void setTemplateOptionsJSString(String templateOptionsJSString);
705
706 /**
707 * Order of a component within a List of other components
708 *
709 * <p>Lower numbers are placed higher up in the list, while higher numbers are placed
710 * lower in the list</p>
711 *
712 * @return int ordering number
713 * @see org.springframework.core.Ordered#getOrder()
714 */
715 int getOrder();
716
717 /**
718 * Setter for the component's order
719 *
720 * @param order
721 */
722 void setOrder(int order);
723
724 /**
725 * The Tooltip widget that renders a tooltip with additional information about the element on
726 * specified trigger event
727 *
728 * @return Tooltip
729 */
730 Tooltip getToolTip();
731
732 /**
733 * Setter for the component tooltip widget instance
734 *
735 * @param toolTip
736 */
737 void setToolTip(Tooltip toolTip);
738
739 /**
740 * String containing JavaScript code for registering event handlers for this component
741 * (blur, focus, click, etc.)
742 *
743 * @return JS event handler script
744 */
745 public String getEventHandlerScript();
746
747 /**
748 * The name of the method that should be invoked for finalizing the component
749 * configuration (full method name, without parameters or return type)
750 *
751 * <p>
752 * Note the method can also be set with the finalizeMethodInvoker
753 * targetMethod property. If the method is on the configured
754 * {@code ViewHelperService}, only this property needs to be configured
755 * </p>
756 *
757 * <p>
758 * The model backing the view will be passed as the first argument method and then
759 * the {@code Component} instance as the second argument. If any additional method
760 * arguments are declared with the finalizeMethodAdditionalArguments, they will then
761 * be passed in the order declared in the list
762 * </p>
763 *
764 * <p>
765 * If the component is selfRendered, the finalize method can return a string which
766 * will be set as the component's renderOutput. The selfRendered indicator will also
767 * be set to true on the component.
768 * </p>
769 *
770 * @return String method name
771 */
772 String getFinalizeMethodToCall();
773
774 /**
775 * The List of Object instances that should be passed as arguments to the finalize method
776 *
777 * <p>
778 * These arguments are passed to the finalize method after the standard model and component
779 * arguments. They are passed in the order declared in the list
780 * </p>
781 *
782 * @return List<Object> additional method arguments
783 */
784 List<Object> getFinalizeMethodAdditionalArguments();
785
786 /**
787 * {@code MethodInvokerConfig} instance for the method that should be invoked
788 * for finalizing the component configuration
789 *
790 * <p>
791 * MethodInvoker can be configured to specify the class or object the method
792 * should be called on. For static method invocations, the targetClass
793 * property can be configured. For object invocations, that targetObject
794 * property can be configured
795 * </p>
796 *
797 * <p>
798 * If the component is selfRendered, the finalize method can return a string which
799 * will be set as the component's renderOutput. The selfRendered indicator will also
800 * be set to true on the component.
801 * </p>
802 *
803 * @return MethodInvokerConfig instance
804 */
805 MethodInvokerConfig getFinalizeMethodInvoker();
806
807 /**
808 * Indicates whether the component contains its own render output (through
809 * the renderOutput property)
810 *
811 * <p>
812 * If self rendered is true, the corresponding template for the component
813 * will not be invoked and the renderOutput String will be written to the
814 * response as is.
815 * </p>
816 *
817 * @return boolean true if component is self rendered, false if not (renders
818 * through template)
819 */
820 boolean isSelfRendered();
821
822 /**
823 * Setter for the self render indicator
824 *
825 * @param selfRendered
826 */
827 void setSelfRendered(boolean selfRendered);
828
829 /**
830 * Rendering output for the component that will be sent as part of the
831 * response (can contain static text and HTML)
832 *
833 * @return String render output
834 */
835 String getRenderedHtmlOutput();
836
837 /**
838 * Setter for the component's render output
839 *
840 * @param renderOutput
841 */
842 void setRenderedHtmlOutput(String renderOutput);
843
844 /**
845 * Disables the storage of the component in session (when the framework determines it needs to be due to a
846 * refresh condition)
847 *
848 * <p>
849 * When the framework determines there is a condition on the component that requires it to keep around between
850 * posts, it will store the component instance in session. This flag can be set to disable this behavior (which
851 * would require custom application logic to support behavior such as refresh)
852 * </p>
853 *
854 * @return boolean true if the component should not be stored in session, false if session storage is allowed
855 */
856 boolean isDisableSessionPersistence();
857
858 /**
859 * Setter for disabling storage of the component in session
860 *
861 * @param disableSessionPersistence
862 */
863 void setDisableSessionPersistence(boolean disableSessionPersistence);
864
865 /**
866 * Indicates whether the component should be stored with the session view regardless of configuration
867 *
868 * <p>
869 * By default the framework nulls out any components that do not have a refresh condition or are needed for
870 * collection processing. This can be a problem if custom application code is written to refresh a component
871 * without setting the corresponding component flag. In this case this property can be set to true to force the
872 * framework to keep the component in session. Defaults to false
873 * </p>
874 *
875 * @return boolean true if the component should be stored in session, false if not
876 */
877 boolean isForceSessionPersistence();
878
879 /**
880 * Setter for the indicator to force persistence of the component in session
881 *
882 * @param persistInSession
883 */
884 void setForceSessionPersistence(boolean persistInSession);
885
886 /**
887 * Security object that indicates what authorization (permissions) exist for the component
888 *
889 * @return ComponentSecurity instance
890 */
891 ComponentSecurity getComponentSecurity();
892
893 /**
894 * Setter for the components security object
895 *
896 * @param componentSecurity
897 */
898 void setComponentSecurity(ComponentSecurity componentSecurity);
899
900 /**
901 * Spring EL expression, which when evaluates to true, makes this component visible
902 *
903 * @return the SpEl expression string
904 */
905 String getProgressiveRender();
906
907 /**
908 * Setter for progressiveRender Spring EL expression
909 *
910 * @param progressiveRender the progressiveRender to set
911 */
912 void setProgressiveRender(String progressiveRender);
913
914 /**
915 * Spring EL expression, which when evaluates to true, causes this component to be refreshed
916 *
917 * @return the SpEl expression string
918 */
919 String getConditionalRefresh();
920
921 /**
922 * Setter for conditionalRefresh Spring EL expression
923 *
924 * @param conditionalRefresh the conditionalRefresh to set
925 */
926 void setConditionalRefresh(String conditionalRefresh);
927
928 /**
929 * List of control names (ids) extracted from {@link #getProgressiveRender()}
930 *
931 * @return the list of control names
932 */
933 List<String> getProgressiveDisclosureControlNames();
934
935 /**
936 * A JavaScript expression constructed from {@link #getConditionalRefresh()}
937 *
938 * <p>The script can be executed on the client to determine if the original exp was satisfied before
939 * interacting with the server.</p>
940 *
941 * @return the JS script
942 */
943 String getProgressiveDisclosureConditionJs();
944
945 /**
946 * A JavaScript expression constructed from {@link #getProgressiveRender()}
947 *
948 * <p>The script can be executed on the client to determine if the original exp was satisfied before
949 * interacting with the server.</p>
950 *
951 * @return the JS script
952 */
953 String getConditionalRefreshConditionJs();
954
955 /**
956 * The list of control names (ids) extracted from {@link #getConditionalRefresh()}
957 *
958 * @return the list of control names
959 */
960 List<String> getConditionalRefreshControlNames();
961
962 /**
963 * Indicates whether the component will be stored on the client, but hidden, after the first retrieval
964 *
965 * <p>
966 * The component will not be rendered hidden after first retrieval if this flag is set to true. The component will
967 * then be fetched via an ajax call when it should be rendered.
968 * </p>
969 *
970 * @return the progressiveRenderViaAJAX
971 */
972 boolean isProgressiveRenderViaAJAX();
973
974 /**
975 * Setter for the progressiveRenderViaAJAX flag
976 *
977 * @param progressiveRenderViaAJAX the progressiveRenderViaAJAX to set
978 */
979 void setProgressiveRenderViaAJAX(boolean progressiveRenderViaAJAX);
980
981 /**
982 * Determines whether the component will always be retrieved from the server and shown
983 *
984 * <p>
985 * If true, when the progressiveRender condition is satisfied, the component
986 * will always be retrieved from the server and shown(as opposed to being
987 * stored on the client, but hidden, after the first retrieval as is the
988 * case with the progressiveRenderViaAJAX option). <b>By default, this is
989 * false, so components with progressive render capabilities will always be
990 * already within the client html and toggled to be hidden or visible.</b> </p>
991 *
992 * @return the progressiveRenderAndRefresh
993 */
994 boolean isProgressiveRenderAndRefresh();
995
996 /**
997 * Setter for the progressiveRenderAndRefresh flag
998 *
999 * @param progressiveRenderAndRefresh the progressiveRenderAndRefresh to set
1000 */
1001 void setProgressiveRenderAndRefresh(boolean progressiveRenderAndRefresh);
1002
1003 /**
1004 * Specifies a property by name that when its value changes will automatically perform
1005 * a refresh on this component
1006 *
1007 * <p>
1008 * This can be a comma
1009 * separated list of multiple properties that require this component to be
1010 * refreshed when any of them change. <Br>DO NOT use with progressiveRender
1011 * unless it is know that progressiveRender condition will always be
1012 * satisfied before one of these fields can be changed.
1013 * </p>
1014 *
1015 * @return List property names that should trigger a refresh when their values change
1016 */
1017 List<String> getRefreshWhenChangedPropertyNames();
1018
1019 /**
1020 * Setter for the list of property names that trigger a refresh
1021 *
1022 * @param refreshWhenChangedPropertyNames
1023 */
1024 void setRefreshWhenChangedPropertyNames(List<String> refreshWhenChangedPropertyNames);
1025
1026 /**
1027 * Returns a list of componentIds which will be also be refreshed when this component is refreshed
1028 *
1029 * <p>
1030 * This will be a comma separated list of componentIds that need to be refreshed when a refresh
1031 * condition has been set on this component.
1032 * </p>
1033 *
1034 * @return List<String>
1035 */
1036 public List<String> getAdditionalComponentsToRefresh();
1037
1038 /**
1039 * Setter for alsoRefreshComponents
1040 *
1041 * @param additionalComponentsToRefresh
1042 */
1043 public void setAdditionalComponentsToRefresh(List<String> additionalComponentsToRefresh);
1044
1045 /**
1046 * Returns a string for representing the list of additional components to be refreshed as
1047 * a JavaScript value
1048 *
1049 * @return String representation of the list of componentIds for the components that need to be refreshed
1050 */
1051 public String getAdditionalComponentsToRefreshJs();
1052
1053 /**
1054 * Indicates the component can be refreshed by an action
1055 *
1056 * <p>
1057 * This is set by the framework for configured ajax action buttons, should not be set in
1058 * configuration
1059 * </p>
1060 *
1061 * @return boolean true if the component is refreshed by an action, false if not
1062 */
1063 boolean isRefreshedByAction();
1064
1065 /**
1066 * Setter for the refreshed by action indicator
1067 *
1068 * <p>
1069 * This is set by the framework for configured ajax action buttons, should not be set in
1070 * configuration
1071 * </p>
1072 *
1073 * @param refreshedByAction
1074 */
1075 void setRefreshedByAction(boolean refreshedByAction);
1076
1077 /**
1078 * If true if this component is disclosed by an action in js, a placeholder will be put in this components place
1079 * if render is also false.
1080 *
1081 * @return true if this component is disclosed by an action
1082 */
1083 public boolean isDisclosedByAction();
1084
1085 /**
1086 * Set if this component is disclosed by some outside action
1087 *
1088 * @param disclosedByAction
1089 */
1090 public void setDisclosedByAction(boolean disclosedByAction);
1091
1092 /**
1093 * Indicates whether data contained within the component should be reset (set to default) when the
1094 * component is refreshed
1095 *
1096 * @return boolean true if data should be refreshed, false if data should remain as is
1097 */
1098 boolean isResetDataOnRefresh();
1099
1100 /**
1101 * Setter for the reset data on refresh indicator
1102 *
1103 * @param resetDataOnRefresh
1104 */
1105 void setResetDataOnRefresh(boolean resetDataOnRefresh);
1106
1107 /**
1108 * Time in seconds after which the component is automatically refreshed
1109 *
1110 * @return time in seconds
1111 */
1112 int getRefreshTimer();
1113
1114 /**
1115 * Setter for refreshTimer
1116 *
1117 * @param refreshTimer
1118 */
1119 void setRefreshTimer(int refreshTimer);
1120
1121 /**
1122 * The DataAttributes that will be written to the html element for this component as data-
1123 *
1124 * <p>They can be access through .data() call in jQuery.</p>
1125 *
1126 * @return map of data attributes, where key is data attribute name and the map value is the data
1127 * attribute value
1128 */
1129 Map<String, String> getDataAttributes();
1130
1131 /**
1132 * Setter for data attributes to include for the component
1133 *
1134 * @param dataAttributes
1135 */
1136 void setDataAttributes(Map<String, String> dataAttributes);
1137
1138 /**
1139 * Setter for script data attributes to include for the component
1140 *
1141 * @param dataAttributes
1142 */
1143 void setScriptDataAttributes(Map<String, String> dataAttributes);
1144
1145 /**
1146 * The DataAttributes that will be written to the html as a script call to data for this component (these cannot be
1147 * used for jQuery selection directly)
1148 *
1149 * <p>They can be accessed through .data() call in jQuery.</p>
1150 *
1151 * @return map of data attributes, where key is data attribute name and the map value is the data
1152 * attribute value
1153 */
1154 Map<String, String> getScriptDataAttributes();
1155
1156 /**
1157 * Add a data attribute to the dataAttributes map
1158 *
1159 * @param key
1160 * @param value
1161 */
1162 void addDataAttribute(String key, String value);
1163
1164 /**
1165 * Add a script data attribute to the scriptDataAttributes map
1166 *
1167 * @param key
1168 * @param value
1169 */
1170 void addScriptDataAttribute(String key, String value);
1171
1172 /**
1173 * The string that can be put into a the tag of a component to add data attributes inline
1174 *
1175 * @return html string for data attributes as html formatted element attributes
1176 */
1177 String getSimpleDataAttributes();
1178
1179 /**
1180 * Returns a js string that can be used to right js data attributes to for the component
1181 *
1182 * @return html string for the js required to add the script data attributes
1183 */
1184 String getScriptDataAttributesJs();
1185
1186 /**
1187 * The role attribute of this component, use to define aria roles
1188 *
1189 * @return the role attribute
1190 */
1191 String getRole();
1192
1193 /**
1194 * @see Component#getRole()
1195 */
1196 void setRole(String role);
1197
1198 /**
1199 * The aria attributes of this component and their values
1200 * (without "aria-", this is automatically appended during rendering)
1201 *
1202 * @return the aria attributes of this component
1203 */
1204 Map<String, String> getAriaAttributes();
1205
1206 /**
1207 * @see org.kuali.rice.krad.uif.component.Component#getAriaAttributes()
1208 */
1209 void setAriaAttributes(Map<String, String> ariaAttributes);
1210
1211 /**
1212 * Add an aria attribute to the ariaAttributes list
1213 *
1214 * @param key the attribute (no "aria-" prefix)
1215 * @param value the attribute's value
1216 */
1217 void addAriaAttribute(String key, String value);
1218
1219 /**
1220 * Get the aria attributes as a String that can be used during template output
1221 *
1222 * @return the aria attributes as a string
1223 */
1224 String getAriaAttributesAsString();
1225
1226 /**
1227 * Validates different requirements of component compiling a series of reports detailing information on errors
1228 * found in the component. Used by the RiceDictionaryValidator.
1229 *
1230 * @param tracer Record of component's location
1231 */
1232 void completeValidation(ValidationTrace tracer);
1233
1234 /**
1235 * Raw html or string content to render before this component renders
1236 *
1237 * @return the preRenderContent string
1238 */
1239 public String getPreRenderContent();
1240
1241 /**
1242 * Set the preRenderContent
1243 *
1244 * @param preRenderContent
1245 */
1246 public void setPreRenderContent(String preRenderContent);
1247
1248 /**
1249 * Raw html or string content to render after this component renders
1250 *
1251 * @return the postRenderContent string
1252 */
1253 public String getPostRenderContent();
1254
1255 /**
1256 * Set the postRenderContent
1257 *
1258 * @param postRenderContent
1259 */
1260 public void setPostRenderContent(String postRenderContent);
1261
1262 /**
1263 * Gets the method to call on refresh.
1264 *
1265 * @return method to call
1266 */
1267 String getMethodToCallOnRefresh();
1268
1269 /**
1270 * Limits the field data to send on a refresh methodToCall server call to the names/group id/field id
1271 * specified in this list.
1272 *
1273 * <p>The names in the list should be the propertyNames of the fields sent with this request. A wildcard("*")
1274 * can be used at the END of a name to specify all fields with names that begin with the string
1275 * before the wildcard. If the array contains 1 item with the keyword "NONE", then no form fields are sent.
1276 * In addition, a group id or field id with the "#" id selector prefix can be used to send all input data which
1277 * are nested within them. Note that this only limits the fields which exist on the form and data required
1278 * by the KRAD framework is still sent (eg, methodToCall, formKey, sessionId, etc.)</p>
1279 *
1280 * @return the only input fields to send by name with the action request
1281 */
1282 public List<String> getFieldsToSendOnRefresh();
1283
1284 /**
1285 * @see org.kuali.rice.krad.uif.component.Component#getFieldsToSendOnRefresh()
1286 */
1287 public void setFieldsToSendOnRefresh(List<String> fieldsToSendOnRefresh);
1288
1289 /**
1290 * Gets a string representing all CSS style classes.
1291 *
1292 * @return string representation of CSS classes
1293 */
1294 String getStyleClassesAsString();
1295
1296 /**
1297 * Names a model property path, which if set and resolves to true, indicates that this component
1298 * should be excluded from the lifecycle at the initialize phase.
1299 *
1300 * <p>
1301 * If prefixed with the '#' character, this path will be relative to the view's "pre-model"
1302 * context rather than the model.
1303 * </p>
1304 *
1305 * <p>
1306 * This property is superseded by {@link #getExcludeUnless()}; when both resolve to true, the
1307 * component will be included. When neither property is set, the component is unconditionally
1308 * included.
1309 * </p>
1310 *
1311 * @return model property path
1312 * @see ViewLifecycleUtils#isExcluded(Component)
1313 */
1314 String getExcludeIf();
1315
1316 /**
1317 * Names a model property path, which if set and resolves to null or false, indicates that this
1318 * component should be excluded from the lifecycle at the initialize phase.
1319 *
1320 * <p>
1321 * If prefixed with the '#' character, this path will be relative to the view's "pre-model"
1322 * context rather than the model.
1323 * </p>
1324 *
1325 * <p>
1326 * This property supersedes {@link #getExcludeIf()}; when both resolve to true, the component
1327 * will be included. When neither property is set, the component is unconditionally included.
1328 * </p>
1329 *
1330 * @return model property path
1331 * @see ViewLifecycleUtils#isExcluded(Component)
1332 */
1333 String getExcludeUnless();
1334
1335 /**
1336 * Whether to omit fields from form post unless they are explicitly specified by the
1337 * {@link org.kuali.rice.krad.uif.element.Action#fieldsToSend} property.
1338 *
1339 * @return whether fields will be omitted from form post
1340 */
1341 boolean isOmitFromFormPost();
1342
1343 /**
1344 * @see #isOmitFromFormPost()
1345 */
1346 void setOmitFromFormPost(boolean omitFromFormPost);
1347
1348
1349 }