WT AmoCRM library — Joomla Form Fields

WT AmoCRM library - Joomla Form Fields

Documentation for the Webtolk\Amocrm\Fields classes from the WT AmoCRM library for Joomla. These fields are intended for Joomla XML forms and help display AmoCRM account data, select tags, custom fields, pipelines, and AmoCRM entities.

General rules

All fields use the standard Joomla Form XML mechanism:

<field
    name="example"
    type="Leadstagslist"
    label="Lead tag"
/>

Standard Joomla attributes such as name, type, label, description, default, hint, multiple, showon, class, required, and others are handled by the Joomla core and are not described in detail here. The sections below list only the custom XML attributes explicitly read by WT AmoCRM field classes from $this->element.

The fields require a configured WT AmoCRM system plugin, valid AmoCRM connection parameters, and an available AmoCRM API. If an API error occurs, some fields enqueue a Joomla message or render an error block.

Quick matrix of fields and attributes

Important: in the current code, CompaniestagslistField declares $type = 'Сompaniestagslist', where the first character looks like a Cyrillic С, not a Latin C. Until the code is fixed separately, copy the XML type from the current documentation or source code to avoid an unrecognized field type.

Accountinfo

Purpose

Accountinfo displays an information block about the AmoCRM account and the current AmoCRM user on whose behalf the integration works. The field is useful in component or plugin settings where an administrator needs to see that the AmoCRM connection works and which account is connected.

Class and layout

• Class: Webtolk\Amocrm\Fields\AccountinfoField
• Joomla base class: Joomla\CMS\Form\FormField
• XML type: Accountinfo
• Layout: libraries.webtolk.amocrm.fields.accountinfo
• The field does not store a value. getInput() returns a space, while the main HTML is rendered through the label/layout path.

Custom XML attributes

None. The class does not read additional XML attributes from $this->element.

Runtime logic

1. Creates an instance of Webtolk\Amocrm\Amocrm.
2. Calls $amocrm->account()->getAccountInfo().
3. If the response contains error_code, the layout receives an error flag and the error object.
4. If the account is loaded successfully, the field additionally requests the AmoCRM user by current_user_id through $amocrm->users()->getUserById(...).
5. The layout displays the account name, creation and modification dates, name, email, and administrator flag of the current AmoCRM user.

XML example

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

When to use

Use the field in an administrative settings form to visually confirm the AmoCRM connection. It is not suitable for storing a value, filtering, or selecting an item.

Contactinfo

Purpose

Contactinfo displays a link and brief information about the AmoCRM contact linked to a Joomla user through the WT AmoCRM synchronization table. The field is not a select list and does not store a value; it renders an information block.

Class and layout

• Class: Webtolk\Amocrm\Fields\ContactinfoField
• Joomla base class: Joomla\CMS\Form\FormField
• XML type: Contactinfo
• Layout: libraries.webtolk.amocrm.fields.contactinfo
• The Joomla user ID -> AmoCRM contact ID mapping is checked through Webtolk\Amocrm\Helper\UserHelper::checkIsAmoCRMUser().

Custom XML attributes

Joomla user selection logic

1. If joomlauserid is set, the field casts it to integer and uses it as the Joomla user ID.
2. If joomlauserid is not set and joomlauseridsource is set, the field reads an integer from the current input by that name.
3. If the user ID is not found, the field shows the warning LIB_WTAMOCRM_FIELD_AMOCRMCONTACTINFO_NO_JOOMLA_USER_ID.
4. If the Joomla user is found but there is no linked AmoCRM contact, the field shows LIB_WTAMOCRM_FIELD_AMOCRMCONTACTINFO_NO_AMOCRM_CONTACT_ID.
5. If the contact is found, the field requests the AmoCRM contact by ID and renders a link to that contact in AmoCRM.
6. If showtags="true" and the response contains _embedded->tags, the layout displays tags as badges.

Example: user ID from URL/request

Suitable for a user form where the ID is available in input as id.

<field
    name="amocrm_contact_info"
    type="Contactinfo"
    label="AmoCRM contact"
    joomlauseridsource="id"
    with="tags"
    showtags="true"
/>

Example: fixed user ID

<field
    name="amocrm_contact_info_for_user_42"
    type="Contactinfo"
    label="AmoCRM contact for user #42"
    joomlauserid="42"
    with="tags"
    showtags="true"
/>

Practical notes

• To display tags, specify both showtags="true" and a suitable with, for example with="tags", so AmoCRM returns tags in _embedded.
• joomlauserid is convenient for static output of a specific user, while joomlauseridsource is intended for edit forms where the ID is taken from the request.
• The field displays information; it does not provide a value to be saved.

Webhookslist

Purpose

Webhookslist displays an informational list of webhooks registered in AmoCRM. The layout shows the webhook URL, status, creation and modification dates, and AmoCRM events.

Class and layout

• Class: Webtolk\Amocrm\Fields\WebhookslistField
• Joomla base class: Joomla\CMS\Form\FormField
• XML type: Webhookslist
• Layout: libraries.webtolk.amocrm.fields.webhookslist

