Class Field

Field definitions for the DataTables Editor.

Each Database column that is used with Editor can be described with this Field method (both for Editor and Join instances). It basically tells Editor what table column to use, how to format the data and if you want to read and/or write this column.

Inheritance

System.Object

Field

Namespace: DataTables

Assembly: DataTables-Editor-Server.dll

Syntax

public class Field : object

Constructors

Field(String)

Create a new Field instance - common db name and http name

Declaration

public Field(string dbField)

Parameters

Type	Name	Description
System.String	dbField	Database name for the field. This is also used as the HTTP name for the field

Field(String, String)

Create a new Field instance - different db and http names

Declaration

public Field(string dbField, string name)

Parameters

Type	Name	Description
System.String	dbField	Database name for the field
System.String	name	HTTP name (JSON data and form submit)

Field(String, String, Type, String)

Create a new Field instance - different db and http names with type specified

Declaration

public Field(string dbField, string name = null, Type type = null, string typeError = null)

Parameters

Type	Name	Description
System.String	dbField	Database name for the field. This is also used as the HTTP name for the field
System.String	name	HTTP name (JSON data and form submit)
Type	type	Type that the value should take
System.String	typeError	Error message if the field's value cannot be cast to the given type

Field(String, Type, String)

Create a new Field instance - common db name and http name with type specified

Declaration

public Field(string dbField = null, Type type = null, string typeError = null)

Parameters

Type	Name	Description
System.String	dbField	Database name for the field. This is also used as the HTTP name for the field
Type	type	Type that the value should take
System.String	typeError	Error message if the field's value cannot be cast to the given type

Methods

DbField()

Set the DB field name.

Declaration

public string DbField()

Returns

Type	Description
System.String	Database field name

DbField(String)

Set the DB field name.

Note that when used as a setter, an alias can be given for the field using the SQL as keyword - for example: firstName as name. In this situation the dbField is set to the field name before the as, and the field's name (name()) is set to the name after the as.

As a result of this, the following constructs have identical functionality:

• .field.DbField( 'firstName as name' );
• .field.DbField( 'firstName', 'name' );

Declaration

public Field DbField(string field)

Parameters

Type	Name	Description
System.String	field	Database field name

Returns

Type	Description
Field	Self for chaining

DbType()

Declaration

public DbType? DbType()

Returns

Type	Description
System.Nullable<DbType>

DbType(Nullable<DbType>)

Declaration

public Field DbType(DbType? type)

Parameters

Type	Name	Description
System.Nullable<DbType>	type

Returns

Type	Description
Field

Get()

Get the 'Get' flag for the field.

Declaration

public bool Get()

Returns

Type	Description
System.Boolean	Get flag

Get(Boolean)

Set the 'Get' flag of the field.

A field can be marked as write only by setting the Get property to false

Declaration

public Field Get(bool get)

Parameters

Type	Name	Description
System.Boolean	get	Flag value to set

Returns

Type	Description
Field	Self for chaining

GetFormatter(Func<Object, Dictionary<String, Object>, Object>)

Get formatter for the field's data.

When the data has been retrieved from the server, it can be passed through a formatter here, which will manipulate (format) the data as required. This can be useful when, for example, working with dates and a particular format is required on the client-side.

Editor has a number of formatters available with the

Format

class which can be used directly with this method.

Declaration

public Field GetFormatter(Func<object, Dictionary<string, object>, object> fn)

Parameters

Type	Name	Description
Func<System.Object, Dictionary<System.String, System.Object>, System.Object>	fn	Get formatter that will transform the db value into the http value

Returns

Type	Description
Field	Self for chaining

GetValue()

Get the 'Get' value for the field

Declaration

public dynamic GetValue()

Returns

Type	Description
System.Object	Get value

GetValue(Func<Object>)

Set a "Get" delegate. When set, the delegate given here is executed when the data for the field is requested and the value returned is send to the client-side, regardless of what value is held by the database (if this field even has a database value!)

Declaration

public Field GetValue(Func<object> val)

Parameters

Type	Name	Description
Func<System.Object>	val	Delegate to set for "Get"

Returns

Type	Description
Field	Self for chaining

GetValue(Object)

Set a "Get" value. When set this value is used to send to the client-side, regardless of what value is held by the database. (if this field even has a database value!)

Declaration

public Field GetValue(object val)

Parameters

Type	Name	Description
System.Object	val	Value to set for "Get"

Returns

Type	Description
Field	Self for chaining

Name()

Get the HTTP / JSON name for the field.

The name is typically the same as the DbField name, since it makes things less confusing(!), but it is possible to set a different name for the data which is used in the JSON returned to DataTables in a 'get' operation and the field name used in a 'set' operation.

Declaration

public string Name()

Returns

Type	Description
System.String	Field HTTP name

Name(String)

Set the HTTP / JSON name for the field.

The name is typically the same as the DbField name, since it makes things less confusing(!), but it is possible to set a different name for the data which is used in the JSON returned to DataTables in a 'get' operation and the field name used in a 'set' operation.

