Docs/UX: clarify Custom Field 'Value' vs 'Default Value' behavior (not rendered/stored the same way in Content Drive)
@dario-daza is already working on this.
Since Jul 29, 2026.
- Dominant language
- Java
- Stars
- 970
- Forks
- 486
- Avg merge
- 3d 33m
- Merged PRs (30d)
- 170
Description
Description
While QA'ing #36736 (Content Drive dynamic "Show in List" columns), it took a full code investigation to understand why a "Custom Field" marked "Show in List" sometimes renders empty and sometimes renders content in the Content Drive table. The UI gives no indication of this behavior, and there's no documentation covering it. This task is to add UI/documentation clarity so future users (QA, admins, developers) don't have to reverse-engineer the code to understand it.
Root cause found (for reference):
A Custom Field has two separate config inputs when added to a Content Type:
- Value (large code editor, bound to
field.values()) — Velocity/HTML source only used when something explicitly evaluates it (e.g. the field's iframe/component widget in the Edit Content screen). It is never copied into a contentlet's actual stored data. - Default Value (small single-line input, bound to
field.defaultValue()) — seeds the actual per-contentlet stored value the first time content of that type is created.
Content Drive (and other list/browse views) only ever displays the raw, already-stored per-contentlet value for a field (contentlet.get(field.variable())) — it never evaluates Velocity. RenderFieldStrategy.renderFieldValue() (dotCMS/src/main/java/com/dotmarketing/portlets/contentlet/transform/strategy/RenderFieldStrategy.java) is the only place that runs VelocityUtil against a field value, and it's gated behind an opt-in TransformOptions.RENDER_FIELDS flag that Content Drive's transform pipeline (BrowserAPIImpl → DotTransformerBuilder.defaultOptions() / .webAssetOptions()) never requests.
Net effect: typing Velocity/HTML only into Value produces nothing visible in Content Drive (or similar list views), which reads as a bug until you understand the Value/Default Value distinction. Neither the field editor UI nor current docs explain this.
Acceptance Criteria
- Content Type field editor: add inline help text/tooltip on the Custom Field "Value" property clarifying that it is Velocity/HTML source evaluated only in specific render contexts (e.g. page/container rendering, iframe widgets) and is not stored per-contentlet or shown in content list/browse views (Content Drive, etc.).
- Content Type field editor: add inline help text/tooltip on the Custom Field "Default Value" property clarifying that this is what seeds the actual per-contentlet stored value shown in list/browse views.
- Public documentation (docs.dotcms.com or equivalent) updated with a short note on Custom Field's Value vs Default Value distinction and where each is/isn't rendered.
- (Optional/nice-to-have) Add a short internal note near
RenderFieldStrategy/TransformOptions.RENDER_FIELDSexplaining which list/browse views intentionally skip Velocity evaluation, to save the next investigator the same reverse-engineering effort.
Priority
Low
Additional Context
- Found while QA'ing #36736 (Content Drive: dynamic table columns from content type "Show In List" fields).
- Related: #36795 (Content Drive: boolean Radio/Select field spacing issue + content type filter not resetting after clear) — filed from the same QA pass.
- This is purely a documentation/UX clarity request — no functional/behavior change is being asked for here.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.