Riverlea - add stream preview/edit to admin page

[ufundo]

Overview

Add stream listing/previewing/editing to the Riverlea settings page. Rename the page "Theme Settings"

Before

• No way to edit preview or edit streams through the UI
• Confusing settings UX: you set the Theme on the Display Settings page, but some other theme related things are on the Riverlea Settings page (where non-devs will never find them)
• You have to change the theme for everyone on your whole site to see what it looks like

After

• Unified page where you can manage your themes.
• You can still set the theme on Display Settings page for now (though I would suggest replacing that with a link to the new page in future)
• Ability to clone and then edit the four base theme
• The base themes are NOT editable
• You can preview themes before you select them

Technical Details

The stream list, preview and editor are built with WebComponents. Some of the loading and templating could be streamlined if/when #34325 is merged.

Old Description

This builds on #32127 to add a UI for previewing and editing Riverlea streams.

It's not ready for merging but the idea is to demonstrate the point of adding the entity in #32127 and get feedback on a) how it looks; b) the technical approach.

Before

• streams are hard coded things

After

• streams are db entities
• listing of streams at civicrm/admin/riverlea/streams
• base streams are not editable
• you can clone the base streams or add a blank stream in order to edit it

Technical Details

It's WebComponents again. This seems quite a good place to test them because a) there's opportunity for various bits of interaction between the components in this PR; but b) there probably quite self-contained and won't need to interact with anything outside of this PR.

The stream list also component also I think demonstrates how a WebComponent search kit listing might work.

Comments

@vingle would you be able to take a look? There's no upgrader for the entity included here so on the test site is probably best.

[civibot]

🤖 Thank you for contributing to CiviCRM! ❤️ We will need to test and review this PR. 👷

Introduction for new contributors...

• If this is your first PR, an admin will greenlight automated testing with the command ok to test or add to whitelist.
• A series of tests will automatically run. You can see the results at the bottom of this page (if there are any problems, it will include a link to see what went wrong).
• A demo site will be built where anyone can try out a version of CiviCRM that includes your changes.
• If this process needs to be repeated, an admin will issue the command test this please to rerun tests and build a new demo site.
• Before this PR can be merged, it needs to be reviewed. Please keep in mind that reviewers are volunteers, and their response time can vary from a few hours to a few weeks depending on their availability and their knowledge of this particular part of CiviCRM.
• A great way to speed up this process is to "trade reviews" with someone - find an open PR that you feel able to review, and leave a comment like "I'm reviewing this now, could you please review mine?" (include a link to yours). You don't have to wait for a response to get started (and you don't have to stop at one!) the more you review, the faster this process goes for everyone 😄
• To ensure that you are credited properly in the final release notes, please add yourself to contributor-key.yml
• For more information about contributing, see CONTRIBUTING.md.

Quick links for reviewers...

• ➡️ PR Demo site (can be rebuilt with the command test this please).
• 📖 Review standards
• 🗒️ Review template (brief or verbose)

➡️ Online demo of this PR 🔗

[ufundo]

Ok, there was some teething on Drupal (and the list is a bit squished).

But demo should be working now here: http://core-32344-987dd.test-1.civicrm.org:8003/civicrm/admin/riverlea/streams

[vingle]

This is really impressive @ufundo. The one-click preview alone is huge!

I've only time for a quick explore this week. I'd perhaps separate test / discussion around the follow areas:

• the code itself, which I can't review. Is the stream stored in the dbse as JSON? And is that what's ouptuted in the 'details'?
• the UX/UI, which I can… I'd be tempted for more of an extensions manager list+details+buttons table-ish list UI than two-column grid. Could still be a web component for each table row (?) as it's nice you're using that. We want something that both survives all changes, but also reflects them to help illustrate, a nice design challenge. Happy to have a go on a branch…
• what can be customised… (I like your choices but would prob add primary hover, unless we swap that for a tint - and the backgrounds are a bit misleading without simplifying how RL core handles backgrounds). I'm assuming 'new streams' are built on core variables, ie Minetta?
• how this interacts with dark mode… I love that you can edit dark mode colours.. ie if I clone Hackney I get Hackney's Dark mode? And if I make a new stream I get none? Or Minetta's? Obvs is theme settings is forcing light mode, this doesn't fully work - might need some text around that.
• test how this interacts with all the CMSs and most popular admin themes
• add some 'test this before you make it public text' to the enable on front-end pages button. Also I really need a RiverLea 'crm-buttons' flex wrapper to add gap to button groups!

