Runtime API

`ctx` — The WebContext Object

In SØAD, every transaction method receives a single parameter named ctx, which stands for WebContext. This object encapsulates all information and utility methods relevant to the current request lifecycle.

The ctx object gives developers access to:

Session management
Input parameters and headers
Output data for views (via ctx.output)
Redirection, file upload handling, and more

The ctx object is automatically passed into each method of your transaction class (e.g., view(self, ctx), submit(self, ctx)) and serves as the primary interface for handling request-response logic.

Available Methods and Properties

Feature	Description
`ctx.getRequest()`	Returns the underlying `HttpServletRequest` object. Use this to get request parameters.
`ctx.getResponse()`	Returns the `HttpServletResponse` object.
`ctx.output`	A map used to pass values into the view layer (used by Handlebars templates).
`ctx.go_to`	The response object that will be rendered (e.g., `render.as_view(...)`).
`ctx.ctxPath`	The context path of the deployed application (useful for building URLs).
`ctx.getAppName()`	Returns the name of the application.
`ctx.getGroup()`	Returns the group name of the current transaction.
`ctx.getCode()`	Returns the name of the current transaction code.
`ctx.getMethod()`	Returns the HTTP method used for the request (GET, POST, etc.).

Example Usage

def view(self, ctx):
    request = ctx.getRequest()
    user_id = request.getParameter("id")
    ctx.output["user"] = User.findById(user_id)
    ctx.go_to = render.as_view(ctx, "profile")

def login(self, ctx):
    request = ctx.getRequest()
    username = request.getParameter("username")
    password = request.getParameter("password")

    if Auth.validate(username, password):
        session = ctx.getRequest().getSession(True)
        session.setAttribute("user", username)
        ctx.go_to = "%s/t/dashboard/home" % ctx.ctxPath
    else:
        ctx.output["error"] = "Invalid credentials"
        ctx.go_to = render.as_view(ctx, "login")

Integration with View

The ctx.output map is what feeds data into the Handlebars views.

ctx.output["user_name"] = "Borhan"
ctx.go_to = render.as_view(ctx, "welcome")

In your HTML:

<h1>Welcome, {{user_name}}</h1>

How to Access ctx in a Servlet Filter

If you need to access the ctx object from within a component like a Servlet Filter, you can retrieve it directly from the request attribute.

Use the following method to get the ctx object:

ctx = request.getAttribute("soadContext")

`render` — Response Output Utilities

The render module defines how a transaction responds to a request. These utilities help return HTML, JSON, string, files, or binary content from the server. Each render method should be assigned to ctx.go_to.

1. `render.as_view()`

Renders a Handlebars HTML template as the response. This is the most common way to return a page to the browser in SØAD.

This function uses the view name to locate the appropriate .html file within the transaction's corresponding _group folder. If not specified, it defaults to the current transaction's group and code.

Function Signature:

render.as_view(ctx, view, group=None, code=None, loc=None, file=None, combine_map=None)

Parameters:

ctx: The transaction context object.
view (str): The name of the view (HTML template) to render.
group (str, optional): The group/module name. Defaults to the current transaction’s group.
code (str, optional): The transaction code. Defaults to the current transaction.
loc (str, optional): Alternative path location override.
file (str, optional): Direct path to an HTML file.
combine_map (Map, optional): Extra data to merge into the Handlebars context.

Basic usage:

ctx.output["title"] = "Welcome"
ctx.go_to = render.as_view(ctx, "home")

This will render _home/home.html and pass title as a Handlebars variable.

Render from another transaction group:

ctx.go_to = render.as_view(ctx, "register", group="auth", code="signup")

This will look for _auth/signup/register.html.

2. `render.as_json()`

Returns a JSON-formatted response to the client. Useful for AJAX or API-style interactions.

Function Signature:

render.as_json(ctx, obj=None)

Parameters:

obj (optional): a dictionary or serializable object to return as JSON. If not provided, ctx.output is used.

Basic usage:

ctx.output["message"] = "Operation successful"
ctx.go_to = render.as_json(ctx)

data = {"status": "success", "user": {"id": 1, "name": "Borhan"}}
ctx.go_to = render.as_json(ctx, data)

Example with ActiveJDBC model:

