How to use Data Sources

Create a data source in Fliplet Studio, add columns and a security rule, and read and write its records from screen code.

Create a data source in Fliplet Studio, add columns and a security rule, and read and write its records from screen code.

Before you start

This page applies to Fliplet Studio and the Fliplet JavaScript SDK, on web and native.

• Open your project in Fliplet Studio. Data Sources is in the project sidebar.
• Screen code is edited in the Code view, where screens are files in src/screens.

Create the data source

1. In the project sidebar, select Data Sources.
2. Select Create new data source.
3. In the prompt, enter a name of up to 255 characters. The name is required.
4. Select OK.

The new data source opens. [UNVERIFIED: Studio UI, seen only in code because showing it needs a create] It starts with the sample columns Column 1 and Column 2 and two rows of demo data. These are built in the browser, so nothing is stored until you save.

Name the columns

On the Entries tab, row 1 holds the column names and the rows after it hold records.

Studio shows this warning on a data source: "Modifying data while live users are accessing the app may overwrite data."

Two columns can't share a name: the grid renames a duplicate. A column still called Column (1), Column (2), and so on, with no values, is removed on save.

1. In row 1, replace each sample name with your column name.
2. To add a column, select a cell in the column to its right.
3. Select Insert column before in the toolbar.
4. Replace the demo data rows with your first records.
5. Select Save changes. [UNVERIFIED: Studio UI, this button on the Entries tab appears only after an edit]

Add a security rule

A new data source has no security rules, so requests that the rules apply to are refused until you add one.

Choose who the rule covers under Allow:

Select Logged in users when only people who have signed in should reach the records. Select All users only for records anyone may see. The dialog starts on All users, so change it if you need a login. Secure Data Sources covers Specific users and Specific token.

> [!CAUTION] > Security: A rule with All users and Read opens the records to anyone using the project.

Choose what the rule allows under Users can. These are checkboxes, so one rule can cover several operations. Your code needs a rule for each operation it uses:

1. Select the Security rules tab.
2. Select Add new rule.
3. Select Create my own rule.
4. Under Allow, select who the rule covers.
5. Under Users can, select every operation your code uses.
6. Select Add rule. It stays disabled until you select an operation.
7. Select Save & Apply. [UNVERIFIED: Studio UI, this button appears only after a rule changes]

Applies to defaults to All projects. Include or exclude columns and Request data requirements are optional.

The Add new rule menu also has pre-configured rules, such as All users can read. Selecting one adds it to the list and opens it in Edit security rule. Select Confirm, and it still needs Save & Apply. Logged in users can write grants insert only.

Connect from screen code

Fliplet.DataSources comes from the package fliplet-datasources, which the project must list as a dependency. It isn't available at boot.

1. In the Build view, enter a request in the chat box to add the fliplet-datasources dependency. [UNVERIFIED: Studio UI, the chat's reply wasn't checked and no way to add the dependency by hand was found]
2. Select Send message.
3. Find the data source's ID in the ID column of the Data Sources list, or as Data source ID on the Settings tab.
4. In your screen file, connect by ID with Fliplet.DataSources.connect(), or by name with Fliplet.DataSources.connectByName().

Both return a promise for a connection. The chat's add_dependencies tool stores the dependency on the project's AI preview screen, and an eager dependency loads on every screen. It's ready when Fliplet() resolves. A lazy dependency is loaded with Fliplet.require.lazy.chain(). When the dependency has loaded, Fliplet.DataSources is defined in your screen code.

await Fliplet();

const connection = await Fliplet.DataSources.connect(123);

Read records

Call connection.find() with the options you need. It returns an array of records.

const tasks = await connection.find({
  where: { Status: 'Open' },
  order: [['data.Title', 'ASC']],
  limit: 20
});

tasks.forEach((task) => {
  console.log(task.id, task.data.Title);
});

Each record has an id, and its column values are under data. findOne() takes the same options and returns the first record or undefined. findById() returns one record. For other query options, see Fliplet.DataSources.

Offline availability on the Settings tab controls offline use. New data sources start as Online only, which requires an internet connection. Available offline works without internet.

On native, when the local database is available and offline: false isn't passed to connect(), reads try the offline database first. If it can't be opened or the read fails, the read repeats online. Web reads go to the server. Offline reads don't apply order. See Use data online and offline.

Add, update, and delete records

1. Call connection.insert() with an object of column values to add a record. It resolves to the new entry.
2. Call connection.update() with a record's ID and the columns to change. Other columns keep their values.
3. Call connection.removeById() with a record's ID to delete the record.

const entry = await connection.insert({ Title: 'Book venue', Status: 'Open' });

await connection.update(entry.id, { Status: 'Done' });

await connection.removeById(entry.id);

Writing a key that isn't a column adds it as a new column.

Check it worked

Security rules aren't checked for Studio users outside preview, or in preview with security turned off, so test in preview with Enforce security on. With a Logged in users rule, sign in inside the preview first: a Studio login doesn't count.

A refused request rejects the promise, so wrap your calls in try and catch.

1. Hover over Preview settings in the top bar.
2. If Enforce security is off, turn it on.
3. Select Refresh preview.
4. In the preview pane, go to your screen.
5. Use the feature that runs your code.

If your code reads records, your screen shows them. To check a write:

1. Select Data Sources in the project sidebar.
2. On the data source's row, select Actions.
3. Select Edit.

The Entries tab shows the new record.

If it didn't work

When no rule grants the operation, the request fails with this error, where the operation is read, write, update, or delete: [UNVERIFIED: Studio UI, this message was seen only in code because showing it needs a refused request]

The security rules for the Data Source "Tasks" do not allow this app to read data.

Requests made with an app token get this error instead:

You are not allowed to read this data.

See also

• Create and configure a Data Source: full detail on setting up a data source.
• Add, edit, import and export records: managing records in Studio.
• Secure Data Sources: writing detailed security rules.
• Fliplet.DataSources: every method and query option.
• Data Source access and permission errors: fixing access errors.