Custom XML attributes

Runtime logic

1. Creates a webhooks API object through (new Amocrm())->webhooks().
2. Checks onlycurrentsite.
3. If onlycurrentsite="true" and the current webhook URL is available, calls getWebhooks() with a destination filter.
4. If the filter is not enabled, calls getWebhooks([]) and receives the complete webhook list.
5. The layout displays the total count, display mode, and list of webhook records.

Example: show all webhooks

<field
    name="amocrm_webhooks_all"
    type="Webhookslist"
    label="All AmoCRM webhooks"
/>

Example: show webhooks for the current site only

<field
    name="amocrm_webhooks_current_site"
    type="Webhookslist"
    label="Current site webhooks"
    onlycurrentsite="true"
/>

Practical notes

• onlycurrentsite is checked as the string true; values such as 1, yes, or on do not enable the filter.
• The field is informational and does not save a selected value.

Leadstagslist

Purpose

Leadstagslist renders a select list of AmoCRM lead tags. The option value is the tag ID, and the option text contains the tag name and ID.

Class

• Class: Webtolk\Amocrm\Fields\LeadstagslistField
• Joomla base class: Joomla\CMS\Form\Field\ListField
• XML type: Leadstagslist
• AmoCRM endpoint wrapper: $amocrm->tags()->getTags('leads', $request_options)

Custom XML attributes

Example

<field
    name="lead_tag_id"
    type="Leadstagslist"
    label="Lead tag"
    limit="100"
/>

Error and empty data logic

• If the AmoCRM response is empty, the field returns an option with the text there is no tags in Amo CRM.
• If AmoCRM returns error_code, the message is enqueued in Joomla as an error, and the options remain empty.

Contactstagslist

Purpose

Contactstagslist renders a select list of AmoCRM contact tags. The option value is the tag ID.

Class

• Class: Webtolk\Amocrm\Fields\ContactstagslistField
• Joomla base class: Joomla\CMS\Form\Field\ListField
• XML type: Contactstagslist
• AmoCRM endpoint wrapper: $amocrm->tags()->getTags('contacts', $request_options)

Custom XML attributes

Example

<field
    name="contact_tag_id"
    type="Contactstagslist"
    label="Contact tag"
    limit="200"
/>

Error and empty data logic

• If the AmoCRM response is empty, the field returns an option with the text there is no tags in Amo CRM.
• If AmoCRM returns error_code, the message is enqueued in Joomla as an error.

Сompaniestagslist

Purpose

Сompaniestagslist renders a select list of AmoCRM company tags. The option value is the company tag ID.

Class

• Class: Webtolk\Amocrm\Fields\CompaniestagslistField
• Joomla base class: Joomla\CMS\Form\Field\ListField
• XML type: Сompaniestagslist in the current code
• AmoCRM endpoint wrapper: $amocrm->tags()->getTags('companies', $request_options)

Important warning about XML type

The source code declares the field as:

protected $type = 'Сompaniestagslist';

The first character in the string looks like a Cyrillic С, not a Latin C. Visually the characters are almost identical, but for Joomla they are different strings. Until the code is fixed, use the exact type from the current source/documentation and test the field in the form.

Custom XML attributes

Example

<field
    name="company_tag_id"
    type="Сompaniestagslist"
    label="Company tag"
    limit="100"
/>

Error and empty data logic

• If the AmoCRM response is empty, the field returns an option with the text there is no tags in Amo CRM.
• If AmoCRM returns error_code, the message is enqueued in Joomla as an error.

Leadcustomfieldslist

Purpose

Leadcustomfieldslist renders a select list of AmoCRM lead custom fields. The option value is the custom field ID, and the option text contains the field name and type.

Class

• Class: Webtolk\Amocrm\Fields\LeadcustomfieldslistField
• Joomla base class: Joomla\CMS\Form\Field\ListField
• XML type: Leadcustomfieldslist
• AmoCRM endpoint wrapper: $amocrm->customfields()->getLeadsCustomFields()

Custom XML attributes

None. The class does not read additional XML attributes from $this->element.

Example

<field
    name="lead_custom_field_id"
    type="Leadcustomfieldslist"
    label="Lead custom field"
/>

Error and empty data logic

• If the AmoCRM response is empty, the field returns the option there is no custom_fields in Amo CRM.
• If AmoCRM returns error_code, the message is enqueued in Joomla as an error.

Contactcustomfieldslist

Purpose

Contactcustomfieldslist renders a select list of AmoCRM contact custom fields. Additionally, the field can show or hide the service option "Do not use".

Class

• Class: Webtolk\Amocrm\Fields\ContactcustomfieldslistField
• Joomla base class: Joomla\CMS\Form\Field\ListField
• XML type: Contactcustomfieldslist
• AmoCRM endpoint wrapper: $amocrm->customfields()->getContactsCustomFields()

Custom XML attributes

Example: show the "Do not use" option

<field
    name="contact_custom_field_id"
    type="Contactcustomfieldslist"
    label="Contact custom field"
/>

