Lutece Patterns

Field prefixes: _str (String), _n (int), _b (boolean), _date (Timestamp), _list (Collection).

Interfaces to implement when needed:

• RBACResource → RBAC permissions (getResourceTypeCode(), getResourceId())
• AdminWorkgroupResource → workgroup filtering
• IExtendableResource → resource extension system

2. DAO

@ApplicationScoped
public final class TaskDAO implements ITaskDAO {
    private static final String SQL_QUERY_SELECTALL = "SELECT id_task, title, completed FROM myplugin_task";
    private static final String SQL_QUERY_SELECT     = SQL_QUERY_SELECTALL + " WHERE id_task = ?";
    private static final String SQL_QUERY_INSERT     = "INSERT INTO myplugin_task ( title, completed ) VALUES ( ?, ? )";
    private static final String SQL_QUERY_UPDATE     = "UPDATE myplugin_task SET title = ?, completed = ? WHERE id_task = ?";
    private static final String SQL_QUERY_DELETE     = "DELETE FROM myplugin_task WHERE id_task = ?";

    @Override
    public void insert(Task task, Plugin plugin) {
        try (DAOUtil daoUtil = new DAOUtil(SQL_QUERY_INSERT, Statement.RETURN_GENERATED_KEYS, plugin)) {
            int nIndex = 1;
            daoUtil.setString(nIndex++, task.getTitle());
            daoUtil.setBoolean(nIndex++, task.isCompleted());
            daoUtil.executeUpdate();

            if (daoUtil.nextGeneratedKey()) {
                task.setIdTask(daoUtil.getGeneratedKeyInt(1));
            }
        }
    }

    @Override
    public Task load(int nId, Plugin plugin) {
        Task task = null;
        try (DAOUtil daoUtil = new DAOUtil(SQL_QUERY_SELECT, plugin)) {
            daoUtil.setInt(1, nId);
            daoUtil.executeQuery();

            if (daoUtil.next()) {
                task = dataToObject(daoUtil);
            }
        }
        return task;
    }

    private Task dataToObject(DAOUtil daoUtil) {
        int nIndex = 1;
        Task task = new Task();
        task.setIdTask(daoUtil.getInt(nIndex++));
        task.setTitle(daoUtil.getString(nIndex++));
        task.setCompleted(daoUtil.getBoolean(nIndex++));
        return task;
    }
}

Rules: @ApplicationScoped. Always try-with-resources. nIndex++ for parameter binding. Extract dataToObject() to avoid duplication between load() and selectAll().

3. Home (Static Facade)

public final class TaskHome {
    private static ITaskDAO _dao = CDI.current().select(ITaskDAO.class).get();
    private static Plugin _plugin = PluginService.getPlugin("myplugin");

    private TaskHome() {}

    public static Task create(Task task) {
        _dao.insert(task, _plugin);
        return task;
    }

    public static Task findByPrimaryKey(int nId) {
        return _dao.load(nId, _plugin);
    }

    public static void update(Task task) {
        _dao.store(task, _plugin);
    }

    public static void remove(int nId) {
        _dao.delete(nId, _plugin);
    }

    public static List<Task> findAll() {
        return _dao.selectAll(_plugin);
    }
}

Rules: Private constructor. All methods static. CDI lookup for DAO. Plugin reference via PluginService.getPlugin().

4. JspBean — CRUD Lifecycle

The bean extends MVCAdminJspBean with @Named, @Controller and a CDI scope:

• @SessionScoped — if the bean stores per-user state as instance fields (working objects like _task, filters). This is the typical case for CRUD beans. Note: with @Inject @Pager IPager (§5), pagination state is managed automatically — no manual _strCurrentPageIndex/_nItemsPerPage fields needed.
• @RequestScoped — if the bean is stateless (no session instance fields, e.g., dashboard, simple actions).

Method naming convention — strict:

Action method structure (every do* follows this exact order):

