Model
Naming conventions
These are the basic rules for a builder while creating a model.
Model name
English
This makes it understandable for most users what the model is used for.PascalCase
The model name must be PascalCase and singular. This makes the model names readable and consistent. Examples: Invoice and InvoiceLine.
Description
The advice is to add a short descriptionwith useful information;
about the functionality of the model;
with the reason for using the model.
Best practice If there are specifics regarding the data model, name them so other developers could keep that in mind when working with/on this model. |
Properties
Models should be light and nimble. If relations could be used, you should use them to create a solid database and to prevent redundant data. Loading times will benefit from this setup.
When adding a lot of properties to a model you might run into a limit. Depending on the types of properties used, this limit lies around 25 properties per model. Please prevent yourself from going anywhere near this limit.
Naming conventions
Property name
English
This makes it understandable for most users what the model is used for.Capitalize property name
Save the name capitalized, so always start the name with an uppercase letter and use a space between the separating words.
The property name must comply with the following rules:
- Name must start with a letter.
- Only use alphanumeric (A to Z) characters or numbers (0 to 9).
- Use a space ( ) for separating words.
Example
Date/Datetime properties affix with at, for example, Created at.
Checkbox properties prefix with is and affix with a question mark, for example
Is valid?.
All others can only save the name capitalized, for example, First name.Use Snake case for the database name
The platform will automatically convert any used capitals to lowercase called snake case. By using snake_case the properties remain readable for the human eye.
The database must comply with the following rules:
- Name must start with a letter.
- Only use alphanumeric (a to z) characters or numbers (0 to 9).
- Use an underscore ( _ ) for separating words.
Example
Date/Datetime properties affix with _at, for example, created_at.
Checkbox properties prefix with is_, for example, is_valid.
All others can only use snake cases, for example, first_name.
Property types
Choose the type that is best suited for your needs, for example: don’t store a password in a text property but use a password property.
Best practice Regarding the multi-file property:
|
Application Memory
Size of a single public file has a maximum of 10MB
Applications are allowed to store a total of 1GB of record data in the database.
The assets in applications hosted on the Betty Blocks public cloud have a separate storage, the application asset size has a limit of max 50GB.
Default value
Almost all properties (like CHECKBOX, DATE, EMAIL ADDRESS, LIST, NUMBER, PRICE, and TEXT) and all belong-to relations allow you to set a static or dynamic default value. As soon as a new record is created, and no manual input was set for the concerning property, the default value will be stored.
Best practice When using a list property, it's best to set one of the values as the default value and make it required. By doing so, the empty value isn’t an ‘invisible’ value. |
Format
Properties like DATE, DATETIME, DATE, NUMBER, NUMBER WITH DECIMAL, and PRICE allow you to set a default format.
Best practice To speed up the creation of your web pages and benefit from the consistency of the data displayed by the application, set a default format per property. |
Validations
These are the basic rules for validation:
Mark at least one property as required
By checking this option a record can not be stored in the database unless this information is provided. If you create a new property on a model and make it mandatory by selecting this option, this will affect the currently present records. If you don’t take precautions, the application doesn’t let you update existing records since this info is missing.Mark it unique to prevent duplicates
Use this validation when there should be no duplicates in the database, for example, the property email address of a web user.
Best practice Prevent the app from creating empty records by making at least one property per model required. |
Best practice Prevent the app from creating duplicates by marking unique at least one property per model. |
Update property
If for whatever reason you want to rename a relation that isn’t (widely) used, it is advised to:
only rename the Name and don’t rename the Database name; or
remove the wrongly named property and create a new one since
The initially defined name is used in the database and will not change if you rename it. As a Betty Blocks user, this will not have any effect, but if something goes horribly wrong with the applications and changes have to be made in the Betty Blocks database, it will be much harder to debug.
Delete property
Unused properties shouldn’t be in the application. Delete unused properties to prevent yourself and your colleagues from using the wrong properties in the application.
Checking the property references
Before deleting a property, you must check the property’s dependencies and all templates. I.E.: If the property is used in an action, this action could return an error after the deletion.
Relations
Models should be light and nimble. By doing so, you create a solid database and reduce loading times.
Naming conventions
Name
English
This makes it understandable for most users what the model is used for.Capitalize Relation name
Save the name capitalized, so always start the name with an uppercase letter and use a space between the separating words.
The relation name must comply with the following rules:
- Name must start with a letter.
- Only use alphanumeric (A to Z) characters or numbers (0 to 9).
- Use a space ( ) for separating words.Use Snake case for Database name
The platform will automatically convert any used capitals to lowercase called snake case. By using snake_case the properties remain readable for the human eye, for example invoice_lines.
The database must comply with the following rules:
- Name must start with a letter.
- Only use alphanumeric (a to z) characters or numbers (0 to 9).
- Use an underscore ( _ ) for separating words.
Relation types
These are the basic rules for creating a relation:
Choose the right type of relation;
When creating a relation, decide which relation type to use and how to name it.
Use singular for “Belongs to” relations
Example
Invoice >-------------- ( belongs to ) ----------------|-Customer
Always validate the presence of this relation (make it required) unless there are very strong reasons not to do so.
Use plural for “Has many” relations
Example
Customer-|-------------- ( has many ) ------------------<Invoices
Use plural for “Has and belongs to many” relations
Example
User>------ (has and belongs to many) -----<Roles
Best practice If for whatever reason you want to rename a relation that isn’t (widely) used, it is advised to
or
The initially defined name is used in the database and will not change if you rename it. As a Betty Blocks user, this will not have any effect, but if something goes horribly wrong with the applications and changes have to be made in the Betty Blocks database, it will be much harder to debug.
Advise
|
Best practice A “has and belongs to many” relation doesn’t give much flexibility because it’s only saving the relation between the two models. Create a bridge table for more flexibility.
Example An Order could have a has and belongs to relation to the Product. This relation doesn’t allow you to store how many items of this product are in this order. You can consider using a bridge table by creating an extra model Orderline and connecting the model to both other models via a belong to relation.
|
Delete relation
Relations that aren’t used shouldn’t be in the application. Delete unused relations to prevent yourself and your colleagues from using the wrong relations in the application.
Best practice Check the relation’s dependencies before deleting. If the relation is used, for example: in an action, after deletion, this action could return an error. Use the dependencies to navigate to the actions, pages, etc., so the relationship can be deleted without complications. |
Permissions
Permissions determine what a user (based on the given role) is or isn't authorized to do. Every back office user and Data API user needs a role.
Example
You could have administrators and order pickers. An order picker should only be able to read the invoices and their invoicelines while the administrator is able to not only read them, but also update and delete them. Set the permissions on the model level to accomplish this.
The role public is a default role that is applied to unauthenticated users in the page builder and Data API. Check the models which can possibly show data in the front end.
Validations
The validations tab displays an overview of the type of validations used on the model’s properties. Existing validations could easily be edited by clicking the tab Properties.
Best practice Use the tab Validations to check the belongs to relations are set to required. |
Settings
Model name
You are able to rename existing models. If your model isn’t widely used it is advised to apply the best practice.
Best practice When renaming a model, the original name remains in the Betty Blocks database. If in case of errors, Betty Blocks needs to apply manual changes in the database this could be complicated when the model name doesn’t correspond with the Betty Blocks database. Therefore, if you need to rename a model, it’s always best to delete the wrongly named model and replace it with a new one. |
Allow import
By enabling the import functionality, you’re able to import data towards Betty Blocks. It could be useful for testing to have data in your application, but it’s time-consuming if you’d add this data by hand. Therefore the import functionality would be useful. By setting this option to TRUE, you’re able to do an import via the grid view of the model.
Best practice When importing a lot of data, we advise you to create a new model (the name starting with Import, for example, ImportCustomer) and only import the data as text. When all the data is imported, the data can be processed via a batch action. The action gives more flexibility than directly importing it into the related model because the action can check duplicates, assign related models, and any other conditions. |
Allow mass delete
When creating an application it might be useful to mass delete records using the grid view.
Example
When a developer is creating an application he will be testing if indeed the Invoice and InvoiceLines are created. This could create a lot of test data that you want to delete with one simple click. But, as soon as the developer finishes his job and the app is taken into production, having this option still active is a big risk. Customers could have placed orders that you’ve accidentally deleted in the back office.
Important Disable ‘Allow mass delete’ before merging to the next sandbox. |
Settings model
When enabling the settings model option in your app, all data in this model will be merged through to all sandboxes. This is useful if the data in this model doesn’t have to change a lot and will be used as a setting, for example, roles, countries, and VAT rates. This setting should only be used if the containing record has a meta-purpose.
Think twice before changing an existing model into a settings model. Turning a model into a settings model will transfer all records within the model to the merged-to sandbox on merge. This data will be overwritten on every merge and will be active after the second merge (as protection). It will also overwrite the existing records, including their association with other records (excluding all has and belongs to many relations).
Label property (only for back office usage)
Label properties are set to ID by default. This ID doesn’t give much information to a back office user. Consider changing them to a property that could be of interest to the end-user.
Best practice Change the label property to a property that is more of interest to the end user, like invoice_number, email_address, account_id, etc.. |
Order property (only for back office usage)
The default order in which data is shown in the back office can be changed by setting the order property.
Best practice Consider what information is useful for back office users. These users might be interested in the most recently placed orders, so descendingly order them by created_at date. If you’d create a list of organizations, an alphabetically ordered list of organization names would be more useful. |
Log mutations (only for back office usage)
There might be some key features in the app that should be logged. This setting logs every mutation (create/update/delete) in a hashed format with the UUIDs, old value, and new value.
Important note: the log mutation is only untraceable to a specific record when the record has been deleted.
Example
You might need to show an IBAN on your site which your customers have to transfer their money. If you’re able to change this IBAN in the app, it’s advised to log by who and when the change was made. By setting this option to TRUE, these changes could be made visible in the grid view.
Delete model
Models that are unused shouldn’t be in the application. Delete unused models to prevent yourself and your colleagues from using the wrong models in the application.
Best practice Check the model’s dependencies before deleting it. If the model is used, for example: in an action, after deletion, this action could return an error. Use the dependencies to navigate to the actions, pages, etc., so the model can be deleted without complications. |
Readable schema overview
The schema overview could be very useful to get an understanding of the application. To make it live up to its potential, you’ll need to organize the overview.
Best practice Drag and drop the models in such a way that there are no overlapping models and lines crossing each other. |