/intraweb-framework

name: Intraweb Framework
description: Guides and standards for using the Intraweb stateful web framework in Delphi projects.

Intraweb Framework - Spec-Kit

Intraweb is a VCL-for-the-Web framework that allows you to create stateful business web applications in a semantic way similar to creating Desktop applications. When dealing with Intraweb in Copilot or your project, consider the following best practices to ensure maintainability and scalability.

1. Sessions (UserSession) and Global Variables

**Golden Rule:** Do not use classic unit `var` global variables or Singleton instances for user data, since Intraweb applications run in a Multithread environment with concurrent sessions (each user has their own).

• To maintain user-specific data, strictly use the `UserSessionUnit.pas` unit (`ServerController.UserSession` Instance).

//❌ BAD: Incorrect Usage (Global scope variable serves all sessions, Multithreading problem)
var
  LCustomerId: Integer;

//✅ GOOD: Correct Usage (Safe properties of the current context)
UserSession.CustomerId := 10;

2. ServerController and Configuration

The global system parameters, database connection pool and initializations that do not depend on the user must be resolved in the `ServerController` (`IWServerController.pas`) object. Avoid injecting heavy dependencies and direct database scopes in `TIWAppForm`.

3. Non-Blocking User Interfaces (Asynchronous Callbacks)

In the web context, you should not use blocking code to "wait" for the user, such as `ShowMessage`, `InputBox`, or classic VCL ModalResults calls that rely on code locking on the same line.

• Use the `OnAsyncClick` property for DOM updates without full-screen postback.
• In Intraweb version 15 or newer, explore the capabilities of `WebApplication.ShowMessage` combined with Ajax calls and safe web interface interrupts.

//❌ BAD: Blocking the thread on the Intraweb
procedure TIWForm1.iwBtnSaveClick(Sender: TObject);
begin
  if Application.MessageBox('Deseja salvar?', 'Confirme', MB_YESNO) = IDYES then
    //Rescue code
end;

//✅ GOOD: Using Ajax Async from Intraweb
procedure TIWForm1.iwBtnSaveAsyncClick(Sender: TObject; EventParams: TStringList);
begin
  WebApplication.ShowMessage('Registro Salvo via Callback Assíncrono!', smAlert);
end;

4. Separation of Rules and UI

It is easy to build monstrous projects on the Intraweb by grouping the entire system rule behind the click (ex: num `iwBtnProcessarAsyncClick`). Follow the SRP (Single Responsibility Principle) principles:

• The form maps to the Controller request and re-renders components. The rules remain in the *Application/Services* layer.
• An Application/Service or Repository layer that is used in the Intraweb **cannot couple or know** the `IWApplication` unit (do not use `WebApplication.ShowMessage` among persistence Services).

5. Naming of Visual Components (Intraweb Prefixes)

Use `iw` concatenated with the native typologies:

• `TIWButton` -> `iwBtnSave`
• `TIWEdit` -> `iwEdtName`
• `TIWLabel` -> `iwLblTitle`
• `TIWComboBox` -> `iwCmbStatus`
• `TIWGrid` -> `iwGrdItems`
• `TIWRegion` -> `iwRegContainer`

6. Dynamic HTML and Custom CSS

Despite being VCL-like, the massive stylizations in the components create large DOMS in the interface. Prefer to define external CSS files using `ExtraHeader` injection in the form and apply the `Css` property to the tags of the T visual components `TIW*` instead of manually painting the color of buttons and fonts via the Object Inspector.