Insert HTML

C1Editor provides asynchronous APIs for inserting HTML content before, after, or inside existing document elements.

These APIs support dynamic document editing scenarios such as template generation, mail merge workflows, contextual annotations, generated content insertion, and UI-driven document composition.

Content can be inserted by targeting elements through:

Element ID
HTML tag name
CSS class name

When targeting by tag name or class name, the operation applies to all matching elements in the document.

Supported Operations

The HTML insertion APIs support:

Inserting content before an element
Inserting content after an element
Inserting content inside an element
Replacing existing element content
Targeting elements by ID, tag, or class
Applying insertions to multiple matching elements
Inserting plain text or HTML fragments

Insert Content Before an Element

InsertBeforeElementAsync inserts content immediately before the target element.

The following example inserts content before an element identified by ID.

await c1Editor1.InsertBeforeElementAsync(    "_InsertBefore_",
    elementId: "insert-before-target");

C1WinForms Editor - Inserting content before an element

Insert Content After an Element

InsertAfterElementAsync inserts content immediately after the target element.

The following example inserts content after an element identified by ID.

await c1Editor1.InsertAfterElementAsync(    "_InsertAfter_",
    elementId: "insert-after-target");

C1WinForms Editor - Inserting content after an element

Insert Content Inside an Element

InsertIntoElementAsync inserts content inside the target element.

Insertion behavior is controlled through ContentInsertMode.

Mode	Description
`First`	Inserts content at the beginning of the element
`Last`	Inserts content at the end of the element
`Replace`	Replaces the existing element content

The following examples demonstrate how to insert content at the beginning of an element, append content to the end of an element, and replace existing element content using InsertIntoElementAsync.

C1WinForms Editor - Inserting content inside an element

Insert Content at the Beginning of an Element

await c1Editor1.InsertIntoElementAsync(
    "_InsertInto_First_",
    ContentInsertMode.First,
    elementId: "sentence-3");

Insert Content at the End of an Element

await c1Editor1.InsertIntoElementAsync(
    "_InsertInto_Last_",
    ContentInsertMode.Last,
    elementId: "sentence-4");

Replace Existing Element Content

await c1Editor1.InsertIntoElementAsync(
    "_InsertInto_Replace_",
    ContentInsertMode.Replace,
    elementId: "replace-target");

Element Targeting

Target elements can be identified using the following parameters.

Target Type	Description
`elementId`	Targets a specific element by ID
`elementTag`	Targets all matching HTML tags
`elementClass`	Targets all elements with the specified CSS class

Note: When multiple target parameters (elementId, elementTag, and elementClass) are specified, all provided parameters must match the same element. The parameters are evaluated together and are not treated as alternative matching criteria.

The following example inserts content before an element that matches the specified ID, tag name, and CSS class:

await c1Editor1.InsertBeforeElementAsync(
    "InsertBeforeTarget",
    elementId: "combined-target",
    elementTag: "span",
    elementClass: "highlight");

Asynchronous Processing

All HTML insertion APIs execute asynchronously to help maintain UI responsiveness during document updates.

This behavior is particularly useful when:

Working with large documents
Updating multiple matching elements
Performing repeated document modifications

Use async and await when calling insertion APIs.

HTML Fragment Support

Inserted content can include:

Plain text
HTML fragments
Nested HTML elements

The following example inserts formatted HTML content before a target element.

string imageHtml =
    "<img src='sample.png' " +
    "alt='Preview Image' " +
    "style='max-width:600px;' />";

await c1Editor1.InsertBeforeElementAsync(
    imageHtml,
    elementId: "target");

HTML fragments are inserted directly into the document structure. Applications should ensure that generated HTML content is valid and properly encoded before insertion.

Limitations

Limitation	Description
HTML validation is not performed	Invalid HTML fragments may produce unexpected document structure or formatting
Bulk operations affect all matches	Tag-based and class-based targeting can modify multiple elements simultaneously

Sample Code

The following example initializes C1Editor, loads an HTML document, and inserts content into target elements through button actions.

public partial class Inserts : UserControl
{
    public Inserts()
    {
        InitializeComponent();
        c1Editor1.C1EditorReady += c1Editor1_C1EditorReadyAsync;
        c1Editor1.ClientSizeChanged += C1Editor1_Resize;
        c1Editor1.SizeChanged += C1Editor1_Resize;
    }

    private void C1Editor1_Resize(object sender, EventArgs e)
    {
        c1Editor1.Focus();
    }

    private async void c1Editor1_C1EditorReadyAsync(object sender, EventArgs e)
    {
        string filename = @"Resources\PageForInserts.html";
        if (File.Exists(filename))
        {
            await c1Editor1.LoadDocumentAsync(Path.GetFullPath(filename));
            await c1Editor1.SetDefaultStylesAsync(null, true);
        }
    }

    private async void btnInsertBefore_Click(object sender, EventArgs e)
    {
        await c1Editor1.InsertBeforeElementAsync("_InsertBefore_", elementId: "insert-before-target");
    }
  
    private async void btnInsertAfter_Click(object sender, EventArgs e)
    {
        await c1Editor1.InsertAfterElementAsync("_InsertAfter_", elementId: "insert-after-target");
    }
  
    private async void btnInsertIntoFirst_Click(object sender, EventArgs e)
    {
        await c1Editor1.InsertIntoElementAsync("_InsertInto_First_", C1.Win.Editor.ContentInsertMode.First, elementId: "sentence-3");
    }
  
    private async void btnInsertIntoLast_Click(object sender, EventArgs e)
    {
        await c1Editor1.InsertIntoElementAsync("_InsertInto_Last_", C1.Win.Editor.ContentInsertMode.Last, elementId: "sentence-4");
    }
  
    private async void btnInsertIntoReplace_Click(object sender, EventArgs e)
    {
        await c1Editor1.InsertIntoElementAsync("_InsertInto_Replace_", C1.Win.Editor.ContentInsertMode.Replace, elementId: "replace-target");
    }
}