wordpress-mobile/azteceditor-ios

A reusable native iOS visual HTML text editor component.

Aztec for iOS: Native HTML Editor

About Aztec & WordPressEditor

Aztec is a Swift library that provides a UITextView subclass with HTML visual-editing capabilities.

• Use this library if you want to create an App that interacts with raw HTML content.

WordPressEditor is a Swift library that provides a plugin to make Aztec work with WordPress content.

• Use this library if you want to create an App that interacts with WordPress HTML content.

Requirements

• iOS 11 and above
• Xcode 12 and above

Running the Example App

To run the Example app, you first open the file Aztec.xcworkspace from the root directory of Aztec.

Make sure the AztecExample target it selected, and press CMD + R to run it.

Integrating the Library with Carthage

Both libraries are available through Carthage. To install it, simply add the following line to your Cartfile:

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

Follow these instructions to add Aztec.framework or WordPressEditor.framework to your App.

Then:

1. Open your project, head to Build Settings for your target and add $(SDKROOT)/usr/include/libxml2/ to your Header Search Paths.
2. Go to Build Phases > Link Binary With Libraries and add Aztec.framework.
3. Add import Aztec to your project's source.

Integrating the Library with CocoaPods

Both libraries are available through CocoaPods. To install them, simply 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"

Usage

After installing Aztec, import the module and use the Aztec.TextView view as shown below:

import Aztec

// ...

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

Contributing

Read our Contributing Guide to learn about reporting issues, contributing code, and more ways to contribute.

Getting in Touch

If you have questions about getting setup or just want to say hi, join the WordPress Slack and drop a message on the #mobile channel.

License

AztecEditor-iOS and WordPress-Editor-iOS are open source projects covered by the Mozilla Public License Version 2.0.

azteceditor-ios's Issues

Evaluate performance issues.

I'm seeing performance issues when copy-pasting the full range of text.

Evaluate and improve Aztec's performance.

Image layout problem

There's a problem in when we're invalidating the layout when adding images. This causes the app to sometimes show errors in the log, and sometimes crash.

How to reproduce:

Repeat the exact steps from this video.

Make the demo App load a sample HTML file.

Title has it. Formatting should work for the following types:

• Bold
• Italic
• Underline
• Strikethrough

Initial Editing Logic for Bold

We need to implement the logic to update the DOM data whenever an edit takes place. The best way to start is by focusing on the full editing logic for a singly style, in order to tackle the problem atomically.

We should expect this code to be reusable for other styles.

Scenarios to handle:

• Toggling Bold
  • When the full selection text is bold.
  • When the full selection text is non-bold.
  • When the full selection text is mixed.

Link Editing (in Demo App)

Add link editing to the Demo App.

Master Issue: Media (in WPiOS).

Add media support in WPiOS. It doesn't really need to access any services at all. It only needs to emulate uploading and all media interactions just like the old editor did (we can use it for reference).

Tasks:

• Media picker
• Upload pictures
• Upload videos
• Cancel uploads in progress
• Edit meta-data

Self closing tags are not being written properly

If you have html content with tags that are self closing/empty tags like this:

<img src="a.jpg" />
<br/>

they get converted back to

<img src="a.jpg">
<br>

and even if you have something like this:

<img src="a.jpg">Imagem</img>

It gets converted to

<img src="a.jpg">

Remove extra spacing and invisible characters from certain HTML tags.

HTML tags can come with extra spacing and invisible characters that should be trimmed (in most cases).

For example:

<html><body>

hello

</body></html>

Should be rendered as hello.

Copy / Paste support for lists.

Implement copy / paste support for lists.

Master Issue: Import Component.

Master issue for the HTML import component.

• Define the parsing library we're going to use. (libxml2... read here)
• Parse from HTML to an internal representation of HTML.
  • Write basic implementation.
  • Handle HTML attributes.
  • Complete unit tests coverage.
• Parse from the internal representation of HTML into NSAttributedString.
  • Write basic implementation.
  • Handle HTML attributes.
  • Complete unit tests coverage.

HTML-mode editing (in Demo App).

Title has it. This is scoped for the Demo App only.

Selection causes the default font to change.

There's a very weird bug that's causing the Visual Editor default font to change, if you select a styled text-range and switch to HTML and back to Visual.

Video showing the issue here.

Blockquote support.

Add blockquote support to the editor.

Task list:

• #143 Improve caret calculation
• #144 Caret disappears on new line
• #145 Custom attributes removed on new line
• DOM implementation

Duplicated tags when editing.

When editing styled text, we're getting duplicated tags.

Video here.

Smart tag grouping & reorganization when adding or removing tags.

When adding a tag to the DOM, we need to reduce tag fragmentation to the minimum. This implies that nodes need to be added in a "smart" way.

The following is an example showing the selected text wrapped by [ and ].

<em>Hello there<u>[ man!</u> How are you?]</em>

After applying bold, the non-smart result would be:

<em>Hello there<u><b> man!</b></u><b> How are you?</b></em>

