# Types

# Boolean

Boolean represents a value of false or true, it stores 1 or 0 on the database and don't have any specific configuration.

Attributes

listDisabled default is false and if set to true it will remove the ability to change state from the List template, and will show only "green|red" control in read only mode.
ui can define how the field is presented on the detail template. Default value is "switch", but it can be set to "radio" which will use a traditional radio button control.

{
  "listDisabled": true,
  "ui": "switch | radio"
}

# Color

Color represents an hexadecimal value of a color, in the UI is represented by an advanced color picker.

Data Source Options

List of specific colors that have special highlight on the color picker

["#ff4500", "#ff8c00"]

# Combobox

Combobox represents a list of values.

Data Source Options

We can define a regular SQL query that always need to select id and name (use alias to force the name)

{
  "sql": "SELECT id, title as name FROM ay_profile WHERE id <> 1"
}

We can define static result sets that will feed the data source

{
  "rs": [
    {
      "id": "1",
      "name": "Ok"
    },
    {
      "id": "-1",
      "name": "Error"
    }
  ]
}

Is it also possible to define a diferent source for authorized requests versus request with no logged user. The example below users default keyword to define the source for a logged user, and the public keyword will be applied when the API is used without authentication (possible if the endpoint is public or if using the SDK without a previous authentication).

{
  "default": {
    "name": "Surveys",
    "sql": "SELECT id, title as name FROM survey WHERE tenant_id=[user.tenant_id]",
    "cache": {
      "active": true,
      "reset": [100]
    }
  },
  "public": {
    "sql": "SELECT id, title as name FROM survey"
  }
}

Attributes

Configuration to make client-side cache. The name is an unique identifier for the result set, this means that if you use the combobox in several places you should use the same name for all equal result sets. The cache has an active property that can be true or false, the reset is an array of schema ids that will reset the cache if that schema suffer an insert/update/delete action. The filters is also an array of filters that are run only on client-side.
The ignoreEmpty is a boolean with false as a default value, and it only makes sense if the combo is trigged by another combobox. If the property is true means that the set of values will not be filtered even if the parent combo as no value picked (so it will show all values). When the user picks a parent value, it will filter the values of this combo acoordingly, just like a regular chained combobox does.

{
  "name": "Thesaurus",
  "ignoreEmpty": false,
  "cache": {
    "active": true,
    "reset": [400],
    "filters": [
      {
        "field": "type",
        "op": "=",
        "value": "2"
      }
    ]
  }
}

multiple is a boolean that allows several avalues to be set. Values are saved separated by commas. The value defaults to false.
allowCreate is a boolean that allows creation of new entries on the client side (besides selecting from the result set). Works only with multiple active. The value defaults to false.
source only useful if the sql has a join and can't be used on the api to get the set of values, in those cases the source field should have the name of the table of the sql.

{
  "multiple": true,
  "allowCreate": true
}

watchParms is and advanced configuration to make chained comboboxes.

{
  "watchParams": {
    "field_name": ""
  }
}

Where "field_name" is the name of the field that triggers a change of the result set of this combobox. Using watchParams for non cached objects will trigger a specific endpoint to be called with the new result set for the combobox. For combobox width cache the cache.filters specification will be use to get the the result set.

link is a property that allows to create a link to another place of the MAYS UI. It allows specifying a specific schema, a wildcard (*) or a setting direct to true when the field value contains the processed path
fromRoot allow you to define an absolute link if true, if false the link generation will be relative to the current url.

{
  "link": {
    "schema": 120
  },
  "fromRoot": true
}

{
  "link": {
    "direct": true
  }
}

transferMode at true will set 2 lists side by side, where the list on the left has all the possible values and the right side has the selected values.
transferTitle it's possible to configure the titles of left and right column of the transfer UI component.

{
  "transferMode": true,
  "transferTitle": ["Left title", "Right title"]
}

# Datetime

Represents a time, date or datetime object, on the UI it shows a date picker.

Attributes

Define the type and format of the date. Both attributes are mandatory. Format is what is used to display on the interface (e.g. you can change that to match regional settings like UK or USA date formats). valueFormat is the format used to store information on the database.

It's possible to define the amount of days before and after the current date, that we allow the user to pick on the interface (this is not a hard rule checked on server side).

If min is set to -5 means that we can set the date up to 5 days before the current date, if we set to 5 this means that the first possible date is only 5 days after the current date.

If max is set to 10 days it means that you can set the date just for the next 10 days, after that it's not possible.

Both properties can be set to "NOW" which means the current date.

Date configuration looks like this

{
  "type": "date",
  "format": "yyyy/MM/dd",
  "valueFormat": "yyyy-MM-dd",
  "min": -5,
  "max": 5
}