And then the big questions/tests

• what happens to custom streams when underlying RL core or RL streams change?
• can people enter custom css or values that break anything. Or that force something that requires RiverLea to not change in the future without breaking (e.g. it locks font-size to rems and colour to rgba which sounds ok?)
• is the cascade order of the custom stream consistent across all CMSs front and back-end? Triggered by a recent Drupal 10.4/11.1 upgrade that changed the cascade order between custom themes and contributed themes and broke a bunch of sites…
• if someone sets text and bg to white, or font-size to 0 or adds .crm-container {display: none'} is there a safe exit/reset mode and does that always work?
• are the permissions to limit access to this screen sufficient / absolute? I think the worst case security risk is changing form labels with css to get people to enter, say, passwords or credit cards in plain text fields.. maybe more of an issue if this is to be used in combination with the iframe/oembed.

[vingle]

If you add crm-buttons here then the buttons will have a gap between them…

(sidenote I need strip the margin on the buttons when that starts to wrap)

[ufundo]

Makes sense

[vingle]

also would help here:

[vingle]

An alternative UI approach to a table like the extensions screen would be panel panel-info with panel-heading, panel-body and panel-footer… and then full-width. something like this (with added crm-accordion-settings to the details & a summary):

[ufundo]

Do you have a particular problem with the responsive grid @vingle ?

For me it seems much preferable if you might have a lot of entries and you have a nice wide screen. If they are fixed to fullwidth then they can become very very wide, and unnecessarily push later items below the fold.

[ufundo]

extensions manager list+details+buttons table-ish list UI than two-column grid

Just noting it should be responsive columns rather than fixed at 2. Unless I broke it somehow.

Personally I'd prefer the extensions list to work this way also... I think it is a commonly preferred layout for in app/plug-in library type things?

[ufundo]

Just noting this will need updating for changes to variable names in master.

[vingle]

@ufundo – it's more I don't like introducing new UX patterns with every new feature - it's not such good UX. My first choice would be make it look like the Extensions table. Second choice, SearchKit or FormBuilder. Third choice like ThemeTest. Am sure there's other UX's we could borrow.

[ufundo]

Right I see what you mean. You can create grid displays like this in SearchKit already - though the responsivity options need a bit of work, and hasn't been used for any core screens yet. Something got to be the first one?

[vingle]

@ufundo - it's tricky because Civi doesn't have a pattern library. But it should because Civi has a mountain of patterns, all introduced with new functions like this! I guess the central question is - what does your layout add that other existing layouts don't offer? ie why is a new pattern needed?

You need to be able to have two highlight border / bg colours simultaneously, but other than that this seems well-served by a tabular Civi layout with inline buttons? The extensions table in particular has details/summary expand region and three shades of coloured background. The design I sketched is similar to ThemeTest as I'm guessing themers might use both, but better imho would be to use a more common UX like Extensions table.

(NB - I'm not trying to be a blocker here, design is obvs subjective. Just flagging the UX principle of re-using patterns as much as possible to make life easier for users - who gradually, subconsciously learn how they should behave around each pattern, and have to start from scratch with each new pattern they encounter).

[ufundo]

@vingle I added those panel classes and crm-buttons but kept it as a grid... it looks nice I think!

Screencast.from.2025-06-16.17-35-47.mp4

Definitely still needs some thinking about which variables to expose first... and how they can automatically cascade.

[ufundo]

( test site page: http://core-32344-4x7n9sa.test-1.civicrm.org:8003/civicrm/admin/riverlea/streams )

[colemanw]

@ufundo this is too cool to let go stale. Would you be able to rebase?

[ufundo]

It's cool but a bit premature - waiting for the current batch of variable renames before rebasing.

[vingle]

They got merged today! #33802

[mlutfy]

@ufundo Would this be a good time to rebase?

I was curious to see if this patch still works. I managed to somewhat get it to work:

https://github.com/civicrm/civicrm-core/compare/master...mlutfy:civicrm-core:pr32344test?expand=1

There are two lines of code that I had to comment because the functions didn't exist. I probably missed a piece of a patch. The live preview does not work, but the rest seems to work:

ext/riverlea/js/stream-list.js:      const previewSession = null; // [ML]FIXME CRM.riverlea.previewSession();
ext/riverlea/js/editor.js:      // [ML]FIXME framePreview.render(this.unsavedData);

I also renamed a few RiverLea variables that have been changed recently, but not all of them.

[ufundo]

@mlutfy I've had a go rebasing this.

I've also tried to make the display of the currently selected themes clearer.

In light of discussion on Riverlea docs MR I've moved the theme list to "/civicrm/admin/theme" and combined with the other theme settings.

[ufundo]

Outstanding:

• restore the nice + safe options for font sizes
• sort out how editing colours interacts with dark mode

[vingle]

has changed to:

civi-riverlea-stream-card .btn.btn-stream-selected {
  background-color: var(--crm-success-color);
  color: var(--crm-success-text-color);
}
civi-riverlea-stream-card .btn.btn-set-preview.btn-stream-selected {
  background-color: var(--crm-warning-color);
  color: var(--crm-warning-text-color);
}

[ufundo]

ah good catch thanks @vingle

[vingle]

border: var(--crm-border); would get rid of the default iframe 2px shaded border.

[ufundo]

👍

[vingle]

Cool!

is very nice.

At one point I think you styled .is-set-preview with a border to indiciate it's the current preview? Something like .is-set-preview .panel { --crm-panel-border: 1px solid var(--crm-warning-color); } might be helpful:

The edit screen is a bit messy, but that's mostly down to the theme's handling of fieldsets, while the flexbox needs the --crm-flex-gap variable on it, but it impacts too many layouts to just add that to _base.css (.crm-flex-gap utility maybe to add it?).

Could maybe benefit from an info popup on the border radius input to explain it's rems, and restore the font-size input info ("For systems where 1rem = 16px (which is the default in all browsers) these sizes represent: Smallest 12px, Small 14px, Default 16px, Big 18px, Bigger 24px.")

[mlutfy]

Very cool!

Could the checkbox be a toggle?

pr32344-1.webm

diff --git a/ext/riverlea/js/editor.js b/ext/riverlea/js/editor.js
index 91873062d7..56684325b0 100644
--- a/ext/riverlea/js/editor.js
+++ b/ext/riverlea/js/editor.js
@@ -120,7 +120,7 @@
       inputContainer.innerHTML = `
         <h2>${this.data.label}</h2>
 
-        <label class="civi-riverlea-stream-dark-toggle"></label>
+        <label class="civi-riverlea-stream-dark-toggle crm-form-toggle-container">${ ts('Edit dark mode') }</label>
 
         <fieldset class="civi-riverlea-stream-meta-inputs"></fieldset>
 
@@ -134,9 +134,9 @@
         <fieldset class="civi-riverlea-stream-custom-inputs"></fieldset>
       `;
 
-      inputContainer.querySelector('.civi-riverlea-stream-dark-toggle').innerText = ts('Edit dark mode');
       const darkModeToggle = document.createElement('input');
       darkModeToggle.type = 'checkbox';
+      darkModeToggle.className = 'crm-form-toggle';
       darkModeToggle.checked = (this.darkMode === 'dark');
       darkModeToggle.onchange = () => {
         this.darkMode = darkModeToggle.checked ? 'dark' : 'light';

and a minor issue: when the public theme is using the "default" option, the "current frontend theme" shows as empty:

but I'm not sure what else to propose, and could definitely be a "fix later" issue.

[ufundo]

At one point I think you styled .is-set-preview with a border to indiciate it's the current preview?

I took it out because I thought it was a bit messy. There were borders for currently selected too. Positioning them at the top works much better I think, but have restored the border for the preview.

The edit screen is a bit messy

Yeh neatened it up a bit now

Could maybe benefit from an info popup on the border radius input to explain it's rems, and restore the font-size input info ("For systems where 1rem = 16px (which is the default in all browsers) these sizes represent: Smallest 12px, Small 14px, Default 16px, Big 18px, Bigger 24px.")

Does this really add anything, when you can see what these do on the screen in front of you instantly?

Could the checkbox be a toggle?

Yes!

and a minor issue: when the public theme is using the "default" option, the "current frontend theme" shows as empty:

Added more graceful handling for this.

[mlutfy]

Excellent, thanks for improving!

@vingle @colemanw This looks merge-ready to me. Any objections?

[vingle]

Does this really add anything, when you can see what these do on the screen in front of you instantly?

@ufundo - border-radius, unlike say font size, still often make sense to be, 3px, or 50%. So knowing the unit is 'rem' is useful - but it could go in parenthesis in the label. For the font sizes - I'd also find it useful if I'm trying to match a front-end layout with an existing front-end theme to know that 'large' is 24px, etc. But agree this info maybe won't be useful to many users.

But I wouldn't call that a blocker on merging this.

[mlutfy]

Thank you @ufundo @vingle !