Example: hide the "Do not use" option

<field
    name="contact_custom_field_id"
    type="Contactcustomfieldslist"
    label="Contact custom field"
    hidenone="true"
/>

Error and empty data logic

• If the AmoCRM response is empty, the field returns the option there is no custom_fields in Amo CRM for contacts.
• If hidenone is not enabled, option -1 is added before the custom fields.
• If AmoCRM returns error_code, the message is enqueued in Joomla as an error.

Companycustomfieldslist

Purpose

Companycustomfieldslist renders a select list of AmoCRM company custom fields. The option value is the custom field ID.

Class

• Class: Webtolk\Amocrm\Fields\CompanycustomfieldslistField
• Joomla base class: Joomla\CMS\Form\Field\ListField
• XML type: Companycustomfieldslist
• AmoCRM endpoint wrapper: $amocrm->customfields()->getCompaniesCustomFields()

Custom XML attributes

None. The class does not read additional XML attributes from $this->element.

Example

<field
    name="company_custom_field_id"
    type="Companycustomfieldslist"
    label="Company custom field"
/>

Error and empty data logic

• If the AmoCRM response is empty, the field returns the option there is no custom_fields in Amo CRM for companies.
• If AmoCRM returns error_code, the message is enqueued in Joomla as an error.

Leadspipelineslist

Purpose

Leadspipelineslist renders a select list of AmoCRM lead pipelines. The option value is the pipeline ID, and the option text contains the pipeline name and ID.

Class

• Class: Webtolk\Amocrm\Fields\LeadspipelineslistField
• Joomla base class: Joomla\CMS\Form\Field\ListField
• XML type: Leadspipelineslist
• AmoCRM endpoint wrapper: $amocrm->leads()->getLeadsPiplines()

Custom XML attributes

None. The class does not read additional XML attributes from $this->element.

Example

<field
    name="pipeline_id"
    type="Leadspipelineslist"
    label="AmoCRM pipeline"
/>

Error and empty data logic

• If the AmoCRM response is empty, the field adds an option with the text there is no tags in Amo CRM.
• If AmoCRM returns error_code, the message is enqueued in Joomla as an error.

Entitymodalselect

Purpose

Entitymodalselect extends Joomla ModalSelectField and opens a modal window for selecting an AmoCRM entity through com_ajax of the wt_amocrm system plugin. The field stores the selected entity ID.

Class and layout

• Class: Webtolk\Amocrm\Fields\EntitymodalselectField
• Joomla base class: 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

Custom XML attributes

Supported entity values

The code comment mentions tags, but getValueTitle() does not contain a separate branch for tags. Public documentation should use contacts and leads.

Example: contact selection

<field
    name="amocrm_contact_id"
    type="Entitymodalselect"
    label="AmoCRM contact"
    entity="contacts"
/>

Example: lead selection

<field
    name="amocrm_lead_id"
    type="Entitymodalselect"
    label="AmoCRM lead"
    entity="leads"
/>

Runtime logic

1. setup() reads entity; if the attribute is empty, contacts is used.
2. The field builds a modal select URL through com_ajax and adds the Joomla form token.
3. The modal title is taken from the language constant LIB_WTAMOCRM_FIELD_ENTITY_MODAL_SELECT_CHOOSE_{ENTITY}.
4. If the field has no hint, the hint is set to the modal title.
5. When displaying an already saved value, getValueTitle() casts the value to an integer ID and requests the entity name from AmoCRM.
6. If the ID is empty, the field shows an empty value.

Practical notes

• The field value is the ID of the selected AmoCRM entity.
• Use separate fields with different name values for contacts and leads.
• Do not use entity="tags" in public examples until the code receives separate support for displaying a selected tag.

Complete XML example

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

        <field
            name="amocrm_contact_info"
            type="Contactinfo"
            label="Current user's AmoCRM contact"
            joomlauseridsource="id"
            with="tags"
            showtags="true"
        />

        <field
            name="amocrm_webhooks"
            type="Webhookslist"
            label="Current site webhooks"
            onlycurrentsite="true"
        />

        <field
            name="lead_tag_id"
            type="Leadstagslist"
            label="Lead tag"
            limit="100"
        />

        <field
            name="contact_custom_field_id"
            type="Contactcustomfieldslist"
            label="Contact custom field"
            hidenone="true"
        />

        <field
            name="pipeline_id"
            type="Leadspipelineslist"
            label="AmoCRM pipeline"
        />

        <field
            name="amocrm_lead_id"
            type="Entitymodalselect"
            label="AmoCRM lead"
            entity="leads"
        />
    </fieldset>
</form>

What to check during implementation

• The WT AmoCRM connection to the AmoCRM account works without errors.
• The wt_amocrm system plugin is enabled when Entitymodalselect is used.
• A Joomla user ID -> AmoCRM contact ID link exists for Contactinfo.
• AmoCRM contains the corresponding data for tag, custom field, and pipeline lists.
• For Webhookslist onlycurrentsite="true", a correct webhook token is available in the integration settings so the library can build the current site URL.