public String doCreateTask(HttpServletRequest request) throws AccessDeniedException {
    // 1. CSRF token validation
    if (!getSecurityTokenService().validate(request, ACTION_CREATE_TASK)) {
        throw new AccessDeniedException(ERROR_INVALID_TOKEN);
    }

    // 2. Populate bean from request
    Task task = new Task();
    populate(task, request);

    // 3. Validate (Jakarta Bean Validation)
    Set<ConstraintViolation<Task>> errors = validate(task);
    if (!errors.isEmpty()) {
        return redirect(request, VIEW_CREATE_TASK);
    }

    // 4. Business logic
    TaskHome.create(task);

    // 5. Redirect to list
    return redirectView(request, VIEW_MANAGE_TASKS);
}

View method structure (every get* for forms) — uses @Inject Models, NOT getModel():

import fr.paris.lutece.portal.web.cdi.mvc.Models;

@Inject
private Models _models;

public String getCreateTask(HttpServletRequest request) {
    _models.put(MARK_TASK, new Task());
    _models.put(SecurityTokenService.MARK_TOKEN,
        getSecurityTokenService().getToken(request, ACTION_CREATE_TASK));

    return getPage(PROPERTY_PAGE_TITLE_CREATE_TASK, TEMPLATE_CREATE_TASK);
}

IMPORTANT: getModel() is deprecated. _models.asMap() returns an unmodifiable map — never pass it to a method that calls put(). Helper methods must accept Models directly.

5. Pagination (List views) — @Inject @Pager IPager + paginationAjax

Use CDI-injected IPager instead of manual LocalizedPaginator. The @Pager qualifier configures the paginator via annotation attributes. PaginatorHandler (session-scoped) manages pagination state automatically.

Default approach: paginationAjax — AJAX-driven table with JSON endpoint. The macro handles table rendering, sorting, pagination controls, and action buttons automatically.

JspBean — Pager injection + JSON endpoint

@Inject
@Pager( name = "taskList", listBookmark = "task_list",
        defaultItemsPerPage = "myplugin.task.itemsPerPage",
        baseUrl = "jsp/admin/plugins/myplugin/ManageTasks.jsp" )
private IPager<Task, Task> _pager;

@View( value = VIEW_MANAGE, defaultView = true )
public String getManageTasks( HttpServletRequest request )
{
    List<Task> listTasks = TaskHome.findAll();

    _pager.withListItem( listTasks )
          .populateModels( request, _models, getLocale() );
    // _models now contains: "task_list" (page items), "paginator", "nb_items_per_page"

    return getPage( PROPERTY_PAGE_TITLE_MANAGE, TEMPLATE_MANAGE_TASKS );
}

// JSON endpoint for AJAX pagination — called by the paginationAjax macro
@Action( value = ACTION_GET_ITEMS )
@ResponseBody
public List<Task> getTaskItems( @RequestParam( "page" ) int numPage )
{
    return _pager.getPaginator( ).get( ).getPageItems( numPage );
}

Requires imports:

• fr.paris.lutece.portal.web.util.Pager (annotation)
• fr.paris.lutece.portal.web.util.IPager (interface)
• fr.paris.lutece.portal.util.mvc.commons.annotations.ResponseBody
• fr.paris.lutece.portal.util.mvc.commons.annotations.RequestParam

Template — paginationAjax macro

<#assign taskColumns = [
  {"name": "#i18n{myplugin.model.entity.task.attribute.title}", "property": "title", "sortable": true},
  {"name": "#i18n{myplugin.model.entity.task.attribute.completed}", "property": "completed", "sortable": false}
]>
<#assign taskActions = {
  "edit": {
    "url": "jsp/admin/plugins/myplugin/ManageTasks.jsp?view=modifyTask&id={idTask}",
    "icon": "edit",
    "title": "#i18n{portal.util.labelModify}",
    "btnClass": "btn-primary btn-sm"
  },
  "delete": {
    "url": "jsp/admin/plugins/myplugin/ManageTasks.jsp?action=confirmRemoveTask&id={idTask}",
    "icon": "trash",
    "title": "#i18n{portal.util.labelDelete}",
    "btnClass": "btn-danger btn-sm",
    "confirm": "false"
  }
}>
<@paginationAjax paginator=paginator columns=taskColumns
    ajaxUrl='jsp/admin/plugins/myplugin/ManageTasks.jsp?action=getTaskItems'
    tableId='taskTable'
    combo=1 showcount=1
    actions=taskActions />

