В инструкциях к техническим устройствам частенько можно встретить раздел под названием «Типовые неисправности», в которых содержится информация вида «Телевизор не включается — проверить предохранитель и если он перегорел, то заменить».
Банально? Безусловно. Но решает массу проблем.

Поэтому я решил собрать в одно место такие «типовые неисправности», которые судя по вопросам, как на этом сайте, так и в чате Телеграм, встречаются довольно часто и при разработке сайтов. Да и на собственном опыте тоже сталкивался не единожды.

Поскольку статья в основном ориентирована для новичков, сначала вкратце, что есть что.

Версии Evolution и в чем их принципиальное отличие друг от друга.

Версия 1.4.x — это классическая версия, прямой потомок MODx Evolution. Дополнительно есть возможность установки шаблонизатора Twig (плагин EvoTwig2) и использовать контроллеры.
Вeрсия 2.х — с интеграцией Laravel v.6 с шаблонизатором Blade, на сегодня уже можно сказать, что это промежуточная версия, на ее замену пришла версия 3.х.
Вeрсия 3.х — с интеграцией Laravel v.8 с шаблонизатором Blade и полностью переделанным разделом работы с пользователями. Так же поддерживается работа в классическом варианте, как в версии 1.4.х, без применения Laravel и Blade.

Компоненты для cms Evolution

Документация по ним находится в разделе Компоненты
docs.evo.im/04_extras.html
их довольно много, и они не все актуальные, поэтому сделаю небольшой обзор наиболее популярных и актуальных с указанием, для чего каждый из них предусмотрен.

Самые ходовые компоненты, которые используются практически в каждом проекте, уже находятся «в коробке» и устанавливаются вместе с cms. Остановлюсь лишь на некоторых из них:
DocLister — базовый сниппет, вывод документов, пришел на замену Ditto, но имеет значительно более высокую функциональность. Кроме того, на его базе создано большое количество других компонентов.
FormLister — создание любых форм, от обычных форм обратной связи и вплоть до создания личнго кабинета веб-пользователя. Пришел на замену eForm, WebLogin, WebLoginPE, WebSignup.
DLMenu — создание меню, находится в составе DocLister. Пришел на замену Wayfinder.
DLCrumbs — создание хлебных крошек, находится в составе DocLister. Пришел на замену Breadcrumbs.
DLSitemap — создание карты сайта sitemap.xml, находится в составе DocLister. Пришел на замену SiteMap.

Дополнительно Вам могут потребоваться:
Commerce — создание интернет магазина, корзина, избранное, сравнение, модуль управления заказами, мультивалютность. Пришел на замену Shopkeeper.
editDocs — импорт / экспорт документов (товаров) и другие функции. Пришел на замену catalogFill.
Документация здесь editdocs.grishin.net/
eFilter — создание фильтров по параметрам, дополнительно в комплекте содержится сниппет для сортировки getSortBlock.
evoSearch — организация поиска на сайте. Пришел на замену AjaxSearch.
SimpleGallery — создание фотогалерей и фотоальбомов, заменил все что было раньше в этой области.
TagSaver — поиск по тегам.
JotX — отзывы и комментарии.
multiTV — создание списков и блоков на странице. Несмотря на возраст, компонент сохраняет свою актуальность и популярность.
multiFields и PageBuilder — по назначению компоненты аналогичные multiTV, но более современные и более функциональные. Особое внимание рекомендую обратить на PageBuilder, особенно если нужны блоки в блоках.
Документация multiFields здесь
64j.gitbook.io/multifields-2/
evoBabel и bLang — мультиязычность, имеют отличия в подходах реализации. bLang — языковые версии на одной странице (устаревший компонент с подобным принципом реализации YAMS), evoBabel — языковые версии каждая на своей отдельной странице.

Компоненты для админки.
ClientSettings — для организации пользовательских настроек, сейчас, пожалуй, ни один проект без него не обходится.
TemplateEdit 3 — как альтернатива, а где-то и на замену старого, доброго и неувядающего ManagerManager, который в версии 1.4.х по-прежнему идет «из коробки».

В версии 3.х «из коробки» не идет ничего, и если что кому нужно — устанавливайте самостоятельно.

Теперь о «типовых неисправностях», которые неисправностями не являются, и тем более, скорее всего и не баги, а просто некоторые особенности или обычные «грабли», на которые можно наступить не только новичку, но и более опытному разработчику.

1. Кэш
Несмотря на свою банальность и широкую известность, пожалуй, самая топовая «неисправность».
Если что-то где-то не так, если, к примеру «все сделал правильно, а оно не работает», то первое что надо сделать — это очистить кэш, как в админке сайта, так и кэш браузера (историю). При этом историю посещений браузера всю чистить не обязательно, достаточно очистить кэш просматриваемой страницы горячими клавишами, например, для браузера Chrome Ctrl+Shift+R.
Бывает, что очищать кэш браузера необходимо и в админке сайта, например, при настройках SSL, кастомизации админки, и в других случаях.
Чтобы снизить влияние кэш, можно в конфигурации сайта параметр Способ кэширования установить в режим Отключить для администраторов

