Довідка Miditaur Code Editor

Зміст

Для користувачів

Інтерфейс редактора Miditaur Code Editor

Інтерфейс редактора простий, інтуїтивно зрозумілий, легкий для засвоєння. 

Для розробників

Файли JavaScript - опис та призначення

Файли JavaScript забезпечують змістовну та функціональну складову редактора «Miditaur Code Editor».

Кожен JavaScript файл має свою семантичну назву, яка відображає його основне призначення.

JavaScript файли розміщені у відповідній диреторії з назвою js.

Ключові файли - детальний опис

Cтворення структури базового редактора HTML - editor.js

editor.js - код у цьому файлі визначає функцію createEditor, яка створює структуру базового редактора HTML на сторінці.

Детальний опис коду файлу editor.js:
Функція createEditor:
  • Створюється контейнер div з ідентифікатором editor-block, який буде містити редактор коду.
  • Створюється елемент textarea з ідентифікатором code-input, де користувач вводитиме свій HTML код. Це текстове поле також має підказку у вигляді placeholder, що пропонує користувачеві ввести HTML код.
  • Створюється iframe з ідентифікатором code-output, який використовується для виведення результату введеного HTML коду.
  • Створюється прихований елемент input з типом file та ідентифікатором file-input. Цей елемент, швидше за все, призначений для завантаження файлів користувачем, але поки не відображається на сторінці через властивість style.display = 'none'.
Додавання елементів у DOM:
  • Усі створені елементи додаються в контейнер editorBlock.
  • Потім цей контейнер додається до body документа, таким чином, він стає видимим на сторінці.
Виклик функції:
  • В кінці викликається функція createEditor(), що призводить до створення і відображення редактора на веб-сторінці.

Налаштування - options.js

options.js - Налаштування Codemirror екземпляра редактора, константа його поточної версії.

Зміна поточної версії редактора:

Змінити поточну версію редактора можна за допомогою константи const version = '5.X.X'; у файлі options.js

Підключення зовнішніх файлів

  • css.js - підключення зовнішніх css файлів
  • scripts.js - підключення зовнішніх JavaScript файлів

Сніппети

  • snipcss.js - файл містить CSS сніппети і функціонал їх додавання у вікно редактора коду.
  • sniphtml.js - файл містить HTML сніппети і функціонал їх додавання у вікно редактора коду.
  • snipjs.js - файл містить JavaScript сніппети і функціонал їх додавання у вікно редактора коду.

HTML теги options.js

  • options.jshtmltags.js - містить набори тегів відповідно категорій, призначення іконок

Структура

nav.js - містить константу головного навігаційного меню редактора та прив'язки функцій до його пунктів меню.  

footer.js - містить функцію створення футера та її виклик.

Модальні вікна - modal.js

modal.js

Іконки для категорій - icons.js

icons.js

scripts.js

Файл scripts.js відповідає за підготовку робочого середовища редактора на базі CodeMirror, завантаження всіх необхідних залежностей та індивідуальних скриптів для розширення функціоналу вашого проекту.

Цей файл є асинхронним скриптом для завантаження та ініціалізації бібліотеки CodeMirror разом із численними додатковими модулями, режимами, аддонами, а також іншими сторонніми скриптами.

Детальний опис кожної частини:
Функція loadScript:

Використовується для динамічного завантаження JavaScript-файлів. Вона створює елемент <script>, встановлює атрибут src на переданий URL, і додає цей елемент до document.body.
Функція повертає проміс[1], який резолвиться[2], коли скрипт завантажується успішно (onload), або відхиляється в разі помилки (onerror).

Подія DOMContentLoaded:

Викликається після повного завантаження DOM-структури. Це означає, що скрипти будуть завантажуватися тільки після того, як сторінка повністю завантажена.

Завантаження основного скрипта CodeMirror:

Першим кроком завантажується основний скрипт CodeMirror, який є базовим редактором.

