@jahia/agentic 0.0.0

package/dist/cursor/.agents/skills/jahia-dev-java/references/rendering.md

@@ -0,0 +1,191 @@
+# Jahia Rendering Reference
+
+## Table of Contents
+1. [View script selection](#1-view-script-selection)
+2. [JSP rendering with taglibs](#2-jsp-rendering-with-taglibs)
+3. [Templates, areas, and cascading](#3-templates-areas-and-cascading)
+4. [Caching directives](#4-caching-directives)
+5. [Navigation menus](#5-navigation-menus)
+6. [Rendering filters](#6-rendering-filters)
+7. [List rendering](#7-list-rendering)
+
+---
+
+## 1. View script selection
+
+**JSP naming convention:**
+```
+src/main/webapp/{nodeType_with_slash}/{templateType}/{viewName}.{displayType}.jsp
+```
+
+Examples:
+```
+src/main/webapp/jnt_article/html/article.jsp          # default view
+src/main/webapp/jnt_article/html/article.summary.jsp  # "summary" named view
+src/main/webapp/jnt_article/json/article.json.jsp     # JSON template type
+src/main/webapp/jnt_article/html/article.hidden.header.jsp  # hidden view
+```
+
+**Prefix `hidden.`** on a view name to exclude it from the UI view selector.
+
+---
+
+## 2. JSP rendering with taglibs
+
+### Standard taglib declarations
+```jsp
+<%@ taglib prefix="template" uri="http://www.jahia.org/tags/templateLib" %>
+<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
+<%@ taglib prefix="fmt" uri="http://java.sun.com/jsp/jstl/fmt" %>
+<%@ taglib prefix="fn" uri="http://java.sun.com/jsp/jstl/functions" %>
+<%@ taglib prefix="jcr" uri="http://www.jahia.org/tags/jcr" %>
+<%@ taglib prefix="ui" uri="http://www.jahia.org/tags/uiComponentsLib" %>
+```
+
+### Key implicit variables
+
+| Variable | Type | Description |
+|----------|------|-------------|
+| `currentNode` | `JCRNodeWrapper` | The node being rendered |
+| `currentUser` | `JahiaUser` | The currently logged-in user |
+| `renderContext` | `RenderContext` | Current rendering context |
+| `url` | `URLGenerator` | URL generation helper |
+
+### Common template taglib usage
+```jsp
+<template:module node="${currentNode}" view="summary"/>
+<template:area path="maincontent"/>
+<template:addCacheDependency node="${commentNode}"/>
+<template:link node="${targetNode}"/>
+```
+
+### Full JSP view example
+```jsp
+<%@ taglib prefix="template" uri="http://www.jahia.org/tags/templateLib" %>
+<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
+<%@ taglib prefix="fn" uri="http://java.sun.com/jsp/jstl/functions" %>
+
+<c:set var="title" value="${currentNode.properties['jcr:title'].string}"/>
+<c:set var="body" value="${currentNode.properties['body'].string}"/>
+
+<article class="my-article">
+    <h1>${fn:escapeXml(title)}</h1>
+    <div class="body">${body}</div>
+    <template:area path="related-content"/>
+</article>
+```
+
+---
+
+## 3. Templates, areas, and cascading
+
+Page rendering cascades: page → home template → base template → template view.
+
+**Absolute areas** (`level` attribute): use an ancestor path instead of the template sequence.
+- Level 0 = home page
+- Level 1 = first sub-page level
+
+---
+
+## 4. Caching directives
+
+### Per-view cache configuration
+
+Create a `.properties` file alongside the JSP:
+
+```properties
+# jnt_banner/html/banner.properties
+cache.expiration=30      # Cache for 30 seconds
+# cache.expiration=-1   # Never cache this view
+cache.perUser=true       # Cache per user
+cache.mainResource=true  # Cache depends on the main resource
+```
+
+### Adding cache dependencies in JSPs
+
+```jsp
+<template:addCacheDependency node="${commentsNode}"/>
+<template:addCacheDependency
+    flushOnPathMatchingRegexp="\Q${renderContext.mainResource.node.path}\E/.*/comments/.*"/>
+```
+
+---
+
+## 5. Navigation menus
+
+```jsp
+<jcr:node var="siteNode" path="${renderContext.site.path}"/>
+<c:set var="homeNode" value="${siteNode.node['home']}"/>
+
+<nav>
+  <ul>
+    <c:forEach var="pageNode" items="${homeNode.nodes}">
+      <c:if test="${pageNode.nodeType.name == 'jnt:page'}">
+        <li>
+          <template:link node="${pageNode}">
+            <c:out value="${pageNode.properties['jcr:title'].string}"/>
+          </template:link>
+        </li>
+      </c:if>
+    </c:forEach>
+  </ul>
+</nav>
+```
+
+---
+
+## 6. Rendering filters
+
+Filters intercept every module render. Extend `AbstractFilter` and register as OSGi `RenderFilter` services.
+
+### Priority rules
+- Priority > 16: runs once, result is cached
+- Priority < 16: runs on EVERY request (very expensive — avoid)
+
+### Filter implementation
+```java
+@Component(service = RenderFilter.class)
+public class MyFilter extends AbstractFilter {
+
+    @Activate
+    public void activate() {
+        setPriority(20);
+        setApplyOnConfigurations("page");
+        setApplyOnTemplateTypes("html,html-*");
+        setApplyOnNodeTypes("jnt:myContent");
+    }
+
+    @Override
+    public String execute(String previousOut, RenderContext renderContext,
+            Resource resource, RenderChain chain) throws Exception {
+        String output = super.execute(previousOut, renderContext, resource, chain);
+        return output;
+    }
+}
+```
+
+---
+
+## 7. List rendering
+
+The `jmix:list` mixin provides built-in list rendering.
+
+### moduleMap parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `currentList` | Iterable of nodes to display |
+| `begin` | Start index |
+| `end` | End index |
+| `listQuery` | JCR SQL2 query |
+| `subNodesView` | View name used for child nodes |
+| `editable` | Whether list is editable (default: true) |
+
+### Query-based list example (`hidden.load.jsp`)
+```jsp
+<query:definition var="listQuery"
+    statement="SELECT * FROM [jnt:article] WHERE ISDESCENDANTNODE('${renderContext.mainResource.node.path}') ORDER BY [jcr:lastModified] DESC"
+    limit="10"/>
+<c:set target="${moduleMap}" property="listQuery" value="${listQuery}"/>
+<c:set target="${moduleMap}" property="editable" value="false"/>
+```

package/dist/cursor/.agents/skills/jahia-dev-java/references/ui-extensions.md

@@ -0,0 +1,344 @@
+# Jahia UI Extensions Reference
+
+## Table of Contents
+1. [Overview: two extension layers](#1-overview-two-extension-layers)
+2. [Component registry](#2-component-registry)
+3. [Content Editor JSON overrides](#3-content-editor-json-overrides)
+4. [jContent UI extension points](#4-jcontent-ui-extension-points)
+5. [Adding UI actions](#5-adding-ui-actions)
+6. [Adding settings pages (admin routes)](#6-adding-settings-pages-admin-routes)
+7. [Custom selector types](#7-custom-selector-types)
+8. [Custom picker configuration](#8-custom-picker-configuration)
+9. [Dynamic forms in Content Editor](#9-dynamic-forms-in-content-editor)
+10. [CKEditor customization](#10-ckeditor-customization)
+11. [Debugging JSON overrides and registry](#11-debugging-json-overrides-and-registry)
+
+---
+
+## 1. Overview: two extension layers
+
+| Mechanism | What it controls | Format |
+|-----------|-----------------|--------|
+| **Content Editor JSON overrides** | Form layout, field visibility, labels, sections, field order | JSON files in module JAR |
+| **Component registry** | Actions, accordions, nav items, selectors, routes, settings pages | JavaScript (React/JSX) |
+
+The component registry lives in the JavaScript layer. JSON overrides live in the Java module under `META-INF/jahia-content-editor-forms/`.
+
+---
+
+## 2. Component registry
+
+```javascript
+import { registry } from '@jahia/ui-extender';
+
+registry.add('action', 'myAction', myActionObj, {
+    targets: ['contentActions:5'],
+    label: 'myModule:myAction.label'
+});
+
+registry.addOrReplace('adminRoute', 'mySettings', {
+    targets: ['administration-sites:10'],
+    label: 'myModule:settings.label',
+    isSelectable: true,
+    iframeUrl: window.contextJsParameters.contextPath + '/cms/adminframe/default/en/settings.myPage.html'
+});
+
+const existing = registry.get('action', 'createContent');
+const allActions = registry.find({ target: 'contentActions' });
+registry.remove('action', 'myAction');
+```
+
+### Registration timing
+
+```javascript
+import { registry } from '@jahia/ui-extender';
+import register from './myModule.register';
+
+export default function () {
+    registry.add('callback', 'myModule', {
+        targets: ['jahiaApp-init:50'],
+        callback: register
+    });
+}
+```
+
+### Common registry types
+
+| Type | Purpose |
+|------|---------|
+| `action` | UI action in menus, headers, or toolbars |
+| `selectorType` | Custom field input in Content Editor |
+| `adminRoute` | Admin panel page |
+| `route` | Custom top-level route |
+| `primary-nav-item` | Top-level navigation entry |
+| `accordionItem` | Secondary navigation accordion in jContent |
+| `callback` | Initialization callback |
+
+---
+
+## 3. Content Editor JSON overrides
+
+### File location
+
+```
+src/main/resources/META-INF/jahia-content-editor-forms/
+    forms/          # Form-level overrides (by nodetype)
+    fieldsets/      # Fieldset-level overrides (by mixin or type)
+```
+
+Naming convention: replace `:` with `_` — `jnt:article` → `jnt_article.json`
+
+### Form override structure
+
+```json
+{
+  "nodeType": "myns:myContent",
+  "priority": 2.0,
+  "hasPreview": true,
+  "sections": [
+    {
+      "name": "content",
+      "fieldSets": [
+        {
+          "name": "<main>",
+          "rank": 1.0,
+          "fields": [
+            {
+              "name": "jcr:title",
+              "declaringNodeType": "mix:title",
+              "rank": 1.0,
+              "labelKey": "myModule:label.title"
+            },
+            {
+              "name": "myProp",
+              "hide": false,
+              "mandatory": true
+            }
+          ]
+        }
+      ]
+    },
+    { "name": "classification", "hide": true },
+    { "name": "layout", "hide": true }
+  ]
+}
+```
+
+### Key override actions
+
+| Goal | JSON |
+|------|------|
+| Hide a section | `{"name": "layout", "hide": true}` |
+| Hide a field | In field: `"hide": true` |
+| Make a field mandatory | In field: `"mandatory": true` |
+| Reorder a field | In field: `"rank": 3.0` |
+| Change a field label | In field: `"labelKey": "basename:myKey"` |
+
+### `declaringNodeType` requirement
+
+Use when the field comes from a mixin or parent type:
+
+```json
+{
+  "name": "j:invalidLanguages",
+  "declaringNodeType": "jmix:i18n",
+  "hide": false
+}
+```
+
+### Known limitations
+
+- `multiple` and `i18n` properties CANNOT be overridden by JSON
+- `valueConstraints` for choicelists can only remove existing items, not add new ones
+
+---
+
+## 4. jContent UI extension points
+
+### Adding an accordion
+
+```javascript
+const baseAccordion = registry.get('accordionItem', 'pages');
+registry.add('accordionItem', 'myCustomAccordion', baseAccordion, {
+    targets: ['jcontent:99'],
+    label: 'myModule:accordion.label',
+    rootPath: '/sites/{site}/contents/my-section',
+    requiredSitePermission: 'myCustomPermission',
+    isEnabled: (siteKey) => siteKey !== 'systemsite',
+    treeConfig: Object.assign({}, baseAccordion.treeConfig, { hideRoot: false })
+});
+```
+
+**Important:** Always use `Object.assign({}, base.nestedObj, {...})` when overriding nested config objects.
+
+---
+
+## 5. Adding UI actions
+
+### Available action targets
+
+| Target | Location |
+|--------|----------|
+| `contentItemContextActions` | Right-click menu on content items |
+| `contentItemActions` | Three-dot menu on content items |
+| `browseControlBar` | Three-dot menu in header |
+| `headerPrimaryActions` | Header primary action buttons |
+| `selectedContentActions` | Actions for selected content |
+| `publishMenu` | Publish dropdown menu items |
+
+### Registering an action
+
+```javascript
+registry.add('action', 'myCustomAction', {
+    buttonLabel: 'myModule:actions.myAction.label',
+    targets: ['contentItemActions:5', 'contentItemContextActions:5'],
+    showOnNodeTypes: ['jnt:article', 'jnt:page'],
+    requiredPermission: ['jcr:modifyProperties'],
+    onClick: ({ path, paths, client, notificationContext }) => {
+        console.log('Action on:', path);
+    }
+});
+```
+
+---
+
+## 6. Adding settings pages (admin routes)
+
+```javascript
+registry.add('adminRoute', 'mySettings', {
+    targets: ['administration-sites:50'],
+    requiredPermission: 'adminTemplates',
+    label: 'myModule:settings.label',
+    isSelectable: true,
+    render: () => <MySettingsPage/>
+});
+```
+
+### iFrame-based admin route
+
+```javascript
+registry.add('adminRoute', 'myLegacySettings', {
+    targets: ['administration-server-systemComponents:10'],
+    requiredPermission: 'adminTemplates',
+    label: 'myModule:legacy.label',
+    isSelectable: true,
+    iframeUrl: window.contextJsParameters.contextPath +
+        '/cms/adminframe/default/$lang/settings.myLegacyPage.html?redirect=false'
+});
+```
+
+### Administration target groups
+
+| Target group | Description |
+|-------------|-------------|
+| `administration-server-usersAndRoles` | Server > Users and Roles |
+| `administration-server-systemComponents` | Server > System Components |
+| `administration-sites` | Sites section |
+
+---
+
+## 7. Custom selector types
+
+```javascript
+registry.add('selectorType', 'MyColorPicker', {
+    targets: ['BuiltInTypes:10'],
+    cmp: MyColorPickerComponent,
+    supportedTypes: ['String'],
+});
+```
+
+Reference in CND:
+```cnd
+- myColor (string, MyColorPicker)
+```
+
+---
+
+## 8. Custom picker configuration
+
+```javascript
+registry.add('pickerConfig', 'myPicker', {
+    accordionItem: 'pages',
+    searchSelectorType: ['jnt:article', 'jnt:page'],
+    selectableTypes: ['jnt:article'],
+    openableTypes: ['jnt:page', 'jnt:contentFolder']
+});
+```
+
+Reference in CND:
+```cnd
+- relatedArticle (weakreference, picker[type='myPicker'])
+```
+
+---
+
+## 9. Dynamic forms in Content Editor
+
+Implement `DynamicFieldSetExtractor` for server-side dynamic forms:
+
+```java
+@Component(service = DynamicFieldSetExtractor.class)
+public class MyDynamicExtractor implements DynamicFieldSetExtractor {
+
+    @Override
+    public Set<String> getExtendedNodeTypesToFill(JCRNodeWrapper node,
+            ExtendedNodeType primaryNodeType, Locale locale, RenderContext ctx) {
+        String category = node.getPropertyAsString("myCategory");
+        if ("premium".equals(category)) {
+            return Collections.singleton("myns:premiumFields");
+        }
+        return Collections.emptySet();
+    }
+}
+```
+
+---
+
+## 10. CKEditor customization
+
+### CKEditor 5 (Jahia 8.2+)
+
+```javascript
+registry.add('ckeditor5Plugin', 'myPlugin', {
+    plugin: MyCKEditorPlugin,
+    config: { toolbar: { items: ['myButton'] } }
+});
+```
+
+### CKEditor 4 (legacy)
+
+Place custom configuration in `src/main/resources/javascript/ckeditor/config.js`.
+
+---
+
+## 11. Debugging JSON overrides and registry
+
+### Checking JSON override registration
+
+Look in Jahia startup logs for `StaticDefinitionsRegistry` entries:
+```
+INFO  [StaticDefinitionsRegistry] - Successfully loaded static form for name myns:myContent
+```
+
+### Querying the generated form via GraphQL
+
+```graphql
+{
+  forms {
+    editForm(uiLocale: "en", locale: "en", uuidOrPath: "/sites/mySite/home/myContent") {
+      sections {
+        name
+        fieldSets { name fields { name selectorType mandatory hide } }
+      }
+    }
+  }
+}
+```
+
+### Inspecting the component registry in browser console
+
+```javascript
+window.jahia.uiExtender.registry.find({ type: 'action' });
+window.jahia.uiExtender.registry.get('accordionItem', 'pages');
+window.jahia.uiExtender.registry.find({ target: 'contentItemActions' });
+```