Sample Projects Guide

September 12, 2025 · View on GitHub

DelphiMVCFramework comes with 40+ sample projects that demonstrate all framework features. Each sample is self-contained and focuses on specific functionality.

📁 Sample Structure

All samples are located in the samples/ directory. Each sample is a complete, runnable project that demonstrates specific features of the framework.

🚀 Core Samples

Hello World

Location: samples/hello_world/ The simplest possible DMVCFramework server demonstrating basic setup and routing.

Renders

Location: samples/renders/ Comprehensive demonstration of all rendering capabilities:

Object serialization
List rendering
Dataset to JSON conversion
Custom serialization attributes
HATEOAS support

Functional Actions Showcase

Location: samples/function_actions_showcase/ Demonstrates the new functional actions feature where functions can be used as controller actions:

[MVCPath('/sum/($A)/($B)')]
function GetSum(const A, B: Integer): Integer;

[MVCPath('/person')]
function GetPerson: TPerson;

🛡️ Middleware Samples

CORS Middleware

Location: samples/middleware_cors/ Cross-Origin Resource Sharing configuration and handling.

Static Files Middleware

Location: samples/middleware_staticfiles/ Serving static content and SPA applications:

File serving configuration
SPA routing support
Custom file filtering
Security considerations

JWT Blacklist Middleware

Location: samples/middleware_jwtblacklist/ JWT token blacklisting and logout functionality for JWT-based authentication.

Analytics Middleware

Location: samples/middleware_analytics/ API usage analytics with automatic CSV generation for monitoring and analysis.

Compression Middleware

Location: samples/middleware_compression/ Response compression with gzip and deflate support.

💾 ActiveRecord and Database Samples

ActiveRecord Showcase

Location: samples/activerecord_showcase/ Complete demonstration of the MVCActiveRecord ORM:

Entity mapping and attributes
CRUD operations
RQL queries
Relationships
Validation
Nullable types
Connection management

ActiveRecord CRUD

Location: samples/activerecord_crud/ RESTful CRUD operations using MVCActiveRecord with automatic endpoint generation.

Articles CRUD VCL Client Meta

Location: samples/articles_crud_vcl_client_meta/ VCL client application demonstrating metadata-driven dataset initialization and JSON data loading.

🌐 JSON-RPC Samples

JSON-RPC with Published Objects

Location: samples/jsonrpc_with_published_objects/ Complete JSON-RPC 2.0 implementation:

Exposing regular Delphi objects
Automatic method publishing
Async JSON-RPC calls (new feature)
Parameter marshalling
Error handling

Simple JSON-RPC

Basic JSON-RPC server implementation with method calls and notifications.

🔐 Security and Authentication Samples

JWT Authentication

Location: samples/jsonwebtoken/ Complete JWT implementation:

Token generation and validation
Claims handling
Token expiration
Authentication middleware

Basic Authentication

HTTP Basic Authentication implementation with custom authentication handlers.

Custom Authentication

Implementing custom authentication schemes and authorization logic.

🎨 Server-Side Views

Mustache Templates

Location: samples/serversideviews_mustache/ Server-side rendering using Mustache templating engine:

Template syntax
Partial templates
Data binding
Dynamic content generation

eLua Server Side Views

Location: samples/serversideviews_lua/ Server-side view support using eLua scripting engine (requires Lua DLLs).

TemplatePro

Advanced templating with TemplatePro engine for complex template scenarios.

📋 Advanced Features

Server-Sent Events

Location: samples/serversentevents/ Real-time push notifications using Server-Sent Events:

Event streaming
Connection management
Real-time updates
Client-server communication

File Upload

Location: samples/fileupload/ File handling operations:

Multipart form data handling
File upload processing
Progress tracking
Security considerations

HTMX Support

Location: samples/htmx/ HTMX server-side support through MVCFramework.HTMX.pas:

HTMX request handling
Dynamic content updates
Server-side rendering for HTMX

Profiling

Location: samples/profiling/ Built-in profiler demonstration:

procedure ProfiledAction;
begin
  begin var Prof := Profiler.Start('DataProcessing');
    ProcessData();
  end; // Automatically logged
end;

Spring4D Nullables

Location: samples/renders_spring4d_nullables/ Support for Spring4D nullable types in serialization and rendering.

🛠️ Specialized Samples

Custom Exception Handling

Location: samples/custom_exception_handling/ Implementing custom exception handling mechanisms for better error management.

Entity Processor

Advanced entity processing and validation with lifecycle hooks and business rules.

Avoid Mid-Air Collisions

Location: samples/avoid_mid_air_collisions_sample/ Demonstrates ETag-based conflict detection and resolution for safe concurrent updates.

Swagger API Versioning Primer

