AppML Data Controllers — CRUD Operations and Data Management

In this tutorial, you will learn about AppML Data Controllers. We cover key concepts, practical examples, and best practices to help you master this topic.

AppML data controllers are the runtime layer that translates model definitions into actual database operations, handling every create, read, update, and delete request without you writing SQL.

What You'll Learn

You will understand how AppML data controllers process HTTP requests, execute database operations, and return responses based on your model configuration.

Why It Matters

Data controllers eliminate the most repetitive part of web development. You do not write SQL queries, API endpoints, or data access layers. The controller reads your model and generates all database interactions automatically.

Real-World Use

The DodaZIP configuration portal uses AppML data controllers to manage user settings, compression profiles, and storage locations. Adding a new configuration option requires only a model change, not a new API endpoint.

flowchart LR
    A[HTTP Request] --> B[AppML Router]
    B --> C{Action Type}
    C --> D[Create]
    C --> E[Read]
    C --> F[Update]
    C --> G[Delete]
    D --> H[Validate]
    E --> I[Query Builder]
    F --> J[Validate]
    G --> K[Delete Query]
    H --> L[Insert Query]
    I --> M[Result Set]
    J --> N[Update Query]
    L --> O[Database]
    M --> O
    N --> O
    K --> O
    O --> P[JSON Response]
    style O fill:#1e293b,color:#fff
    style P fill:#0f172a,color:#fff

How Controllers Handle Requests

When a browser requests an AppML page, the runtime determines the action based on the HTTP method and URL parameters. GET requests trigger read operations. POST requests with form data trigger create or update operations. DELETE requests trigger delete operations.

The controller validates all input against the model's field definitions, builds the appropriate SQL query, executes it through PDO, and returns the result.

Creating Records

To insert a new record, AppML uses a POST request with form fields matching the model definition.

<!-- Model: products.xml -->
<appml>
  <datasource type="sqlite">
    <table name="products">
      <field name="name" type="string" required="true"/>
      <field name="price" type="decimal" required="true"/>
      <field name="stock" type="integer" default="0"/>
    </table>
  </datasource>
</appml>

When the user submits the form with name=Laptop, price=999.99, stock=10, AppML generates:

INSERT INTO products (name, price, stock) VALUES ('Laptop', 999.99, 10)

Expected output: The new product appears in the list view with an auto-generated primary key.

Reading and Listing Records

The list view is generated from the model with sorting, pagination, and search built in.

<view type="list" table="products">
  <column field="name" header="Product Name"/>
  <column field="price" header="Price" format="currency"/>
  <column field="stock" header="Quantity"/>
</view>

Expected output: A table showing all products with formatted price as currency. Clicking column headers sorts the data. The search box filters rows.

AppML generates the corresponding SQL with optional search and sort parameters:

SELECT id, name, price, stock FROM products
WHERE name LIKE '%search%'
ORDER BY name ASC
LIMIT 25 OFFSET 0

Expected output: The generated SQL uses parameterized queries to prevent SQL Injection.

Updating Records

When editing an existing record, AppML recognizes the primary key in the URL and generates an UPDATE statement.

UPDATE products SET name = 'Gaming Laptop', price = 1299.99, stock = 5 WHERE id = 42

Expected output: The record with ID 42 is updated. The list view reflects the changes immediately.

Deleting Records

A delete request removes the record and returns the user to the list view with a confirmation message.

DELETE FROM products WHERE id = 42

Expected output: The record is removed. A success message displays above the list view.

Common Mistakes

1. Assuming controllers handle file uploads automatically: AppML data controllers handle scalar field types. File uploads require additional configuration with a separate upload handler.

2. Not setting proper HTTP methods in custom forms: If you use a custom form with method GET instead of POST, the controller treats it as a read operation instead of create or update.

3. Modifying database data outside AppML: Changes made directly in the database bypass AppML's validation and may cause inconsistent state. Always use the AppML interface.

4. Relying on controllers for business logic: Data controllers handle CRUD. Complex business logic like order fulfillment or invoice generation needs custom code.

5. Not configuring pagination limits: Without limits, a list view with thousands of records slows the database and overwhelms the browser.

Practice Questions

1. What HTTP method does AppML use for creating a new record?

POST. The form data is validated and inserted as a new row.

2. How does AppML know which record to update?

The record ID is identified through the primary key field in the URL or form data.

3. What SQL injection protection does AppML provide?

AppML uses PDO parameterized queries for all database operations, preventing SQL injection.

4. Can AppML controllers handle transactions?

Yes. AppML wraps related create, update, or delete operations in database transactions for data integrity.

5. How does the controller determine the action type?

Through the HTTP method and URL parameters. GET is read, POST with data is create or update, DELETE is delete.

Challenge

Create a model with an orders table and a products table. Add a custom form that submits a new order, which triggers inserts into both the orders and order_items tables. Verify the controller handles the relationship correctly.

Frequently Asked Questions

Mini Project

Create a model for an inventory system with products and stock movements. Add a custom form that creates a stock movement record and updates the product quantity in the same Transaction. Verify both operations succeed or fail together.

What's Next

Continue to Data Services to learn how AppML connects to different data source types including databases, XML files, and JSON APIs.