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).

// ❌ RUIM: Uso Incorreto (Variável de escopo global atende todos as sessões, problema de Multithreading)
var
  LCustomerId: Integer;

// ✅ BOM: Uso Correto (Propriedades seguras do contexto atual)
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.

// ❌ RUIM: Bloqueando a thread no Intraweb 
procedure TIWForm1.iwBtnSaveClick(Sender: TObject);
begin
  if Application.MessageBox('Deseja salvar?', 'Confirme', MB_YESNO) = IDYES then
    // Código de salvamento
end;

// ✅ BOM: Usando Ajax Async do 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.