Location: samples/swagger_api_versioning_primer/ API versioning strategies with Swagger/OpenAPI documentation.

Custom Type Serializers

Implementing custom serialization logic for complex data types.

📱 Platform-Specific Samples

Server in DLL

Demonstrates packaging DMVCFramework server as a Windows DLL.

Linux Daemon

Running DMVCFramework applications as Linux daemons with proper signal handling.

Apache Module

Deploying DMVCFramework applications as Apache modules.

🧪 Client Samples

REST Client Showcase

Demonstrates the built-in REST client capabilities:

HTTP method support
Authentication
Response handling
Error management

VCL Client Applications

Desktop client applications consuming DMVCFramework APIs.

🚀 Running the Samples

Prerequisites

DelphiMVCFramework installed and configured
Appropriate Delphi version (see compatibility matrix)
Database connections configured (for database samples)

Basic Steps

Navigate to the desired sample directory
Open the project file (.dproj) in Delphi
Configure database connections if required (check documentation in sample)
Compile and run (F9)
Test the endpoints using browser, Postman, or provided client

Database Setup for ActiveRecord Samples

Some samples require database setup. Connection configurations are typically found in:

Configuration files within the sample directory
WebModule creation procedures
Dedicated database setup units

Common databases used in samples:

PostgreSQL - Full feature samples
SQLite - Embedded database samples
Firebird - Cross-platform samples
MySQL/MariaDB - Alternative SQL database samples

Testing the Samples

Web Browser: For simple GET requests and web interfaces

http://localhost:8080/api/hello
http://localhost:8080/api/customers

Postman/Insomnia: For comprehensive REST API testing with different HTTP methods

curl: Command-line testing

curl -X GET http://localhost:8080/api/customers
curl -X POST http://localhost:8080/api/customers -H "Content-Type: application/json" -d '{"name":"John Doe"}'

Built-in Swagger UI: Many samples include automatic API documentation

http://localhost:8080/api/system/describeserver.info

📖 Learning Path

Beginner (Start Here)

hello_world - Basic framework concepts
renders - Data serialization and response handling
middleware_staticfiles - Static content serving
jsonwebtoken - Basic authentication

Intermediate

activerecord_showcase - ORM and database integration
jsonrpc_with_published_objects - JSON-RPC services
serversideviews_mustache - Server-side rendering
serversentevents - Real-time features

Advanced

custom_exception_handling - Error handling strategies
profiling - Performance optimization
middleware_jwtblacklist - Advanced security
htmx - Modern web development patterns

🤝 Sample Guidelines

Each sample includes:

README.md - Setup instructions and feature explanation
Complete source code - Fully functional project
Database scripts (if needed) - Setup and sample data
Documentation comments - Code explanation
Configuration examples - Different deployment scenarios

Sample Structure

sample_name/
├── README.md              # Setup and usage instructions
├── ProjectName.dpr        # Main project file
├── ProjectName.dproj      # Delphi project file
├── WebModuleU.pas         # Web module with configuration
├── ControllerU.pas        # Sample controller(s)
├── EntityU.pas           # Data models (if applicable)
├── templates/            # Template files (if applicable)
├── www/                  # Static files (if applicable)
└── sql/                  # Database scripts (if applicable)

💡 Tips for Using Samples

Start Simple: Begin with hello_world and gradually progress to more complex samples
Read Documentation: Each sample has specific setup requirements
Database Configuration: Check connection strings and database requirements
Port Conflicts: Default port is usually 8080, change if needed
Dependencies: Some samples require additional libraries or services
Learning Approach: Study the code, modify it, experiment with changes

🔧 Common Issues

Port Already in Use

Change the port in the main program file or WebModule configuration

Database Connection Errors

Verify connection strings, database server status, and credentials

Missing Dependencies

Check if additional libraries or services are required (Redis, specific database drivers, etc.)

Compilation Errors

Ensure all library paths are correctly configured in Delphi IDE

🎯 Sample Categories Summary

Category	Sample Count	Key Features
Core Framework	5+	Basic setup, routing, rendering
Middleware	8+	CORS, authentication, static files, compression
Database/ORM	6+	ActiveRecord, CRUD, multiple databases
JSON-RPC	3+	RPC services, async calls, object publishing
Security	4+	JWT, Basic Auth, custom authentication
Views/Templates	3+	Mustache, eLua, TemplatePro
Advanced Features	10+	SSE, profiling, HTMX, file handling
Client Applications	3+	REST clients, VCL applications
Platform Specific	4+	DLL, Linux, Apache module

📚 Remember: Each sample is designed to be educational and practical. Use them as starting points for your own applications and don't hesitate to modify and experiment with the code to better understand the framework's capabilities.