# PRO HTML Paste Processing Plugin from MSWord

Users paste a lot from Word and Excel. Jodit HTML Editor cleans up all unnecessary code and makes HTML just beautiful.

This plugin provides enhanced functionality for pasting content from Microsoft Word and Excel, ensuring clean and properly formatted HTML output.

## Options

### pasteFromWord.enable

- Type: `boolean`
- Default: `false`

Enables or disables the paste from Word processing functionality. By default, this feature is disabled and needs to be explicitly enabled.

```js
Jodit.make('#editor', {
	pasteFromWord: {
		enable: true
	}
});
```

### pasteFromWord.convertUnitsToPixel

- Type: `boolean`
- Default: `false`

When enabled, this option converts all units (cm, pt, etc.) to pixels in the pasted content.

```js
Jodit.make('#editor', {
	pasteFromWord: {
		enable: true,
		convertUnitsToPixel: true
	}
});
```

### pasteFromWord.allowedStyleProps

- Type: `string[]`
- Default: See below

A list of CSS style properties that will be preserved when pasting from Word. All other style properties will be removed.

Default value:
```js
[
	'background',
	'background-color',
	'border',
	'border-.*',
	'color',
	'float',
	'font-family',
	'font-size',
	'font-style',
	'font-weight',
	'height',
	'line-height',
	'list-style-type',
	'margin',
	'margin-bottom',
	'margin-left',
	'margin-right',
	'margin-top',
	'padding',
	'text-align',
	'text-justify',
	'text-decoration',
	'text-indent',
	'vertical-align',
	'width'
]
```

You can customize this list to allow only specific style properties:

```js
Jodit.make('#editor', {
	pasteFromWord: {
		enable: true,
		allowedStyleProps: [
			'color',
			'font-weight',
			'text-align'
		]
	}
});
```

## Usage Examples

### Basic Usage

```js
Jodit.make('#editor', {
	pasteFromWord: {
		enable: true,
		convertUnitsToPixel: true
	}
});
```

### Customized Style Properties

```js
Jodit.make('#editor', {
	pasteFromWord: {
		enable: true,
		convertUnitsToPixel: true,
		allowedStyleProps: [
			'background-color',
			'color',
			'font-family',
			'font-size',
			'font-weight',
			'text-align',
			'text-decoration'
		]
	}
});
```

### Disabling the Plugin

To completely disable the plugin:

```js
Jodit.make('#editor', {
	disablePlugins: ['pasteFromWordPro']
});
```

## Integration with Core Jodit Options

The plugin works in combination with the following core Jodit options:

### askBeforePasteFromWord

- Type: `boolean`
- Default: `true`

When enabled, Jodit will show a dialog asking how to paste content from Word.

### defaultActionOnPaste / defaultActionOnPasteFromWord

- Type: `number`
- Default: `Jodit.INSERT_AS_HTML`

Determines the default action when pasting content.

Example of integration with core options:

```js
Jodit.make('#editor', {
	askBeforePasteFromWord: false,
	pasteFromWord: {
		enable: true,
		convertUnitsToPixel: true
	},
	beautifyHTML: false,
	defaultActionOnPaste: Jodit.INSERT_AS_HTML
});
```

## Styles for Nested Lists

In order for the counters to work correctly with nested lists (e.g., 1, 1.1, 1.2), you must include the following CSS in your stylesheet:

```css
ul ol[data-list-style-type='decimal'],
ol ol[data-list-style-type='decimal'] {
	counter-reset: item;
}

ol ol[data-list-style-type='decimal'] > li,
ul ol[data-list-style-type='decimal'] > li {
	display: block;
}

ol ol[data-list-style-type='decimal'] > li:before,
ul ol[data-list-style-type='decimal'] > li:before {
	content: counters(item, '.') '. ';
	counter-increment: item;
}
```

This CSS ensures that nested lists are properly formatted with hierarchical numbering.

## How It Works

