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.
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.
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.
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.
Before Graffiti builds your dynamic form, it asks your widget or plug-in for its internal data in the form of a NameValueCollection.
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.