WT AmoCRM library — Joomla Form Fields

WT AmoCRM library — Joomla Form Fields

Документация по классам Webtolk\Amocrm\Fields из библиотеки WT AmoCRM для Joomla. Поля предназначены для XML-форм Joomla и помогают выводить данные аккаунта AmoCRM, выбирать теги, пользовательские поля, воронки и сущности AmoCRM.

Общие правила

Все поля используют стандартный механизм Joomla Form XML:

<field
    name="example"
    type="Leadstagslist"
    label="Тег сделки"
/>

Стандартные атрибуты Joomla (name, type, label, description, default, hint, multiple, showon, class, required и другие) обрабатываются ядром Joomla и здесь подробно не описываются. Ниже перечислены только кастомные XML-атрибуты, которые явно читаются классами WT AmoCRM из $this->element.

Для работы полей требуется настроенный системный плагин WT AmoCRM, корректные параметры подключения к AmoCRM и доступность AmoCRM API. При ошибках API часть полей показывает сообщение Joomla или рендерит блок ошибки.

Краткая матрица полей и атрибутов

Важно: в текущем коде CompaniestagslistField объявляет $type = 'Сompaniestagslist', где первая буква выглядит как кириллическая С, а не латинская C. До отдельного исправления кода копируйте XML type из актуальной документации или исходного кода, чтобы не получить нераспознанный тип поля.

Accountinfo

Назначение

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

Класс и layout

• Класс: Webtolk\Amocrm\Fields\AccountinfoField
• Базовый класс Joomla: Joomla\CMS\Form\FormField
• XML type: Accountinfo
• Layout: libraries.webtolk.amocrm.fields.accountinfo
• Поле не сохраняет значение. getInput() возвращает пробел, а основной HTML рендерится через label/layout.

Кастомные XML-атрибуты

Нет. Класс не читает дополнительные XML-атрибуты из $this->element.

Логика работы

1. Создаёт экземпляр Webtolk\Amocrm\Amocrm.
2. Вызывает $amocrm->account()->getAccountInfo().
3. Если ответ содержит error_code, layout получает флаг ошибки и объект ошибки.
4. Если аккаунт получен успешно, поле дополнительно запрашивает пользователя AmoCRM по current_user_id через $amocrm->users()->getUserById(...).
5. Layout показывает название аккаунта, даты создания/изменения, имя, email и признак администратора текущего пользователя AmoCRM.

Пример XML

<field
    name="amocrm_account_info"
    type="Accountinfo"
    label="AmoCRM account"
/>

Когда использовать

Используйте поле в административной форме настроек, чтобы визуально подтвердить подключение к AmoCRM. Поле не подходит для хранения значения, фильтра или выбора.

Contactinfo

Назначение

Contactinfo показывает ссылку и краткую информацию о контакте AmoCRM, который связан с пользователем Joomla через таблицу синхронизации WT AmoCRM. Поле не является select-списком и не сохраняет значение; оно выводит информационный блок.

Класс и layout

• Класс: Webtolk\Amocrm\Fields\ContactinfoField
• Базовый класс Joomla: Joomla\CMS\Form\FormField
• XML type: Contactinfo
• Layout: libraries.webtolk.amocrm.fields.contactinfo
• Маппинг Joomla user ID -> AmoCRM contact ID проверяется через Webtolk\Amocrm\Helper\UserHelper::checkIsAmoCRMUser().

Кастомные XML-атрибуты

Логика выбора пользователя Joomla

1. Если указан joomlauserid, поле приводит его к integer и использует как ID пользователя Joomla.
2. Если joomlauserid отсутствует и указан joomlauseridsource, поле читает integer из текущего input по этому имени.
3. Если ID пользователя не найден, поле показывает предупреждение LIB_WTAMOCRM_FIELD_AMOCRMCONTACTINFO_NO_JOOMLA_USER_ID.
4. Если пользователь Joomla найден, но связи с AmoCRM-контактом нет, поле показывает сообщение LIB_WTAMOCRM_FIELD_AMOCRMCONTACTINFO_NO_AMOCRM_CONTACT_ID.
5. Если контакт найден, поле запрашивает AmoCRM contact by ID и выводит ссылку на контакт в AmoCRM.
6. Если showtags="true" и в ответе есть _embedded->tags, layout показывает теги как badges.

Пример: ID пользователя из URL/request

