Comment on page
A collection (or table0 contains a list of items of the same type, like users, companies or tasks. Your portal will come with several collections by default, such as Users and Companies.
Your portal's data tab allows you to view your existing collections, create new collections, add additional fields to your existing collections and create, update and delete collection records. It's your very own database.
A collection contains a list of items of the same type, like users, companies or tasks. Your portal will come with several collections by default, such as Users and Companies. But you can add a collection to store any sort of list that you'll need for your company.
Each collection is built of records and fields. Again, each collection comes with some default fields such as id, uuid and created at.
A record is simply an individual item in a collection. Imagine a row in a table or a row in a spreadsheet. If you have a collection of users, then an individual user is represented by a record.
Information related to each record is stored in fields. Each field can store different types of information such as text, checkboxes, select options or a relationship to another record.
You can add any number of fields to each collection, including the User and Company collections. This will help you track and store even the most complex of records.
Each field is defined by a Type and a Name. The type controls what type of data you can store in the field (more on that later) and what sort of input box you and your clients will see when they interact with the field.
Before diving any further into collections and field types it makes sense to start with a simple example. As mentioned, each table comes with a User and Company collection. But what if you wanted to list your client's Projects?
- Visit the data tab in your portal's builder. Click New Collection at the top of the left sidebar.
- Choose a name for your collection; in this case, Project. Pro tip: It's much easier if your collection name is singular. Even though it will be a list of Projects, each individual record will be a Project.
- Press Save
It's time to start thinking about what a project is. It's probably got a Name, it might have a Description. When we work on a project it's for a specific client, so we'll have to store what Company it's belonging to. We might want to specify the project Owner, that's the person on our team who looks after the project. And then we might have a Start Date and a Due Date and a cost field.
Breaking it down, that's 6 new fields we will have to add to our new collection, but first we need to decide what field type each will need to be.
- Name A simple text field
- Description A simple text field
- Company This will need to be a relationship between Project and Company. There will be 4 different options that let you describe the relationship (more on this later). A Project can only have one Company. A Company can be associated with many Projects.
- Owner Similar to the above, this will need to be a relationship between Project and User. The relationship is as follows: A Project can only have one Owner. A User can be associated with many Projects.
- Start Date A simple date field
- Due Date A simple date field
- Cost A simple Integer (decimal) field
Don't forget to hit Save.
As you saw in the above example, field types help us model the collection in a reasonable way, and then link records to other records (often in other collections).
There are several field types and you can have as many as each as you like:
- Text Good for text of any length. When editing text fields, you can insert multiple lines. Example field: First Name Example Value: John
- Date A date and its time. When editing a ate you will be presented with a calendar widget to specify a date (and time) Example field: Due Date Example Value: 2021-09-04 08:27:50
- Number (Integer) Whole numbers like 1,2,3. Inputs will only accept numbers and any non-whole numbers will be truncated to their whole numbers (i.e 7.9 becomes 7). Example field: Rating Example Value: 3
- Number (Decimal) Non-whole numbers like 1.46, 2.0, 3.334. Inputs will only accept numbers (of any kind) Example field: Cost Example Value: 5.676
- Boolean (Yes/No) Good for values that are binary, i.e. true or false, on or off, disabled or enabled. It renders either a checkbox or a dropdown (with yes and no as options). Example field: Is Active Example Value: False
- Single option select Great for when you want to choose only one option from a set of pre-defined options. You'll see a list of options when you edit one of these fields. Example field: Project Type Example Value: Campaign
- Multiple options select Great for when you want to choose multiple options from a set of pre-defined options. You'll see a list of options when you edit one of these fields. Example field: Tags Example Value: Help, Inquiry
- Duration A length of time (without any dates). Great for storing how long something took (or should take) Example field: Open Time Example Value: 01:23:56
- Rollup A summary of related fields. Choose a relationship on the same collection, choose which field on the related collection you need to summarize and then choose how to summarize it. An example would be if you wanted to calculate the total cost of all projects that each client/company has in the above example. You would add a rollup field to the Company collection with the projects relationship we defined earlier. The field to summarize would be Cost and you would want to SUM the costs, so you get the total sum of costs of all projects associated with a given company. You can read more about Rollup fields here
- Relationship A relationship lets you link one record to another (or many others). The examples above showed how you can relate Projects to Companies, and Projects to Owners, but there are 4 different types of relationships all together. You can read more about them here
- One to One: This is when each side of the relationship can only be directly related to at most one other record. For example, if each Company needed to be assigned an admin, you could say that each Company can have exactly one admin, but an admin can only be the admin of at most one company. That way you can easily access the company's admin's details.
- Many to One: This is the most common relationship. The relationships used in our examples were examples of many to one relationships. That is to say, A given many projects can have the same company, but a project can only have one company. If you are using this data in the builder, the company will have a list of projects associated with it, but the project will have only one company associated with it.
- One to Many This behaves the same as many to one but in reverse. It's handy if you can't figure out exactly which side of the relationship to put the field on. Although it's always preferable to use a Many to One. For example, instead of adding the Many to one relationship on the Project table, you could instead add a One to Many relationship on the Company table, the end result would be the same.
- Many to Many This is the most complex of all the relationships, but it is very useful if you need to have multiple options on both sides of the relationship. If we take our Project owner relationship, but instead of a project only having one owner, if we change it to allow it to have multiple owners, then we would need a many to many relationship. Each project can have many owners, and an owner (user) can be the owner to many projects. When using this data in your portal, each side of the relationship will have a list of the opposite type. I.e. users will have a list of owned projects and projects will have a list of owners.