Development environment
Use a clean 1.0.0 checkout and Perl 5.34 or newer. Run the chat through tools/run-local.sh with a fresh local configuration. The web server invokes cgi-bin/chat.pl using its shebang, so check that interpreter separately from the one in your interactive shell.
perl -v
perl -c cgi-bin/chat.pl
For UI work, open a guest or test member on a second browser profile and exercise both layouts, a reconnect, and the relevant admin or public form.
Perl in this project
my declares a lexically scoped variable. Scalars such as $chat hold values or references. \@items and \%fields take references to an array or hash, and $record->{name} reads an entry from a hash reference. For a call like $service->read($name), Perl passes the service as the first argument before $name. A method often starts with my ($self, $name) = @_;.
use strict;
use warnings;
sub public_room_names {
my ($rooms) = @_;
return [map { $_->{name} } grep { !$_->{closed} } @$rooms];
}
Here grep filters records, map transforms each remaining record, and the surrounding brackets return an array reference. The example only operates on an already-authorized list of records. Reuse the relevant policy module when selecting records in a real request.
From request to response
cgi-bin/chat.plestablishes the Perl runtime and creates the chat application object.Sources/RequestContext.pmestablishes request-scoped input and identity. A persistent worker can serve multiple users, so transient state belongs within that context.- Core actions and registered plugins validate and authorize a request, then call the appropriate service or repository.
- The template engine renders HTML, or the delivery layer produces versioned message events. The browser applies the result through the matching client module.
To trace one feature, start with its form action or the script triggered by its button, follow the action mapping, and find the template and response code. For example, administration settings are rendered in Templates/admin/ and handled by Plugins/Administration/Settings.pm.
Files, state, and repositories
Sources/ contains current services, policies, and storage adapters. Repositories own file reads and writes. When a feature changes a durable record, extend the existing service and its repository so file identity, locking, and publication remain coordinated. The file identity marker and settings marker are part of persistent state during backup and upgrades.
Settings.static.dat wires bundled actions and extensions. SiteSettings.default.dat provides defaults for new sites. Mutable administrator settings are stored in Variables/site-settings.json. Templates and static browser files ship together. The file reference lists each file and its purpose or available entry points.
Plugins and extension points
Use a bundled module from the current source as the starting point. A command plugin such as Plugins/CommandHandlers/TextCommands.pm returns a blessed hash containing command_handlers, mapping command names to handler references. The matching configuration maps command names to the module under custom_command_handlers. Public action plugins use the action registry. Explore the module and its corresponding entry in Settings.static.dat together.
Declare the GTChat build your plugin supports, give it a unique command name, and ship its own translations and templates as needed. Treat request parameters as user input. Resolve the current account and room through the established request and permission mechanisms. Keep package changes separate from bundled modules and validate a failed request, a successful request, and behavior on reconnect before publishing.
Historical plugins that return executable client strings need to be adapted. 1.0.0 uses fixed client action identifiers and typed message events. Use the CHAT_EVENT template helper and the existing client action definitions for UI updates.
Write your first command
- On your disposable development installation, add the module below as
cgi-bin/Plugins/CommandHandlers/Hello.pm. - Add
hello => 'plugindir::CommandHandlers/Hello.pm'tocustom_command_handlersinSettings.static.dat. In the same file’s permission defaults, add'command.hello' => 1for the local example. Review the site’s existing command permission settings if it already has its own configuration. - Test
perl -c cgi-bin/Plugins/CommandHandlers/Hello.pm, start the development server, and sign in as a member. Type/hello. The message should appear in your session. Verify that a second browser session and the room history do not receive the reply.
package GT_Chat::Plugins::Hello;
use strict;
use warnings;
return bless({
command_handlers => { hello => \&hello_handler },
});
sub hello_handler {
my ($plugin, $chat, $command, $arguments) = @_;
my $user = $chat->{current_user};
my $message = $chat->createOutput({
template => 'text',
name => $user->{name},
nick => $user->{nick},
color => $user->{color},
text => $chat->toHTML('Hello from your GTChat plugin.'),
});
return [$message->restrictToCurrentUser];
}
The object returned by the module declares its exported command handlers. The server checks permission and supplies the current request context before dispatch. The return value is an array reference of output records. restrictToCurrentUser binds each reply to the current user and, when available, the current session. For a public room message, use the intended room policy and recipient restriction. Use localized strings before distributing a plugin.
Templates, translation, and appearance
The bundled template engine uses named includes and data tags. INCLUDE shares layout fragments, T looks up localized text, and GET_HTML escapes values inserted in HTML. Use the context-specific escaping already present in neighboring templates for URLs, JavaScript strings, and HTML. A display condition does not replace authorization on the corresponding action.
Update English and German language files in pairs. A new menu item needs a localized caption and a real route. Shared styling is in www/style.css. Keep dark and light definitions independent of the accent palette and verify the surface, links, and controls in both modes.
Transport and client events
The browser uses the versioned protocol for JSON chat batches. The event name is chat on the SSE connection. Polling and document streaming wrap the same versioned event data. A transcript update, private message, roster change, moderation event, appearance change, and disconnect each have their own handler.
Keep the changed templates and browser assets in the same release. Test a normal message, private delivery, and a reconnect. Check that deciding which room or account receives an event remains a server responsibility. Rendering a message is separate from admitting a sender or acknowledging durable storage.