Skip to main content
Version: 3.x

On-Screen Help

Version
3.x
Updated
View markdown

How to make the admin's on-screen help describe your installation: amend or replace the note on any screen, add your own articles in a Customizations section of the guide, and shadow a shipped article entirely. Nothing here touches core, and none of it is overwritten by an update.

This is the counterpart to the fields you add. A heavily customized product or question form is only half-delivered if the help drawer still describes the stock screen.

Read com_configbox_customization_overview.md first. All paths are relative to the customization directory, KenedoPlatform::p()->getDirCustomization() — Joomla data/customization/, WordPress the separate customization plugin, Magento the ConfigboxCustomizations module.

1. Where it goes​

Everything lives under one folder, help/, whose layout mirrors the guide's — so there is no second convention to learn:

<customization>/help/
    _screens/
        adminquestions.md          amend or replace that screen's note
        img/
            our-fields.png         images for screen notes
    customizations/
        _category_.json            the section's label and position
        README.md                  its landing page
        our-workflow.md            your own articles
        img/
            workflow.png
    settings/
        tour-the-settings-sections.md    SHADOWS the shipped article at that path
        img/
            our-settings.png

Three capabilities, one folder:

You want to…Put a file atResult
Add to a screen's helphelp/_screens/<controller>.mdAppended below the shipped note
Replace a screen's helpthe same, with mode: replaceYours instead of the shipped note
Add your own articleshelp/customizations/*.mdA Customizations section in the guide
Take over a shipped articlehelp/<system>/<same-filename>.mdYours is served; core's is not

Images live with the content that uses them. A customization file's images resolve against the customization directory, so ![](img/our-fields.png) in help/_screens/adminquestions.md means help/_screens/img/our-fields.png. You never reference the component's folders, and the component never reaches into yours.

2. Amending a screen note​

The help drawer shows a short screen note above the linked article. To document fields you added, drop a file named after the screen's controller:

<!-- <customization>/help/_screens/adminquestions.md -->

## Fields added by this project

- **Minimum width (mm)** — refuses a configuration narrower than this. Leave empty for no minimum.
- **Cut-length warning** — shows the customer an advisory when a part would be under 250 mm.

![The added fields](img/our-fields.png)

That is the whole file. No front matter is needed — the default is to append, which is what you almost always want: the shipped note is still true, you are adding to it.

The appended block is wrapped in .cb-help-note-customization, so a site that wants it to read as one voice with the shipped note can style or hide it.

Replacing instead​

When the screen has been reworked enough that the shipped note is misleading:

---
mode: replace
title: Questions (this store)
---

Our question forms differ from stock CBX — start with the workflow article.

mode: replace drops the shipped note entirely. title and article override the shipped values where you set them, so you can retitle the screen or point its "read more" at your own article.

Prefer append. A replaced note is a copy of core's that will rot: the next CBX version improves the shipped note and your replacement silently keeps the old story. Replace only when the shipped note is actually wrong for your install.

Which filename?​

The screen's controller name — adminquestions, adminproducts, adminconfig. A form view (adminproduct) shares its controller's note, exactly as core notes do, and you can also name the view specifically if you want a note on the form but not the list.

You can also document a screen core says nothing about; your note then stands alone.

3. Your own section: customizations/​

Anything in help/customizations/ becomes a section of the guide, listed beside Products, Pricing and the rest, and included in the help area's search.

// <customization>/help/customizations/_category_.json
{ "label": "Acme customizations", "position": 50 }

position orders it against the shipped sections (they run 1–8, so a high number puts yours last; omit it and it sorts after them anyway). Articles use the same front matter as the guide:

---
sidebar_label: Our order workflow
sidebar_position: 2
description: How orders move through Acme's approval steps.
---

# Our order workflow

Orders here pass an approval step before they are released...

![The approval panel](img/approval.png)

README.md becomes the section's landing page. Write these the way the shipped guide is written — the authoring standard in docs/admin-guide/_authoring-standard.md applies, and it is also exactly the construct set the in-admin renderer supports.

Link a screen at one of your articles by naming it in the screen note's front matter:

---
article: customizations/our-order-workflow.md
---

4. Shadowing a shipped article​

Put a file at the same path a shipped article uses and yours is served instead:

<customization>/help/settings/tour-the-settings-sections.md

The guide still lists one article at that path — yours. Its images resolve against your directory, and it is indexed for search in place of the original.

This is the sharpest tool here. A shadowed article no longer benefits from anything CBX improves in it, and nothing announces that to the reader. Shadow when the shipped article is actively wrong for your install; otherwise a customizations/ article that links to the shipped one ages far better.

5. Deployment checklist​

  1. Create <customization>/help/ and the files you need.
  2. Put images in an img/ folder beside the file that uses them.
  3. Open the screen in the admin and check the drawer; open Help in the CBX menu for the section and article views.
  4. Search the help area for a phrase from your article — new articles are indexed automatically.

No cache clear, no registration, no database entry: the files are read at request time.

6. Gotchas​

  • Append is the default; mode: replace is opt-in. A note with no front matter appends.
  • Only .md files are served, and only from inside help/ — paths are resolved with realpath() and anything escaping the folder is refused. Help paths arrive from request variables, so this matters.
  • Images belong to their own layer. A customization file cannot reference the component's images with a relative path, and does not need to: keep your own in your img/ folders.
  • The renderer is the guide's, not Markdown at large. Headings, paragraphs, lists, tables, blockquotes, fenced code, images, emphasis, inline code and relative links. No inline HTML.
  • Shadowing hides core silently. Nothing warns the reader that they are not seeing the shipped article — see §4.
  • A replaced note loses core's front matter unless you restate it: if the shipped note pointed at an article and yours does not, that link disappears.

See also​

  • com_configbox_customization_overview.md — the layer, and where it lives per platform
  • com_configbox_custom_properties.md — the fields you are documenting
  • com_configbox_language_overrides.md — changing shipped text rather than adding help
  • docs/admin-guide/_authoring-standard.md — how the shipped guide is written, and the construct set the in-admin renderer supports (underscore-prefixed, so it is not published to the docs site)
Last updated on