Tool Architecture

Sakai tools are modular web applications that provide specific functionality like assignments, gradebook, or forums. Tools integrate with the kernel services and are rendered within the portal framework.

What is a Tool?

A tool is a user interface component that provides specific educational functionality. Tools are:

Self-contained: Each tool is a separate web application
Service-based: Tools use kernel services for core functionality
Portal-rendered: Tools render within the portal’s iframe or portlet containers
Site-scoped: Tools are placed within sites and pages

Tool Interface

The core Tool interface defines the contract for all Sakai tools:

package org.sakaiproject.tool.api;

/**
 * Tool models a Sakai user interface producing tool.
 * Tool and its attributes are immutable.
 */
public interface Tool {
    /** Request attribute for document fragment mode */
    public static final String FRAGMENT = "sakai.fragment";
    
    /** Request attribute for portlet mode */
    public static final String PORTLET = "sakai.portlet";
    
    /** Request attribute containing the Tool definition */
    public static final String TOOL = "sakai.tool";
    
    /** Request attribute containing the ToolSession */
    public static final String TOOL_SESSION = "sakai.tool.session";
    
    /** Request attribute containing Tool placement */
    public static final String PLACEMENT = "sakai.tool.placement";
    
    /** Request attribute/parameter for placement id */
    public static final String PLACEMENT_ID = "sakai.tool.placement.id";
    
    /**
     * Access the well known id of the tool.
     */
    String getId();
    
    /**
     * Access the tool's home destination.
     */
    String getHome();
    
    /**
     * Access the tool title.
     */
    String getTitle();
    
    /**
     * Access the tool description.
     */
    String getDescription();
    
    /**
     * Access the configuration properties from registration.
     */
    Properties getRegisteredConfig();
}

Reference: kernel/api/src/main/java/org/sakaiproject/tool/api/Tool.java:27-100

Tool Module Structure

Typical tool structure follows this pattern:

tool-name/
├── api/                        # Service interfaces (optional)
│   └── src/main/java/
│       └── org/sakaiproject/toolname/api/
├── impl/                       # Service implementations (optional)
│   └── src/
│       ├── main/java/
│       └── main/webapp/WEB-INF/
│           └── components.xml
├── tool/                       # Web application (UI)
│   └── src/
│       ├── main/java/         # Controllers, servlets
│       ├── main/webapp/       # JSP, HTML, CSS, JS
│       └── main/resources/    # i18n bundles
└── pom.xml

Example: Assignment Tool Structure

assignment/
├── api/          # Assignment service API
├── impl/         # Assignment service implementation
└── tool/         # Assignment web UI

Reference: source/assignment/

Not all tools have separate API/implementation modules. Simple tools may only have a tool/ module that uses existing kernel services.

Tool Types

Sakai supports different types of tools based on their rendering approach:

Standard Tools
Portlet Tools
Helper Tools

Traditional tools that render full HTML pages within an iframe.

Most common tool type
Full control over HTML/CSS/JS
Rendered via IFrameToolRenderService

Examples: Assignments, Gradebook, Resources

Tools that follow the JSR-168/286 portlet specification.

Rendered as portal fragments
Use PortletToolRenderService
Less common in modern Sakai

Lightweight tools that provide specific helper functionality.

Used by other tools
Return to parent tool when done
Use HELPER_DONE_URL session attribute

Reference: portal/README.md:25-26

Tool Registration

Tools are registered in the system through configuration files that define:

Tool ID (unique identifier)
Title and description
Categories and keywords
Required permissions
Configuration properties

Tool Order Configuration

The system maintains a default tool ordering: Reference: kernel/component-manager/src/main/bundle/org/sakaiproject/config/toolOrder.xml

Tool Integration with Kernel Services

Tools should use kernel services for all core functionality:

public class AssignmentController {
    
    // Inject kernel services
    private SiteService siteService;
    private UserDirectoryService userService;
    private ContentHostingService contentService;
    private EventTrackingService eventService;
    
    public void init() {
        // Get services from ComponentManager
        siteService = ComponentManager.get(SiteService.class);
        userService = ComponentManager.get(UserDirectoryService.class);
        contentService = ComponentManager.get(ContentHostingService.class);
        eventService = ComponentManager.get(EventTrackingService.class);
    }
    
    public void submitAssignment(String assignmentId) {
        // Get current user
        User user = userService.getCurrentUser();
        
        // Get current site
        String siteId = ToolManager.getCurrentPlacement().getContext();
        Site site = siteService.getSite(siteId);
        
        // Post event
        Event event = eventService.newEvent(
            "assignment.submit",
            "/assignment/a/" + assignmentId,
            true
        );
        eventService.post(event);
    }
}

Don’t implement your own user management, authorization, or content storage. Always use kernel services:

User management → UserDirectoryService
Authorization → AuthzGroupService
Content storage → ContentHostingService
Email → EmailService

Tool Placement

A placement is an instance of a tool within a site page. The same tool can be placed multiple times with different configurations.

// Get current placement
Placement placement = ToolManager.getCurrentPlacement();

// Get placement context (site ID)
String siteId = placement.getContext();

// Get placement configuration
Properties config = placement.getConfig();
String customSetting = config.getProperty("custom.setting");

// Get placement ID (unique instance ID)
String placementId = placement.getId();

