UI Structure & Templating
Relevant source files
The following files were used as context for generating this wiki page:- src/main/resources/templates/fragments/layout.html
- src/main/resources/static/css/style.css
- src/main/resources/static/js/app.js
- src/main/resources/templates/contracts/form.html
- src/main/resources/templates/customers/list.html
- src/main/resources/templates/customers/form.html
- src/main/resources/templates/contracts/list.html
- src/main/resources/templates/reports/index.html
- src/main/resources/templates/error.html
- pom.xml
The PayMaster application employs a server-side rendering (SSR) architecture using Java's Spring Boot framework with Thymeleaf as the templating engine. The frontend is built upon Bootstrap 5 for its responsive grid system and components, which are then customized with a dedicated stylesheet (style.css). Client-side interactivity is managed by a single, comprehensive vanilla JavaScript file (app.js), which handles form validation, API communication, and dynamic UI updates.
This structure provides a clear separation between the page layout defined on the server and the dynamic user experience enhancements handled by the client. The use of Thymeleaf fragments ensures a consistent look and feel across all pages by reusing common UI elements like the navigation bar, footer, and alert messages.
Technology Stack
The UI is constructed using a combination of server-side templating and client-side libraries. The core technologies are identified from the project's configuration and HTML files.
| Technology / Library | Purpose | Source |
|---|---|---|
| Spring Boot | Backend framework serving the application. | pom.xml:10-13 |
| Thymeleaf | Server-side Java template engine for rendering HTML. | pom.xml:41-44 |
| Bootstrap 5.3.2 | CSS framework for layout and components. | layout.html:8 |
| Bootstrap Icons 1.11.1 | Icon set used throughout the UI. | layout.html:10 |
| Vazirmatn Font | Primary font for the application (Persian). | layout.html:12 |
| Chart.js 4.4.0 | Library for rendering data visualization charts. | layout.html:142 |
| Custom CSS | Application-specific styling and theming. | layout.html:14 |
| Custom JavaScript | Client-side logic, validation, and API calls. | layout.html:143 |
Sources: pom.xml:10-44, src/main/resources/templates/fragments/layout.html:8-14, 142-143
Templating with Thymeleaf
The application leverages Thymeleaf fragments to maintain a consistent UI structure. The central layout file, layout.html, defines the main HTML structure, including the <head>, navigation bar, footer, and script imports. Other pages then use th:replace to inject their specific content into this master layout.
Sources: src/main/resources/templates/fragments/layout.html
Core Fragments
The layout.html file provides several reusable fragments:
head(title): Includes all CSS links, meta tags, and sets the page title dynamically.navbar: The main top navigation bar.footer: The application footer.alerts: A container for displaying global success or error messages.scripts: Includes all JavaScript files (Bootstrap, Chart.js, app.js).
This diagram illustrates how a typical list page is assembled using fragments from layout.html.
Styling and CSS Architecture
All custom styles are consolidated in style.css. The file is well-structured and uses CSS custom properties (variables) for theming, making it easy to change the application's color scheme.
Sources: src/main/resources/static/css/style.css
CSS Variables
A set of root variables defines the primary color palette, status colors, and layout metrics like shadows and border-radius.
| Variable Name | Default Value | Description |
|---|---|---|
--pm-primary | #3498db | Main theme color for buttons, links, and active states. |
--pm-success | #2ecc71 | Color for success states and messages. |
--pm-warning | #f39c12 | Color for warnings and pending states. |
--pm-danger | #e74c3c | Color for errors, deletions, and danger states. |
--pm-dark | #2c3e50 | Primary text and dark element color. |
--pm-light | #ecf0f1 | Light backgrounds and borders. |
--pm-radius | 0.5rem | Default border radius for components like cards and buttons. |
--pm-shadow | 0 0.5rem 1rem rgba(0, 0, 0, 0.1) | Default shadow for cards on hover. |
Sources: src/main/resources/static/css/style.css:10-38
Structure
The stylesheet is organized into logical sections:
- Root Variables & Fonts: Defines the color palette, fonts, and global metrics.
- Global Styles: Basic resets, body styles, scrollbar styling, and RTL support.
- Component Styles: Customizations for Bootstrap components (
.navbar,.card,.table,.btn,.form-control, etc.). - Custom Components: Styles for non-Bootstrap elements like
.stats-boxand.empty-state. - Utility Classes: Helper classes for colors, shadows, and borders (e.g.,
.text-primary,.shadow-lg). - Animations: Keyframe animations like
fadeInandpulse. - Responsive & Print Styles: Media queries for different screen sizes and for printing.
Sources: src/main/resources/static/css/style.css
Client-Side Scripting (app.js)
The file app.js is the core of the application's client-side functionality. It is structured into several modules that handle distinct responsibilities.
This diagram shows the high-level architecture of app.js.
Key Modules in app.js
| Module | Description |
|---|---|
CONFIG | A global configuration object holding constants like API base URL, debounce delay, and date format. |
Utils | A collection of utility functions for number/currency formatting, date/ID validation, and showing toast notifications. |
ApiService | A wrapper around fetch for making GET and POST requests to the backend API. It abstracts away the API base URL. |
FormValidator | Manages form validation, including real-time, asynchronous checks for national code and mobile number uniqueness by calling the ApiService. |
ContractCalculator | Handles the real-time calculation of loan installments on the contract creation form, fetching results from the /api/calculate-installments endpoint. |
UIComponents | Initializes Bootstrap components (tooltips, modals) and custom UI features like loading buttons and a "scroll to top" button. |
Sources: src/main/resources/static/js/app.js:10-808
Asynchronous Validation Flow
A key feature of the UI is the asynchronous validation of form fields like the customer's national code. This provides instant feedback to the user without a full page reload.
The following sequence diagram illustrates this process:
Page Structure and Components
The application consists of several standard page types, each with a consistent structure.
List Pages (/customers, /contracts)
List pages are used to display collections of data, such as customers or contracts.
- Header: Contains the page title and a "Create New" button.
- Filtering/Search: A form to filter or search the list. For contracts, this is a set of status pills. For customers, it's a keyword search input.
- Data Table: A responsive table (
<table class="table table-hover">) displays the data. Rows have hover effects. - Actions: Each row includes a button group for view, edit, and delete operations.
- Pagination: A pagination component is shown in the card footer if there are multiple pages of results.
- Empty State: If no data is found, a user-friendly message with an icon and a call-to-action button is displayed.
Sources: src/main/resources/templates/customers/list.html, src/main/resources/templates/contracts/list.html
Form Pages (/customers/new, /contracts/new)
Form pages are used for creating and editing data.
- Breadcrumbs: Provide navigation back to the list page and dashboard.
- Form Layout: Forms are placed within a
.cardand use a responsive grid for field layout. - Input Groups: Fields are enhanced with
input-groupto show icons or units (e.g.,%,ریال). - Validation: Standard HTML5 validation (
required,pattern) is used, supplemented byapp.jsfor real-time feedback. Invalid fields get anis-invalidclass. - Interactive Components: The contract form includes a "Calculation Preview" section that updates in real-time as the user types, powered by the
ContractCalculatormodule and Chart.js.
Sources: src/main/resources/templates/customers/form.html, src/main/resources/templates/contracts/form.html
Report & Dashboard Pages
The reports page uses a different layout to present analytics and statistics.
- Stat Cards: Key metrics are displayed in large, easy-to-read cards at the top.
- Charts: Data is visualized using Chart.js. The page includes a bar chart for receivables and a doughnut chart for collection status. Chart data is passed directly from the server into an inline
<script>block.
Sources: src/main/resources/templates/reports/index.html:23-71, 78-123
Conclusion
The UI of PayMaster is a well-architected system that balances the stability of server-side rendering with the responsiveness of modern client-side JavaScript. The use of Thymeleaf fragments promotes code reuse and maintainability, while the structured CSS and modular JavaScript file (app.js) allow for scalable and organized front-end development. This hybrid approach results in a user interface that is both robust and interactive.