Key points:

• columns: array of {name, property, sortable} — property matches the entity's JSON bean property name
• actions: object with edit / delete keys — URL placeholders {property} are replaced by JS from the JSON data
• ajaxUrl: points to the @Action @ResponseBody endpoint
• The macro renders the complete table card with pagination controls, sorting, and action buttons

With delegate (lazy loading from IDs)

@Inject
@Pager( name = "taskList", listBookmark = "task_list",
        defaultItemsPerPage = "myplugin.task.itemsPerPage",
        baseUrl = "jsp/admin/plugins/myplugin/ManageTasks.jsp" )
private IPager<Integer, Task> _pager;

public String getManageTasks( HttpServletRequest request )
{
    List<Integer> listIds = TaskHome.findAllIds();

    _pager.withIdList( listIds )
          .populateModels( request, _models,
              ids -> TaskHome.findByIds( ids ),  // delegate: load only current page
              getLocale() );

    return getPage( PROPERTY_PAGE_TITLE_MANAGE, TEMPLATE_MANAGE_TASKS );
}

Fallback: paginationAdmin (manual table)

Use paginationAdmin only when paginationAjax is not suitable (e.g., workflow state columns, child entity navigation buttons, or other per-row dynamic content that isn't part of the entity JSON):

<@paginationAdmin paginator=paginator nb_items_per_page=nb_items_per_page />

@Pager annotation attributes:

6. XPage (Front-office)

@RequestScoped
@Named("myplugin.xpage.tasks")
public class TasksApp extends AbstractXPageApplication {
    @Inject
    private TaskService _taskService;

    @Override
    public XPage getPage(HttpServletRequest request, int nMode, Plugin plugin) {
        XPage page = new XPage();
        page.setTitle(I18nService.getLocalizedString(PROPERTY_PAGE_TITLE, request.getLocale()));
        page.setContent(getTaskList(request));
        return page;
    }
}

Rules: @RequestScoped. Implements XPageApplication. Declared in plugin.xml <applications>.

7. Daemon (Background task)

public class TaskCleanupDaemon extends Daemon {
    @Override
    public void run() {
        int nCleaned = TaskHome.removeExpired();
        setLastRunLogs("Cleaned " + nCleaned + " expired tasks");
    }
}

Declared in plugin.xml:

<daemons>
    <daemon>
        <daemon-id>taskCleanup</daemon-id>
        <daemon-name>myplugin.daemon.taskCleanup.name</daemon-name>
        <daemon-description>myplugin.daemon.taskCleanup.description</daemon-description>
        <daemon-class>fr.paris.lutece.plugins.myplugin.daemon.TaskCleanupDaemon</daemon-class>
    </daemon>
</daemons>

Configuration via properties: daemon.taskCleanup.interval=3600, daemon.taskCleanup.onstartup=0. Signal on demand: AppDaemonService.signalDaemon("taskCleanup").

8. CDI Patterns — Quick Reference

9. Configuration Access

// Properties (static, from .properties files)
String val = AppPropertiesService.getProperty("myplugin.my.key");
int n = AppPropertiesService.getPropertyInt("myplugin.items.per.page", 50);

// Datastore (runtime, from database — overrides properties)
String ds = DatastoreService.getInstanceDataValue("myplugin.setting", "default");
DatastoreService.setInstanceDataValue("myplugin.setting", "newValue");

// In Freemarker templates
// #{dskey{myplugin.setting}}

10. Security Checklist

Every admin feature MUST:

1. Call init(request, RIGHT_MANAGE_TASKS) to check the user right
2. Include SecurityTokenService.MARK_TOKEN in every form model
3. Validate getSecurityTokenService().validate(request, ACTION) in every do* method
4. Filter collections with RBACService.getAuthorizedCollection() when RBAC is enabled
5. Filter by workgroup with AdminWorkgroupService.getAuthorizedCollection() when needed