Deliverypoints: CDEK pickup points in Joomla Form

WT CDEK library - Documentation

Category: Libraries

Deliverypoints in WT CDEK for Joomla covers pickup points and lockers by address. This reference explains its purpose, parameters and XML examples for Joomla Form.

Webtolk\Cdekapi\Fields\DeliverypointsField, added in 1.4.0, loads points for an address and stores the selected point code. The address can come from fixed XML values or watched form fields.

Attribute	Default	Values and behavior
`city`	Not set	Fixed city name.
`zip`	Not set	Fixed postal code. Sent to AJAX as `postal_code`.
`fias_guid`	Not set	FIAS settlement UUID, not CDEK `city_uuid`. A nonempty UUID takes precedence over city/postal-code lookup.
`watchfield`	Not set	Named JSON object with `city`, `zip` and/or `fias_guid` keys. One source is sufficient; at least one address value must be nonempty for default AJAX lookup.
`point_type`	`ALL`	`ALL`: all types; `PVZ`: pickup offices; `POSTAMAT`: parcel lockers.
`is_reception`	No restriction	Accepts outgoing parcels: `true`/`1` for yes, `false`/`0` for no. Empty or absent means no filter.
`is_handout`	No restriction	Hands parcels out to recipients. Same boolean values as is_reception.

Mode precedence: the presence of any city, zip or fias_guid attribute, including city="", disables watchfield completely. Fixed and watched address values are not merged. Point/service filters do not disable watching. Scalar watchfield="city" is not valid for Deliverypoints: use a JSON object with supported keys.

Fixed XML address

<field name="fixed_point" type="Deliverypoints"
       addfieldprefix="Webtolk\Cdekapi\Fields"
       label="CDEK pickup point" city="Саратов" zip="410012"
       point_type="PVZ" is_handout="true" />

The list loads on initialization. City and postal code help resolve a unique city. If lookup returns several distinct city codes, the list stays empty. No manual refresh button is needed.

Parcel lockers by FIAS UUID

<field name="locker" type="Deliverypoints"
       addfieldprefix="Webtolk\Cdekapi\Fields"
       label="Parcel locker"
       fias_guid="bf465fda-7834-47d5-986b-ccdb584a85a6"
       point_type="POSTAMAT" is_handout="true" />

The example uses Saratov's FIAS UUID; replace it with the required settlement UUID. A nonempty UUID requests points directly, without a city lookup. UUID format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. An empty result may mean that no points match the selected filters.

Another data group and handout-only offices

<form addfieldprefix="Webtolk\Cdekapi\Fields">
    <fields name="address">
        <fieldset name="address_fields">
            <field name="city" type="text" label="City" />
            <field name="zip" type="text" label="Postal code" />
        </fieldset>
    </fields>
    <fields name="delivery">
        <fieldset name="delivery_fields">
            <field name="point" type="Deliverypoints" label="Pickup point"
                   watchfield='{"city":"address.city","zip":"address.zip"}'
                   point_type="PVZ" is_reception="false" is_handout="true" />
        </fieldset>
    </fields>
</form>

address.city refers to city in fields name="address". Combining is_reception="false" and is_handout="true" selects points that hand parcels out but do not accept outgoing shipments.

Loading, saved selection and validation

The default provider is com_ajax, system plugin wtcdek, action deliverypoints. Loading runs automatically at startup and when the address changes. Address changes clear the previous selection. On the initial successful load, a saved code absent from the response is retained with a warning; this does not prove that the point is available.

Your extension owns persistence and server-side code validation. Do not add validate="options" to Deliverypoints: its server-side options contain only the placeholder and previously saved code, so a newly fetched AJAX option may be rejected. Validate the selected code and its address association in your server-side logic.

Joomla Form Fields

Overview and getting started

WT CDEK 1.4.0 source code on GitHub