Datetime configuration

{
  "type": "datetime",
  "format": "yyyy-MM-dd HH:mm"
}

Time configuration

{
  "type": "time",
  "format": "HH:mm"
}

When used as a filter, it's possible to define the UI component in range mode by setting a filter on the field with the LIKE operator. In that mode is also possible to define range shortcuts, the following are available.

{
  "shortcuts": ["48H", "LASTWEEK", "LASTMONTH", "LASTYEAR"]
}

Default Value

Optionally the field can have the current date/datetime/time value

NOW

# File

Represents a generic file, on the UI it shows an upload control.

Attributes

The extension uses a comma separated value of each a allowed extension. Default values are pdf,zip,docx,xlsx.
keepname is a boolean if true the original filename will be used on the server, if false it will be use a random id for the name of the file. The keepname default value is true, so it's an optional configuration.
size is a numeric value in MB that defines the maximum size of the file. The default value is defined by the maxUploadSize from the framework.
path is a multi dimension array that allows to customize the folder where the asset will be stored. The first array means the level the folder and the internal array can use prefix, field and sufix as properties to help creating the folder name. We also have a transformFunction that will perform over the field value (check below the available functions) We can use field names to use their values or we can literal strings on the prefix or sufix properties. For instance the below example would store the file on "contents/schema_name/2020__01/2020/filename.txt" assuming that year is a schema field with value 2020, and month has value 01 and the day field is 10. This property is also available for images.
encoded is a boolean that provide an effective way to protect files/images by hidding the path of the file using a specific endpoint to download the file. This implies that the folder you are trying to protect must be inaccessible for common users (using an htaccess file on the folder with "Deny from all" directive). The default value is false.

{
  "extension": "jpg,pdf,zip",
  "keepname": true,
  "encoded": true,
  "size": 10,
  "path": [
    [
      {
        "field": "year",
        "sufix": "_"
      },
      {
        "prefix": "_",
        "field": "month"
      }
    ],
    [
      {
        "field": "date",
        "transformFunction": "year"
      }
    ]
  ]
}

# Gmaps

Represents a latitude, longitude and zoom value. On the UI it's represented by a google maps with search, and drag and drop features with a marker that defines the coordinate. Internally the data is stored separated by commas. e.g. 38.73361347737698,-9.179645492913892,13 if output is set to "plain", or json if set to json (default).

output: "json | plain"

Attributes

{
  "output": "json",
  "mode": "places"
}

The mode allow to change the behavior, default is empty value and allow user to pan freely on the map, if mode is set to "places" only the search works and the information retrieved is more complete (name, address, lat, lon and zoom).
It's possible to define a coordinate which will be the default center of the map when it's empty.

{
  "lat": 39.7436214,
  "lng": -9.1952226,
  "zoom": 11
}

# Hidden

Special field that only exists on the database, it has no visual representation on the UI but's it's available in terms of data.

# Image

Used to store image paths.

Attributes

The extension uses a comma separated value of each a allowed extension.
editor is mandatory for the moment and the only possible value is "standard".
width and height define the size of the image, this is also mandatory.
The thumbs is optional and allows to create copies of the original image. For each thumb we need to define the suf which is the sufix string that will be added to the original name of the file and the width and height for the thumb. Since thumbs is an array we can define more that one thumb per image.
path see the File type for more info.
if set to true, downloadButton will show up a download button on the detail template.
target can be set to "S3" to write the image content on a S3 like bucket.
you can set optimization settings for the image using the following properties under the optimization property: format, quality and optimizeThumbs

{
  "extension": "jpg,svg",
  "thumbs": [
    {
      "suf": "@1x",
      "width": "100",
      "height": "50"
    }
  ],
  "editor": "standard",
  "width": "200",
  "height": "100",
  "path": [
    [
      {
        "field": "some_field"
      }
    ]
  ],
  "downloadButton": true,
  "optimization": {
    "format": "webp",
    "quality": 95,
    "optimizeThumbs": true
  }
}

Path Transform Functions

At the current moment we have support for the following:

year: only valid if the target field is a date, it will get the year (e.g 2020)
quarter: only valid for dates, it will get the quarter number of the year (1, 2, 3 or 4)

# Number

Used to store numbers (integer or decimal).

Attributes

The format property allows us to define if the number should be integer, decimal or currency, if no value provided integer will be the default format, otherwise we can use "decimal". Notice that for using decimal format the column on the database should be a TEXT based column or a DECIMAL(M,D).

{
  "format": "decimal"
}

The symbol can be used for visual formating.

{
  "format": "currency",
  "symbol": "€"
}

