.. _use_kladr:

Использование КЛАДР в M3-приложениях
====================================

В приложениях работа с КЛАДР заключается в выборе адреса. 
Для добавления на форму необходимо воспользоваться классом :class:`kladr.addrfield.ExtAddrComponent`::

    from kladr.addrfield import ExtAddrComponent
    # ***********
    
    class SomeWindow():
        
        def __init__(self):
        
            ur_address = ExtAddrComponent()
            
            # *********
            
            self.form.extend([
                # *********
                ur_address,
            ])

По умолчанию компонент выглядит следующим образом:

.. figure:: _static/images/addrcomponent-default.png
    :align: center

Настройка отображения компонента ``ExtAddrComponent``
-----------------------------------------------------

С помощью атрибута ``level`` устанавливается количество отображаемых полей.
Перечень значений атрибута ``level``:

* ExtAddrComponent.PLACE - отображается только поле населенного пункта
* ExtAddrComponent.STREET - отображаются поля населенного пункта и улицы
* ExtAddrComponent.HOUSE - отображаются поля населенного пункта, улицы и номера дома
* ExtAddrComponent.FLAT - отображаются поля населенного пункта, улицы, номера дома и номера квартиры (по умолчанию)

.. figure:: _static/images/addrcomponent-level2.png
    :align: center
    
    ``ExtAddrComponent`` с атрибутом ``level`` равным ``ExtAddrComponent.STREET``

С помощью атрибута ``view_mode`` устанавливается высота компонента.
Перечень значений атрибута ``view_mode``:

* ExtAddrComponent.VIEW_1 - все поля выстраиваются в одну строку + поле полного адреса
* ExtAddrComponent.VIEW_2 - все поля выстраиваются в две строки + поле полного адреса (по умолчанию). Данный параметр не используется при значении атрибута ``level`` == ExtAddrComponent.PLACE
* ExtAddrComponent.VIEW_3 - все поля выстраиваются в три строки + поле полного адреса. Данный параметр не используется при значенияз атрибута ``level`` == ExtAddrComponent.PLACE или ExtAddrComponent.STREET

.. figure:: _static/images/addrcomponent-view3.png
    :align: center
    
    ``ExtAddrComponent`` с атрибутом ``view_mode`` равным ``ExtAddrComponent.VIEW_3``


Для сохранения адреса в моделях приложения необходимо определить в них поля соответствующие кодам полей компонента ``ExtAddrComponent``.
::

    class SomeModel():
        # ***********
        place = models.CharField(max_length=13, null=True, default ='')  # Населенный пункт
        street = models.CharField(max_length=17, null=True, default ='') # Улица
        house = models.CharField(max_length=10, null=True, default ='')  # Дом
        flat = models.CharField(max_length=5, null=True, default ='')  # Квартира
        zipcode = models.CharField(max_length=6, null=True, default ='') # Индекс
        addr =  models.CharField(max_length=200, null=True, default ='') # Адрес

При необходимости стандартные коды полей компонента и подписи полей можно переопределить, например::

    fact_address = ExtAddrComponent()
    fact_address.flat_field_name = 'fact_flat'
    fact_address.addr_field_name = 'fact_addr'
    fact_address.street_field_name = 'fact_street'
    fact_address.place_field_name = 'fact_place'
    fact_address.house_field_name = 'fact_house'
    fact_address.zipcode_field_name = 'fact_zipcode'
    fact_address.house_label = u'Дом/Корпус'