Data forms - WilStead/VueCoreFramework GitHub Wiki

When displaying an individual data item (a row) for view or edit, VueCoreFramework utilizes a customized version of vue-form-generator combined with Vuetify controls. For this reason, it will be helpful for you to browse the documentation for each of those libraries (here and here, respectively) if you wish to better understand the material that follows.

Every property on your Entity Framework entity classes which is supported by the database should also be supported by the data forms on the client-side front end. Navigation properties to objects will allow users to manage the relationships, and simple data types will allow well-formatted viewing and editing. VueCoreFramework detects properties by reflecting on the class, not on the Entity Framework entity type, which means that even non-mapped properties will be displayed by VueCoreFramework, allowing you to create computed properties and ViewModel-like logic in your entity classes, if that is how you prefer to structure your code.

Keys (both primary and foreign) are always hidden from the client automatically. If you use a natural key as your primary key that you want to be displayed, it is suggested you create a non-mapped property on your entity class whose getter simply returns the value of your key; VueCoreFramework will pick up that property.

Types

Unless you specify otherwise with property Attributes, as described below, VueCoreFramework will decide what type of field to use to display each property on your entity classes automatically, based on their types.

  • bool - A checkbox.
  • DateTime - A date picker and a time picker (see below if you want to show only one).
  • enum - If your enum type has the FlagsAttribute then it will be represented with a multi-select, allowing the user to select more than one value, which will be combined as usual for flags. If not, it will be represented with a single select. You can set the DisplayAttribute's Name property on individual enum values to give them a friendly display name (e.g. the MyCamelCaseValue value can be displayed as "My Camel Case Value" on the client). See here for a note about how "None" values in an enum are handled by the framework.
  • string - A text field.
  • TimeSpan - A set of numeric text fields. See here for more information.
  • All numeric types - A text field with the numeric type applied (only numbers are accepted as input, and up/down arrows allow spinning the values in addition to direct text input). Unless you specify otherwise (see below) the step value for real types defaults to 0.1, and for integer types it defaults to 1.
  • Any other type is displayed as a non-interactive label. This includes entity types which are not actual navigation properties (such as computed properties which return an entity type).

Attributes

Property attribute decorators allow you to tell VueCoreFramework about each of your properties. While VueCoreFramework will work correctly without them in most cases by using default values, these defaults may not line up with your database schema, so you are advised to carefully read through the documentation below in order to ensure that everything works properly.

CulturalAttribute

