Guide Creating Your First App - osama1998H/Moca GitHub Wiki

Creating Your First App

Scaffold an app with moca app new, define DocTypes, write hooks, and install.

Scaffold a New App

moca app new todo

This creates:

apps/todo/
├── go.mod
├── manifest.yaml
├── hooks.go
└── modules/
    └── todo/
        └── doctypes/

The app is automatically added to go.work. The scaffolded hooks.go file also registers the app's Initialize() function so moca serve and moca build server can load its hooks and controllers automatically.

Define a DocType

Create apps/todo/modules/todo/doctypes/todo_item/todo_item.json:

{
  "name": "Todo Item",
  "module": "Todo",
  "label": "Todo Item",
  "naming_rule": {
    "rule": "autoincrement"
  },
  "title_field": "title",
  "fields": [
    { "name": "title", "field_type": "Data", "label": "Title", "required": true, "in_list_view": true, "searchable": true },
    { "name": "status", "field_type": "Select", "label": "Status", "options": "Open\nCompleted", "default": "Open", "in_list_view": true, "in_filter": true },
    { "name": "due_date", "field_type": "Date", "label": "Due Date" },
    { "name": "priority", "field_type": "Select", "label": "Priority", "options": "Low\nMedium\nHigh", "default": "Medium" }
  ],
  "api_config": {
    "enabled": true,
    "allow_list": true,
    "allow_get": true,
    "allow_create": true,
    "allow_update": true,
    "allow_delete": true,
    "allow_count": true
  },
  "permissions": [
    { "role": "System Manager", "doctype_perm": 63 }
  ]
}

When you scaffold with moca app new todo --doctype "Todo Item", the generated DocType now uses title_field: "title" and includes api_config by default so you do not need to patch the generated JSON before enabling CRUD access.

Write Hooks

Edit apps/todo/hooks.go:

package todo

import (
    "time"

    "github.com/osama1998H/moca/pkg/apps"
    "github.com/osama1998H/moca/pkg/document"
    "github.com/osama1998H/moca/pkg/hooks"
)

func init() {
    apps.MustRegisterInit("todo", Initialize)
}

func Initialize(cr *document.ControllerRegistry, hr *hooks.HookRegistry) {
    // Register controller overrides if needed:
    // cr.RegisterOverride("Todo Item", NewTodoItemController)

    hr.Register("Todo Item", document.EventValidate, hooks.PrioritizedHandler{
        AppName: "todo",
        Handler: func(ctx *document.DocContext, doc document.Document) error {
            if doc.Get("status") == "Completed" && doc.Get("due_date") == nil {
                if err := doc.Set("due_date", time.Now().Format("2006-01-02")); err != nil {
                    return err
                }
            }
            return nil
        },
        Priority: 10,
    })
}

Install the App

moca app install todo --site mysite
moca db migrate --site mysite
moca build app todo

moca app install now seeds the app's DocType and DocPerm records as part of installation, so newly installed DocTypes are visible to the resource API and Desk sidebar without extra bootstrap steps.

Use moca build server when you need a compiled moca-server binary with installed apps blank-imported into the build.

Test Your App

Run the app's tests:

moca test run --app todo --site mysite

This runs all tests in the app's test directory using Moca's test runner with fixture support and coverage reporting.

Add Desk Extensions (Optional)

moca app new todo --desk   # If you want frontend extensions

See Creating Desk Extensions for adding custom UI components.