Skip to content

Commit fdb347b

Browse files
biz87biz87
authored
Merge pull request #815 from modx-pro/msearch
Документация для mSearch
2 parents 69f8d66 + 6ef743a commit fdb347b

File tree

8 files changed

+1164
-0
lines changed

8 files changed

+1164
-0
lines changed

‎docs/components/msearch/index.md‎

Lines changed: 223 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,223 @@
1+
---
2+
title: mSearch
3+
description: Полнотекстовый поиск с морфологическим анализом для MODX 3
4+
logo: https://modstore.pro/assets/extras/msearch2/logo-lg.jpg
5+
author: modx-pro
6+
repository: https://github.com/modx-pro/msearch
7+
8+
items: [
9+
{
10+
text: 'Сниппеты',
11+
items: [
12+
{ text: 'mSearch', link: 'snippets/msearch' },
13+
{ text: 'mSearchForm', link: 'snippets/msearchform' },
14+
],
15+
},
16+
{
17+
text: 'Интерфейс',
18+
items: [
19+
{ text: 'Поиск', link: 'interface/search' },
20+
{ text: 'Индексация', link: 'interface/indexes' },
21+
{ text: 'Запросы', link: 'interface/queries' },
22+
{ text: 'Алиасы', link: 'interface/aliases' },
23+
{ text: 'Словари', link: 'interface/dictionaries' },
24+
],
25+
},
26+
]
27+
---
28+
# mSearch
29+
30+
Полнотекстовый поиск с морфологическим анализом для MODX Revolution 3.x.
31+
32+
## Возможности
33+
34+
- **Морфологический анализ** — поиск по словоформам с помощью библиотеки phpMorphy (русский, английский, немецкий, украинский языки)
35+
- **Словарный индекс** — быстрый поиск с настраиваемыми весами полей
36+
- **Алиасы поиска** — синонимы и замены для расширения результатов
37+
- **Статистика запросов** — отслеживание популярных запросов
38+
- **Автоматическая индексация** — при сохранении ресурсов
39+
- **Отложенная индексация** — фоновая индексация через [Scheduler](/components/scheduler/)
40+
- **Vue-интерфейс** — современная админ-панель на Vue 3 + PrimeVue
41+
- **Автодополнение** — подсказки при вводе запроса
42+
43+
## Системные требования
44+
45+
| Требование | Версия |
46+
|------------|--------|
47+
| MODX Revolution | 3.0.0+ |
48+
| PHP | 8.1+ |
49+
| MySQL | 5.7+ / MariaDB 10.3+ |
50+
51+
### Зависимости
52+
53+
- **pdoTools 3.x** — для работы сниппетов и шаблонизатора Fenom
54+
- **[VueTools](/components/vuetools/)** — для административного интерфейса
55+
- **[Scheduler](/components/scheduler/)** *(опционально)* — для отложенной индексации
56+
57+
## Установка
58+
59+
### Через менеджер пакетов
60+
61+
1. Перейдите в **Extras → Installer**
62+
2. Нажмите **Download Extras**
63+
3. Найдите **mSearch** в списке
64+
4. Нажмите **Download** и затем **Install**
65+
66+
После установки:
67+
1. Перейдите в **Extras → mSearch → Словари**
68+
2. Скачайте морфологический словарь для нужного языка (русский, английский, немецкий, украинский)
69+
3. Перейдите на вкладку **Индексация** и создайте поисковый индекс
70+
71+
## Быстрый старт
72+
73+
### 1. Создайте страницу поиска
74+
75+
Создайте ресурс для вывода результатов поиска, например `/search/`.
76+
77+
### 2. Добавьте форму и результаты
78+
79+
```fenom
80+
{'!mSearchForm' | snippet : [
81+
'pageId' => 5,
82+
'autocomplete' => 1
83+
]}
84+
85+
{'!mSearch' | snippet : [
86+
'tpl' => 'mSearch.row',
87+
'limit' => 10
88+
]}
89+
```
90+
91+
### 3. Настройте индексацию
92+
93+
Укажите в системных настройках поля для индексации:
94+
95+
```
96+
mse_index_fields = pagetitle:3,longtitle:2,description:2,introtext:2,content:1
97+
```
98+
99+
Числа — это веса полей. Чем больше вес, тем выше будут результаты с совпадениями в этом поле.
100+
101+
## Системные настройки
102+
103+
Все настройки имеют префикс `mse_` и находятся в пространстве имён `msearch`.
104+
105+
### Индексация
106+
107+
| Настройка | По умолчанию | Описание |
108+
|-----------|--------------|----------|
109+
| `mse_index_fields` | `pagetitle:3,longtitle:2,description:2,introtext:2,content:1` | Поля для индексации с весами |
110+
| `mse_index_min_word_length` | `3` | Минимальная длина слова для индексации |
111+
| `mse_index_split_words` | `#\s\|[,.:;!?"'«»„"()\[\]{}<>]#u` | Регулярное выражение для разделения текста на слова |
112+
| `mse_use_scheduler` | `false` | Использовать Scheduler для отложенной индексации |
113+
114+
### Поиск
115+
116+
| Настройка | По умолчанию | Описание |
117+
|-----------|--------------|----------|
118+
| `mse_search_exact_match_bonus` | `10` | Бонус за точное совпадение запроса в тексте |
119+
| `mse_search_like_match_bonus` | `3` | Бонус за LIKE-совпадение |
120+
| `mse_search_all_words_bonus` | `5` | Бонус если все слова запроса найдены |
121+
| `mse_search_split_words` | `#\s+#u` | Регулярное выражение для разделения запроса |
122+
123+
### Фронтенд
124+
125+
| Настройка | По умолчанию | Описание |
126+
|-----------|--------------|----------|
127+
| `mse_frontend_css` | `[[++assets_url]]components/msearch/css/web/msearch.css` | URL CSS файла |
128+
| `mse_frontend_js` | `[[++assets_url]]components/msearch/js/web/msearch.js` | URL JS файла |
129+
130+
## Плейсхолдеры
131+
132+
После выполнения поиска доступны плейсхолдеры:
133+
134+
| Плейсхолдер | Описание |
135+
|-------------|----------|
136+
| `[[+mse.total]]` | Общее количество найденных результатов |
137+
| `[[+mse.query]]` | Обработанный поисковый запрос |
138+
139+
В чанке результата (tpl):
140+
141+
| Плейсхолдер | Описание |
142+
|-------------|----------|
143+
| `[[+weight]]` | Вес (релевантность) результата |
144+
| `[[+intro]]` | Текст с подсвеченными совпадениями |
145+
| `[[+idx]]` | Порядковый номер результата |
146+
147+
## События
148+
149+
| Событие | Описание |
150+
|---------|----------|
151+
| `mseOnBeforeIndex` | Перед индексацией ресурса |
152+
| `mseOnGetWorkFields` | Изменение списка полей для индексации |
153+
| `mseOnAfterIndex` | После индексации ресурса |
154+
| `mseOnBeforeSearch` | Перед выполнением поиска |
155+
| `mseOnAfterSearch` | После выполнения поиска |
156+
157+
## Отличия от mSearch2
158+
159+
mSearch — это полностью переписанный компонент для MODX 3.x:
160+
161+
| Аспект | mSearch2 | mSearch |
162+
|--------|----------|---------|
163+
| MODX | 2.x | 3.x |
164+
| PHP | 5.6+ | 8.1+ |
165+
| Интерфейс | ExtJS | Vue 3 + PrimeVue |
166+
| Архитектура | Процедурный | Service-based |
167+
| Алиасы | Синонимы | Алиасы (синонимы + замены) |
168+
| Фильтрация | mFilter2 | Нет (используйте pdoTools) |
169+
| phpMorphy | Встроенный | Composer-пакет `cijic/phpmorphy` |
170+
| Источник словарей | SourceForge | GitHub |
171+
| Эстонский язык | Да | Нет |
172+
| Scheduler | Нет | Да (отложенная индексация) |
173+
174+
::: warning mFilter2
175+
Сниппет mFilter2 не входит в mSearch. Для фильтрации используйте стандартные возможности pdoTools или сторонние решения.
176+
:::
177+
178+
## Примеры
179+
180+
### Базовый поиск
181+
182+
```fenom
183+
<form action="{'search' | url}" method="get">
184+
<input type="text" name="mse_query" value="{$_GET['mse_query']}" placeholder="Поиск...">
185+
<button type="submit">Найти</button>
186+
</form>
187+
188+
{'!mSearch' | snippet : [
189+
'tpl' => 'mSearch.row',
190+
'limit' => 10
191+
]}
192+
```
193+
194+
### С пагинацией
195+
196+
```fenom
197+
{'!mSearchForm' | snippet : ['pageId' => $_modx->resource.id]}
198+
199+
{'!pdoPage' | snippet : [
200+
'element' => 'mSearch',
201+
'tpl' => 'mSearch.row',
202+
'limit' => 10
203+
]}
204+
205+
{$_modx->getPlaceholder('page.nav')}
206+
```
207+
208+
### Поиск товаров MiniShop3
209+
210+
```fenom
211+
{'!pdoPage' | snippet : [
212+
'element' => 'msProducts',
213+
'parents' => 0,
214+
'resources' => '!mSearch' | snippet : ['return' => 'ids', 'limit' => 0] | default : '999999',
215+
'sortby' => 'ids'
216+
]}
217+
218+
{$_modx->getPlaceholder('page.nav')}
219+
```
220+
221+
## Поддержка
222+
223+
- GitHub Issues: [modx-pro/msearch](https://github.com/modx-pro/msearch/issues)

‎docs/components/msearch/interface/aliases.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# Алиасы
2+
3+
Вкладка для управления синонимами и заменами поисковых слов.
4+
5+
## Назначение
6+
7+
Алиасы позволяют расширить результаты поиска, связывая различные написания слов. Это полезно для:
8+
9+
- Исправления опечаток
10+
- Добавления синонимов
11+
- Транслитерации
12+
- Связывания брендов с альтернативными названиями
13+
14+
## Режимы работы
15+
16+
### Синоним (Add)
17+
18+
Слово добавляется к поисковому запросу вместе с оригиналом.
19+
20+
**Пример:** алиас `вискас` → `whiskas`
21+
22+
- Запрос: «вискас корм»
23+
- Поиск по: «вискас», «whiskas», «корм»
24+
25+
### Замена (Replace)
26+
27+
Оригинальное слово полностью заменяется на алиас.
28+
29+
**Пример:** алиас `уискас` → `whiskas` (с флагом замены)
30+
31+
- Запрос: «уискас корм»
32+
- Поиск по: «whiskas», «корм»
33+
34+
## Интерфейс
35+
36+
### Таблица алиасов
37+
38+
| Колонка | Описание |
39+
|---------|----------|
40+
| Слово | Исходное слово (что ищет пользователь) |
41+
| Замена | Слово для замены/добавления |
42+
| Полная замена | `Replace` — замена, `Add` — синоним |
43+
| Активен | Статус алиаса |
44+
45+
### Действия
46+
47+
| Кнопка | Описание |
48+
|--------|----------|
49+
| Создать алиас | Добавить новый алиас |
50+
| Редактировать | Изменить существующий алиас |
51+
| Удалить | Удалить алиас |
52+
53+
## Создание алиаса
54+
55+
1. Нажмите **Создать алиас**
56+
2. Заполните поля:
57+
- **Слово** — что ищет пользователь
58+
- **Замена** — на что заменить или что добавить
59+
- **Полная замена** — включить для режима замены
60+
- **Активен** — включить/отключить алиас
61+
3. Нажмите **Save**
62+
63+
## Примеры использования
64+
65+
### Исправление опечаток
66+
67+
| Слово | Замена | Режим |
68+
|-------|--------|-------|
69+
| `самсунг` | `samsung` | Замена |
70+
| `эпл` | `apple` | Замена |
71+
| `ксяоми` | `xiaomi` | Замена |
72+
73+
### Добавление синонимов
74+
75+
| Слово | Замена | Режим |
76+
|-------|--------|-------|
77+
| `телефон` | `смартфон` | Синоним |
78+
| `ноутбук` | `лэптоп` | Синоним |
79+
| `принтер` | `мфу` | Синоним |
80+
81+
### Транслитерация брендов
82+
83+
| Слово | Замена | Режим |
84+
|-------|--------|-------|
85+
| `найк` | `nike` | Замена |
86+
| `адидас` | `adidas` | Замена |
87+
| `пума` | `puma` | Замена |
88+
89+
### Обработка сокращений
90+
91+
| Слово | Замена | Режим |
92+
|-------|--------|-------|
93+
| `комп` | `компьютер` | Синоним |
94+
| `телек` | `телевизор` | Синоним |
95+
| `мобила` | `мобильный телефон` | Замена |
96+
97+
## Рекомендации
98+
99+
### Анализируйте запросы
100+
101+
Регулярно проверяйте вкладку [Запросы](/components/msearch/interface/queries):
102+
103+
1. Найдите запросы с нулевыми результатами
104+
2. Определите, есть ли релевантный контент
105+
3. Если контент есть — создайте алиас
106+
107+
### Не злоупотребляйте
108+
109+
- Создавайте алиасы только для реальных синонимов
110+
- Избегайте слишком общих замен
111+
- Тестируйте результаты поиска после добавления
112+
113+
### Приоритет морфологии
114+
115+
Алиасы применяются **до** морфологического анализа. Если слово распознаётся морфологическим словарём, его словоформы также будут учтены.
116+
117+
## Отличия от mSearch2
118+
119+
| Аспект | mSearch2 | mSearch |
120+
|--------|----------|---------|
121+
| Название | Синонимы | Алиасы |
122+
| Режимы | Добавление/Замена | Add/Replace |
123+
| Интерфейс | ExtJS | Vue 3 + PrimeVue |

0 commit comments

Comments
 (0)