Only applicable to text properties of type string, this attribute enables user localization of a property. The property's value will be stored as a stringified JSON object whose keys are culture codes (e.g. "en-US"), with keys equal to the localized value of the property for that culture. The front end client will only display the value appropriate for the user's current culture (which is "en-US" by default, and can be configured in the user's profile). When the user edits a value, the new value will be saved in the JSON object for the current culture, leaving all other localized values intact.

The JSON object will also have a key called "default" whose value will be the culture code used to initially set the value of the property. This default determines which localized value will be returned when a culture is specified which has no value set for the property.

DataTypeAttribute

Can be used to inform VueCoreFramework what type of data a property represents. This is optional in most cases, as VueCoreFramework is able to make a guess based on the property type, but in some cases it can be helpful to make the type explicit.

  • Use a custom type of "Color" to indicate that a string property represents a color. This will cause the property's field on the form to display a color picker rather than a text field. The data will be represented as a 7-character hex string (in the format #000000). Note that this raw string representation will be shown on data tables, which only display text, not rich content like colors. For this reason you are encouraged to use the HideInTable variant of the HiddenAttribute (described above) to avoid this non-user-friendly appearance on tables, although that is up to you.
  • The custom type "Label" can be used on any property to indicate that regardless of its type it should be displayed as a read-only label. Note that the property's ToString value will be used as the text of the label, so if the property's type doesn't have nicely-formatted ToString output, you should consider hiding the property instead, and providing a computed property decorated with the "Label" type which converts its value into a user-friendly string.
  • The Currency type can be used on numeric properties to automatically apply a Step value of 0.01.
  • The Date type indicates that a DateTime property is to use a date picker only, not both date and time pickers.
  • The DateTime type is not really necessary, as VueCoreFramework recognizes DateTime properties automatically, but it is recognized.
  • The Duration type is recognized but unnecessary when applied to a TimeSpan property, since VueCoreFramework recognizes TimeSpan properties automatically. However, it has a special use for long properties. See here for more information.
  • The EmailAddress type applies the email input type to the text field, and email address format validation.
  • The Password type applies the password input type to the text field. Input characters are masked, and a toggle button is provided to show them.
  • The PhoneNumber type applies the telephone input type to the text field, and performs U.S. phone number format validation. The validation is permissive, accepting letters (e.g. 1-800-PHONENO) as well as most forms of "ext", but denies invalid numbers (e.g. too short, too long, or with invalid registers). For fields which accept non-U.S. phone numbers, you should not use this data type; instead, provide your own validation using the ValidatorAttribute described below.
  • The PostalCode type performs U.S. postal code validation on the text field (accepts both short and long variants). For non-U.S. postal code fields, you should not use this data type; instead, provide your own validation using the ValidatorAttribute described below.
  • The ImageUrl and Url types both apply the url type to the text field, but do not perform any sort of validation (it isn't trivial to produce a regular expression that can validate any URL a browser could accept). You are advised to supply your own validation using the ValidatorAttribute described below, if you need to restrict input to valid URLs.
  • The Time type indicates that a DateTime property is to use a time picker only, not both date and time pickers.
  • No other data types are recognized, and the framework will treat unrecognized types as plain text fields. For this reason, unless you are specifying one of the above types, you are advised to leave the DataTypeAttribute off and let the framework decide on the correct field type based on the property's actual type.

DisplayAttribute

Used to control the decoration of a property's field on the form.

  • GroupName - As you would expect, this will group all properties which share the same group name together on the form under that name as a heading.
  • Name - This sets a label for the field (but see below!).
  • Prompt - This sets placeholder text for most field types. Note that text fields, checkboxes, selects, and date/time controls all use placeholder text as both placeholder and label (see the Vuetify documentation for text fields for an example of how this works). For these fields, if you also set a label using Name, it will appear above the field as a sort of heading, with the placeholder text appearing below it. Therefore, you should not set both a label and placeholder text for these types of fields, unless you intend to have both.
  • Description - This sets hint text for the field, which appears below it (usually only when the field has focus).

EditableAttribute

Can have its AllowEdit property set to false to indicate that a field is read-only (or disabled, depending on the field type).

HelpAttribute

Used to set help text which is displayed over a field on hover (vs. the hint text which appears below it on focus).

HiddenAttribute

Can be applied to a property to indicate that it should not be shown on the client front-end. You can also apply the property with a false constructor parameter and set the HideInTable property in order to indicate that the property can be shown on detail forms for viewing and editing individual items, but shouldn't be shown on data tables.

IconAttribute

Can be applied to any property which is displayed with a text field (including non-string properties which use text fields, such as numeric types), bool properties, and enum properties. Its Icon property accepts a string which must be the name of a Material Icon (replace spaces with underscores). This icon will be displayed on the left side of the field.

NameAttribute

Can be applied to any property to indicate that it is the name of the data item. This signals VueCoreFramework that this property is to be treated like a sort of heading for the item: it will be pulled to the top of the form, and to the left-most column on data tables.

NavigationAttribute

Can be applied to any non-collection navigation property to manage the controls shown on its field. Setting its NavigationType property to "reference" restricts the field to displaying only view/edit controls (no add, select, or delete controls, even if the relationship would normally allow these). Setting it to "single" restricts the field to displaying only add, delete, and view/edit controls (no select control even for many-to-one relationships).

Note that you cannot add controls to relationships which don't normally support them; this attribute merely allows you to remove ones which you do not want to allow. Note also that this attribute has no effect on collection navigation properties. Applying it will not replace their usual, specialized data table controls with the simple buttons used for a single-object navigation property.

RangeAttribute

Can be used to set the minimum and maximum values accepted in most field types. For most text fields, this indicates the minimum and maximum string lengths accepted. For numeric text fields, it indicates the minimum and maximum values accepted. For DateTime fields it indicates the earliest and latest date/times allowed. For duration-type fields, it indicates the shortest and longest durations accepted (as TimeSpan strings; negative values are allowed). Other field types ignore range.

StepAttribute

Can be used on a numeric property to indicate the step value used when the up/down spinners are used, and to define the smallest precision accepted by the text field. Can also be used for duration-type properties to indicate the step for the seconds field (if used). Note that although TimeSpan Ticks allow a much smaller precision, the fields used for durations in VueCoreFramwwork use moment.js internally, which means the minimum precision that will actually be preserved for a duration is milliseconds (0.001).

TextAttribute

Can be applied to any property which is displayed with a text field (including non-string properties which use text fields, such as numeric types). It has a number of optional properties which allow you to customize the display of the text field:

  • Prefix and Suffix - These accept strings which will be included before and after the input area of the text field. This can be used, for example, to include a "$" before a currency input field, or "(per day)" at the end of a numeric text field.
  • Rows - This property accepts an integer, and is used to indicate the number of rows in a textarea. Any amount greater than 1 will convert the text field into a textarea. Rows is ignored for text fields with the number input type.

ValidatorAttribute

Its Validator property accepts a string which must match a key on the validators object in ClientApp/vfg/vfg-custom-validators.ts, a map to known default validators or to validator functions. See the documentation for vue-form-generator for more information.