# Paste Code Sample Plugin

This plugin facilitates the insertion and embedding of syntax-highlighted code snippets.

The Paste Code Sample (pasteCode) plugin empowers users to paste and embed syntax-highlighted code snippets into an editable area.

Moreover, it incorporates a button into the toolbar. Upon clicking this button, a dialog box appears for inputting raw code.

## Installation:

Add "pasteCode" to your Jodit's extraPlugins variable

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

## Options

### globalHighlightLib

- Type: Boolean
- Default: false

This config option allows you to use the global version of [`Prism.js`](https://prismjs.com/)(or another highlight library) when highlighting code sample blocks,
instead of using the `Prism.js` version built into the` paste-code` plugin.
This allows a special version of `Prism.js` to be used, including additional languages.

When using this option, make sure that `Prism.js` and any language add-ons are loaded to the site along with the Jodit script:

```html
<textarea id="editor"></textarea>
<script
	src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/prism.min.js"
	data-manual
></script>
<script>
	Jodit.make('#editor', {
		pasteCode: {
			globalHighlightLib: true
		}
	});
</script>
```

### highlightLib

- Type:

```ts
interface highlightLib {
	highlight: (code: string, language: string) => string;
	isLangLoaded: (lang: string) => boolean;
	langUrl: (lang: string) => string;
	beforeLibLoad?: () => CanPromise<void>;
	afterLibLoad?: () => CanPromise<void>;
	js: string[];
	css: string[];
}
```

- Default:

```javascript
const highlightLib = {
	beforeLibLoad(): void {
		window.Prism = window.Prism || {};
		window.Prism.manual = true;
	},
	js: [
		'https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/prism.min.js',
		'https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/plugins/autoloader/prism-autoloader.min.js'
	],

	isLangLoaded(lang) {
		if (lang === 'html') {
			return true;
		}
		return typeof Prism !== 'undefined' ? Boolean(Prism.languages[lang]) : false;
	},

	langUrl: (lang) =>
		`https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-${lang}.min.js`,

	css: [
		'https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/themes/prism.min.css'
	],

	highlight: (code, language) => {
		return typeof Prism !== 'undefined'
			? Prism.highlight(
					code,
					Prism.languages[language] || Prism.languages.plain,
					language
			  )
			: htmlspecialchars(code);
	}
};
```

In contrast to `globalHighlightLib`, the Jodit editor itself includes the styles and scripts of` prism.js`( or another lib.).

#### highlightLib.js

- Type: String[]
- Default: 
```js
[
	'https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/prism.min.js',
	'https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/plugins/autoloader/prism-autoloader.min.js'
]
```

The `js` field lists the scripts that need to be loaded for syntax highlighting.
You can specify multiple languages here.

For example:

```js
Jodit.make('#editor', {
	pasteCode: {
		highlightLib: {
			js: [
				'https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/prism.min.js',
				'https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-csv.min.js'
			]
		}
	}
});
```

#### highlightLib.css

- Type: String[]
- Default: `['https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/themes/prism.min.css']`

The `css` field lists the styles that need to be loaded for syntax highlighting.
You can specify a different theme here.

For example:

```js
Jodit.make('#editor', {
	pasteCode: {
		highlightLib: {
			css: [
				'https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/themes/prism-twilight.min.css'
			]
		}
	}
});
```

#### highlightLib.beforeLibLoad

- Type: Function
- Default:
```js
function beforeLibLoad() {
	window.Prism = window.Prism || {};
	window.Prism.manual = true;
}
```

This optional method is called before the syntax highlighting library is loaded. You can use it to set up any global variables or configurations needed by the library.

#### highlightLib.afterLibLoad

- Type: Function
- Default: `undefined`

This optional method is called after the syntax highlighting library is loaded. You can use it to perform any additional setup or configuration after the library is available.

#### highlightLib.langUrl

- Type: Function
- Default:

```typescript
function langUrl(lang: string): string {
	return `https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-${lang}.min.js`;
}
```

The Prism.JS(or another lib) init script only highlights a limited number of languages. If a language is selected that has not yet been loaded,
Jodit will find it from the URL that this function generates.

For example:

```js
Jodit.make('#editor', {
	pasteCode: {
		highlightLib: {
			langUrl: (lang) =>
				`https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-${lang}.js`
		}
	}
});
```

#### highlightLib.isLangLoaded

- Type: Function
- Default:

```js
function isLangLoaded(lang) {
	if (lang === 'html') {
		return true;
	}
	return typeof Prism !== 'undefined' ? Boolean(Prism.languages[lang]) : false;
}
```

Determines whether the language handler needs to be loaded, or it has already been loaded earlier

#### highlightLib.highlight

- Type: Function
- Default:

```js
function highlight(code, language) {
	return typeof Prism !== 'undefined'
		? Prism.highlight(
				code,
				Prism.languages[language] || Prism.languages.plain,
				language
		  )
		: htmlspecialchars(code);
}
```

The primary method of the syntax highlighting library generates a string where language tokens
are replaced with span blocks.
This method can be substituted with another one. It is the only method where the call to the highlighting library is defined.

As such, you can utilize a different library with this plugin.
For instance, let's use another popular syntax highlighting [highlight.js](https://highlightjs.org/)

```js
Jodit.make('#editor', {
	pasteCode: {
		insertTemplate: (jodit, language, value) =>
			`<pre><code class="hljs language-${language}">${Jodit.modules.Helpers.htmlspecialchars(value)}</code></pre>`,

		highlightLib: {
			js: [
				'//cdnjs.cloudflare.com/ajax/libs/highlight.js/11.3.1/highlight.min.js'
			],

			isLangLoaded(lang) {
				if (lang === 'html') {
					return true;
				}
				return Boolean(hljs.listLanguages()[lang]);
			},

			langUrl: (lang) =>
				`//cdnjs.cloudflare.com/ajax/libs/highlight.js/11.3.1/languages/${lang}.min.js`,

			css: [
				'//cdnjs.cloudflare.com/ajax/libs/highlight.js/11.3.1/styles/default.min.css',
			],

			highlight: (code, language) => {
				return hljs.highlight(code, { language: language }).value;
			}
		}
	}
});
```

### defaultLanguage

- Type: String
- Default: 'html'

- Specifies the default language in which the code editor will open.

### canonicalLanguageCode

- Type:

```ts
function canonicalLanguageCode(lang: string): string {
	...
}
```

- Default:

```ts
function canonicalLanguageCode(lang: string): string {
	switch (lang) {
		case 'ts':
			return 'typescript';

		case 'js':
			return 'javascript';

		case 'markup':
			return 'html';
	}
	return lang;
}
```

Specifies the canonical names of languages

### insertTemplate

- Type: Function
- Default:

```ts
function (jodit: IJodit, language: string, value: string) {
	return `<pre class="language-${language}">${Jodit.modules.Helpers.htmlspecialchars(
		value
	)}</pre>`
}
```

- Signature:

```ts
interface insertTemplate {
	(
    jodit: IJodit,
    language: string,
    value: string
  ) => string;
}
```

Enables you to define a function that generates the string to be inserted.

### languages

- Type: `Array<{value: string, text: string}>`
- Default:

```js
[
	{ value: 'plaintext', text: 'Plain' },
	{ value: 'html', text: 'HTML/XML' },
	{ value: 'bash', text: 'Bash' },
	{ value: 'php', text: 'PHP' },
	{ value: 'javascript', text: 'JavaScript' },
	{ value: 'typescript', text: 'TypeScript' },
	{ value: 'jsx', text: 'JSX' },
	{ value: 'java', text: 'Java' },
	{ value: 'css', text: 'CSS' },
	{ value: 'php', text: 'PHP' },
	{ value: 'ruby', text: 'Ruby' },
	{ value: 'python', text: 'Python' },
	{ value: 'java', text: 'Java' },
	{ value: 'c', text: 'C' },
	{ value: 'csharp', text: 'C#' },
	{ value: 'cpp', text: 'C++' },
	{ value: 'sql', text: 'SQL' },
	{ value: 'docker', text: 'Docker' },
	{ value: 'http', text: 'HTTP' },
	{ value: 'ini', text: 'INI' },
	{ value: 'yaml', text: 'YAML' },
	{ value: 'json', text: 'JSON' },
	{ value: 'json5', text: 'JSON5' },
	{ value: 'makefile', text: 'Makefile' },
	{ value: 'swift', text: 'Swift' }
];
```

This configuration option allows you to specify a list of languages that will be displayed in the language dropdown menu.

### dialog

- Type: `Object`
- Default:
```js
{
    width: 700,
    height: 600
}
```

Allows setting the size of the dialog.

#### dialog.width

- Type: `number`
- Default: `700`

The width of the dialog in pixels.

#### dialog.height

- Type: `number`
- Default: `600`

The height of the dialog in pixels.

## Example

```js
Jodit.make('#editor', {
	pasteCode: {
		defaultLanguage: 'js',

		languages: Jodit.atom([
			{ value: 'js', text: 'JS' },
			{ value: 'css', text: 'CSS' }
		]),

		insertTemplate: (_, lang, value) => `<code>${value}</code>`,

		dialog: {
			width: 1000
		}
	}
});
```

## Code block contextual UI (popup + drag anchor)

Existing code blocks get a contextual UI built entirely from base Jodit
entities (`UIElement`, `Popup`, toolbar controls):

- a **drag anchor** that appears in the left gutter **on hover** — grab it to
  move the whole code block within the editor. It is rendered outside the block
  (it never covers the code) as a `position: fixed` element appended to the
  document body, so the editor's horizontal overflow does not clip it;
- a **popup toolbar** shown **on click**, below the block, with a **language
  dropdown**, **Edit**, **Copy** and **Delete** buttons.

The drag anchor relies on the core
[`drag-and-drop-element`](https://github.com/xdan/jodit) plugin: on `mousedown`
it fires the `startDragElement` event, which that plugin listens to in order to
drag any element (a `<pre>` does not need to be listed in `draggableTags`).

### `pasteCode.popup`

- Type: `Array<IControlType | string>`
- Default: `['codeBlock.edit', 'codeBlock.copy', '|', 'codeBlock.remove']`

The buttons shown after the language dropdown. Use the built-in `codeBlock.*`
controls, controls from other plugins, or inline control objects.

```js
Jodit.make('#editor', {
	pasteCode: {
		// only keep copy + delete, in that order
		popup: ['codeBlock.copy', '|', 'codeBlock.remove']
	}
});
```

Built-in controls:

- `codeBlock.edit` — open the edit dialog for the block (`pencil` icon).
- `codeBlock.copy` — copy the code text to the clipboard. Fires
  `afterCopyCode.pasteCode` with the copied text.
- `codeBlock.remove` — delete the code block (`bin` icon).

The language dropdown is always prepended and is populated from
[`pasteCode.languages`](#languages). Choosing a language rewrites the
`language-*` class and re-highlights the block.