Images

A logo, or a file that the user uploads, gets into a document through the JavaScript API of the Document Editor: inline in the text, anchored to a paragraph or at a fixed position on a page. Your code also scales, aligns, describes and removes the image a user has selected, in addition to what the image tools of the ribbon offer.

The examples extend the view of the ASP.NET Core tutorial.

How Images Are Placed

An image can be placed in the document in three ways:

TXTextControl.images returns the ImageCollection of the text part that has the input focus: the main text, a header or footer, or a text frame.

For anchored and fixed images, a value of ImageInsertionMode decides how the image and the text share the space:

Insert an Image From a File

All methods that insert an image take the image data as a Base64-encoded string, not a file name or URL. In the browser, the FileReader API reads a file that the user selects and returns it as a data URL, which contains the Base64 data after a comma.

The following code inserts the selected image file inline at the input position, or anchored and right-aligned with the text flowing around it. Add it below the editor in Views/Home/Index.cshtml:

<input type="file" id="imageFile" accept="image/*" />
<input type="button" onclick="insertInlineImage()" value="Insert Inline Image" />
<input type="button" onclick="insertAnchoredImage()" value="Insert Anchored Image" />

<script>
    // Reads the selected file and passes its Base64 data to the callback
    function readImageFile(callback) {
        var file = document.getElementById("imageFile").files[0];
        if (!file) {
            return;
        }

        var reader = new FileReader();
        reader.onload = function () {
            // Keep only the Base64 data after the comma of the data URL
            callback(String(reader.result).split(",")[1]);
        };
        reader.readAsDataURL(file);
    }

    function insertInlineImage() {
        readImageFile(function (base64) {
            // -1 inserts the image at the current input position
            TXTextControl.images.addInline(base64, -1, function (image) {
                image.setName("logo");
                image.setDescriptiveText("Company logo");
            }, function (error) {
                console.log(error.msg);
            });
        });
    }

    function insertAnchoredImage() {
        readImageFile(function (base64) {
            TXTextControl.images.addAnchored(base64,
                TXTextControl.HorizontalAlignment.Right,
                -1,
                TXTextControl.ImageInsertionMode.DisplaceText,
                function (image) {
                    image.setDescriptiveText("Product photo");
                },
                function (error) {
                    console.log(error.msg);
                });
        });
    }
</script>

The code works as follows:

• addInline takes the Base64 data and the text position. The value -1 stands for the current input position. The callback receives the new Image, and the error callback receives an error message in msg.
• addAnchored also takes the horizontal alignment within the paragraph, a value of HorizontalAlignment, and the insertion mode.
• setName gives the image a name, so that your code can find it later with getItemByName.
• setDescriptiveText sets the alternative text that screen readers use. An accessible PDF document is only fully compliant when its images have one.

Select an image file, click into the document and click one of the buttons. Supported File Formats lists the image formats of TX Text Control, including SVG.

To place an image at a fixed position, addAtFixedPositionOnPage takes a page number and a location on the page, and addAtFixedPositionInDocument a location relative to the top left corner of the document, where the gaps between the pages count as well. Both take the location as an object with x and y. addAtFixedPosition without a suffix is obsolete.

Change the Selected Image

When a user clicks an image, the editor selects it and shows the contextual Frame Formatting tab, in which users wrap text around the image, position and size it and set its name, ID and descriptive text:

ImageCollection.getItem without an ID passes the image the user has selected, or null. The following code scales it to half its size and removes it:

<input type="button" onclick="scaleSelectedImage()" value="Scale to 50%" />
<input type="button" onclick="removeSelectedImage()" value="Remove Image" />

<script>
    function scaleSelectedImage() {
        TXTextControl.images.getItem(function (image) {
            if (image === null) {
                console.log("Select an image first.");
                return;
            }

            // The size of an image is changed by scaling it
            image.setHorizontalScaling(50, function () {
                image.setVerticalScaling(50, function () {
                    image.getSize(function (size) {
                        console.log("New size: " + size.width + " x " + size.height + " twips");
                    });
                });
            });
        });
    }

    function removeSelectedImage() {
        TXTextControl.images.getItem(function (image) {
            if (image !== null) {
                TXTextControl.images.remove(image);
            }
        });
    }
</script>

• setHorizontalScaling and setVerticalScaling set the scaling in percent. For images, the size can't be set directly: setSize is read-only for them.
• getSize passes the size in twips as an object with width and height.
• ImageCollection.remove removes the image from the document.

Other Image Properties

An Image inherits the members of FrameBase, which images share with other objects in the document, such as text frames and barcodes:

To let users select an image that lies behind the text with a mouse click, call setSelectObjects with true.

React to Image Events

The editor raises imageCreated, imageDeleted, imageSelected and imageDeselected. Their handlers receive ImageEventArgs, whose image property contains the ID, name, location and text position of the image:

TXTextControl.addEventListener("textControlLoaded", function () {
  TXTextControl.addEventListener("imageSelected", function (e) {
    console.log("Image selected: " + e.image.name);
  });
});

Events lists the events for frames in general, such as frameMoved and frameSized.

Next Steps

• Shapes: text frames, drawings and other objects in the document.
• Tables: insert and format tables.
• Images in Mail Merge and Reporting: fill image placeholders of a template with data.
• Images in Document Processing: add images on the server with ServerTextControl.