Завантаження режимів CodeMirror:

Далі завантажуються різні режими для роботи з різними мовами програмування та розмітки, такими як XML, JavaScript, CSS, HTML Mixed, Markdown, Python.

Завантаження аддонів CodeMirror:

Після цього завантажуються аддони для розширення функціональності CodeMirror. Це можуть бути функції автоматичного закриття тегів, підсвічування відповідних дужок, анотації скроллбару, прості смуги прокрутки, підсвічування під час пошуку та багато іншого.

Сторонні бібліотеки та скрипти:

Завантажуються також сторонні скрипти та бібліотеки, такі як jQuery, HTMLHint, CSSLint, JSHint тощо.

Функції підказок та згортання коду:

Завантажуються модулі для автодоповнення коду (HTML, CSS, JavaScript) та функції для згортання коду по різних правилах, наприклад, за допомогою дужок або відступів.

Інші аддони:

Включає аддони для відображення заглушок (placeholder), режиму повноекранного перегляду, автоматичного оновлення та діалогових вікон.

Підключення власних скриптів:

Після завантаження бібліотек CodeMirror завантажуються кастомні скрипти, які містять логіку програми: опції, функції, робота з модальними вікнами, обробка сніппетів (HTML, CSS, JS), іконки, меню та інші специфічні функціональні можливості.

Фінальне повідомлення:

Після успішного завантаження всіх скриптів виводиться повідомлення в консоль. У разі помилки виводиться повідомлення про невдале завантаження скрипта.

В результаті тривалого тестування були зроблені висновки про те, що змінювати послідовність підключення у цьому файлі категорично заборонено, бо це може привести до небажаних проблем. Рядки, які не можна переміщувати позначені відповідними коментарями.

css.js

Файл містить функцію, яка дозволяє гнучко і динамічно підключати різні CSS файли до сторінки, що є корисним у випадках, коли список стилів може змінюватися або коли потрібно завантажувати стилі після певних дій (наприклад, після завантаження JavaScript).

Функція loadStyles

Призначення: Функція loadStyles створює список з URL до CSS файлів та динамічно додає їх до документу через елемент <link> у <head>. Це дозволяє підключати стилі до сторінки на етапі виконання JavaScript, а не на етапі завантаження HTML.

Масив styles

Зміст: Масив styles містить шляхи до різних CSS файлів, які потрібно підключити.

Вміст масиву:
  • Основні стилі: Це файли, такі як normalize.css та reset.css, які допомагають вирівняти стилі між різними браузерами.
  • Стилі CodeMirror: Файли з папки cm/ представляють теми та аддони для CodeMirror, зокрема теми редактора (наприклад, rubyblue.css, dracula.css, тощо) та стилі для різних плагінів (наприклад, dialog.css, lint.css, show-hint.css).
  • Сторонні стилі: Також є сторонні CSS файли, такі як codemirror-colorpicker.css, який підключає стилі для кольорового вибору в CodeMirror.
  • Кастомні стилі: Файли editor.css і all.css є  кастомними стилями, які можуть містити індивідуальні налаштування зовнішнього вигляду редактора чи інших елементів сторінки.
Перебір масиву та додавання стилів

Функція використовує метод forEach, щоб перебрати кожен елемент у масиві styles.

Для кожного елемента:

  • Створюється новий елемент <link>.
  • Встановлюється атрибут rel="stylesheet" для вказівки, що це CSS файл.
  • Атрибут href встановлюється на значення, яке відповідає шляху до відповідного файлу стилів.
  • Елемент <link> додається до document.head, що підключає стилі до сторінки.
Виклик функції loadStyles

Після визначення функції вона одразу викликається, що запускає процес динамічного додавання всіх стилів до сторінки.

Створення найпростішого редактора

Кроки та код для реалізації редактора з функціональністю перемикання між вкладками HTML, CSS, і JavaScript і автоматичним виконанням коду і виводу результату в одному вікні.

