1. What This Feature Does
Layout Editor admins can now restrict certain blocks (Module Table blocks and a specific list of reference blocks) so they only appear for records of selected module versions. For example, the Medication block can be configured to show only when a PreAssessment record's version is set to KIPU; the Treatment History block can be set to show for ASAM and KIPU but hidden for UR, and so on.
The visibility rule is enforced on three surfaces:
Edit View — blocks show/hide dynamically as the user changes the version field.
Detail View — restricted blocks return empty content for non-matching versions.
PDF Export — restricted blocks are removed from the PDF before it renders.
💡 Note: A block with no version assignment behaves as before — always visible. The feature is fully backwards-compatible: existing layouts continue to work without any setup.
2. Scope — Which Blocks Support Versions
Version assignment is intentionally limited to a small, well-defined set of blocks. Regular blocks like Patient Information or Basic Information do NOT show the Versions dropdown.
Eligible blocks:
Any Module Table block (a block backed by a custom sub-table — they have a small "ref block" indicator in Layout Editor).
Reference blocks with these specific labels:
Block Label |
Substances of Abuse |
Treatment History |
Medication |
Related Contacts |
Insurance Policies |
Travel Record |
Spend Tracking |
⚠️ Important: If you do not see the Versions dropdown on a block, that block is not eligible. Other blocks remain unrestricted and are always visible regardless of the record's version.
3. Prerequisites
Before configuring version-based visibility on any block:
You must be signed in as an Administrator.
The module must have a Module Type / version field defined (the field whose value drives visibility — e.g., the "Type" field on PreAssessments holding ASAM / KIPU / UR / etc.).
At least one version value must exist in that field's picklist for the dropdown to be useful.
💡 Tip: On modules that do NOT have a Module Type field configured, the Versions dropdown will not appear in Layout Editor at all. Talk to your developer if you need a version field added to a module.
4. Assigning Versions to a Block
4.1 Open Layout Editor
Sign in as an Administrator.
Go to Settings → CRM Settings → Module Management → Module layout & Fields.
Select the module you want to configure (e.g., PreAssessments).
Scroll to the eligible block (e.g., Treatment History) — see Section 2 for the list.
4.2 Open the Versions Dropdown
5. Look at the right-hand side of the block header. You will see a small "Versions" button with a count badge.
6. The badge shows: a number for "N versions selected" or the word "All" when no version restriction is set.
7. Click the Versions button to open the dropdown.
The dropdown contains:
A search box at the top — useful when there are many versions.
Pills (one per version value) — click to toggle that version on or off for this block.
A note at the bottom: "No selection = visible for all versions" (shown only when no pills are active).
4.3 Toggle a Version Pill
8. Click a pill to add the version. The dropdown closes immediately.
9. A confirmation dialog appears:
"Adding version <X> will restrict this block to the selected version(s). Records with other versions will not see this block. Do you want to continue?"
Click Yes to apply, No to cancel.
On Yes — the pill turns active (filled), the badge updates, and the block is saved.
Removing a version works the same way — click an active pill, confirm the prompt, and the version is removed. The confirmation prompt for removal reads:
"Removing version <X> means this block will no longer be shown for that version. Do you want to continue?"
4.4 Search the Version List
When a module has many versions, type into the search box at the top of the dropdown. Matching pills stay visible; non-matching pills are hidden until you clear the search. Closing the dropdown automatically clears the search.
5. Visual Feedback — Which Blocks Will Be Hidden?
To preview which blocks a record of a specific version would see, use the version picklist at the top of the Layout Editor.
5.1 Block Dimming
Pick a version from the picklist at the top of the page.
Any eligible block whose Versions assignment does NOT include that picklist value is dimmed — shown with diagonal stripes and reduced opacity.
A small badge in the top-right of the dimmed block reads: "Hidden for selected version".
You can still click on a dimmed block and adjust its Versions assignment — the dimming is visual-only.
💡 Tip: Use this to sanity-check your configuration before saving. Switch through ASAM → KIPU → UR in the picklist and confirm the right blocks dim/un-dim for each version.
5.2 Reset to "All Versions"
Set the picklist back to its empty/default state to remove all dimming.
Or remove all version pills from a block — the block will show normally for every record version.
6. Copy and Move — Between Versions
When you copy or move a layout from one version to another (the standard Copy/Move feature in Layout Editor), block version assignments are now propagated automatically alongside fields and layout positions.
6.1 Copy Layout
Copies fields, layout, AND block-level version assignments from the source version to the target version.
A block currently assigned to ASAM will gain the target version after the copy, retaining ASAM as well.
Existing assignments on the target version's blocks are preserved.
6.2 Move Layout
Same propagation rules as Copy, but the block ends up only on the new version.
6.3 "Apply All" Mode
When the Apply All option is checked during a copy, every block with any non-empty version assignment is updated to also include the source version on the target picklist. This mirrors the existing per-field Apply All behaviour.
⚠️ Note: If the block-level update fails for any reason during Copy/Move, the field-level and layout-level updates that already succeeded are NOT rolled back. Each layer is independent — partial success is preferred over complete failure.
7. What End Users See
Once you have assigned versions to a block, here is what users see when working with records.
7.1 Edit View
When a user opens the Edit form of a record, only blocks compatible with the current version field value are shown.
In the above screenshot, I observed that the Related Contact and Treatment History blocks are hidden, and the Substance of Abuse block is displayed.
7.2 Detail View
Hidden blocks return empty content — they don't render at all.
Compatible blocks render normally with their data.
7.3 PDF Export
When the user generates a PDF, version-restricted blocks are filtered out before the PDF is built.
The PDF only contains the blocks compatible with the record's version, plus all unrestricted blocks.
8. Troubleshooting
Problem: I expected a block to be hidden for ASAM but it still shows.
Verify the block has at least one Version pill active and ASAM is NOT one of them.
Verify the record's version field actually equals "ASAM" (exact case-sensitive match).
Verify the block is in the eligible list (Section 2). Regular blocks are always shown.
Refresh the user's browser (Ctrl+F5) — older cached scripts may not run the visibility filter.
Problem: The Medication block is empty / not loading.
Should be fixed in the latest commit (CRM-2921). The block now uses the same AJAX loader pattern as Treatment History and Substances of Abuse. If still empty, hard-refresh the detail page and check the browser console (F12) for AJAX errors.
Problem: PDF still includes blocks that should be hidden.
Check the record's version field value at the moment the PDF is generated.
Confirm the Versions pill assignments are correct in Layout Editor.
PDFs render with the stored data — if a record was saved with an old version then version was changed, the new version determines what the PDF shows.
Problem: After Copy / Move Layout, the new layout doesn't carry the version pill assignments.
Confirm the source layout actually had pill assignments (not just empty).
The block-level copy is wrapped in a try/catch — if a database error occurs during the block copy, the field/layout copies will still succeed, but the block versions might not carry over. Re-apply manually if needed.
Problem: Block dimming in Layout Editor doesn't update when I switch the picklist.
Confirm you are switching the picklist at the top of the Layout Editor (the Module Type picklist), not the block-level Versions dropdown.
Refresh the Layout Editor page if dimming gets out of sync.