Aztec Editor iOS

The repository provides two distinct libraries depending on your content requirements:

• Aztec: A Swift library providing a UITextView subclass with HTML visual-editing capabilities. Use this if your app interacts with raw HTML content.
• WordPressEditor: A Swift library that provides a plugin to make Aztec work specifically with WordPress HTML content. Use this if your app interacts with WordPress-specific HTML.

The TextView class is the central entry point for UI integration. It is a UITextView subclass that manages:

• Attribute Maintenance: Keeps track of custom NSAttributedString attributes and attachments (like images or videos) during user edits.
• Formatting: Handles character attributes (bold, italic) via AttributeFormatter and paragraph attributes (lists, blockquotes, headings) via ParagraphAttributedFormatter using the toggle(formatter, atRange) method.
• Embeds: Manages NSTextAttachment subclasses like MediaAttachment and RenderableAttachment. You can insert embeds using replace(at:NSRange, with: NSTextAttachment).
• User Interaction: Automatically handles complex editing scenarios like line breaks, deleting list items, and managing indents for lists and quotes.

The conversion from NSAttributedString back to HTML follows this pipeline:

1. Parsing: AttributedStringParser iterates through the NSAttributedString (paragraph by paragraph) and uses StringAttributesConverters and AttachmentConverters to reconstruct a DOM tree.
2. Simplification: The parser traverses the DOM tree to merge nodes and create a simplified version.
3. Serialization: HTMLSerializer transforms the simplified DOM tree into the final HTML string.

Aztec is composed of two primary systems that can be used independently or together:

1. TextView: A UI component (subclass of UITextView) used for the presentation and editing of HTML content.
2. HTML Converters: Logic used to transform raw HTML strings into NSAttributedString objects and vice-versa.

When used together via the TextView class, the system maintains custom NSAttributedString attributes and attachments as the user edits, ensuring the underlying content remains a valid HTML representation.

The conversion from HTML to NSAttributedString follows this pipeline:

1. Parsing: HTMLParser uses the libXML2 library to transform raw HTML text into an in-memory XML DOM node tree.
2. Serialization: AttributedStringSerializer converts the DOM tree into an NSAttributedString.

During this process, specialized Converter classes (like ImageElementConverter or LIElementConverter) map specific HTML elements to custom attributes or attachments. The resulting NSAttributedString contains special attributes:

• HTMLRepresentation: Stores the original HTML elements and attributes.
• ParagraphStyle: A subclass of NSParagraphMutableStyle that represents element hierarchies (e.g., nested lists or blockquotes).

If you need to update the reference PNG images used in tests, you can generate new ones by writing the UIImagePNGRepresentation of an image to a specific file path. This is typically done while a breakpoint is active in the test execution environment to ensure the correct file system context is available.

UIImagePNGRepresentation(image).write(to: URL(fileURLWithPath: "some/path"))

Add the following lines to your Podfile:

pod "WordPress-Aztec-iOS", "1.0" # or the version number you want
pod "WordPress-Editor-iOS", "1.0"

Add the package URL https://github.com/wordpress-mobile/AztecEditor-iOS to your package dependencies.

Note: SPM support was added in version 1.20.0. Tags prior to this version will fail to resolve in SPM.

You can also add the repository URL directly via the Xcode interface.

let package = Package(
    name: "YourPackage",
    products: [
        .library(name: "YourLibrary", targets: ["YourTarget"]),
    ],
    dependencies: [
        .package(url: "https://github.com/wordpress-mobile/AztecEditor-iOS", .upToNextMajor(from: "1.20.0")),
    ],
    targets: [
        .target(
            name: "YourTarget",
            dependencies: [
                .product(name: "Aztec", package: "AztecEditor-iOS"),
                .product(name: "WordPressEditor", package: "AztecEditor-iOS"),
            ]
        ),
    ]
)

Add the following lines to your Cartfile:

github "wordpress-mobile/AztecEditor-iOS" "1.0" # or the version number you want
github "wordpress-mobile/WordPressEditor-iOS" "1.0"

After running Carthage, follow these steps to integrate the frameworks into your project:

1. In your target's Build Settings, add $(SDKROOT)/usr/include/libxml2/ to your Header Search Paths.
2. In Build Phases > Link Binary With Libraries, add Aztec.framework.
3. Use import Aztec in your Swift source files.

The HTMLConverter class provides the main API for data conversion. Use these methods to bridge the gap between raw HTML strings and rich text objects:

• HTML to NSAttributedString: Use attributedString(from:html, defaultAttributes) to convert an HTML string into an NSAttributedString object.
• NSAttributedString to HTML: Use html(from:NSAttributedString, pretify) to convert an NSAttributedString back into an HTML string.

// Convert HTML to NSAttributedString
let attributedString = HTMLConverter.attributedString(from: htmlString, defaultAttributes: myDefaults)

// Convert NSAttributedString to HTML
let htmlString = HTMLConverter.html(from: attributedString, pretify: true)

After installing and importing the Aztec module, you can instantiate an Aztec.TextView to provide visual HTML editing. The initializer requires a default font, a paragraph style, and a default image for missing images.

import Aztec

// ...

let textView = Aztec.TextView(
    defaultFont: UIFont,
    defaultParagraphStyle: ParagraphStyle = ParagraphStyle.default,
    defaultMissingImage: UIImage) {
    // ...
}