Portal URL Patterns

Tools can be accessed through various portal URL patterns:

Standard Tool Access

/portal/site/{site-id}/page/{page-id}

Direct Tool Access

Bypass site navigation and go directly to a tool:

/portal/directtool/{tool-id}?sakai.site={site-id}

Examples:

/portal/directtool/sakai.samigo?sakai.site=e4a2b1db-f452-4ef0-8aee-b4bdde701c8c
/portal/directtool/sakai.rsf.evaluation?sakai.site=~

Reference: portal/README.md:36-44

Tool Development Frameworks

Sakai supports multiple frameworks for tool development:

Spring MVC + Thymeleaf (Recommended)

Preferred for new development

Modern Spring MVC controllers
Thymeleaf templating
RESTful endpoints
Clean separation of concerns

@Controller
@RequestMapping("/assignments")
public class AssignmentController {
    
    @GetMapping("/list")
    public String listAssignments(Model model) {
        model.addAttribute("assignments", assignmentService.getAssignments());
        return "assignment/list";
    }
}

Web Components + Lit

Strategic direction for frontend

Encapsulated, reusable components
Shadow DOM for style isolation
Modern JavaScript (ES2022+)
Integration with existing tools

import { LitElement, html, css } from 'lit';

class SakaiAssignment extends LitElement {
  static properties = {
    assignmentId: { type: String }
  };
  
  render() {
    return html`<div class="assignment">...</div>`;
  }
}

customElements.define('sakai-assignment', SakaiAssignment);

JSF 2.3

Used in many existing tools

Component-based framework
Still supported but not recommended for new tools

Wicket

Component-based web framework

Used in several tools
Good for complex UIs
Not recommended for new development

Best Practices

1. Use Kernel Services

✅ Correct:

UserDirectoryService userService = ComponentManager.get(UserDirectoryService.class);
User user = userService.getCurrentUser();

❌ Incorrect:

// Don't implement your own user management!
User user = new User(session.getAttribute("userId"));

2. Post Events for Significant Actions

// Post events for analytics and integration
Event event = eventService.newEvent(
    "assignment.submit",      // Event type
    assignmentReference,       // Resource reference  
    true                       // Is modification?
);
eventService.post(event);

3. Internationalization

Always support i18n:

// Load resource bundle
ResourceLoader rb = new ResourceLoader("org.sakaiproject.tool.bundle");

// Get localized string
String message = rb.getString("assignment.submit.success");

4. Accessibility

Follow accessibility best practices:

Semantic HTML
ARIA labels where needed
Keyboard navigation
Screen reader support

5. Responsive Design

Use Bootstrap 5.2 for responsive layouts:

<div class="container">
  <div class="row">
    <div class="col-md-8">Main content</div>
    <div class="col-md-4">Sidebar</div>
  </div>
</div>

Tool Helper Pattern

Tools can use helper tools for specific functionality:

// Set return URL for helper
SessionManager.getCurrentToolSession()
    .setAttribute(Tool.HELPER_DONE_URL, returnUrl);

// Redirect to helper tool
response.sendRedirect("/sakai-filepicker-helper/tool");

When the helper completes, it redirects back to HELPER_DONE_URL. Reference: kernel/api/src/main/java/org/sakaiproject/tool/api/Tool.java:56

Next Steps

Architecture Overview

Understand the overall system architecture

Kernel Services

Learn about available kernel services

Sites & Workspaces

Understand how tools are organized in sites

Getting Started

Core Concepts

Key Features

Administration

Development

Tool Architecture

Tool Architecture

What is a Tool?

Tool Interface

Tool Module Structure

Example: Assignment Tool Structure

Tool Types

Tool Registration

Tool Order Configuration

Tool Integration with Kernel Services

Tool Placement

Portal URL Patterns

Standard Tool Access

Direct Tool Access

Tool Development Frameworks

Best Practices

1. Use Kernel Services

2. Post Events for Significant Actions

3. Internationalization

4. Accessibility

5. Responsive Design

Tool Helper Pattern

Next Steps

Architecture Overview

Kernel Services

Sites & Workspaces

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Key Features

Administration

Development

​Tool Architecture

​What is a Tool?

​Tool Interface

​Tool Module Structure

​Example: Assignment Tool Structure

​Tool Types

​Tool Registration

​Tool Order Configuration

​Tool Integration with Kernel Services

​Tool Placement

​Portal URL Patterns

​Standard Tool Access

​Direct Tool Access

​Tool Development Frameworks

​Best Practices

​1. Use Kernel Services

​2. Post Events for Significant Actions

​3. Internationalization

​4. Accessibility

​5. Responsive Design

​Tool Helper Pattern

​Next Steps

Architecture Overview

Kernel Services

Sites & Workspaces

Build docs developers (and LLMs) love

Tool Architecture

What is a Tool?

Tool Interface

Tool Module Structure

Example: Assignment Tool Structure

Tool Types

Tool Registration

Tool Order Configuration

Tool Integration with Kernel Services

Tool Placement

Portal URL Patterns

Standard Tool Access

Direct Tool Access

Tool Development Frameworks

Best Practices

1. Use Kernel Services

2. Post Events for Significant Actions

3. Internationalization

4. Accessibility

5. Responsive Design

Tool Helper Pattern

Next Steps