|
1 | 1 | # code-input |
2 | 2 |
|
3 | | -> **:warning: This document is a work in progress for the next release. [Read latest released instructions.](https://github.com/WebCoder49/code-input/tree/v2.5.1/README.md)** |
| 3 | +[](https://code-input-js.org)[](https://github.com/WebCoder49/code-input)[](https://yarnpkg.com/package?name=@webcoder49/code-input)[](https://www.npmjs.com/package/@webcoder49/code-input) |
4 | 4 |
|
5 | | -[](https://github.com/WebCoder49/code-input)[](https://www.npmjs.com/package/@webcoder49/code-input) |
6 | | - |
7 | | -[](LICENSE) [](https://github.com/WebCoder49/code-input/releases) [](https://codepen.io/WebCoder49/full/jOypJOx) |
8 | | - |
9 | | -> ___Fully customisable, editable syntax-highlighted textareas that can be placed in any HTML form.___ [[🚀 View the Demo](https://codepen.io/WebCoder49/full/jOypJOx)] |
10 | | -
|
11 | | - |
12 | | -*This demonstration uses themes from [Prism.js](https://prismjs.com/) and [highlight.js](https://highlightjs.org/), two syntax-highlighting programs which work well with and have compatibility built-in with code-input.* |
13 | | - |
14 | | -*A frontend JavaScript library, with:*<br/> |
15 | | -[](https://github.com/WebCoder49/code-input-for-typescript) |
| 5 | +[](LICENSE) [](https://github.com/WebCoder49/code-input/releases) |
| 6 | +> **An editable <textarea> that supports *any* syntax highlighting algorithm, for code or something else. Also, added plugins.** |
| 7 | +> |
| 8 | +> Aiming to be more flexible, lightweight, modular, progressively enhanced and standards-based than the alternatives, we support HTML forms, the `<textarea>` JavaScript interface, more languages and more use cases. |
16 | 9 |
|
17 | 10 | --- |
18 | 11 |
|
19 | | -## What does it do? |
20 | | -**`code-input`** lets you **turn any ordinary JavaScript syntax-highlighting theme and program into customisable syntax-highlighted textareas** using an HTML custom element. It uses vanilla CSS to superimpose a `textarea` on a `pre code` block, then handles indentations, scrolling and fixes any resulting bugs with JavaScript. To see how it works behind the scenes (not how to use this library), please see [this CSS-Tricks article](https://css-tricks.com/creating-an-editable-textarea-that-supports-syntax-highlighted-code/ "Creating an Editable Textarea That Supports Syntax-Highlighted Code") I wrote. |
21 | | - |
22 | | -## What are the advantages of using code-input, and what can it be used for? |
23 | | -Unlike other front-end code-editor projects, the simplicity of how `code-input` works means it is **highly customisable**. As it is not a full-featured editor, you can **choose what features you want it to include, and use your favourite syntax-highlighting algorithms and themes**. |
24 | | - |
25 | | -The `<code-input>` element works like a `<textarea>` and therefore **works in HTML5 forms and supports using the `name`, `value` and `placeholder` attributes, events like `onchange`, form resets, to name a few...** [(Demo)](https://codepen.io/WebCoder49/details/JjmqjZv) |
26 | | - |
27 | | -`code-input` has also accumulated many **features in optional [plugins](./plugins/README.md)** from open-source contributions, allowing you to choose any features you want. If a feature you want is not present, [please open an issue / contribute it!](#contributing) |
28 | | - |
29 | | -## 🚀 Getting Started With `code-input` (in 4 simple steps) |
30 | | - |
31 | | -## [`code-input` also supports TypeScript (click)](https://github.com/WebCoder49/code-input-for-typescript) |
32 | | - |
33 | | -**You can follow the instructions below, or use the starter code available [here for highlight.js](https://codepen.io/WebCoder49/pen/vYMpMoJ?editors=1100) and [here for Prism.js](https://codepen.io/WebCoder49/pen/ExzNRyb?editors=1100).** |
34 | | - |
35 | | -`code-input` is designed to be **both easy to use and customisable**. Here's how to use it to create syntax-highlighted textareas: |
36 | | - |
37 | | -### 1. Import `code-input` |
38 | | -- **First, import your favourite syntax-highlighter's JS and CSS theme files** to turn editable. |
39 | | -- Then, import the CSS and JS files of `code-input` from a downloaded release or a CDN. The non-minified files are useful for using during development. |
40 | | - |
41 | | -<details> |
42 | | -<summary> |
43 | | -Locally downloaded (Click) |
44 | | -</summary> |
| 12 | +Demos and usage instructions are available at <https://code-input-js.org> and [the `docs` directory](docs/), to let you get started quickly! |
45 | 13 |
|
46 | | -```html |
47 | | -<!--In the <head>--> |
48 | | -<script src="path/to/code-input.min.js"></script> |
49 | | -<link rel="stylesheet" href="path/to/code-input.min.css"> |
50 | | -``` |
51 | | -</details> |
52 | | -<details> |
53 | | -<summary> |
54 | | -From JSDelivr CDN (click) |
55 | | -</summary> |
56 | | - |
57 | | -```html |
58 | | -<!--In the <head>--> |
59 | | -< script src= "https://cdn.jsdelivr.net/gh/WebCoder49/[email protected]/code-input.min.js"></ script> |
60 | | -< link rel= "stylesheet" href= "https://cdn.jsdelivr.net/gh/WebCoder49/[email protected]/code-input.min.css"> |
61 | | -``` |
62 | | -</details> |
63 | | - |
64 | | -### 2. Creating a template |
65 | | -The next step is to set up a `template` to link `code-input` to your syntax-highlighter. If you're using Prism.js or highlight.js, you can use the built-in template, or you can create your own otherwise. In these examples, I am registering the template as `"syntax-highlighted"`, but you can use any template name as long as you are consistent. |
66 | | - |
67 | | -- *Highlight.js:* |
68 | | - ```js |
69 | | - codeInput.registerTemplate("syntax-highlighted", new codeInput.templates.Hljs(hljs, [] /* Array of plugins (see below) */)); |
70 | | - ``` |
71 | | - |
72 | | -- *Prism.js:* |
73 | | - ```js |
74 | | - codeInput.registerTemplate("syntax-highlighted", new codeInput.templates.Prism(Prism, [] /* Array of plugins (see below) */)); |
75 | | - ``` |
76 | | - |
77 | | -- *Custom:* |
78 | | - ```js |
79 | | - codeInput.registerTemplate("syntax-highlighted", new codeInput.Template( |
80 | | - function(result_element) { /* Highlight function - with `pre code` code element */ |
81 | | - /* Highlight code in result_element - code is already escaped so it doesn't become HTML */ |
82 | | - }, |
83 | | - |
84 | | - true, /* Optional - Is the `pre` element styled as well as the `code` element? |
85 | | - * Changing this to false uses the code element as the scrollable one rather |
86 | | - * than the pre element */ |
87 | | - |
88 | | - true, /* Optional - This is used for editing code - setting this to true sets the `code` |
89 | | - * element's class to `language-<the code-input's lang attribute>` */ |
90 | | - |
91 | | - false /* Optional - Setting this to true passes the `<code-input>` element as a second |
92 | | - * argument to the highlight function to be used for getting data- attribute values |
93 | | - * and using the DOM for the code-input */, |
94 | | - |
95 | | - [] // Array of plugins (see below) |
96 | | - )); |
97 | | - ``` |
98 | | - |
99 | | -### 3. Adding plugins |
100 | | -[Plugins](./plugins/) allow you to add extra features to a template, like [automatic indentation](plugins/indent.js) or [support for highlight.js's language autodetection](plugins/autodetect.js). To use them, just: |
101 | | -- Import the plugins' JS files after you have imported `code-input` and before registering the template. |
102 | | -- Place instances of the plugins in the array of plugins argument when registering, like this: |
103 | | -```html |
104 | | -<script src="code-input.js"></script> |
105 | | -<!--...--> |
106 | | -<script src="plugins/autodetect.js"></script> |
107 | | -<script src="plugins/indent.js"></script> |
108 | | -<!--...--> |
109 | | -<script> |
110 | | - codeInput.registerTemplate("syntax-highlighted", |
111 | | - new codeInput.templates.Hljs( |
112 | | - hljs, |
113 | | - [ |
114 | | - new codeInput.plugins.Autodetect(), |
115 | | - new codeInput.plugins.Indent(true, 2) // 2 spaces indentation |
116 | | - ] |
117 | | - ) |
118 | | - ); |
119 | | -</script> |
120 | | -``` |
121 | | - |
122 | | -> ⚠️ Unfortunately placing multiple plugins of the same type in a template can currently cause errors and undefined behaviour, even if such a configuration makes logical sense. [This is issue #118](https://github.com/WebCoder49/code-input/issues/118) ~~and will be fixed as soon as possible - if you'd like to help and have the time you're welcome, but it's also at the top of the maintainer's To-Do list.~~ and should be fixed in major version 3 - right now, I don't believe there's much demand or use, and workarounds are not too complex. |
123 | | -
|
124 | | -To see a full list of plugins and their functions, please see [plugins/README.md](./plugins/README.md). |
125 | | - |
126 | | -### 4. Using the component |
127 | | -Now that you have registered a template, you can use the custom `<code-input>` element in HTML. I recommend it surrounds a fallback `<textarea code-input-fallback>` element which will be used instead when JavaScript support is absent, and will pass its attributes to the `<code-input>` element otherwise, as shown below. If you have more than one template registered, you need to add the template name as the `template` attribute. With the element, using the `language` attribute will add a `language-{value}` class to the `pre code` block. You can now use HTML attributes and events, as well as CSS styles, to make your element as simple or interactive as you like, as if it were a `textarea` element! |
128 | | - ```HTML |
129 | | - <code-input language="HTML"><textarea code-input-fallback></textarea></code-input> |
130 | | - ``` |
131 | | - *or* |
132 | | - ```HTML |
133 | | - <code-input language="HTML" template="syntax-highlighted" onchange="console.log('Your code is', this.value)"><textarea code-input-fallback placeholder="Type code here">< href='https://github.com/WebCoder49/code-input'>code-input</a></textarea></code-input> |
134 | | - ``` |
| 14 | +--- |
135 | 15 |
|
136 | | -> ⚠️ At the moment, you need to set the `--padding` property rather than `padding` for a `code-input` element's CSS. All other properties should work as normal. |
| 16 | + |
| 17 | +*This demonstration uses themes from [Prism.js](https://prismjs.com/) and [highlight.js](https://highlightjs.org/), two syntax-highlighting programs which work well with and have compatibility built-in with code-input.* |
137 | 18 |
|
138 | 19 | ## Contributing |
139 | 20 | If you have any features you would like to add to `code-input` as plugins or core functionality, or have found any bugs, please [open an issue](https://github.com/WebCoder49/code-input/issues) or [fork and submit a pull request](https://github.com/WebCoder49/code-input/fork)! All contributions to this open-source project will be greatly appreciated. You can see [more info in our `CONTRIBUTING.md` file](CONTRIBUTING.md). |
|
0 commit comments