# Password

Used to store passwords.

Attributes

The encrypt property allows us to define the method used to encrypt or hash a password. At this moment it supports hashing with "bcrypt" (default), "md5", "argon" and encryption using "2-way". Support for "argon2" will be available soon (7.2. PHP min).
The return property only works for 2-way and if true will return the decrypted value on the endpoints.

{
  "encrypt": "md5",
  "return": false
}

# Priority

Used to define the priority of an object inside the schema where it belongs. An unique number is stored for each object.

# Socialvideo

Used to store the url of a video from youtube or vimeo. On the UI of MAYS CMS this is represented by an input field that receives the url and then shows the preview of the video.

Attributes

The encrypt property allows us to customize the widht and height of the video window.

{
  "preview": {
    "width": "400",
    "height": "300"
  }
}

# Subschema

This is a fake field since it doesn't store any information on the database, yet it still needs to exist on the table. The meta-data of the fields is used to define the relation of this object with another schema. This relation makes the object the "parent" and each row of the related schema the child. In terms of table model, this means that the child table needs to use the parent_id, parent_schema_id and parent_column fields to make this relation happens (which is automatic using the framework).

Attributes

The maxItems property defines the maximum number of elements that the subschema can have for a specific parent.
The schema property allows us to define the schema id of the child schema, the filters property by default is true and allow us to define if the UI filters section is visible or not for the subschema, this is usefull when you use the same schema on a root menu option and also as a subschema and you don't want to show the filters just on the subschema.

The overrideColumns property allows to override the list_width of the field, this way is possible to hide columns from the list on a subschema and keep that column visible on the schema (this is only usefull when using the same schema in two places).

{
  "maxItems": 3,
  "schema": 161,
  "filters": true,
  "overrideColumns": [
    {
      "field1": 10
    },
    {
      "field2": 0
    }
  ]
}

# Text

Used to store text on different formats.

Attributes

The format property allows us to define the format of text we want to validate and store. By default it stores a common string without any validation or restriction.

We can use one of the following values:

email
phone
alpha a-Z characters only
url
textarea this means the field can contain html tags because it uses on the UI a WYSIWYG editor

{
  "format": "email"
}

The height property defines the height of the textarea (only available for this format of text).
The type is also available for the textarea format and can assume one of the following values: standard, basic, advanced or naked (no editor will be used, just a textarea html tag). The default value is "standard".
listMaxChars can control the amount of text that is displayed on the List Template. Default is 80 characters and if set to 0 means that the whole text will show up.

{
  "height": 200,
  "listMaxChars": 50,
  "type": "standard"
}

allowPaths is boolean only available for format='url' and will allow urls without the protocol portion, making it possible to accept relative urls. The default value is false.

# Urlseo

Used to store the slug of the object. This field needs to have a source defined, to automaticaly create the slug.

Attributes

source points to the field name (not the column) that is going to be used to generate the slug

{
  "source": "title"
}

# Iframe

Used to include pieces of code that aren't possible to integrate in a easy way with the UI.

Attributes

src points to url of the iframe. By default the id of the record will be passed to the iframe as a GET parameter called "id", and the parent id as "pid".

{
  "src": "http://participa-www.afteryou.pt/external/map/index.php?ro=0"
}

height is the height of the iframe defined in pixels or other valid CSS unit.

{
  "height": "400px"
}

This element is very special since it creates an html iframe tag on the UI and allow the iframe to communicate with the framework. The two main communications are setting the value and resizing the content (to resize the iframe height based on the size of the iframe).

Setting the value of the field

window.parent.postMessage(
  {
    type: "data",
    value: "anything you want",
    id: id,
    field: field
  },
  "*"
);

Resizing the iframe

/* auto resize iframe script - start */
findGetParameter = function (parameterName) {
  var result = null,
    tmp = [];
  location.search
    .substr(1)
    .split("&")
    .forEach(function (item) {
      tmp = item.split("=");
      if (tmp[0] === parameterName) result = decodeURIComponent(tmp[1]);
    });
  return result;
};

var lastHeight = -1;
var id = findGetParameter("id");
var field = findGetParameter("field");

sendResize = function () {
  if (
    document.body.scrollHeight != 0 &&
    lastHeight != document.body.scrollHeight
  ) {
    lastHeight = document.body.scrollHeight;
    window.parent.postMessage(
      {
        type: "resize",
        height: lastHeight,
        id: id,
        field: field
      },
      "*"
    );
  }
};

setInterval(function () {
  sendResize();
}, 1000);
window.onresize = function () {
  sendResize();
};
sendResize();
/* auto resize iframe script - end */

← Introduction Attributes →