Get Started!

Simple / PlainText Controls

You'll no doubt want to add UI elements that are editable, you can opt to use regular html inputs, but the EDIT mode uses Content Editable HTML to let you create editable elements.

General

There's a ready to use control, PlainText that lets you associate an element on screen with a property on a document in the DataBase for a user to edit.

Here we're looking at how to use the simple mercury region directly, like the PlainText control uses.

What Happens

When we enable EDIT mode, elements marked with the data-mercury attribute, AKA Regions, are made editable. Each region has a form field associated with it. The page is loaded with the HTML value of the editable element populating the form field. When the changes are saved the value of the different editable regions are serialized into each of their associated form fields. These are then POSTed to the server where the values are extracted & stored into the persistent storage.

Attributes

The edit-ability of the element is controlled via HTML attributes.

  • data-mercury="simple" - Set the Mercury region flag

  • data-item-id - The Id of the associated DataItem

  • data-item-type - The DataItem's Full Name

  • data-field - The Client Id of the Form field to carry the value

To reduce pollution of normal page views, we only add these attributes while MODE == "EDIT".

Overrides

As with the pollution of the HTML, we don't want to waste render time populating elements and controls unless we're in the appropriate MODE.

Always

Use the initialize override to perform actions that are common, such as loading and casting the source DataItem.

protected override void initialize()
{
  base.initialize();

  loadDataItem();

  oMyType = oDataItem as MyType;
}

In this example we're assuming that a DataSource has been associated with the control via the designer, the loadDataItem() statement is handling the loading and referencing of the datatype.

During EDIT

Use the initialize_EDIT override to perform actions that are only associated with the EDIT mode.

protected override void initialize_EDIT()
{
  base.initialize_EDIT();

  hField.Value = oMyType.cMainTitle;
}

During SAVE

Use the initialize_SAVE override to perform actions that are only to be undertaken during a SAVE mode.

protected override void initialize_SAVE()
{
  base.initialize_SAVE();

  FixHiddenControl(hField);

  oMyType.cMainTitle = hField.Value;
}

The HTML

You would use HTML like the following to support the above :

<%if ( oMyType == null ) { return; %>

<%if( MODE == "EDIT" ) { %>

  <h1 data-mercury="simple"
      data-item-type="MyApp.Mytypes.MyType"
      data-item-id=<%=oMyType.nId%>"
      data-field="<%=hField.ClientID%>"
      id="main_title"
      ><%=oMyType.cMainTitle%></h1>

  <asp:hiddenfield runat="server"
                   id="hField"
                   clientidmode="autoid">
  </asp:hiddenfield>

<%} else {%>

  <h1>
    <%=oMyType.cMainTitle%>
  </h1>

<%}%>

You can see how the HTML is much cleaner while we're not in EDIT mode.

Also, this is the only time white-space is relevant, Make sure you have no white space between the start, end tags and the value held within. Else this space will be double after each load & save.

The use of the oMyType == null test at the top ensures the control doesn't error if the data item hasn't been found / associated.

Where's the Actual save

You'll notice there's no call to MyApp.DB.MyTypes.Save(oMyType) in the SAVE example above. This is because we've assumed a DataSource has been associated via the designer.

When a DataSource is included in the page and the SAVE mode is executed the DataItem is automatically written to the DB after all of the control's initialize_SAVE methods have been executed. None of the other .net runtime is executed; having saved the request is redirected back into VIEW mode, rendering the regular page to the user editing the content.

If you've not used the Designer to select an associated data item, say you're rendering a listing, in that situation you would need to call Save on the item(s) directly.