Component Guidelines

JSP fragment, form, table, and reusable UI conventions.

Overview

This project uses JSP-based presentation, not a component framework. Treat JSP includes, fragments, tag files, form layouts, tables, and shared CSS classes as the reusable UI units.

JSP Includes And Fragments

Use shared fragments for repeated layout pieces such as header, navigation, sidebar, footer, pagination, and message banners.
Use .jspf includes for the current JSP presentation layer. The authenticated application frame lives in src/main/webapp/WEB-INF/jsp/common/header.jspf and owns the dark sidebar, top utility bar, module navigation, global search, user display, and logout link.
Any .jspf fragment that contains user-visible Simplified Chinese text must declare <%@ page pageEncoding="UTF-8" %> at the top. Do not rely only on the including JSP page or response Content-Type; Tomcat/Jasper can otherwise compile the fragment with a non-UTF-8 default and render mojibake.
JSP-rendered HTML responses must be served as text/html;charset=UTF-8 by the encoding filter or the JSP page directive. Request/response character encoding alone is not enough for browsers to decode Simplified Chinese safely.
Preserve role-conditioned navigation in that shared frame: administrator-only links stay inside sessionScope.userRole == 'administrator'; staff links stay inside administrator or librarian; reader-only links stay inside sessionScope.userRole == 'reader'.
For active navigation in forwarded JSPs, derive the current location from the public Servlet path before falling back to the JSP servlet path. Use exact matches or slash-delimited prefixes; do not use broad fn:contains checks against requestURI, because forwarded pages expose /WEB-INF/jsp/... paths and can activate unrelated sidebar items.
```
<c:set var="currentPath" value="${requestScope['javax.servlet.forward.servlet_path']}" />
<c:if test="${empty currentPath}">
    <c:set var="currentPath" value="${pageContext.request.servletPath}" />
</c:if>
<a class="${(currentPath == '/books' or fn:startsWith(currentPath, '/books/')) ? 'is-active' : ''}">
```
Keep fragments presentation-focused. They should not open database connections or call DAOs.

Interface Copy

Render user-visible JSP copy in Simplified Chinese, including navigation, headings, form labels, buttons, table headers, empty states, and accessible labels.
Keep machine-readable values unchanged: URLs, request parameter names, CSS classes, Java identifiers, enum codes, database values, and servlet names stay in their existing code form.
Translate display helper output and controller/service messages when they are rendered into JSP pages.

Forms

Forms should post to Servlet controller endpoints, not directly to DAOs or JSP-only handlers.
Render validation messages from request attributes set by controllers.
Preserve user-entered values on validation failure where practical.
Use clear labels, required-field indicators, and server-side validation for book, reader, borrowing, login, and permission forms.

Tables And Reports

Use consistent table patterns for book lists, reader lists, borrowing records, rankings, inventory reports, overdue reports, and system logs.
Include stable empty states and pagination or filtering controls when lists can grow.
Keep search forms aligned with supported filters: title, author, category, and book ID.

Styling

Implement JSP/CSS pages to faithfully restore the approved image design. Prefer semantic class names tied to page structure or reusable UI roles. Avoid adding a frontend component framework unless explicitly introduced later.

3.7 KiB Raw Blame History