@lowdefy/docs-content 0.0.0-experimental-20260710073520

package/content/tutorial/tutorial-actions-operators.md

@@ -0,0 +1,222 @@
+# 4. Interactive pages with actions and operators
+
+If you have been following along, you can continue with your current config. Else, you can find the config from the previous section [here](https://github.com/lowdefy/lowdefy-example-tutorial/tree/main/03-adding-blocks).
+
+## Configuring the reset button
+
+The reset button should reset all the user's inputs. To do this, we can add a [Reset action](/Reset) to the reset button.
+
+#### 4.1. Configure the reset button
+
+Copy the following into the definition of the reset button:
+
+##### `new-ticket.yaml`
+```yaml
+id: new-ticket
+# ...
+blocks:
+  - id: content_card
+    # ...
+    blocks:
+      - id: page_heading
+        # ...
+        # ...
+        # ...
+      - id: reset_button
+        type: Button
+        layout:
+          span: 12
+        properties:
+          title: Reset
+          block: true
+          icon: AiOutlineClear
+################ -------- Copy from here -------- ################
+        events:
+          onClick:
+            - id: reset
+              type: Reset
+################ -------- Copy to here ---------- ################
+      - id: submit_button
+        type: Button
+        # ...
+```
+
+If you add some inputs into the form and click the reset button, those inputs should be cleared.
+
+### How it works
+
+Blocks can define events, which they can trigger when certain events happen on the page. You can then define a array of actions, that are executed sequentially when a block triggers an event. The button triggers an event called `onClick` when it gets clicked. We can add an array of action definitions that will be executed when this action is fired. We only added one action, the [`Reset` action](/Reset), that resets the page state as it was when it first loaded.
+
+## Required fields
+
+We should validate the form to make sure the user input data is clean for the app to work as expected. The `ticket_title` and `ticket_type` fields should be compulsory, and the user should not be able to submit the ticket if they are not completed.
+
+#### 4.2. Mark fields as required
+
+To make the fields required, add a required property to the input blocks like this:
+
+```yaml
+- id: ticket_title
+  type: TextInput
+  required: true
+  properties:
+    title: Title
+```
+
+A red asterisk should appear next to each input field, looking like this:
+
+We can now add a [`Validate` action](/Validate) to the submit button. This will validate the inputs and give an error if any inputs are not filled in.
+
+#### 4.3. Add a Validate action
+
+Add the validate action like this:
+
+##### `new-ticket.yaml`
+```yaml
+id: new-ticket
+# ...
+blocks:
+  - id: content_card
+    # ...
+    blocks:
+      - id: page_heading
+        # ...
+        # ...
+        # ...
+      - id: submit_button
+        type: Button
+        layout:
+          span: 12
+        properties:
+          title: Submit
+          block: true
+          color: primary
+          variant: solid
+          icon: AiOutlineSave
+################ -------- Copy from here -------- ################
+        events:
+          onClick:
+            - id: validate
+              type: Validate
+################ -------- Copy to here ---------- ################
+```
+
+Now if we click the submit button and all our inputs aren't complete, a message pops up saying we have validation errors on the page. All the fields that have not been completed are highlighted in red.
+
+The result should look and work like this. The examples in this tutorial are live versions of the tutorial app, so you can verify that they work like your own app.
+
+Log a ticket
+
+### How it works
+
+The [Validate action](/Validate) we added to the submit button evaluates all the input blocks on the page, and gives an error if any of them fail the validation. This will also stop the execution of any actions after that action. For example, the app won't insert the data into our database if a Request action is used after a failing Validate action. The first time a Validate action is called on a page it sets a flag that tells all the input blocks to show their validation errors.
+
+## Hiding blocks
+
+We would like to ask the user if they had purchased the product within the last month, for which they are formulating a complaint. To do this, we will add a input block with a `visible` property. This property expects a boolean value. In Lowdefy, we can make use of [operators](/operators) to evaluate logic. We'll use the [`_eq`](/_eq) operator to test if the ticket type is equal to `Complaint`.
+
+#### 4.4. Add a block with a visible condition
+
+Add the following [`ButtonSelector`](/ButtonSelector) to your app.
+
+##### `pages/new-ticket.yaml`
+```yaml
+id: new-ticket
+# ...
+blocks:
+  - id: content_card
+    # ...
+    blocks:
+      # ...
+      - id: ticket_description
+        type: TextArea
+        properties:
+          title: Description
+################ -------- Copy from here -------- ################
+      - id: purchase_in_last_month
+        type: ButtonSelector
+        visible: # Test if block should be visible to the user
+          _eq: # Equals operator
+            - _state: ticket_type # Get the ticket_type value from state.
+            - Complaint
+        properties:
+          title: Did you purchase this product within the last month?
+          label:
+            colon: false # Hide the label colon
+          options:
+            - Yes
+            - No
+################ -------- Copy to here ---------- ################
+      - id: reset_button
+        type: Button
+```
+
+If you select the "Complaint" ticket type, the selector confirming if you purchased the product within the last month should appear.
+
+### How it works
+
+If the visible field value is `false`, the block won't be rendered. To change this value while our app is running, we use an operator. [Operators](/operators) evaluate every time something in the app changes, like when a user provides an input.
+
+We used the [`_eq`](/_eq) operator to check the ticket type is equal to 'Complaint'.
+
+To get the value of the `ticket_type` input, we use the [`_state`](/_state) operator. This get a value from the page's [`state`](/page-and-app-state). The page `state` is an object to temporary store page data. All inputs automatically write their values to `state` under the object key of the block `id`, and you can also set values to the page `state` by using the [`SetState`](/SetState) action.
+
+## Validation rules
+
+We would like to add a validation rule on the `purchase_in_last_month` block to warn users that the product that they have purchased may not be eligible for replacement.
+
+#### 4.5. Add a validation rule
+
+Add the following to your app
+##### `pages/new-ticket.yaml`
+```yaml
+id: new-ticket
+# ...
+blocks:
+  - id: content_card
+    # ...
+    blocks:
+      # ...
+      - id: purchase_in_last_month
+        type: ButtonSelector
+        visible: # Test if block should be visible to the user
+          _eq: # Equals operator
+            - _state: ticket_type # Get the ticket_type value from state.
+            - Complaint
+################ ------- Copy from here -------- ################
+        validate:
+          # Show a warning that shows before validate is called
+          # and does not block Validate action.
+          - status: warning
+            message: If you have had the product for over a month, we may not be able to replace it.
+            pass:
+              _eq:
+                - _state: confirm_restart
+                - Yes
+################ -------- Copy to here ---------- ################
+        properties:
+          title: Did you purchase this product within the last month?
+          label:
+            colon: false # Hide the label colon
+          options:
+            - Yes
+            - No
+```
+
+Your app should now show a warning message if `purchase_in_last_month` is not yes.
+
+### How it works
+
+The `validate` field contains an array of validation rules that can be evaluated using operators.
+
+If the pass field receives `true`, the rule passes and nothing happens. If the rule fails and the status is error, the `Validate` action will fail, like it did for required fields. If the status is warning, a warning will be shown to the user, but the `Validate` action will still pass.
+
+Your final new ticket page should look and work like this:
+
+Log a ticket
+
+> You can find the final configuration files for this section [here](https://github.com/lowdefy/lowdefy-example-tutorial/tree/main/04-interactive-pages).
+
+## Up next
+
+Our app doesn't save the form data anywhere when the submit button is clicked. In the next section we will set up a connection and a request to save the data in a local SQLite database.

package/content/tutorial/tutorial-add-blocks.md

@@ -0,0 +1,86 @@
+# 3. Adding blocks
+
+We would like to add an input form with the following fields:
+
+- A title for the ticket.
+- The type of ticket. This should be a selection from a list of types.
+- A description of the ticket.
+
+There should also be submit and reset buttons at the bottom of the page.
+
+#### 3.1. Add some input blocks
+
+Copy the following blocks and add them in the card's blocks array.
+
+###### `new-ticket.yaml`
+```yaml
+id: new-ticket
+    # ...
+blocks:
+  - id: content_card
+    # ...
+    blocks:
+      - id: page_heading
+        type: Title
+        properties:
+          content: Log a ticket # Change the title on the page.
+          level: 3 # Make the title a little smaller (an html `<h3>`).
+################ ------- Copy from here -------- ################
+      - id: ticket_title
+        type: TextInput
+        properties:
+          title: Title
+      - id: ticket_type
+        type: ButtonSelector
+        properties:
+          title: Ticket type
+          options: # Set the allowed options
+            - Suggestion
+            - Complaint
+            - Question
+      - id: ticket_description
+        type: TextArea
+        properties:
+          title: Description
+      - id: reset_button
+        type: Button
+        layout:
+          span: 12 # Set the size of the button (span 12 of 24 columns)
+        properties:
+          title: Reset
+          block: true # Make the button fill all the space available to it
+          type: default # Make the button a plain button
+          icon: AiOutlineClear
+      - id: submit_button
+        type: Button
+        layout:
+          span: 12
+        properties:
+          title: Submit
+          block: true
+          type: primary # Make the button a primary button with color
+          icon: AiOutlineSave
+################ -------- Copy to here ---------- ################
+```
+
+Your new-ticket page should look something like this:
+
+Log a ticket
+
+>  If you would like to see how your config should look at this point, you can find it [here](https://github.com/lowdefy/lowdefy-example-tutorial/tree/main/03-adding-blocks).
+
+### What happened
+
+We added 3 form input blocks to the page. For each of those blocks, we set the `title` property, and for the ticket type selector we set a list of ticket types to the `options` property.
+
+We also added reset button and submit button. We set a few more properties on the buttons to set their layout and appearance.
+
+### How it works
+
+Lowdefy apps are made from blocks. These blocks can be the page layout with header and menu, a piece of text, a chart or table, tabs or even a popup message or icon. You specify which block is rendered with the `type` field. There are 4 block categories, namely display, input, container, and list.
+
+All blocks need to have an `id` that identifies the block. Blocks of category input and list use this `id` as the object key to represent a value in page state, but more on this later.
+
+### Up next
+
+Currently our form doesn't do very much. In the next section we will use [actions](/events-and-actions) and [operators](/operators) to make it more interactive.

package/content/tutorial/tutorial-create-page.md

@@ -0,0 +1,57 @@
+# 2. Creating a page
+
+> Indentation is important
+
+#### 2.3. Navigate to the new page
+
+Your browser should reload, and you should see a link in the header menu to the booking page. If you click on that link it should take you to a page that looks like this:
+
+Log a ticket
+
+If you click on the link in the menu, you should see that your browser path (the part after `localhost:3000` or `example.com`) changes from `welcome` to `new-ticket`.
+
+### What happened
+
+- We created a new page with id `new-ticket`.
+- We used the [`_ref` operator](/_ref) to reference configuration in another file.
+- That page can now be found at the `/new-ticket` route.
+- A link to that page was created in the menu. These links are in the order of the pages.
+
+## Menus
+
+A menu is created by default from all the pages in your app, in the order that they appear in the pages array. Often more control is needed over the menu. You might want to group menu items into different groups, change the title, exclude a page or add an icon. To do this, we can define a menu in the `menus` section of the `lowdefy.yaml` file.
+
+#### 2.4 - Add the menu configuration
+
+Copy the following and add it to your `lowdefy.yaml` file just before the pages section:
+
+```yaml
+################ -------- Copy from here -------- ################
+menus:
+  - id: default
+    links:
+      - id: new-ticket
+        type: MenuLink
+        properties:
+          icon: AiOutlineAlert
+          title: New ticket
+        pageId: new-ticket
+      - id: welcome
+        type: MenuLink
+        properties:
+          icon: AiOutlineHome
+          title: Home
+        pageId: welcome
+################ -------- Copy to here ---------- ################
+pages:
+  - _ref: new-ticket.yaml
+    # ...
+```
+
+The menu links will now have icons and titles.
+
+> If you would like to see how your config should look at this point, you can find it [here](https://github.com/lowdefy/lowdefy-example-tutorial/tree/main/02-creating-a-page).
+
+### Up next
+
+In the next section we will add some more blocks to our page to create a form to capture the ticket data.

package/content/tutorial/tutorial-display-data-page.md

@@ -0,0 +1,181 @@
+# 7. Display ticket data
+
+If you have been following along, you can continue with your current config. Else, you can find the config from the previous section [here](https://github.com/lowdefy/lowdefy-example-tutorial/tree/main/06-requests-sql).
+
+In this section we will add a page with a table to view the tickets that have been saved to our database.
+
+We will make use of the concepts shown throughout the previous steps of this tutorial. If you would like to skip this, the final config can be found [here](https://github.com/lowdefy/lowdefy-example-tutorial/tree/main/07-display-data) and you can move on to [Next Steps](/tutorial-next-steps).
+
+#### 7.1. Create `view-tickets.yaml`
+
+Create a new YAML file in the project directory (the same directory as the `lowdefy.yaml` file) called `view-tickets.yaml`.
+
+In this file we will add an `AgGridBalham` table block, using [Ag-Grid](https://www.ag-grid.com/), that will be used to display the tickets that are currently in our SQLite table.
+
+We shall start with the basic page structure, as follows:
+
+```yaml
+id: view-tickets
+type: PageHeaderMenu
+
+properties:
+  title: View tickets # The title in the browser tab.
+layout:
+  justify: center # Center the contents of the page.
+blocks:
+  - id: content_card
+    type: Card
+    layout:
+      size: 1000 # Set the size of the card so it does not fill the full screen.
+      gap: 28 # Make a 28px gap between all blocks in this card.
+    blocks:
+      - id: page_heading
+        type: Title
+        properties:
+          content: View Tickets # Change the title on the page.
+          level: 3 # Make the title a little smaller (an html `<h3>`).
+```
+
+#### 7.2. Add request to `view-tickets.yaml`
+
+Next we shall add a request to fetch the tickets currently in the tickets table in the SQLite database. To do this, we shall create a `fetch_tickets` request and call it when the page is mounted.
+
+```yaml
+id: view-tickets
+type: PageHeaderMenu
+
+################ -------- Copy from here -------- ################
+requests:
+  - id: fetch_tickets
+    type: KnexRaw
+    connectionId: knex
+    properties:
+      query: SELECT * FROM "tickets"
+
+events:
+  onMount:
+    - id: fetch_tickets
+      type: Request
+      params: fetch_tickets
+################ -------- Copy to here -------- ################
+
+properties:
+  title: View tickets # The title in the browser tab.
+#...
+```
+
+### 7.3. Add an `AgGridBalham` block
+
+We will add an `AgGridBalham` table block to our page to display the tickets that have been saved in the tickets table. We want to display five columns in our table; `ticket_title`, `created_date`, `ticket_type`, `product` and `ticket_description`.
+
+The `rowData` used for our table will be the result from our `fetch_tickets` request and is accessed by making use of the [_request](/_request) operator.
+
+In order to display the `created_date` in a more compact format, we will make use of the [_nunjucks](/_nunjucks) operator.
+
+Add the following config to the `view-tickets.yaml` filename:
+
+```yaml
+#...
+
+blocks:
+  - id: page_heading
+    type: Title
+    properties:
+      content: View Tickets # Change the title on the page.
+      level: 3 # Make the title a little smaller (an html `<h3>`).
+
+  ################ -------- Copy from here -------- ################
+  - id: view_tickets_table
+    type: AgGridBalham
+    properties:
+      enableCellTextSelection: true
+      pagination: true
+      rowData:
+        _request: fetch_tickets
+      defaultColDef:
+        sortable: true
+        resizable: true
+        filter: true
+      columnDefs:
+        - headerName: Title
+          field: ticket_title
+          width: 200
+          filter: false
+        - headerName: Date Created
+          field: created_date
+          width: 140
+          cellRenderer:
+            _function:
+              __nunjucks:
+                template: |
+                  {{ created_date | date('DD MMM YYYY') }}
+                on:
+                  __args: 0.data
+        - headerName: Ticket Type
+          field: ticket_type
+          width: 150
+          filter: false
+        - headerName: Product
+          field: product
+          width: 200
+          filter: false
+        - headerName: Ticket Description
+          field: ticket_description
+          width: 250
+          filter: false
+    ################ -------- Copy to here -------- ################
+  ```
+
+#### 7.4. Update `lowdefy.yaml`
+
+Last step is to add the page to our app. In order to do this, we need to update the `lowdefy.yaml`.
+
+Change the `lowdefy.yaml` to include `view-tickets.yaml` in the list of pages and the list of menu items:
+
+```lowdefy.yaml
+#...
+menus:
+  - id: default
+    links:
+      - id: welcome
+        type: MenuLink
+        properties:
+          icon: AiOutlineHome
+          title: Home
+        pageId: welcome
+      - id: new-ticket
+        type: MenuLink
+        properties:
+          icon: AiOutlineAlert
+          title: New ticket
+        pageId: new-ticket
+      ################ -------- Copy from here -------- ################
+      - id: view-tickets
+        type: MenuLink
+        properties:
+          icon: AiOutlineDatabase
+          title: View tickets
+        pageId: view-tickets
+      ############### -------- Copy to here ---------- ################
+
+pages:
+  - _ref: new-ticket.yaml
+  ################ -------- Copy from here -------- ################
+  - _ref: view-tickets.yaml
+  ################ -------- Copy to here ---------- ################
+  - id: welcome
+    type: PageHeaderMenu
+    properties:
+      title: Welcome
+    # ...
+```
+
+### What happened
+
+We added a new page in order to view the tickets saved in our database.
+
+We defined a `KnexRaw` request, to read the ticket data from our SQLite database, and called that request when the page was mounted.
+
+The data from this request was then displayed in an `AgGridBalham` table block, which we added to the new page.
+
+Lastly, we linked this new page to our app.

package/content/tutorial/tutorial-next-steps.md

@@ -0,0 +1,53 @@
+# Next steps
+
+Congratulations! You have completed the tutorial and built a basic functioning app, which can request data from an API, as well as validate and save user input to a database.
+
+Next, consider joining the Lowdefy community, and exploring Lowdefy in more detail.
+
+### Join the community
+
+Whether Get help with any problems you have, share you ideas, ask questions, and show off the apps you have built, join and hlep us grow the Lowdefy community.
+
+- [Github Discussions](https://github.com/lowdefy/lowdefy/discussions)
+- [Lowdefy Discord](https://discord.gg/QQY9eJ7A2D)
+- [Lowdefy Twitter](https://twitter.com/lowdefy)
+
+### Understand the concepts
+
+To get a more in-depth understanding of how everything works, you can start [here](/overview).
+
+### Play with blocks
+
+The docs are interactive, so you can adjust a block's properties and see how that affects the block in real time. Go look at what you can do with a [`Button`](/Button).
+
+### Look at an example app
+
+One of the best ways to learn is by doing things for yourself. You can clone an example app that is similar to something you want to build, and start experimenting from there.
+
+###### CRUD example
+
+This example shows patterns to implement a data admin app which allows users to view, create new, edit and delete data records.
+
+- [Example demo.](https://example-crud.lowdefy.com)
+- [App source code.](https://github.com/lowdefy/lowdefy-example-crud)
+
+###### Survey example
+
+This is a simple customer survey example built with Lowdefy. With this example we demonstrate how simple it is to define a public webform and thank you page in Lowdefy.
+
+- [Example demo.](https://example-survey.lowdefy.com)
+- [App source code.](https://github.com/lowdefy/lowdefy-example-survey)
+
+###### Case management (ticketing) system example
+
+This example focuses on building a rich UI for a hypothetical case management app, in a customer relations setting.
+
+- [Example demo.](https://example-case-management.lowdefy.com)
+- [App source code.](https://github.com/lowdefy/lowdefy-example-case-management)
+
+###### Movies reporting example
+
+This example demonstrates useful patterns for building a BI report/dashboard pages in Lowdefy. It connects to a MongoDB database with the Atlas Movies sample dataset pre-loaded.
+
+- [Example demo.](https://example-reporting.lowdefy.com)
+- [App source code.](https://github.com/lowdefy/lowdefy-example-reporting)

package/content/tutorial/tutorial-requests-sql.md

@@ -0,0 +1,22 @@
+# 6. Saving data to SQL
+
+If you have been following along, you can continue with your current config. Else, you can find the config from the previous section [here](https://github.com/lowdefy/lowdefy-example-tutorial/tree/main/05-requests-api).
+
+We will now add a `SQLite` [connection and request](/connections-and-requests) to our app to save user tickets to the SQLite database file.
+
+## Configuring the SQLite Connection and Request
+
+We will be saving the data from our form in a SQLite database, using the [`Knex`](/SQLite) connection. To do this, we will first need to set up an SQLite database as described in the following steps:
+
+#### 6.1. Setting up the SQLite database
+
+We will make use of an SQLite database with a table called `tickets`, that has the following columns:
+
+- ticket_title
+- ticket_type
+- ticket_description
+- product
+- purchase_in_last_month
+- created_date
+
+The database used in this tutorial can be downloaded <a href="/tutorial/tutorial_db.sqlite" download>here</a>.