Editable Forms

EditableForms make use of a set of objects called FormElements. FormElements (which can also be extended) represent common data input controls.

Graffiti does its best to stick with the mantra of “convention over configuration”, so unless you want to make some very low-level changes (with the exception of the database connection string) there are never any XML configuration files to edit.

We wanted this same experience to carry across both widgets and plug-ins. However, in order to get the best experience, users need to be able to supply information to them.

This information describes Graffiti's dynamic form functionality and in particular its usage in the EditableForm object, from which both widgets and GraffitiEvent derive.

In Graffiti 1.0 the following FormElements are available to use out of the box:
  • CheckFormElement - represents a standard checkbox.
  • FileFormElement - allows a user to pick a file from the server (/files directory) or upload a new one.
  • ListFormElement - allows a user to pick from a list of options. Currently only supports selecting a single item via a DropDown.
  • TextFormElement - allows a user to enter a single line of text.
  • TextAreaFormElement - allows a user to enter more than one line of text (you control the number of lines/rows).
  • WYSIWYGFormElement - allows a user to enter HTML in a WYSIWYG editing experience.
Graffiti manages the element's state and user interface. You simply need to tell Graffiti which elements you want to use and the order you in which would like to use them.

EditableForm Methods

string EditUrl
By default, both widgets and plug-ins use a relative page called edit.aspx for their editing. If for whatever reason you need more control than is provided for FormElements or need to implement a multiple step process, you can override this property and have Graffiti point your widget or plug-in to a different page.

Note: In the Graffiti beta, you will need to deploy this custom page on your own. In the Graffiti release you will be able to leverage packages.

string Name
This is the name of your widget or plug-in as you would like to see it in a list. Graffiti requires you to implement this in widgets. With plug-ins you can override string Name, but by default the Type name is used.

string FormName
This allows you to override the name rendered on the edit form. By default, the value from Name will be used if this property is not overridden.

NameValueCollection DataAsNameValueCollection()
Before Graffiti builds your dynamic form, it asks your widget or plug-in for its internal data in the form of a NameValueCollection.

FormElementCollection AddFormElements()
This method returns a collection of FormElements which will be used to build the dynamic form. It must be overridden if you want to add any of your own FormElements on the edit page.

StatusType SetValues(HttpContext context, NameValueCollection nvc)
SetValues allows you to get access to the values entered by the user who clicked Save on your dynamic form (opposite of DataAsNameValueCollection). Using StatusType (Success, Warning, or Error), you can tell Graffiti the data received is valid. If you return a Warning or Error, Graffiti will not save the widget or plug-in update.

SetMessage(HttpContext context, string message)
This is the Static method on the EditableForm which you can use to pass a status message back to the Graffiti page. This is helpful when you need to give some kind of error message or warning.

Please refer to the examples on the widgets overview for how to use the methods described above to build your own dynamic form.

Last edited Mar 31, 2010 at 4:38 AM by jkillebrew, version 1


No comments yet.