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