Крок 1: Створення HTML структури для редакторів і панелі інструментів

Створюємо найпростішу html структуру

<!DOCTYPE html>
<html lang="uk">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Редактор коду</title>
	<link rel="icon" href="img/favicon.ico">
    <script src="js/css.js" defer></script> <!-- Підключення до css.js -->
	<script src="js/scripts.js" defer></script> <!-- Підключення до scripts.js -->
    <script src="js/editor.js" defer></script> <!-- Підключення до editor.js -->
</head>
<body>
</body>
</html>

Функція Коментарі

Аддон для коментування та розкоментування коду присутній у базовій комплектації CodeMirror 5.

Для коментування та розкоментування в CodeMirror 5 потрібно використовувати вбудовану команду toggleComment. Вона автоматично коментує або розкоментує вибраний текст.

editor.execCommand('toggleComment'): Ця команда буде автоматично коментувати вибраний текст, якщо він не закоментований, і розкоментувати, якщо закоментований. Таким чином, ми можемо використовувати одну і ту ж команду для обох дій. У редакторі Miditaur Code Editor підключення базових файлів коментарів відбувається у файлі script.js.

//КОМЕНТАРІ
    await loadScript('cm/addon/comment/comment.js');
	await loadScript('cm/addon/comment/continuecomment.js');

У пункті меню навігації "Редагувати" реалізовані підпунктами у файлі nav.js:

<a href="#" id="comment-link" title="Коментувати вибраний код"><i class="fas fa-comment"></i> Коментувати</a>
<a href="#" id="uncomment-link" title="Розкоментувати вибраний код"><i class="fas fa-comment-slash"></i> Розкоментувати</a>

Прив'язка функцій:

// Прив'язка функції для коментування
  // Прив'язка до пункту меню "Коментувати"
  document.getElementById('comment-link').onclick = (e) => {
    e.preventDefault();
    editor.execCommand('toggleComment'); // Виконати коментування/розкоментування
  };

  // Прив'язка до пункту меню "Розкоментувати"
  document.getElementById('uncomment-link').onclick = (e) => {
    e.preventDefault();
    editor.execCommand('toggleComment'); // Виконати коментування/розкоментування
  };

У папці js існує альтернативна авторська розробка системи коментарів - файл comment.js, яка наразі не підключена (закоментована) у файлі scripts.js (див. блок //КОМЕНТАРІ), але протестована на реальному прикладі. Також функцію коментарів може забезпечити ще один підключений сторонній скрипт cm/dist/formatting.js, але він використовується виключно для забезпечення функції форматування тексту (коду) у вікні редактора. 

[1] Проміс — це об'єкт у JavaScript, який представляє результат асинхронної операції. Він може перебувати в одному з трьох станів: Очікування (pending): Операція ще не завершена, і результат ще невідомий. Резолв (fulfilled): Операція завершилася успішно, і проміс має результат (успішний). Відхилення (rejected): Операція завершилася з помилкою, і проміс має причину помилки (неуспішний). Проміси використовуються для роботи з операціями, які виконуються не миттєво, наприклад, завантаження скриптів, запити до сервера тощо. Вони допомагають впоратися з асинхронною логікою таким чином, щоб код залишався зрозумілим і керованим.

[2] Термін "резолвиться" означає, що проміс успішно завершився (його стан змінився з "очікування" на "резолв"), і асоційований з ним результат став доступним для подальшої обробки. Це відбувається, коли асинхронна операція, яку представляє проміс, виконується успішно. У випадку з нашим кодом проміс "резолвиться", коли скрипт успішно завантажується — тобто, коли викликається подія onload для елемента <script>. Отже, коли ми говоримо, що проміс "резолвиться", це означає, що результат асинхронної операції доступний, і ми можемо виконати подальші дії, які були заплановані для успішного завершення операції.