1. When content is pasted from Word, the plugin detects it based on specific markers in the HTML
2. The plugin then processes the content, removing unnecessary markup and preserving only the allowed style properties
3. If `convertUnitsToPixel` is enabled, all units (cm, pt, etc.) are converted to pixels
4. Special handling is applied for lists, tables, and other complex structures
5. The cleaned HTML is then inserted into the editor

This process ensures that content pasted from Word is clean, consistent, and properly formatted according to your specifications.

## Advanced API Reference

For developers looking to extend or customize the paste-from-word functionality, the plugin provides several TypeScript interfaces and classes:

### Core Interfaces

```typescript
// Context object passed to case processing functions
interface ICaseContext extends IDictionary {
    jodit: IJodit;  // Jodit instance
    rtf: string;     // RTF content from clipboard
    // Additional properties from IDictionary
}

// Function type for custom element processing
interface ICaseFn {
    (elm: JElement, context: ICaseContext): null | JElement;
}

// Filter function for rendering decisions
interface RenderFilter {
    (elm: JElement): boolean;
}
```

### Custom Processing Functions

You can create custom processing functions to handle specific Word elements:

```typescript
const customCaseFn: ICaseFn = (element, context) => {
    // Access the Jodit instance
    const { jodit, rtf } = context;

    // Process the element based on your logic
    if (element.tagName === 'p' && element.hasClass('CustomClass')) {
        // Transform or modify the element
        element.addClass('processed');
        element.style.set('color', '#000');
    }

    // Return null to remove the element, or return the modified element
    return element;
};
```

### Render Filters

Create custom filters to control which elements are rendered:

```typescript
const customRenderFilter: RenderFilter = (element) => {
    // Return true to keep the element, false to filter it out
    if (element.tagName === 'span' && element.style.isEmpty()) {
        return false; // Remove empty spans
    }
    return true;
};
```

### Working with JElement

The `JElement` class is the core abstraction for DOM manipulation in the plugin:

```typescript
// JElement provides methods for element manipulation
class JElement {
    tagName: string;           // Element tag name
    attributes: IDictionary;   // Element attributes
    children: JElement[];      // Child elements

    // Style manipulation
    style: Style;              // Style object
    hasClass(className: string): boolean;
    addClass(className: string): void;
    removeClass(className: string): void;

    // Content manipulation
    setText(text: string): void;
    getText(): string;

    // Tree manipulation
    appendChild(child: JElement): void;
    removeChild(child: JElement): void;
    replaceWith(replacement: JElement): void;

    // Conversion
    toDOMElement(document: Document): HTMLElement;
}
```

### Style Class

The `Style` class handles CSS property management:

```typescript
class Style {
    // Get/set individual properties
    get(property: string): string | null;
    set(property: string, value: string): void;
    remove(property: string): void;

    // Bulk operations
    clear(): void;
    isEmpty(): boolean;
    toString(): string;

    // Parse style string
    parse(cssText: string): void;
}
```

### Extending the Plugin

To extend the plugin with custom processing:

```typescript
// Register custom processing after plugin initialization
Jodit.make('#editor', {
    pasteFromWord: {
        enable: true
    },
    events: {
        afterInit: (jodit) => {
            // Access the plugin instance and add custom processors
            // Note: This requires understanding of the plugin's internal structure
        }
    }
});
```

## Internal Processing Pipeline

Understanding the processing pipeline helps in customization:

1. **RTF Detection**: The plugin detects Word content through RTF markers in clipboard data
2. **HTML Parsing**: Converts pasted HTML into JElement tree structure
3. **Case Processing**: Applies transformation functions (ICaseFn) to each element
4. **Style Filtering**: Filters allowed CSS properties based on configuration
5. **Render Filtering**: Applies RenderFilter functions to determine final output
6. **DOM Generation**: Converts processed JElement tree back to HTML

This advanced API allows deep customization of how Word content is processed and cleaned before insertion into the editor.