Declaration

public Field Name(string name)

Parameters

Type	Name	Description
System.String	name	Name to set

Returns

Type	Description
Field	Self for chaining

Options()

Get the Options object configured for this field

Declaration

public Options Options()

Returns

Type	Description
Options	Options object

Options(Options)

Set the options for this field using an Options instance

Declaration

public Field Options(Options opts)

Parameters

Type	Name	Description
Options	opts	Configured options object

Returns

Type	Description
Field	Self for chaining

Options(Func<List<Dictionary<String, Object>>>)

Set a function that will retrieve a list of values that can be used for the options list in radio, select and checkbox inputs from the database for this field.

Declaration

public Field Options(Func<List<Dictionary<string, object>>> fn)

Parameters

Type	Name	Description
Func<List<Dictionary<System.String, System.Object>>>	fn	Delegate that will return a list of options

Returns

Type	Description
Field	Self for chaining

Options(String, String, IEnumerable<String>, Action<Query>, Func<Dictionary<String, Object>, String>)

Provide database information for where to get a list of values that can be used for the options list in radio, select and checkbox inputs from the database for this field.

Note that this is for simple cases only. For more complex operations use the delegate overload.

Declaration

public Field Options(string table, string value, IEnumerable<string> label, Action<Query> condition = null, Func<Dictionary<string, object>, string> format = null)

Parameters

Type	Name	Description
System.String	table	Table name to read the options from
System.String	value	Column name to read the option values from
IEnumerable<System.String>	label	Column name to read the label values from
Action<Query>	condition	Function that will using the Query class passed in to apply a condtion
Func<Dictionary<System.String, System.Object>, System.String>	format	Formatting function (called for every option)

Returns

Type	Description
Field	Self for chaining

Options(String, String, String, Action<Query>, Func<Dictionary<String, Object>, String>)

Provide database information for where to get a list of values that can be used for the options list in radio, select and checkbox inputs from the database for this field.

Note that this is for simple cases only. For more complex operations use the delegate overload.

Declaration

public Field Options(string table, string value, string label, Action<Query> condition = null, Func<Dictionary<string, object>, string> format = null)

Parameters

Type	Name	Description
System.String	table	Table name to read the options from
System.String	value	Column name to read the option values from
System.String	label	Column name to read the label values from
Action<Query>	condition	Function that will using the Query class passed in to apply a condtion
Func<Dictionary<System.String, System.Object>, System.String>	format	Formatting function (called for every option)

Returns

Type	Description
Field	Self for chaining

SearchBuilderOptions()

Get the SearchBuilderOptions object configured for this field

Declaration

public SearchBuilderOptions SearchBuilderOptions()

Returns

Type	Description
SearchBuilderOptions	SearchBuilderOptions object

SearchBuilderOptions(SearchBuilderOptions)

Set the SearchBuilderOptions for this field using a SearchBuilderOptions instance

Declaration

public Field SearchBuilderOptions(SearchBuilderOptions sbOpts)

Parameters

Type	Name	Description
SearchBuilderOptions	sbOpts

Returns

Type	Description
Field	Self for chaining

SearchBuilderOptions(Func<Object, Object, List<Dictionary<String, Object>>>)

Set a function that will retrieve a list of values that can be used for the SearchBuilderOptions list in SearchBuilders for this field.

Declaration

public Field SearchBuilderOptions(Func<object, object, List<Dictionary<string, object>>> fn)

Parameters

Type	Name	Description
Func<System.Object, System.Object, List<Dictionary<System.String, System.Object>>>	fn	Delegate that will return a list of SearchBuilder options

Returns

Type	Description
Field	Self for chaining

SearchPaneOptions()

Get the SearchPaneOptions object configured for this field

Declaration

public SearchPaneOptions SearchPaneOptions()

Returns

Type	Description
SearchPaneOptions	SearchPaneOptions object

SearchPaneOptions(SearchPaneOptions)

Set the SearchPaneOptions for this field using a SearchPaneOptions instance

Declaration

public Field SearchPaneOptions(SearchPaneOptions spOpts)

Parameters

Type	Name	Description
SearchPaneOptions	spOpts

Returns

Type	Description
Field	Self for chaining

SearchPaneOptions(Func<Object, Object, List<Dictionary<String, Object>>>)

Set a function that will retrieve a list of values that can be used for the SearchPaneOptions list in SearchPanes for this field.

Declaration

public Field SearchPaneOptions(Func<object, object, List<Dictionary<string, object>>> fn)

Parameters

Type	Name	Description
Func<System.Object, System.Object, List<Dictionary<System.String, System.Object>>>	fn	Delegate that will return a list of SearchPane options

Returns

Type	Description
Field	Self for chaining

Set()

Get the "Set" flag for this field

Declaration

public Field.SetType Set()

Returns

Type	Description
Field.SetType	Set flag

Set(Field.SetType)

Set the "Set" flag for this field.

