SubForm Controls

By Ben Tiedt, and a little by Robert McLaws

SubForms can be used to extend existing form controls. Instead of subclassing the existing controls, SubForms let you build your own functionality for Community Server Chameleon controls, without having to worry about recompiling your custom controls with every new CS service pack.

For example, the UserAvatarSubForm can be used with form controls that edit User objects such as the EditUserForm.

A sub-form can modify the edited object (User, for example) before the object is committed as well as after it is committed.  A sub-form can have it's own UI, validation, events, etc.

All sub-forms inherit from WrappedSubFormBase and should implement the following members:

• AttachChildControls method - used to find form element controls that will be populated/read by the sub-form
• DataBind method - used to populate the form element controls attached via the AttachChildControls method.  Before the host form calls the DataBind method of sub-forms, the DataSource property will be set to the same value as the host form.
• IsEnabled method - should return true if the sub-form control can be used by the accessing user
• ApplyChangesBeforeCommit method and/or ApplyChangesAfterCommit method - one or both of these methods should be overridden to implement the changes to the object being modified (User in your case when registered with the CreateUserForm control).  Both methods are passed a reference to be object being edited (User when registered with the CreateUserForm control).

Changes applied in the ApplyChangesBeforeCommit() method are made *after* the host form populates the object to be saved but *before* it is committed (so setting properties on the activeObject will be committed by the host form).  Changes applied in the ApplyChangesAfterCommit() method are made *after* the host form commits the activeObject - so additional logic or related objects can be manipulated using the activeObject's commited data (in this case, changes must be committed by the sub-form).

To use a sub-form,

1. Define and configure the sub-form control on the same rendered page as the host form (it can be placed within a User Control)
2. Be sure that  the sub-form control has an ID.
3. Include the ID of the sub-form in the SubFormIds property of the host form (which is comma-separated).  This will "attach" the sub-form to the host form.

Example

See the How to Extend User Registration using Sub-Forms article for an example of implementing a custom Sub-Form control.