MAYS Documentation

# Schema

In the framework, any file with a name starting with 'schema_' and a JSON extension will be automatically loaded. Inside these files, you'll find an array of schemas. Think of a schema as a blueprint for an object of a class. It's a representation of data, often mapping to a table on the database. With schemas, you can define not only the structure but also rules and advanced behaviors.

What sets our framework apart is its flexibility. You can attach metadata to schemas, allowing you to specify not only the basics like data types and mandatory fields but also UI-related properties and advanced logic for interactions between fields.

# Basic example

{
  "id": 1,
  "title": "User",
  "fields": [
    {
      "fieldKey": "username",
      "label": "Username",
      "mandatory": 1,
      "minChars": 4,
      "readOnly": 1,
    },
    {
      "fieldKey": "password",
      "label": "Password",
      "type": "password",
      "mandatory": 1,
      "minChars": 8,
      "attributes": {
          "encrypt": "bcrypt"
      }
    }
  ]
}

This creates a schema named User with two fields where both are mandatory, where the first is a read only text based field with 4 minimum chars and the second one will store the password using an algorithm called "bcrypt".

# Properties

You can ommit every property that as a default value, properties that only affects UI are marked with a ui.

  • id: internal representation, should be unique for each schema.
  • title: PascalCase name of the schema.
  • dbTable: The name of the database table. If omited it will create a new table based on the title.
  • attributes: an object that allow you more specific configuration (see Schema Attributes section for more information)
  • orderBy: the field where you want to order by your results, bu default will be the ìd, or if the schema as a priority field will be the priority the default.
  • orderByDirection: Can be ASC or DESC, meaning that we can define if the sorting order is ascending or descending. Default is ASC, yet if the schema as a priority field DESC will be default.
  • whereRestriction: an array of objects that allow to restrict the information retrieved from the database.
[
  {
    "field": "schema_id",
    "value": 5,
    "op": "="
  }
]
Interested in a more advanced example?

Is it also possible to define different restrictions based in some factors. The below example uses public if no authentication is present, default if there is a user authenticated on the request or admin for a specifc profile group, this means that we can use superadmin or any other profile name that is valid for the system.

{
  "public": [
    {
      "field": "schema_id",
      "value": 5,
      "op": "="
    }
  ],
  "default": [
    {
      "field": "schema_id",
      "value": 4,
      "op": "="
    }
  ],
  "admin": [
    {
      "field": "schema_id",
      "value": 3,
      "op": "="
    }
  ]
}
  • rule: SQL rule that must not return any record, otherwise the insert/update operation will not continue. Notice you can use inside brackets any field of the current schema.
{
  "sql": "SELECT id FROM ay_user WHERE id <> [id] AND username = [username]",
  "message": "The username you entered is already in use!"
}
  • permissions: Comma separated values with the list of permissions that a schema can handle.
List available permissions

list,insert,update,delete,view,csv,xls,preview

Custom properties can be added as needed.

  • pagination: default is 10 and this defines the page size, or amount of records while retriving information partialy.
  • primaryKey: default is id but can be any field that is set as PRIMARY KEY of a table.
  • panels ui: Allow the definition of groups of fields, usefull for generating Tab elements on the UI.
[
  {
    "id": 1,
    "name": "Global"
  },
  {
    "id": 2,
    "name": "Others"
  }
]
  • actions: In order to create custom buttons inside a UI template (list and detail) we can use actions. There are 3 types of actions.
Type Description Example
list available for each row of a table (template list) Export PDF
list_header available for the entire table Delete all rows
detail avaible for a specific record (template detail) Export PDF
Checkout the properties for each action

There are some properties that can be defined for each custom action.

  • permission that must match a valid permission for the schema
  • name the name for the action button
  • icon the icon for the action button (must be a valid icon of the mays icon collection)
  • url the name of the endpoint
  • method the method of the endpoint (GET, POST, PUT, or link)
  • response the type of response of the enpoint (json for regular calls,blob for downloading files or redirect to follow to another url)
  • hideSubschema is a boolean that is true by default, if false the action will not appear if the schema is used as a subschema.
  • filter is an array that allows to define a set of conditions that defines when the button should be visible. The field should be a valid field of the schema that must be present on the list.
{
  "list": [
    {
      "permission": "sendmail",
      "name": "Send E-Mail",
      "icon": "envelope",
      "url": "sendmail",
      "method": "post",
      "hideSubschema": false,
      "filter": [
        {
          "field": "state",
          "op": "=",
          "value": "1"
        }
      ]
    }
  ],
  "detail": [
    {
      "permission": "download",
      "name": "Download",
      "icon": "download",
      "url": "download",
      "method": "get",
      "response": "blob"
    },
    {
      "permission": "previsualize",
      "name": "Pré-visualizar",
      "icon": "preview",
      "url": "http://afteryou.pt/page/[id]",
      "method": "link"
    }
  ]
}