The smart result we must achieve is:

<em>Hello there<b><u> man!</u> How are you?</b></em>

Master Issue: Initial GUI (in WPiOS)

This is the master thread for all things GUI in WPiOS.

• Basic GUI.
  • Show an editable title field.
  • Show an editable content view.
• Toolbar.
  • Make the toolbar come up on top of the keyboard when editing.
  • Enable the bold button.
  • Enable the italic button.
  • Enable the underline button.
  • Enable the strikethrough button.
  • Enable the blockquote button.
  • Enable the ordered list button.
  • Enable the unordered list button.
  • Enable the link button.
  • Enable the media button.

Demo App: you should be able to cancel editing image attributes.

When in the image-attributes VC: there should be an option to cancel editing image attributes, that closes the VC without it affecting the HTML.

Copy / Paste support.

Add copy / paste support.

Shortcode support discussion.

We want to have shortcode parity with the existing WPiOS HTML editor.

This ticket is open for discussion, I'll create a new one once we can agree to a more precise specification.

Here's the list of shortcodes that WordPress.com supports.

Improvements for lowestTextNodeWrapping(range: NSRange)

Here's a list of some possible improvements for this method:

1. The method should be able to cope with a result covering multiple TextNodes.
2. The method should return the intersection range (the localized subrange) for each TextNode.
3. We now have some ElementNodes at the bottom level. Evaluate if we need to include them too in the results of this method.

This method can serve as inspiration on how to store the return value.

Crash when adding a new line at the end of a div tag

If you tap return at the end of a div, Aztec will crash.

Fake upload demo in the Example App.

We should add a fake-upload demo in the example app. It'd allow the user to test cancelling uploads, and it'd allow us to make sure we have everything in place to offer support for real uploads.

HTML comments are being converted to element nodes

If you have html like this:

<!-- This is a comment --!>

It gets converted to

<comment></comment>

Copy / Paste Support for Blockquotes

Implement copy / paste support for blockquotes.

Ordered and unordered lists.

Enable the lists button and add the logic to edit lists in the editor. List behavior is as follows:

Toolbar:

• OL button should highlight when cursor is in an order list
• UL button should highlight when cursor is in an unordered list

Tapping a List Button:

• Scenario 1: When the cursor is in a plain paragraph:
  Should create a new list, and turn the whole paragraph into a list item.
• Scenario 2: When the cursor is in a list of the same type:
  Should turn the item into a plain paragraph. Following list items should be renumbered.
• Scenario 3: When the cursor is in a list of a different type:
  Should change the type of the entire list, and update the list markers appropriately.
• Scenario 4: When the selected text starts with a paragraph then intersects a list of the same type:
  Should add the non-list text to the list and update the item numbering.
• Scenario 5: When the selected text starts with a paragraph then intersects a list of a different type:
  Should create a new list from the selected paragraph, but do not make changes to the other list.
• Scenario 6: When the selected text starts with a list of the same type and intersects a non-list paragraph:
  Should Remove the list.
• Scenario 7: When the selected text starts with a list of a different type and intersects a non-list paragraph:
  Should change the type of the list and update its numbering, but make no changes to the non list paragraph.

Selection:

• Scenario 1: Whenever there was no previous selected text (just the cursor blinking on a line), and a List was applied, the cursor should shift to match the spot at which it was previously located. In another words: we should apply a delta, to consider the new Text Marker.
• Scenario 2: Whenever a list is applied over a Selected Range, we should expand the selection to consider any length-deltas, caused by Text Markers.

Cursor:

• If the current selection intersects a list marker, adjust the selection so it does not intersect the marker. Move the cursor forward or backward depending on the previous cursor location.

Typing:

• Apply the current list and list item custom attributes to newly typed text (keyboard input does not automatically assign custom attributes.)

Carriage returns:

• When there is a carriage return inside a list. Insert a new list marker. Update the numbering of any following items.
• When the cursor is on an empty list item (just the marker and no other text) and a carriage return is added. Remove the empty list item, and insert a normal paragraph in its place. If there are any following list items, replace those items with a new list and new item numbering.

Backspace / Delete:

• When a backspace would intersect a list marker, delete the entire list marker + the carriage return of the preceding list item (if any). If the current list item still had text, merge the remaining text with the previous list item. Update the numbering for any following items.

Integrate Aztec pod into WPiOS.

Title has it.

Add app setting for enabling Aztec in WPiOS

Add an app setting (available only in DEBUG builds) to enable Aztec in WPiOS.

Editing an empty HTML input breaks the editor.

If you try to start editing in the demo app without loading the sample content and loading an empty string instead, the editor has several issues breaking it.

You can test this in branch issue/53-editing-blank-content

The editor is crashing when editing between two image nodes.

When trying to edit in visual mode between images, the app crashes.

See this video showing the crash.

Props to @SergioEstevao for finding this one.

Feature flag Aztec in WPiOS.

Feature flag Aztec in WPiOS so that it works as a hidden feature.

