Skip to content

Latest commit

 

History

History
73 lines (47 loc) · 6.31 KB

field-control.md

File metadata and controls

73 lines (47 loc) · 6.31 KB
title source_url category version tags
Field Control
Concepts
v6.0
field control
field

Field Control

Although this feature is supported in sensenet 7, it is built on the old Web Forms technology that you should not use for new projects. We encourage you to use a more modern UI solution using our client-side packages.

Field Controls are ASP.Net controls that provide GUI for setting/modifying Field values of a Content. Thus, Field Controls are the basic building blocks of Content Views - views that define the HTML layout of Content when presented.

Content build up of Fields, and Fields are presented with Field Controls when Content are being presented with Content Views. Field Controls provide user interfaces both for displaying and for editing Field values.

Field Controls and Fields

Content Views are displayed on the UI using Portlets. You can connect Field Controls to Content Fields in the Content View, using the Field Controls common FieldName property. This allows different Field Controls to be used with a specific Field. There are pre-defined Field Controls for all available Fields in the system.

Generic Field Control

Each Field defines a default Field Control in the Field implementation that can be used when the Field is displayed in a Content View. Moreover, this default setting given by the developer of the Field can be overridden and set in the Field Setting's ControlHint property. The Generic Field Control is a special Field Control that relies upon the default control setting of the given Field and displays the appropriate control. This means that as a builder you don't necessarily have to search the docs for finding out what Field Controls can be used for the different Fields: simply use the Generic Field Control and the Field will be displayed with the appropriate Field Control.

Field Control modes

A Field Control can be rendered in several modes. There is a switch that defines the layout of the control and another one that controls the behavior of the Field Control:

  • FrameMode: a Field Control can be rendered with a frame containing the Name and Description of the Field, or without it - just the control itself. When set to ShowFrame the frame containing Field metadata is rendered around the control, when set to NoFrame only the control itself is rendered.
  • ControlMode: this switch controls the behavior of the control: the Field Control can either provide a UI to allow modifications to the underlying Field's value, or it can render the Field value in browse mode simply to display the Field value without providing means to modify the value. When ControlMode is set to Edit the control is editable, when set to Browse it presents Field value in a browsable-only mode.

The following table sums up the different Field Control modes on a ShortText Field Control example:

When these properties are not explicitly set in a Content View, these mode switches fall back to the corresponding properties of the containing Content View: ViewControlFrameMode and ViewControlMode for controlling the Field Control's FrameMode and ControlMode respectively. Read this section for a short explanation: Content View.

Field Control Templates

The HTML layout generated by a Field Control is either defined by its implementation or an ascx template. Most built-in Field Controls support templated operation. The Field Control Templates used by the various Field Controls are placed in the /Root/Global/fieldcontroltemplates folder. The Browse.ascx and Edit.ascx views under the folders corresponding to the different Field Controls are the different templates used for different ControlModes. The FrameTemplate.ascx placed in the root folder of Field Control templates is the view that defines the layout for the frame rendered around the Field Controls - this frame holds the Name and Description of the given Field. These global Field Control templates are skinnable, meaning that when a new Skin is created Skin-dependent Field Control templates can be defined for the specific skin. Moreover, templates can also be defined locally, different for each Field Control instance that is used in a Content View.

Validation errors

Basic validation logic is handled by the underlying Field (checks input data against Field Settings, validates data type) but the Field Control can also contain validation logic. Any kind of validation error is displayed next to the Field Control (the FrameTemplate.ascx contains a placeholder label for error messages).

Common properties

The following properties are defined for all Field Controls:

  • FieldName: specifies the underlying Field's name of the Content that is presented with the Content View the Field Control is placed in
  • ControlMode: specifies whether the Field Control should be rendered in Browse or Edit mode. Possible values:
    • Browse: control is rendered in browse mode
    • Edit: control is rendered in edit mode
    • None: ControlMode is determined by the ContentView's ViewControlMode property
  • FrameMode: specifies whether the Field Control should be rendered with enclosing frame containing Field Name and Description. Possible values:
    • NoFrame: enclosing frame should is not rendered
    • ShowFrame: enclosing frame is rendered
    • None: FrameMode is determined by the ContentView's ViewControlFrameMode property
  • ReadOnly: when set to true the Field Control will render a read-only control that cannot be edited from UI

Example

The following source code shows how to place a Field Control in a Content View:

  <sn:ShortText runat="server" ID="ShortTextFullName" FieldName="FullName" />

You can fine-adjust Field Control mode with the following syntax:

  <sn:ShortText runat="server" ID="ShortTextFullName" FieldName="FullName" ControlMode="Browse" FrameMode="NoFrame" />