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