Programming API Field

Navigate

    A field is part of a category. It defines type and constraints for one property of a contribution.

    The following types are available:

    • TextField for text input.
    • NumericField for numeric input.
    • DateTimeField for input of date and time.
    • DateField for date-only inputs.
    • TimeField for time-only inputs.
    • LookupField; a list of predefined values, the user can select exactly one.
    • MultipleLookupField; a list of predefined values, the user can select arbitrary number.

    Attributes

    Parameter Type Description
    id int Identifies the field in the database.
    name string Short title of the field.
    description string Longer description about the field.
    key string The key is used as an identifier for the field, when exchanging contribution attributes via the API.
    required boolean Indicates if a value for this field is required.
    category Category Category this field is assigned to.
    order int Position of the field in the list of fields for the category.
    status string Status of the field. Must be one of active, inactive, deleted. Defaults to active.

    Field-specific attributes

    TextField
    Parameter Type Description
    maxlength int Maximum number of characters accepted for the text field.
    textarea boolean Indicates of the field should be displayed as a text box in the front-end.
    NumericField
    Parameter Type Description
    minval float Lowest accepted value for the field.
    maxval float Largest accepted value for the field.
    Lookupfield / MultipleLookupField
    Parameter Type Description
    lookupvalues QuerySet List of LookupValues

    Read-only properties

    Parameter Description
    type_name Human readable type of the field, e.g. “Date and time”
    fieldtype Type of the field, e.g. “DateTimeField”

    Methods

    get_field_types()

    Returns a list of fields types that are available to use.

    Returns

    list

    Example
    >>> from geokey.categories.models import Field
>>> Field.get_field_types()
[TextField, NumericField, DateTimeField]

    validate_input(value)

    Validates the input against the field definition, i.e. the type and constraints.

    Parameter
    value: multiple
    The value that is validated.
    Raises
    InputError
    If the value does not comply to the field definition.

    validate_required(value)

    Checks if an accepted value is provided if the field is required.

    Parameter
    value: multiple
    The value that is validated.
    Raises
    InputError
    If the field is required and no value is provided.

    delete()

    Deletes the field by setting its status to deleted.

    Creating a field instance

    Field.create(name, description, key, required, category, field_type)

    Parameters
    name: string
    Title for the category.
    description: string
    Optional. A long-form description for the category
    key: str
    Key used when exchanging contribution attributes via the API/
    required: boolean
    Indicates if a value for the field is required.
    category: Category
    Category this field is assigned to.
    field_type: string
    Identifies the type of the field.
    Returns

    Field

    Example use
    Field.create(
    'Name of Restaurant',
    'The name of the restaurant',
    'name-of-restaurant'
    True
    category,
    'TextField'

)

    Accessing model instances

    get_list(user, project_id, category_id)

    Returns a list of all fields in a category that the user can access.

    Parameters
    user: User
    User the fields are queried for.
    project_id: integer
    Identifies the project in the database.
    category_id: integer
    Identifies the category in the database.
    Returns

    django.db.models.query.QuerySet: List of Fields

    get_single(user, project_id, category_id, field_id)

    Returns a single field.

    Parameters
    user: User
    User the field is queried for.
    project_id: integer
    Identifies the project in the database.
    category_id: integer
    Identifies the category in the database.
    field_id: integer
    Identifies the field in the database.
    Returns

    Field

    Raises
    Field.DoesNotExist
    If the field was not found in the data base.
    PermissionDenied
    If the field can not be accessed by the user; e.g., the is inactive and the user is not an admin of the project or if the field is inactive.

    as_admin(user, project_id, category_id, field_id)

    Returns a single field if the user is an administrator of the project.

    Parameters
    user: User
    User the field is queried for.
    project_id: integer
    Identifies the project in the database.
    category_id: integer
    Identifies the category in the database.
    field_id: integer
    Identifies the field in the database.
    Returns

    Field

    Raises
    Field.DoesNotExist
    If the field was not found in the data base.
    PermissionDenied
    If the field can not be accessed by the user; e.g., the user is not an administrator of the project.