users = Tb_user.findAll().toMaps()
ctx.go_to = render.as_json(ctx, users)

3. `render.as_html()`

Returns a raw HTML file directly from the filesystem, bypassing the Handlebars rendering engine. Ideal for serving pre-rendered static content.

Function Signature:

render.as_html(ctx, code=None, loc=None)

Parameters:

code (str, optional): The code of the HTML file to render. If not provided, it defaults to the current transaction code.
loc (str, optional): Alternative path location override.

Basic usage:

ctx.go_to = render.as_html(ctx, "dashboard")

Render from a custom folder:

ctx.go_to = render.as_html(ctx, code="faq", loc="/web/static/pages")

This will look for /web/static/pages/<app_name>/<group>/faq.html

4. `render.as_string()`

Returns raw string content (HTML or plain text) directly to the browser. Bypasses any view engine or file lookup.

Use case: Error messages, short inline content, quick HTML feedback.

Function Signature:

render.as_string(ctx, text)

Parameters:

text: The string content to return. This can be HTML or plain text.

Example:

ctx.go_to = render.as_string(ctx, "Access Denied")

5. `render.as_file()`

Sends a file to the client for download or inline viewing.

Function Signature:

render.as_file(ctx, file, content_type, filename=None, attachment=True)

Parameters:

file: a Java File object or file path (string)
content_type: MIME type (e.g., application/pdf, image/png)
filename (optional): custom filename for the download
attachment (bool): if True, forces download; if False, displays inline. Default is True.

Example:

ctx.go_to = render.as_file(ctx, reportFile, "application/pdf", filename="report.pdf", attachment=True)

Display an image:

ctx.go_to = render.as_file(ctx, "/path/to/image.png", "image/png")

6. `render.as_blob()`

Returns raw binary content such as images, audio, or PDF streams.

Use case: Useful when file content is stored in memory (e.g., in a database blob).

Function Signature:

render.as_blob(ctx, data, content_type, filename=None, attachment=True)

Parameters:

data: binary data (bytes) to return
content_type: MIME type (e.g., image/png, application/pdf)
filename (optional): name of the file to suggest for download
attachment (bool): if True, forces download; if False, displays inline. Default is True.

Example:

attachment = Attachment.findById(123)
file_content = attachment.get("content")  # Assuming content is stored as blob
ctx.go_to = render.as_blob(ctx, file_content, "application/pdf", "preview.pdf", attachment=False)

7. `render.as_pdf()`

Renders a Handlebars-based HTML template into a PDF document. Can be served inline or as a download. The PDF generation is handled by the Flying Saucer library, which converts well-formed XML (or XHTML) to PDF format.

Function Signature:

render.as_pdf(ctx, view, group=None, code=None, filename=None, combine_map=None, attachment=False)

Parameters:

view: the Handlebars view name (required)
group: the transaction group name (optional, defaults to current group)
code: the transaction code (optional, defaults to current code)
filename: name of the PDF file returned to client
attachment: if True, triggers download

Example:

report.py

ctx.output["attendance"] = Attendance.findAll()
ctx.output["date"] = "2023-10-01"
ctx.go_to = render.as_pdf(ctx, "report")

report.html

<html>
<head>
    <title>PDF Report</title>
</head>
<body>
    <h1>Attendance Report</h1>
    <p>Date: {{date}}</p>
    <table>
        <tr>
            <th>Name</th>
            <th>Status</th>
        </tr>
        {{#each attendance}}
        <tr>
            <td>{{name}}</td>
            <td>{{status}}</td>
        </tr>
        {{/each}}
    </table>
    <p>End of Report</p>
</body>
</html>

Runtime API

ctx — The WebContext Object

Available Methods and Properties

Example Usage

Integration with View

How to Access ctx in a Servlet Filter

render — Response Output Utilities

1. render.as_view()

2. render.as_json()

3. render.as_html()

4. render.as_string()

5. render.as_file()

6. render.as_blob()

7. render.as_pdf()

`ctx` — The WebContext Object

`render` — Response Output Utilities

1. `render.as_view()`

2. `render.as_json()`

3. `render.as_html()`

4. `render.as_string()`

5. `render.as_file()`

6. `render.as_blob()`

7. `render.as_pdf()`