Подходит для формы пользователя, где ID доступен в input как id.

<field
    name="amocrm_contact_info"
    type="Contactinfo"
    label="Контакт AmoCRM"
    joomlauseridsource="id"
    with="tags"
    showtags="true"
/>

Пример: фиксированный ID пользователя

<field
    name="amocrm_contact_info_for_user_42"
    type="Contactinfo"
    label="Контакт AmoCRM для пользователя #42"
    joomlauserid="42"
    with="tags"
    showtags="true"
/>

Практические замечания

• Если нужно показывать теги, укажите одновременно showtags="true" и подходящий with, например with="tags", чтобы AmoCRM вернула теги в _embedded.
• joomlauserid удобен для статического вывода конкретного пользователя, а joomlauseridsource — для edit forms, где ID берётся из request.
• Поле выводит информацию, а не значение для сохранения.

Webhookslist

Назначение

Webhookslist выводит информационный список webhooks, зарегистрированных в AmoCRM. В layout отображаются URL webhook, статус, даты создания/изменения и события AmoCRM.

Класс и layout

• Класс: Webtolk\Amocrm\Fields\WebhookslistField
• Базовый класс Joomla: Joomla\CMS\Form\FormField
• XML type: Webhookslist
• Layout: libraries.webtolk.amocrm.fields.webhookslist

Кастомные XML-атрибуты

Логика работы

1. Создаёт объект webhooks API через (new Amocrm())->webhooks().
2. Проверяет onlycurrentsite.
3. Если onlycurrentsite="true" и текущий webhook URL доступен, вызывает getWebhooks() с фильтром по destination.
4. Если фильтр не включён, вызывает getWebhooks([]) и получает общий список webhooks.
5. Layout показывает total count, режим отображения и список webhook-записей.

Пример: показать все webhooks

<field
    name="amocrm_webhooks_all"
    type="Webhookslist"
    label="Все webhooks AmoCRM"
/>

Пример: показать webhooks только текущего сайта

<field
    name="amocrm_webhooks_current_site"
    type="Webhookslist"
    label="Webhooks текущего сайта"
    onlycurrentsite="true"
/>

Практические замечания

• Значение onlycurrentsite проверяется как строка true; значения 1, yes, on не считаются включением фильтра.
• Поле информационное и не сохраняет выбранное значение.

Leadstagslist

Назначение

Leadstagslist выводит select-список тегов сделок AmoCRM. Значением option является ID тега, текстом option — имя тега и ID.

Класс

• Класс: Webtolk\Amocrm\Fields\LeadstagslistField
• Базовый класс Joomla: Joomla\CMS\Form\Field\ListField
• XML type: Leadstagslist
• AmoCRM endpoint wrapper: $amocrm->tags()->getTags('leads', $request_options)

Кастомные XML-атрибуты

Пример

<field
    name="lead_tag_id"
    type="Leadstagslist"
    label="Тег сделки"
    limit="100"
/>

Логика ошибок и пустых данных

• Если ответ AmoCRM пустой, поле возвращает option с текстом there is no tags in Amo CRM.
• Если AmoCRM вернула error_code, сообщение добавляется в очередь Joomla как error, а options остаются пустыми.

Contactstagslist

Назначение

Contactstagslist выводит select-список тегов контактов AmoCRM. Значением option является ID тега.

Класс

• Класс: Webtolk\Amocrm\Fields\ContactstagslistField
• Базовый класс Joomla: Joomla\CMS\Form\Field\ListField
• XML type: Contactstagslist
• AmoCRM endpoint wrapper: $amocrm->tags()->getTags('contacts', $request_options)

Кастомные XML-атрибуты

Пример

<field
    name="contact_tag_id"
    type="Contactstagslist"
    label="Тег контакта"
    limit="200"
/>

Логика ошибок и пустых данных

• Если ответ AmoCRM пустой, поле возвращает option с текстом there is no tags in Amo CRM.
• Если AmoCRM вернула error_code, сообщение добавляется в очередь Joomla как error.

Сompaniestagslist

Назначение

Сompaniestagslist выводит select-список тегов компаний AmoCRM. Значением option является ID тега компании.

Класс

• Класс: Webtolk\Amocrm\Fields\CompaniestagslistField
• Базовый класс Joomla: Joomla\CMS\Form\Field\ListField
• XML type: Сompaniestagslist в текущем коде
• AmoCRM endpoint wrapper: $amocrm->tags()->getTags('companies', $request_options)