I'm adding some tentative requirements, but feel free to re-engineer.

Requirements:

• By default Aztec must be hidden / disabled.
• We should have a URL to enable the option to show Aztec in App Settings (only in debug mode).
• The App Settings editor option should probably be a combo instead of a switch. (feel free to disagree and implement differently)
• Once enabled in App Settings a placeholder VC must be shown whenever creating a new post. It's enough for the VC to show a centered text reading "Aztec Editor Placeholder".
• All this code should be enabled in DEBUG mode only. We don't want our users accessing this feature yet.

Store the caret position when switching editing modes.

The caret position should be maintained when switching modes.

Since we have pretty good mechanisms for range matching between HTML and visual mode, we could also use this to match a position.

Text editing support

Text editing right now works partially.

What works:
It works perfectly in HTML mode and reflects the changes when switching to visual mode.

What doesn't work:
When editing in visual mode the changes are not reflected after switching to HTML mode.

Master Issue: Media (in Demo App).

Add media support in the demo app. It doesn't really need to access any services at all. It only needs to emulate uploading and all media interactions just like the old editor did (we can use it for reference).

Tasks:

• Media picker
• Show media inline
• Resize Media to fit screen
• Upload pictures
• Upload videos
• Cancel uploads in progress
• Edit meta-data
• Load media from HTML
• Save media to HTML

Copy / Paste Support for images.

Implement copy / paste support for images.

Image upload support.

The editor should provide the necessary tools to cope with the result of image uploads.

The upload will be handled by the parent application, but the editor should provide all the necessary interfaces to replace local images with remote ones when necessary.

Master Issue: Initial GUI (in Demo App)

This is the master thread for all things GUI in the Demo App.

• Basic GUI.
  • Show an editable title field.
  • Show an editable content view.
• Toolbar.
  • Make the toolbar come up on top of the keyboard when editing.
  • Enable the bold button.
  • Enable the italic button.
  • Enable the underline button.
  • Enable the strikethrough button.
  • Enable the blockquote button.
  • Enable the ordered list button.
  • Enable the unordered list button.
  • Enable the link button.
  • Enable the media button.

Initial Editing logic for Strike-through

Implements style editing for strikethrough. The result should affect the HTML output.

Scenarios to handle:

• Toggling strikethrough
  • When the full selection text is strikethrough.
  • When the full selection text is not striked-through.
  • When the full selection text is mixed.

Set up BuddyBuild.

Set up BuddyBuild so we can distribute the Example application to testers.

/fyi @sendhil

Smart text nodes.

Typing between two non-editable elements in visual mode is not creating the necessary text node in-between.

There's an example video here.

Editing img attributes overrides any custom class attributes

After editing image attributes on the editor, any custom class attributes on the img node will be removed.

Wire exporter to the demo app.

Wire the exporter to the demo app, so we can test exporting our changes to a post.

When "saving" a post, a new VC should be pushed, showing a text view with the post's raw HTML. There's no need to make it editable.

This can also be used to implement the HTML mode.

Initial Editing Logic for Underline

Implements style editing for underline. The result should affect the HTML output.

Scenarios to handle:

• Toggling underline
  • When the full selection text is underline.
  • When the full selection text is non-underline.
  • When the full selection text is mixed.

Initial Editing Logic for Italic

Implements style editing for Italic. The result should affect the HTML output.

Scenarios to handle:

• Toggling Italic
  • When the full selection text is Italic.
  • When the full selection text is non-Italic.
  • When the full selection text is mixed.

Links are not being update correctly in HTML

How to reproduce:

• Start demo app and go to editor demo
• Tap on one of the HTML links in the editor
• Tap on the Link button on the toolbar
• Edit the current link, changing the title and/or the url
• The attributed string is changed correctly
• But the DOM gets messed up, basically it deletes the text content inside the tag.

Convert paragraphs to double line breaks.

Convert HTML paragraphs to double line breaks in HTML mode so that the user doesn't need to edit <p> tags.

The inverse conversion should also take care of generating paragraphs wherever it detects double line breaks.

This should be an optional conversion setting, since other editors could prefer to use regular paragraph elements.

Image alignment and size aren't updated automatically after change is done.

Master Issue: Export Component.

Master issue for the HTML export component.

• Parse from NSAttributedString to an internal representation of HTML.
  • Write basic implementation.
  • Handle HTML attributes.
  • Complete unit tests coverage.
• Parse from the internal representation of HTML to HTML.
  • Write basic implementation.
  • Handle HTML attributes.
  • Complete unit tests coverage.

Proofread Writing in Aztec.

Look for alternatives to add Proofread Writing to Aztec.

References:

• Calypso's Proofread Writing feature.
• http://www.afterthedeadline.com

Copy / Paste support for links.

Implement copy / paste support for links.

Undo / Redo support.

There's a partially-working undo support in Aztec, however the DOM structure is not properly re-created when performing more complex undo / redo operations.

Make sure full support is added.