A field can be marked to be set on create, edit, both or none using this method, providing the ability, for example, to write to created and updated datetime columns as appropriate.

Declaration

public Field Set(Field.SetType set)

Parameters

Type	Name	Description
Field.SetType	set	Set flag

Returns

Type	Description
Field	Self for chaining

Set(Boolean)

Set the "Set" flag for this field.

A field can be marked as read only using this option, to be set only during an create or edit action or to be set during both actions. This provides the ability to have fields that are only set when a new row is created (for example a "created" time stamp).

For more control, use the SetType overload.

Declaration

public Field Set(bool set)

Parameters

Type	Name	Description
System.Boolean	set	Set flag

Returns

Type	Description
Field	Self for chaining

SetFormatter(Func<Object, Dictionary<String, Object>, Object>)

Set formatter for the field's data.

When the data has been retrieved from the server, it can be passed through a formatter here, which will manipulate (format) the data as required. This can be useful when, for example, working with dates and a particular format is required on the client-side.

Editor has a number of formatters available with the

Format

class which can be used directly with this method.

Declaration

public Field SetFormatter(Func<object, Dictionary<string, object>, object> fn)

Parameters

Type	Name	Description
Func<System.Object, Dictionary<System.String, System.Object>, System.Object>	fn	Get formatter delegate

Returns

Type	Description
Field	Self for chaining

SetValue()

Retrieve the "Set" value for the field

Declaration

public dynamic SetValue()

Returns

Type	Description
System.Object	"Set" value

SetValue(Func<Object>)

Set a "Set" delegate. When set, the delegate given here is executed when the data for the field is to be written to the database and the value returned is used, regardless of what is sent by the client-side (if the parameter was even sent!).

Declaration

public Field SetValue(Func<object> val)

Parameters

Type	Name	Description
Func<System.Object>	val	Delegate to set for "Set"

Returns

Type	Description
Field	Self for chaining

SetValue(Object)

Set a "Set" value. When set this value is used to write to the database regardless of what data is sent from the client-side (if the parameter was even sent!).

Declaration

public Field SetValue(object val)

Parameters

Type	Name	Description
System.Object	val	Value to set for "Set"

Returns

Type	Description
Field	Self for chaining

Type()

Get the field type

Declaration

public Type Type()

Returns

Type	Description
Type	Type

Type(Type)

Set the data type for the field's values

Declaration

public Field Type(Type t)

Parameters

Type	Name	Description
Type	t	Type

Returns

Type	Description
Field	Self for chaining

TypeError()

Get the type error message

Declaration

public string TypeError()

Returns

Type	Description
System.String	Type error message

TypeError(String)

If the value retrieved from the database can't be cast to the type given, this is the error message that will be given.

Declaration

public Field TypeError(string err)

Parameters

Type	Name	Description
System.String	err	Error message

Returns

Type	Description
Field	Self for chaining

Upload()

Get the Upload instance for this field

Declaration

public Upload Upload()

Returns

Type	Description
Upload	Upload instance

Upload(Upload)

Set the upload instance for this field

Declaration

public Field Upload(Upload upload)

Parameters

Type	Name	Description
Upload	upload	Upload instance

Returns

Type	Description
Field	Self for chaining

Validator(Func<Object, Dictionary<String, Object>, ValidationHost, String>)

Set the 'validator' of the field.

The validator can be used to check if any abstract piece of data is valid or not according to the given rules of the validation function used.

Multiple validation options can be applied to a field instance by calling this method multiple times. For example, it would be possible to have a 'Required' validation and a 'MaxLength' validation with multiple calls.

Editor has a number of validation available with the

Validation

class which can be used directly with this method.

Declaration

public Field Validator(Func<object, Dictionary<string, object>, ValidationHost, string> fn)

Parameters

Type	Name	Description
Func<System.Object, Dictionary<System.String, System.Object>, ValidationHost, System.String>	fn	Validation method

Returns

Type	Description
Field	Self for chaining

Xss(Boolean)

Option to quickly disable XSS formatting.

Declaration

public Field Xss(Boolean flag)

Parameters

Type	Name	Description
Boolean	flag	Enable / disable XSS

Returns

Type	Description
Field	Self for chaining

Xss(Func<String, String>)

Set a formatting method that will be used for XSS checking / removal. This should be a function that takes a single argument (the value to be cleaned) and returns the cleaned value.

Editor will use the Microsoft security library's Encoder.HtmlEncode method by default for this operation, which is built into the software and no additional configuration is required, but a custom function can be used if you wish to use a different formatter such as HtmlSanitizer.

If you wish to disable this option (which you would only do if you are absolutely confident that your validation will pick up on any XSS inputs) simply pass in 'false' or provide a closure function that returns the value given to the function. This is not recommended.

Declaration

public Field Xss(Func<string, string> fn)

Parameters

Type	Name	Description
Func<System.String, System.String>	fn	Xss formatting method

Returns

Type	Description
Field	Self for chaining