Важное предупреждение о XML type

В исходном коде поле объявлено как:

protected $type = 'Сompaniestagslist';

Первая буква в строке выглядит как кириллическая С, а не латинская C. Визуально эти символы почти одинаковы, но для Joomla это разные строки. До исправления кода используйте точный type из актуального исходника/документации и проверяйте поле в форме.

Кастомные XML-атрибуты

Пример

<field
    name="company_tag_id"
    type="Сompaniestagslist"
    label="Тег компании"
    limit="100"
/>

Логика ошибок и пустых данных

• Если ответ AmoCRM пустой, поле возвращает option с текстом there is no tags in Amo CRM.
• Если AmoCRM вернула error_code, сообщение добавляется в очередь Joomla как error.

Leadcustomfieldslist

Назначение

Leadcustomfieldslist выводит select-список пользовательских полей сделок AmoCRM. Значением option является ID пользовательского поля, текстом option — имя поля и его тип.

Класс

• Класс: Webtolk\Amocrm\Fields\LeadcustomfieldslistField
• Базовый класс Joomla: Joomla\CMS\Form\Field\ListField
• XML type: Leadcustomfieldslist
• AmoCRM endpoint wrapper: $amocrm->customfields()->getLeadsCustomFields()

Кастомные XML-атрибуты

Нет. Класс не читает дополнительные XML-атрибуты из $this->element.

Пример

<field
    name="lead_custom_field_id"
    type="Leadcustomfieldslist"
    label="Пользовательское поле сделки"
/>

Логика ошибок и пустых данных

• Если ответ AmoCRM пустой, поле возвращает option there is no custom_fields in Amo CRM.
• Если AmoCRM вернула error_code, сообщение добавляется в очередь Joomla как error.

Contactcustomfieldslist

Назначение

Contactcustomfieldslist выводит select-список пользовательских полей контактов AmoCRM. Дополнительно поле может показывать или скрывать служебную опцию «Не использовать».

Класс

• Класс: Webtolk\Amocrm\Fields\ContactcustomfieldslistField
• Базовый класс Joomla: Joomla\CMS\Form\Field\ListField
• XML type: Contactcustomfieldslist
• AmoCRM endpoint wrapper: $amocrm->customfields()->getContactsCustomFields()

Кастомные XML-атрибуты

Пример: показать option «Не использовать»

<field
    name="contact_custom_field_id"
    type="Contactcustomfieldslist"
    label="Пользовательское поле контакта"
/>

Пример: скрыть option «Не использовать»

<field
    name="contact_custom_field_id"
    type="Contactcustomfieldslist"
    label="Пользовательское поле контакта"
    hidenone="true"
/>

Логика ошибок и пустых данных

• Если ответ AmoCRM пустой, поле возвращает option there is no custom_fields in Amo CRM for contacts.
• Если hidenone не включён, option -1 добавляется до пользовательских полей.
• Если AmoCRM вернула error_code, сообщение добавляется в очередь Joomla как error.

Companycustomfieldslist

Назначение

Companycustomfieldslist выводит select-список пользовательских полей компаний AmoCRM. Значением option является ID пользовательского поля.

Класс

• Класс: Webtolk\Amocrm\Fields\CompanycustomfieldslistField
• Базовый класс Joomla: Joomla\CMS\Form\Field\ListField
• XML type: Companycustomfieldslist
• AmoCRM endpoint wrapper: $amocrm->customfields()->getCompaniesCustomFields()

Кастомные XML-атрибуты

Нет. Класс не читает дополнительные XML-атрибуты из $this->element.

Пример

<field
    name="company_custom_field_id"
    type="Companycustomfieldslist"
    label="Пользовательское поле компании"
/>

Логика ошибок и пустых данных

• Если ответ AmoCRM пустой, поле возвращает option there is no custom_fields in Amo CRM for companies.
• Если AmoCRM вернула error_code, сообщение добавляется в очередь Joomla как error.

Leadspipelineslist

Назначение

Leadspipelineslist выводит select-список воронок сделок AmoCRM. Значением option является ID воронки, текстом option — название воронки и ID.

Класс

