User-Defined Properties

Last edit: Nov 27, 2019

User-defined Properties are Properties you can create on demand.

Defining user-defined Properties

Properties are defined in YML configuration files for Model Schemas.

properties:
- name: name
  type: string
- name: enabled
  type: boolean
- name: age
  type: integer

The above configuration adds three custom properties: "name" of type string, "enabled" of type boolean, and "age" of type integer.

Property Types

Each Property is described with the type of data that is stored within the database.
Please note that when processing your Property in Liquid, types are automatically converted to those supported by Liquid Data Types.

The table below lists available data types for Property configuration, that are used to configure fields on the database:

Type Description Example
array Arrays hold lists of variables of any type. See Arrays [1, 2, 3]
boolean Booleans are used to represent true/false values. true
date Stores Date "2017-07-07"
datetime Stores DateTime with time zone. It is recommended to store date and time in one format, so if you provide it in different formats, platformOS will convert it to ISO 8601; that’s what GraphQL expects as well. Please note the to_time filter which is very powerful in terms of parsing time. You can display dates/times in any format you want using the localize filter. "2017-07-07 14:00:00 +0000"
file See Custom attachments
float Real numbers 1.0
integer Whole numbers that can be positive, negative, or 0 1
photo See Custom Images
string A UTF-8 character sequence "Some String"

Grouping into models

You can group your Properties into Custom Models.

Form

You can configure Properties settings in Form similarly to other parameters:

...
fields:
  properties:
    name:
      validation:
        presence: true
    age:
      validation:
        presence: true

{% form %}
  <label for="name">Name</label>
  <input value="{{ form.fields.properties.name.value }}" name="{{ form.fields.properties.name.name }}" id="name" type="text">
  {% if form.errors['properties.name'] %}
    <p>{{ form.errors['properties.name'] }}</p>
  {% endif %}
{% endform %}

For more information see our Form Builder Reference and our Building a Contact Form with Models tutorial.

Fetching Property with GraphQL

Properties depend on their parent objects and are accessible in the query after mapping the name of the Property with the query attribute name, you can do that with the property method:

query get_models {
  models(
    per_page: 20,
    filter: {
      model_schema_name: { value: "employee" }
    }
  ) {
    results {
      name: property(name: "name")
      age: property(name: "age")
      enabled: property(name: "enabled")
    }
  }
}

Filtering Property with GraphQL

You can filter GraphQL results based on object properties states.
Each object in the properties array is connected with a Property through its name. Additional options are:

value - matches the value of given property

query get_all_johns {
  models(
    per_page: 20,
    filter: {
      deleted_at: { exists: false },
      properties: [{ name: "name", value: "John" }]
    }
  ) {
    results {
      first_name: property(name: "name")
    }
  }
}

values - matches array of values with given values_operator: OR or AND.

query get_all_johns_and_annas {
  models(
    per_page: 20,
    filter: {
      deleted_at: { exists: false },
      properties: [{ name: "name", values: ["John", "Anna"], values_operator: OR }]
    }
  ) {
    results {
      first_name: property(name: "name")
    }
  }
}

range - available options for range are: lt, lte, gt, gte:

query get_all_adults_below_60 {
  models(
    per_page: 20,
    filter: {
      deleted_at: { exists: false },
      properties: [{ name: "age", range: { gte: $adult_age_treshold, lt: 60 } }]
    }
  ) {
    results {
      first_name: property(name: "name")
    }
  }
}

range uses ISO 8601 date-time formats, for example:

{
  name: "last_time_active",
  range: {
    lte: "2019-10-02T08:13:00",
    gte: "2019-09-01T08:13:00"
  }
}

exists

query get_all_with_name {
  models(
    per_page: 20,
    filter: {
      deleted_at: { exists: false },
      properties: [{ name: "name", exists: true }]
    }
  ) {
    results {
      first_name: property(name: "name")
    }
  }
}

Please note that the above examples are only valid for Properties defined on Model Schema. Please refer to GraphQL schema in order to filter Properties defined on different parents than Model Schema.

Questions?

We are always happy to help with any questions you may have.