Special Method link

Notice that the special link method (opens on a _blank page a new link defined on the url, instead of calling any endpoint) can use a special wildcard called "id" that will be present on "detail" and "list_header" scenarios.

  • fields: the list of fields that belongs to this schema.

# Attributes

This is an object that agrupates several advanced features like inheritance or UI related information.

  • The title ui is the human readable name for the Schema, that will be used for the UI, namely to build a bread-crumb-trail.

  • The fieldTitle ui allows to define a column of the schema to be used on the title or breadcrumb of the page.

  • The fieldTitlePosition ui allows to define where and how the fieldTitle will be shown. Possible values both | breadcrumb | subtitle.

  • extends can hold a schema id in case you want to create inheritance between two schemas. When doing inheritance you can override any field by re-defining it with the new schema_id but keeping the fieldKey and everything you need for the field to work on the new schema.

  • The help ui is UI property that will show some contextual help near the title of the page. This is the default value for the schema and currently is used on the List and Detail Template. If you want to set the help just for the detail template you can use helpDetailTemplate.

  • helpFormat ui allow you to define how the help is displayed for the schema. If nothing is set it will show on mouse hover like a tooltip, if set to "inline" it will show the text below the title of the schema.

  • helpDetailTemplate ui allows to set a specific help text for the template template.

{
  "title": "Users",
  "fieldTitle": "username",
  "fieldTitlePosition": "both",
  "extends": 110,
  "help": "This screen manages the users list",
  "helpDetailTemplate": "This screen allow you to view and update a user.",
  "helpFormat": "inline"
}
  • The import ui property controls if the import has a validation step validateActive, and allows to define custom endpoints for validation and import, that will ignore the default endpoints.

It's also possible to define the path of a sample file.

To build a dynamic or custom template sample we can use the templateEndPoint (default behaviour will generate an excel file based on the schema fields).

{
  "import": {
    "templateSample": "path",
    "validateActive": false,
    "validateEndPoint": "validate-custom | validateSpreadsheet",
    "submitEndPoint": "import-custom | importSpreadsheet",
    "templateEndPoint": "template-custom | templateSpreadsheet"
  }
}
  • There also a specific configuration for the Matrix template.
{
  "matrix": {
    "crossAxisTitle": "Projectos",
    "hasTotal": true
  }
}

Where crossAxisTitle is the upper top title where the X axis cross with the Y axis, and hasTotal shows a last row with the sum of each column if is true.

  • extends and extendsData allow to create hieritance between schemas, the extends receives the id of the parent schema, and the extendsData is a boolean where when is true the schema will behave like an extension of the parent schema (for instance will use the parent schema name for upload folder organization), but if extendsData is false the schema inherits the fields from the parent but behave fully independent from the parent.
{
  "extends": 100,
  "extendsData": true
}
  • editMode ui by default is off (empty value) but can be set to "inline". In this case if the schema is used on a sub-schema the "add" button will allow list inline edition, also the edit action will be inline. This is limited to basic fields like text.
{
  "editMode":"inline"
}
  • buttonLabels ui allow you to define custom labels for some of the schema buttons like the add that appear on top of every list template or subschema list, or the addSave that changes the save button for a detail template.
{
  "buttonLabels": {
    "add": "Custom Ddd button label",
    "addSave": "Custom Save"
  }
}

  • showDefaultFilter ui a boolean that if set to true it will show filters for all filterable fields that are on the list view.

  • preview allows the creation of a button "preview" on the schema that will use the preview route of the "template-www" to allow to users to preview contents of the CMS that are not active. Useful for users to preview contents before going live. The value should be a string with the name of the PHP handler that implements the schema on the website. To learn more read about the "template-www" features and structure.

{
  "preview": "LibraryDetail"
}

Which will be converted to a real route, e.g.

{
  "preview": "/_preview/LibraryDetail/[urlseo]"
}

The following properties are sugar syntax that creates certain fields with just one property.

  • isActive creates the "active" boolen filter very common to set visibility/state of an object.

  • isSubschema if set to true, creates automaticaly parent_id, parent_schema_id, parent_column fields.

  • hasPriority if set to true create a priority type of field that allows you to custom sort elements.

  • hasUrlseo Define a string of the field name that the urlseo

{
  "isActive": true,
  "isSubschema": true,
  "hasPriority": true,
  "hasUrlseo": "title"
}
Last Updated: 11/16/2024, 12:12:27 AM

← Introduction →