# SØAD Framework — Coding Context SØAD is a convention-over-configuration MVC web framework on the JVM. Controllers (called **Transactions**) are written in **Jython** (Python 2.7 syntax on Java), views in **Handlebars.java**, models via **ActiveJDBC** (auto-generated from DB tables). Use this file as context when writing transaction code, view templates, or SQL. **Naming:** Canonical spelling is **SØAD**. "SOAD" and "soad" are accepted shorthand — treat them as identical on input. Use **SØAD** in generated prose, docs, and comments. Keep lowercase `soad` as-is in code identifiers, module names, and file paths — do NOT "correct" those. --- ## HARD RULES (DO NOT VIOLATE) These break code silently if ignored. They always apply. - **Language is Jython = Python 2.7 syntax**, running on the JVM (not CPython). - **DO NOT use f-strings.** `f"Hi {name}"` does NOT work. Use `%` (`"Hi %s" % name`) or `.format()` (`"Hi {}".format(name)`) — both work. - **`except Exception as e:` IS allowed** (verified in this Jython build) — use it. - **`print()` works**, but in containers its output may not reach the IDE log. Prefer `Log.info(ctx, "...")` for anything that must be visible. - **DO NOT use pip or any CPython package** (`requests`, `numpy`, `pandas`, etc.) — they do not exist here. - **Add libraries as Java JARs only.** Import Java classes directly, e.g. `from java.io import File`, `from java.time import LocalDateTime`. Bundled: Guava, Apache Commons (lang3, io, text), Apache POI (Office docs), openpdf (PDF). Full version list in the Utilities section. - **DO NOT write any routing/config file.** Routing is convention-based from folder/file/method names. - **DO NOT hand-write Model classes.** They are auto-generated from DB tables; just `from models import Capitalizedname`. The class name is the **table name with the first letter capitalized and the rest exact — NO English inflection.** SØAD disables ActiveJDBC's default pluralization, so `persons` → `Persons` (not `Person`), `categories` → `Categories` (not `Category`). Match the table spelling exactly. - **`saveIt()` vs `insert()`:** auto-generated id → `saveIt()` for both insert and update. **Manually set id (e.g. UUID) → `insert()` for a NEW record, `saveIt()` for updates.** Calling `saveIt()` on a manually-id'd new record silently runs an UPDATE and inserts nothing. - **DO NOT set `created_at` or `updated_at`.** If a table has these (Timestamp) columns, ActiveJDBC auto-manages them — setting them in code throws an error. To control timestamps yourself, name the columns `created_date`/`updated_date` instead (not auto-managed) and set those. - **Every action method takes `ctx`:** `def view(self, ctx):`. All public methods on a transaction class are reachable as URL actions. - **Default class base is `object`:** `class Foo(object):`. Layout/base inheritance is optional. - **Auto-render: if a method never assigns `ctx.go_to`, the framework renders the default view `_{code}/{code}.html` automatically.** Do NOT call `render.as_view` just to render the default view — leave `ctx.go_to` unset. Assign `ctx.go_to` ONLY for something else: a *different* view (`render.as_view(ctx, "other")`), JSON, a file, or a redirect string. Prefer the default view first; add extra `.html` views only when a transaction needs more than one screen. --- ## Routing URL pattern: **`/t/{group}/{code}/{action}`** - `/t` fixed prefix · `{group}` folder/module · `{code}` = `.py` filename AND class name (capitalized) · `{action}` = method, **defaults to `view`** if omitted. - `/t/web/home` → `web/home.py`, class `Home`, method `view()` - `/t/app/user/edit?id=5` → `User.edit()`, read `id` from request On disk (transaction `example/contact`): ``` example/ contact.py # class Contact _contact/ # views: underscore + code name contact.html # default view (matches code name) edit.html # optional extra views ``` Class name = code with first letter capitalized (`address_book` → `Address_book`). ### Imports - **Built-in SØAD utilities and models — no prefix:** `from utils import render`, `from models import Members`. - **Another custom transaction / utility / layout — `default..` prefix** (imports its Capitalized class from the transaction at `/.py`): - `from default.org.members import Members` — the `org/members` transaction - `from default.utils.member_number_generator import MemberNumberGenerator` — a `utils/member_number_generator` transaction used as a helper - `from default.org.layout import Layout` — a shared layout is just a normal transaction other transactions inherit Pattern: `default..` → the Capitalized class in `/.py`. You don't manage these paths yourself — `create_transaction(group, code)` lays them out; this is only how one transaction references another. --- ## Transaction skeleton ```python from models import Contact class Contact(object): def view(self, ctx): # GET, default action ctx.output["contacts"] = Contact.findAll().orderBy("name ASC") # No ctx.go_to assignment => auto-renders _contact/contact.html def save(self, ctx): """POST""" # docstring marks POST-only r = ctx.getRequest() id = r.getParameter("id") c = Contact.findById(id) if id else Contact() c.set("name", r.getParameter("name")) c.saveIt() ctx.go_to = "/t/example/contact" # PRG: string => redirect ``` `render` is only imported when a method needs a non-default response (a different view, JSON, file, PDF). The skeleton above needs no `render` import. --- ## ctx (WebContext) - `ctx.getRequest()` / `ctx.getResponse()` — servlet request/response - `ctx.output` — map of data passed to the view - `ctx.go_to` — the response. **Unset → auto-renders the default view `_{code}/{code}.html`**; **string → redirect** (`sendRedirect`); **`render.*` result → that rendered output** - `ctx.ctxPath` — app context path; prefix links/redirects with it across environments - `ctx.getGroup()`, `ctx.getCode()`, `ctx.getMethod()`, `ctx.getAppName()` - Read input: `ctx.getRequest().getParameter("name")` - Session: `ctx.getRequest().getSession(True)` --- ## Models (ActiveJDBC — auto-generated) Never define a model class — import it by its table name with the **first letter capitalized and the rest kept exactly as-is**. Table `contact` → `Contact`; `hr_employee` → `Hr_employee`; `persons` → `Persons`; `categories` → `Categories`. **DO NOT apply English inflection.** Stock ActiveJDBC maps `persons` → `Person` and `boxes` → `Box` by default — **SØAD disables this and uses strict exact naming.** So `persons` is `Persons` (NOT `Person`), `categories` is `Categories` (NOT `Category`), `people` is `People`. Always the literal table name with a capital first letter, including any plural `s`. ```python from models import Contact c = Contact() # create c.set("name", "John"); c.set("email", "j@x.com") c.saveIt() Contact.findAll() # read Contact.findById(1) Contact.where("name LIKE ?", "%John%") Contact.findAll().orderBy("name ASC").limit(10) Contact.findAll().orderBy("grade DESC, name ASC") c = Contact.findById(1) # update c.set("name", "Jane"); c.saveIt() c.delete() # delete Contact.findAll().toMaps() # list of dict — handy for render.as_json # Single record by condition: use Model.first(...), NOT .where(...).first() c = Contact.first("name = ?", "John") # correct # c = Contact.where("name = ?", "John").first() # WRONG — LazyList has no .first() ``` The framework wraps each request in a DB transaction: **auto-commit on success, auto-rollback on any exception.** Do NOT manage transactions manually. To force a rollback, raise an exception. **Auto-managed timestamps.** ActiveJDBC treats `created_at` and `updated_at` (Timestamp columns) as magic: it sets `created_at` once on insert and `updated_at` on every update, automatically. - **DO NOT set `created_at`/`updated_at` in code** — `obj.set("created_at", ...)` throws an error in SØAD; ActiveJDBC owns them. - To control timestamps yourself, name the columns `created_date`/`updated_date` (or anything non-magic) — these are NOT auto-managed, so set them normally (`obj.set("created_date", LocalDateTime.now())`). **This is the recommended default.** **saveIt() vs insert() — IDs.** ActiveJDBC picks INSERT vs UPDATE by whether the record looks new: - **Auto-generated id** (`AUTO_INCREMENT`) → `saveIt()` for both create and update. - **Manually set id** (e.g. UUID) → `insert()` for a NEW record, `saveIt()` for updates. Calling `saveIt()` on a new manually-id'd record runs an UPDATE that matches nothing — row silently never inserted, no error. ```python from java.util import UUID m = Members() m.set("id", str(UUID.randomUUID())) m.set("name", "John") m.insert() # correct: INSERT (manual id, new record) # m.saveIt() # WRONG: UPDATE, inserts nothing # Add/edit in one method with manual ids: if record_id: record = Members.findById(record_id); new_record = False else: record = Members(); record.set("id", str(UUID.randomUUID())); new_record = True record.set("name", "value") record.insert() if new_record else record.saveIt() ``` --- ## SQL & Schema changes **You cannot run DDL or write `.sql` files** — you have no SQL tool, and `write_file` only accepts a transaction's `.py` and `.html` views. So when a task needs a new table or column: - **Show the SQL as a fenced `sql` code block in your reply.** Do NOT try to stage it as a file — that call is rejected. - Tell the developer to **run it in the IDE SQL editor**, then **Introspect** to regenerate the models. In-IDE schema changes regenerate models automatically; only external changes need a manual Introspect. - One logical change per block (a `CREATE` or an `ALTER`) so they can be run in order. - **Seed/sample data:** provide it the same way (a code block) only when the user explicitly asks — never by default. Rules for `CREATE TABLE` so the auto-generated model aligns: - **Every table MUST have a PK column named `id`** — typically `INT PRIMARY KEY AUTO_INCREMENT`. - **Model class name = table name with first letter capitalized, rest exactly as-is. NO inflection** — `persons` → `Persons` (not `Person`), `categories` → `Categories`. SØAD disables ActiveJDBC's default pluralization. - **A BLOB column auto-expands into THREE columns.** `resume` (BLOB) → `resume`, `resume_fn`, `resume_ft`. Do NOT manually add the `_fn`/`_ft` columns. - Prefix table names by group/module (e.g. `hr_`) for maintainability. - After schema changes **outside** the IDE, run **Introspect** to regenerate models. In-IDE changes regenerate automatically. Supported types: `VARCHAR(n)`, `TEXT`, `MEDIUMTEXT`, `INT`, `BIGINT`, `BIT`, `DECIMAL(n,d)`, `DATE`, `DATETIME`, `TIME`, `BLOB`, `MEDIUMBLOB`. **MySQL → Java type mapping** (use correct Java type in `.set()` and reads): | MySQL | Java type | |---|---| | VARCHAR / TEXT / MEDIUMTEXT | String | | INT | Integer | | BIGINT | java.math.BigInteger | | BIT | Boolean | | DECIMAL | java.math.BigDecimal | | DATE | java.sql.Date | | DATETIME | **java.time.LocalDateTime** | | TIME | java.sql.Time | | BLOB / MEDIUMBLOB | byte[] | ```python from java.time import LocalDateTime obj.set("created_date", LocalDateTime.now()) ``` Example `CREATE TABLE` (show this in your reply for the developer to run): ```sql CREATE TABLE contact ( id INT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(100) NOT NULL, contact_no VARCHAR(20), email VARCHAR(100), created_date DATETIME, updated_date DATETIME ); ``` → auto-generates model class `Contact`. A later change is a separate `ALTER` block: ```sql ALTER TABLE contact ADD COLUMN company VARCHAR(120); ``` --- ## Render methods (`from utils import render`) **First: you often don't need `render` at all.** If a method leaves `ctx.go_to` unset, the framework auto-renders the default view `_{code}/{code}.html`. Use the methods below only to return something *other* than the default view, assigning the result to `ctx.go_to`. ```python render.as_view(ctx, view, group=None, code=None) # Handlebars HTML (most common) render.as_json(ctx, obj=None) # JSON; defaults to ctx.output render.as_html(ctx, code=None) # raw HTML file, no Handlebars render.as_string(ctx, text) # raw string/HTML render.as_file(ctx, file, content_type, filename=None, attachment=True) render.as_blob(ctx, data, content_type, filename, attachment=False) # filename required render.as_pdf(ctx, view, group=None, code=None, filename=None, attachment=False) ``` - `as_view(ctx, "home")` renders `_home/home.html` in the current group. Pass `group=`/`code=` to render a view from another transaction. - **`render.as_view(...)` returns a callable.** Assign to `ctx.go_to` for normal rendering. To get the HTML **as a string** (email body, PDF input), call it with a trailing `()`: ```python html = render.as_view(ctx, "invoice")() # note the extra () ``` - `as_json` with a model list: `render.as_json(ctx, Contact.findAll().toMaps())`. - `as_file` — `attachment=False` displays inline (e.g. show an image in browser). - `as_pdf` — template must be well-formed XHTML (openpdf-backed HTML→PDF). --- ## Views (Handlebars.java) Views are HTML files in the `_{code}/` folder, populated from `ctx.output`. **The default view `_{code}/{code}.html` renders automatically when a method leaves `ctx.go_to` unset** — a simple `view()` needs no `render` call. Call `render.as_view(ctx, "other")` only to render a *different* view. Generated pages are **full standalone HTML** (`` … ``) unless using a layout. Use `{{ctxPath}}` for links; inside `{{#each}}` use `{{../ctxPath}}`. ```html {{page_title}}
{{#if contacts}}
    {{#each contacts}}
  • {{name}} — {{email}} Edit
    • {{/each}}
{{else}}
No items found
{{/if}}
``` ### Built-in & logical helpers `if`, `else`, `unless`, `each`, `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `and`, `or`, `not`, `in`. Block form and inline-condition form both work: ```html {{#eq status "pending"}}Pending{{else}}Active{{/eq}} {{#if (eq role "admin")}}

Admin

{{/if}} {{#if (in user_role_id allowed_roles)}}Granted{{else}}Denied{{/if}} ``` Use `{{#eq}}` for equality — **`{{#if_eq}}` does NOT exist in SØAD**, do not use it. Inside `{{#each}}`, current item is `{{this}}`. **No `range` helper.** Build the list in the transaction and loop over it: ```python ctx.output["page_numbers"] = list(range(1, total_pages + 1)) ``` ```html {{#each page_numbers}}{{this}}{{/each}} ``` ### SØAD custom helpers **`ref_lookup`** — fetch a column value from a table by key: ```html {{ref_lookup user.id table="user" label="login_id" value="id"}} ``` `label` defaults to `name`, `value` defaults to `id`. Multiple labels: `label="name|email"`. Inside a loop: `{{ref_lookup this.id table="user_details" label="full_name" value="user_id"}}`. **`select` / `option`** — dropdown from a table: ```html {{select table="countries" selected=selected_country label="name" value="code"}} ``` Params: `table`, `refs`, `filter="active=1"`, `id`, `name`, `class`, `label`, `value`, `selected`, `required`, `readonly`, `sel_text` (placeholder, default "Please Select"). Use `{{option ...}}` for just the `