2. Версия php
Нужно всегда обращать внимание на системные требования не только самой cms используемой версии, но и компонентов, которые используются при разработке. Например, если вы используете 1.4.х и системных требованиях написано, что версия php не менее 5.6, но при этом используется какой-то компонент с требованием не ниже 7.3, то и использовать версию на сервере нужно не ниже 7.3. В противном случае cms будет выдавать жуткие ошибки, а достаточно всего лишь поменять версию php. Может быть и наоборот — на сервере к примеру, версия php 7.3, но вы поставили какой-то компонент, который данную версию не поддерживает.

3. Совместимость
Все течет, все изменяется, и довольно быстро.
Кроме версии php есть и другого рода совместимость.
Особенно это касается компонентов, разработанных на базе DocLister — эти компоненты и сам DocLister взаимоувязанные. Например, если Вы на существующий ранее разработанный сайт решили добавить фотогалерею SimpleGallery, то высока вероятность, что при установки из Extras вы установите более новую версию SimpleGallery и она может оказаться не совместимой с ранее установленным DocLister. Решается просто — нужно обновить DocLister.

Но такие проблемы могут быть и по другим компонентам, и связано это с некоторой инерционностью, когда в самой cms что-то изменилось, а в компонентах соответствующие исправления еще не внесены.
Или исправления уже внесены, но по какой-то причине не дошли до репозитория, откуда вы установили компонент.
Поэтому если какой-то компонент «не работает», нужно его найти на github, просмотреть issue и последние фиксы, вполне возможно, что проблема уже и решена и нужно просто переустановит компонент с github.

4. Очередность
Имеет значение, и для плагинов, и для сниппетов, и для скриптов. Поэтому если где-то что-то не срабатывает, прежде всего, надо обратить внимание на очередность используемых элементов — возможно, вы пытаетесь использовать результаты выполнения какого-либо сниппета или плагина, которые еще не получены, т.к. он вызывается позже.
В некоторых компонентах, например, Commerce, в документации указано, при каких событиях этот плагин должен вызываться первым.

5. Ошибки js
Наряду с предыдущими, перед тем как углубляться в поиски причин, нужно проверить, нет ли ошибок скриптов в консоли браузера или других конфликтов, например, дважды вызван jquery. Следует так же иметь ввиду, что некоторые компоненты имеют собственные скрипты, в том числе и jquery, у них могут быть и специальные параметры для их отключения, если в шаблоне такой скрипт уже используется.

6. В админке не отображаются превью multiTV и подобные.
Как правило, с этим сталкиваются на локалке OpenServer, решение можно посмотреть здесь

7. Перенос на хостинг
Если вы перенесли сайт на хостинг, а он там не запускается или что-то криво, то в первую очередь надо сначала проверить свои действия:
— версия php соответствует (по умолчанию версия php на хостинге может отличаться от требуемой)
— ничего не потерялось в архиве, в котором переносились файлы (.htaccess, index.php и др.)
— базу данных подключили и у нее нужная кодировка
— пути к файлам сбросили
— файл assets/cache/siteHostnames.php удалили (или прописали в нем нужный домен)

8. Нет документации (нет в документации)
Если все перепробовал и ничего не получается, значит, пора еще раз более внимательно посмотреть документацию.
Где смотреть:
— на этом же сайте в разделе Документация
docs.evo.im/
— в релизах к новым версиям cms
— файлы readme.md компонентов
— папки docs внутри компонентов
— служебная часть сниппетов и плагинов, бывает, что авторы и там пишут пояснения и даже примеры
— темы на этом сайте, многое уже многократно обсуждено, для этого на сайте имеется встроенный поиск
— на сайтах авторов
— на других ресурсах в интернете, надо воспользоваться поиском

9. Что я делаю не так
Конечно, можно обратиться за помощью к сообществу. Можно это сделать и в чате Телеграм, но чат не индексируется и встроенным поиском там тоже трудно что-то найти, поэтому одни и те же вопросы крутятся по кругу, что иногда вызывает раздражение у отвечающих и непонимание этой раздражительности у спрашивающих.

Поэтому вопросы лучше задавать на этом сайте — или в уже существующих темах, или создать новую тему в разделе Вопросы, если подобных тем нет или вопрос существенно отличается от уже имеемых тем.

Но нужно иметь ввиду, что чтобы получить правильный ответ — нужно задать правильный вопрос. Не экономьте на словах и буквах, постарайтесь максимально полно и понятно сформулировать суть проблемы, как уже пытались ее решать и привести свой код, а так же в чем именно заключается ваш вопрос.

Хорошим тоном считается, после того как вам помогут — написать решение вашего вопроса, на случай, если кто еще будет искать решение подобного вопроса. Если вам помочь не успели и / или вы сами нашли решение — опубликуйте его тоже.

10. Нестандартное решение.
Если ничего похожего среди опубликованных компонентов вы не нашли, то это не означает что их вообще нет в природе и никто ничего подобного ранее не делал, или не сможет сделать под вашу задачу. В этом случае можно опубликовать свое объявление в разделе Работа.

Добавление и расширение списка «типовых неисправностей» приветствуется.