Field Control

From Sense/Net Wiki
Jump to: navigation, search
  •  
  •  
  •  
  •  
  • 100%
  • 6.0
  • Enterprise
  • Community
  • Planned

Overview

Field Control
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.

Details

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 can be connected to Content 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. Not any kind of Field Control can be used for a certain Field. There are pre-defined Field Controls for all available Fields in the system. The supported Field types for a given Field Control is indicated in the reference documentation of the specific Field Controls:

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 wiki 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 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:

Field Control modes
ControlMode = Browse ControlMode = Edit
FrameMode = NoFrame ReferenceWikiFieldControlBN.png ReferenceWikiFieldControlEN.png
FrameMode = ShowFrame ReferenceWikiFieldControlBS.png ReferenceWikiFieldControlES.png

When these properties are not explicitely 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#Content Views and Field Control modes.

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. Read the reference documentation to learn more:

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/Tutorials

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" />

Find more examples at the reference wiki of each Field Control.

Related links

References