• Класс: Webtolk\Amocrm\Fields\LeadspipelineslistField
• Базовый класс Joomla: Joomla\CMS\Form\Field\ListField
• XML type: Leadspipelineslist
• AmoCRM endpoint wrapper: $amocrm->leads()->getLeadsPiplines()

Кастомные XML-атрибуты

Нет. Класс не читает дополнительные XML-атрибуты из $this->element.

Пример

<field
    name="pipeline_id"
    type="Leadspipelineslist"
    label="Воронка AmoCRM"
/>

Логика ошибок и пустых данных

• Если ответ AmoCRM пустой, поле добавляет option с текстом there is no tags in Amo CRM.
• Если AmoCRM вернула error_code, сообщение добавляется в очередь Joomla как error.

Entitymodalselect

Назначение

Entitymodalselect наследует Joomla ModalSelectField и открывает модальное окно выбора сущности AmoCRM через com_ajax системного плагина wt_amocrm. Поле сохраняет ID выбранной сущности.

Класс и layout

• Класс: Webtolk\Amocrm\Fields\EntitymodalselectField
• Базовый класс Joomla: Joomla\CMS\Form\Field\ModalSelectField
• XML type: Entitymodalselect
• Modal URL: index.php?option=com_ajax&plugin=wt_amocrm&group=system&format=html&tmpl=component&action=modalselect&entity=...&action_type=internal
• Modal layout: lib_webtolk_amocrm/layouts/fields/entitymodalselect.php

Кастомные XML-атрибуты

Поддерживаемые значения entity

Комментарий в коде упоминает tags, но getValueTitle() не содержит отдельной ветки для тегов. Для публичной документации используйте contacts и leads.

Пример: выбор контакта

<field
    name="amocrm_contact_id"
    type="Entitymodalselect"
    label="Контакт AmoCRM"
    entity="contacts"
/>

Пример: выбор сделки

<field
    name="amocrm_lead_id"
    type="Entitymodalselect"
    label="Сделка AmoCRM"
    entity="leads"
/>

Логика работы

1. setup() читает entity; если атрибут пустой, используется contacts.
2. Поле строит URL для modal select через com_ajax и добавляет Joomla form token.
3. Заголовок modal берётся из языковой константы LIB_WTAMOCRM_FIELD_ENTITY_MODAL_SELECT_CHOOSE_{ENTITY}.
4. Если у поля нет hint, hint устанавливается равным заголовку modal.
5. При отображении уже сохранённого значения getValueTitle() приводит value к integer ID и запрашивает название сущности в AmoCRM.
6. Если ID пустой, поле показывает пустое значение.

Практические замечания

• Значение поля — ID выбранной сущности AmoCRM.
• Для контактов и сделок используйте отдельные поля с разными name.
• Не используйте entity="tags" в публичных примерах, пока код не получит отдельную поддержку отображения выбранного тега.

Полный пример XML

<form>
    <fieldset name="amocrm">
        <field
            name="amocrm_account_info"
            type="Accountinfo"
            label="AmoCRM account"
        />

        <field
            name="amocrm_contact_info"
            type="Contactinfo"
            label="Контакт AmoCRM текущего пользователя"
            joomlauseridsource="id"
            with="tags"
            showtags="true"
        />

        <field
            name="amocrm_webhooks"
            type="Webhookslist"
            label="Webhooks текущего сайта"
            onlycurrentsite="true"
        />

        <field
            name="lead_tag_id"
            type="Leadstagslist"
            label="Тег сделки"
            limit="100"
        />

        <field
            name="contact_custom_field_id"
            type="Contactcustomfieldslist"
            label="Пользовательское поле контакта"
            hidenone="true"
        />

        <field
            name="pipeline_id"
            type="Leadspipelineslist"
            label="Воронка AmoCRM"
        />

        <field
            name="amocrm_lead_id"
            type="Entitymodalselect"
            label="Сделка AmoCRM"
            entity="leads"
        />
    </fieldset>
</form>

Что проверять при внедрении

• Подключение WT AmoCRM к аккаунту AmoCRM работает без ошибок.
• Системный плагин wt_amocrm включён, если используется Entitymodalselect.
• Для Contactinfo существует связь Joomla user ID -> AmoCRM contact ID.
• Для списков тегов, пользовательских полей и воронок в AmoCRM есть соответствующие данные.
• Для Webhookslist onlycurrentsite="true" в настройках интеграции доступен корректный webhook token, чтобы библиотека могла построить URL текущего сайта.