Simple CRUD Screen with Form Configuration

Description

This screen demonstrates a complete CRUD (Create, Read, Update, Delete) interface with sophisticated form field configuration. The Jobs screen showcases Stack9's simpleCrud screen type, which automatically generates list and form views from a single configuration. It includes field-level control over rendering, validation, layout, and behavior for both create and update operations. The screen also integrates workflow visualization and custom components for specialized rendering needs.

Use Case

Used in an arborist job management system to provide a unified interface for managing jobs. Users can view jobs in a list with workflow status indicators, create new jobs with required fields, and update existing jobs with read-only system fields. The screen handles navigation to detailed job views and displays complex address information using custom components.

Key Features

• Automatic CRUD interface generation from single configuration
• Separate field configurations for create and update forms
• Workflow status visualization in list view
• Custom component integration for address display
• Column-based responsive layout with configurable sizes
• Field type specification (Input, Dropdown, DatePicker, HTMLField)
• Read-only field support for system-generated values
• Navigation routing to detailed views

JSON Definition

{
  "head": {
    "title": "Jobs",
    "key": "jobs",
    "route": "job",
    "app": "jobs",
    "description": "Jobs"
  },
  "screenType": "simpleCrud",
  "entityKey": "job",
  "listQuery": "getjoblist",
  "detailQuery": "getjobdetails",
  "useRouteForUpdate": "job-detail/:id",
  "formFieldset": {
    "create": [
      {
        "field": "client_site_id",
        "label": "Client site",
        "renderAs": "Dropdown"
      },
      {
        "field": "type",
        "label": "Type",
        "colSize": 12
      },
      {
        "field": "client_order_no",
        "label": "Client Order No.",
        "renderAs": "Input",
        "colSize": 12
      },
      {
        "field": "request_dt",
        "label": "Request date",
        "renderAs": "DatePicker",
        "colSize": 12
      },
      {
        "field": "due_dt",
        "label": "Due date",
        "renderAs": "DatePicker",
        "isRequired": true,
        "colSize": 12
      },
      {
        "field": "priority"
      },
      {
        "field": "customer_instructions",
        "label": "Customer instructions",
        "renderAs": "HTMLField"
      },
      {
        "field": "site_access_note",
        "label": "Site access note",
        "renderAs": "Input"
      }
    ],
    "updateUsesCreateFields": true,
    "update": [
      {
        "field": "number",
        "label": "Number (Autogenerated)",
        "isReadOnly": true,
        "renderAs": "Text",
        "colSize": 4
      },
      {
        "field": "tw_estimate_hrs_total",
        "label": "TW estimate hrs total",
        "isReadOnly": true,
        "renderAs": "Text",
        "colSize": 6
      },
      {
        "field": "total_quote_price",
        "label": "Total quote price",
        "renderAs": "Text",
        "colSize": 8
      }
    ]
  },
  "columnsConfiguration": [
    {
      "field": "_workflow_current_step",
      "label": "Workflow",
      "value": "{{_workflow_current_step}}",
      "renderAs": "WorkflowResult"
    },
    {
      "field": "number",
      "label": "Number",
      "value": "{{number}}",
      "renderAs": "Text",
      "options": {
        "linkProp": "job-detail/{{id}}"
      }
    },
    {
      "field": "type",
      "label": "Type",
      "value": "{{type}}",
      "renderAs": "Text"
    },
    {
      "field": "priority",
      "label": "Priority",
      "value": "{{priority}}",
      "renderAs": "Text"
    },
    {
      "field": "request_dt",
      "label": "Request Date",
      "value": "{{request_dt}}",
      "renderAs": "Date"
    },
    {
      "field": "due_dt",
      "label": "Due Date",
      "value": "{{due_dt}}",
      "renderAs": "Date"
    },
    {
      "field": "client_site.client.name",
      "label": "Client",
      "value": "{{client_site.client.name}}",
      "renderAs": "Text"
    },
    {
      "field": "client_site.address_line_1",
      "label": "Client site address",
      "value": "",
      "renderAs": "CustomComponent",
      "options": {
        "customComponentName": "AddressLookupField",
        "props": {
          "address_info": {
            "address_line_1": "{{client_site.address_line_1}}",
            "address_line_2": "{{client_site.address_line_1}}",
            "address_locality_name": "{{client_site.address_locality_name}}",
            "address_state_territory": "{{client_site.address_state_territory}}",
            "address_postcode": "{{client_site.address_postcode}}"
          },
          "renderAsText": true
        }
      }
    }
  ]
}

