refresh()

This method must be implemented by the ControlWrapper. It is invoked for rendering of the control in the same Render Mode as originally specified in initialize().

This method is only called after the initialize() method, and is called at any point when the control configuration or value has been updated. This method will be called at least once after initializing.

Functionality for Grid Panes

For Control Type instances that are being rendered in a grid pane, this method is called once each time a different cell in the grid pane is edited. In those cases, it is not always necessary to regenerate the entire DOM structure of the control. You can update the existing DOM structure, which was previously rendered, based on any updates to the configuration or value of the control. This is applicable only if the control is not in the Always Render mode. The getControl() method on the component interface at this point returns the control instance for the grid pane cell, which is being edited.

Method Argument:

  • updates: This is an array that contains the names of configuration properties updated since the last initialize() or refresh() method invocation. For example: if the array contains the value myProperty, then that means the value of the custom property named myProperty has been updated since the last refresh(). The full set of configuration properties can always be accessed using the control in the component object passed to the ControlWrapper in the initialize() method. There is a set of built-in keys that can reference properties common to all controls: "label", "hint", "required", "enabled", "readOnly", "visible", "locale", and "validation". The updates array can also contain the custom property names, if the value of any of those properties changed since the last refresh() method call.
    Note: When the control is in a grid pane that is not in Always Render mode, the ControlWrapper is shared among the cells of a column. The refresh() method is not called immediately after a property is changed on a cell but only when that cell is edited. The updates array in such cases is empty. The ControlWrapper implementation must query the specific control instance for any change in property values. You can retrieve the specific control instance by using the getControl() method on the component interface.