:py:mod:`core.bones.selectcountry`
==================================

.. py:module:: core.bones.selectcountry

.. autoapi-nested-parse::

   A bone representing a country selection input field in a web application or form.

   The SelectCountryBone is designed to provide a user-friendly way to select a country from a predefined list of
   countries. It inherits from the BaseBone class and extends it to support country-specific functionalities,
   such as displaying country names and handling country codes (e.g., ISO 3166-1 alpha-2 or alpha-3).



Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   core.bones.selectcountry.SelectCountryBone




.. py:class:: SelectCountryBone(*, descr='Country', codes=ISO2, values=None, **kwargs)


   Bases: :py:obj:`viur.core.bones.select.SelectBone`

   A bone representing a country selection input field in a web application or form.

   The SelectCountryBone is designed to provide a user-friendly way to select a country from a predefined list of
   countries. It inherits from the BaseBone class and extends it to support country-specific functionalities,
   such as displaying country names and handling country codes (e.g., ISO 3166-1 alpha-2 or alpha-3).

   :param codes: The version of the ISO-Codes, either 2 or 3
   :param values: Optional, either a str representing a predefined group (currently "dach" and "eu"), a list of
        ISO-Codes (must match the Code-Length from `codes`), or a dict with matching iso-codes as keys and
        the full country-names as values.

   Initializes a new SelectBone.

   :param defaultValue: key(s) of the values which will be checked by default.
   :param values: dict of key->value pairs from which the user can choose from
       -- or a callable that returns a dict.
   :param translation_key_prefix: A prefix for the key of the translation object.
       It is empty by default, so that only the label (dict value) from the values is used.
       A static string or dynamic method can be used (like `translation_key_prefix_bonename`).
   :param kwargs: Additional keyword arguments that will be passed to the superclass' __init__ method.

   .. py:attribute:: ISO3CODES

      ISO 3166-1 alpha-3 (commonly referred to as ISO3) is a part of the ISO 3166 standard, which defines three-letter
      codes to represent countries.


   .. py:attribute:: ISO2CODES

      The ISO 2 country code (also known as ISO 3166-1 alpha-2) is an international standard consisting of two-letter
      codes used to identify countries.


   .. py:attribute:: ISO3TOISO2

      A Map of ISO3 to ISO2 country codes


   .. py:attribute:: ISO2TOISO3

      A built Map of ISO2 to ISO3 country codes


   .. py:attribute:: subgroup_mappings

      

   .. py:attribute:: type
      :value: 'select.country'

      

   .. py:attribute:: ISO2
      :value: 2

      

   .. py:attribute:: ISO3
      :value: 3

      

   .. py:method:: singleValueUnserialize(val)

      Unserializes a single value, converting ISO country codes between ISO 3166-1 alpha-2 and alpha-3 if necessary.

      This method takes a country code string (either ISO 3166-1 alpha-2 or alpha-3) and checks if a conversion is
      needed based on the `self.codes` attribute. If a conversion is required, it attempts to perform the conversion
      using the `ISO3TOISO2` or `ISO2TOISO3` dictionaries. If the conversion is successful, the converted code is
      returned; otherwise, the original value is returned.

      :param val: The value to be unserialized, typically a string representing an ISO country code.

      :return: The unserialized value, either the original or converted ISO country code.