Query Requirements for SimpleCrud

The simpleCrud screen type requires specific query configurations to enable the Stack9 framework's automatic pagination and record loading mechanisms. Both listQuery and detailQuery must expose certain parameters for the framework to function correctly.

List Query Requirements

The listQuery must expose pagination parameters that the Stack9 framework will automatically populate:

Required Parameters

• page: Current page number for pagination (zero-indexed)
• limit: Number of records per page

These parameters MUST be exposed in the query's queryParams section using the template syntax:

{
  "queryTemplate": {
    "queryParams": {
      "page": "{{page}}",
      "limit": "{{limit}}"
    }
  }
}

Recommended Features

• Filters: Include a filters array to enable advanced filtering capabilities (see Query Library Schema Reference - Filter Schema)
• Search Fields: Define querySearchFields for text-based searching across multiple fields

Example List Query

{
  "key": "getproductlist",
  "name": "getProductList",
  "connector": "stack9_api",
  "queryTemplate": {
    "method": "post",
    "path": "/product/search",
    "bodyParams": {
      "$select": ["id", "name", "price", "status"],
      "$where": { "_is_deleted": false },
      "$sort": { "id": "desc" }
    },
    "queryParams": {
      "page": "{{page}}",      // Required for pagination
      "limit": "{{limit}}"      // Required for pagination
    }
  },
  "querySearchFields": ["name", "description", "sku"],
  "filters": [
    {
      "name": "Status",
      "key": "status",
      "typeQueryFilter": "array",
      "field": "status",
      "typeFilter": "MultiDropDown",
      "sequence": 1,
      "dataSource": {
        "type": "static",
        "options": [
          { "label": "Active", "value": "active" },
          { "label": "Inactive", "value": "inactive" }
        ]
      }
    }
  ],
  "userParams": {
    "page": "0",
    "limit": "10"
  }
}

Detail Query Requirements

The detailQuery must expose an id parameter that the Stack9 framework will automatically populate when loading a specific record:

Required Parameter

• id: The unique identifier of the record to load

This parameter is typically used in the bodyParams within a $where clause:

{
  "queryTemplate": {
    "bodyParams": "{\"$where\": {\"_is_deleted\": false, \"id\": {{id}}}}"
  }
}

Example Detail Query

{
  "key": "getproductbyid",
  "name": "getProductById",
  "connector": "stack9_api",
  "queryTemplate": {
    "method": "post",
    "path": "/product/find",
    "bodyParams": {
      "$select": ["*"],
      "$where": {
        "_is_deleted": false,
        "id": "{{id}}"          // Required for record loading
      },
      "$withRelated": ["category", "supplier"]
    }
  },
  "userParams": {
    "id": "1"  // Default value for testing
  }
}

Common Pitfalls and Solutions

Issue	Solution
Pagination not working	Ensure page and limit are in queryParams with {{page}} and {{limit}} template syntax
Detail view shows wrong record	Verify id is properly exposed in bodyParams using {{id}} template
Filters not appearing	Add filters array to your list query definition
Search not working	Define querySearchFields array with searchable field names
Missing related data	Add $withRelated array in detail query for related entities

Notes

• The simpleCrud screen type provides automatic CRUD operations
• updateUsesCreateFields: true inherits create fields for updates
• The colSize property controls responsive grid layout (1-12 scale)
• useRouteForUpdate enables custom routing for edit operations
• WorkflowResult renderer provides visual workflow status
• Custom components can receive complex props with nested data
• HTMLField type supports rich text editing
• Nested property access enables display of related entity data