Riverlea - add Stream entity and previewer #32127
Conversation
|
🤖 Thank you for contributing to CiviCRM! ❤️ We will need to test and review this PR. 👷 Introduction for new contributors...
Quick links for reviewers...
|
|
(Just a note, if testing locally on a pre-existing site you will need to uninstall and then reinstall Riverlea in order to create the DB table) |
|
I'm not in a position (skills-wise) to comment on the code changes here - I can't comment on other consequences they might have. I can only really look at this from a product perspective: Firstly a previewer is definitely really nice - ThemeTest would benefit from that (I spend quantifiable time moving back and forth from Display Setting). But this is more than that… At present:
With this proposal:
And the benefit of all of this change is the previewer? Or Something else ("paves the way for future UI to a) pick a stream based on what it looks like on your site" - ie in a realtime preview?). Side point: as RiverLea flows towards the big C of Civi Core - maybe it's name makes less and less sense? It's no longer a theme like Greenwich and more Civi's theme engine. So maybe - at least if it becomes an entity in core, its name should be something generic like CRMThemer, or at least more generic like 'river' (as river -> stream, is helpful naming to emphasise the cascade order of css). |
|
Hey @vingle With this approach I see two ways to make new streams:
The only advantage implemented in this PR is the previewer. But it's a fairly small step from here to:
|
So all of a stream's custom css (variables, darkmode versions) would be stored within the Entity? If I store it in Git, someone else changes a bunch of variables, can I get that back into my system? Presumably any part of the entity can be edited?
That'd be cool. I created an empty SubTheme extension at the end of last year which I think still works - I just made it public: https://github.com/vingle/branch with a Stream called 'Albany'. Might need a tiny bit more testing/docs before becomming a template. I used the name 'branch' as that seems like a subsidiary water-system from a stream. But obvs branches have other meanings on git so perhaps another name works (I thought about 'estuary', 'tributary', 'source', 'channel', 'canal', 'brook' - branch seems the most accurate, but probably confusing).
That's interesting - maybe overlaps with the oembed stuff… ie for the example of someone creating a 'join newsletter' or 'petition' widget they want to embed on a dozen different sites, each with a different font and bg-colour… then giving each embed some unique class could let you save a unique variable… ie |
The standard way managed entities work is you a file version (which can be checked in to git). Then you have a database (database) version. These start in sync. If you make edits to the database version (using the UI), you then have the option to a) export them - ie make the same changes to the file version; b) revert the database changes, go back to the file version. If you make edits to the file version they will generally be synced to your database version (unless that has local changes - which you might not want to lose. In that case you have the option to revert to the file version to get the latest changes from the file.)
https://lab.civicrm.org/ufundo/river_rea/-/tree/dev . I called it river_rea which is obviously way too close to River Lea 🤦
My thinking was that we don't need to create another hierarchy, and we should use stream for all the variations within River Lea. A stream = River Lea Theme = super easy to maintain theme. (I've started seeing it the other way round, the stream is the little drops of ink you add to the river at the beginning, and then the river takes that and spreads it all over the UI :))
I think this approach would lend itself to adding a url parameter ie. https://mycivi.com/contribution-page?stream=my_blue_stream and https://mycivi.com/contribution-page?stream=my_green_stream which then loads the appropriate vars on that page (without having to add css classes programmatically, which would be hard I think). |
|
My thinking was that we don't need to create another hierarchy, and we should use stream for all the variations within River Lea. A stream = River Lea Theme = super easy to maintain theme.
Fair point.
(I've started seeing it the other way round, the stream is the little drops of ink you add to the river at the beginning, and then the river takes that and spreads it all over the UI :))
Nooooh! 😅 as the ‘crm-c-text’ variable / drop flows from the River source, it first takes one colour from core, then as it branches into one Stream it takes a different colour, while in a second Stream no new variable/drop is defined so it stays the same (ie the order has to follow the cascade..)
(without having to add css classes programmatically, which would be hard I think).
That makes sense
|
|
Further possibility with this kind of model: automating contrast checks between vars we know need to contrast. IE messages in the editor like "your crm-c-primary and crm-c-primary-text currently have contrast rating 5:1 which meets AA but you should increase for AAA" |
Sold! |
|
https://lab.civicrm.org/extensions/deptfordcreek/-/merge_requests/1 demonstrates the change in what "external streams" would look like before/after the core change. The "external stream" could also put all it's var in the Managed file, and not have any separate css files. |
|
I think we need thel change to |
Overview
Move the Stream definitions in Riverlea from hard-coded to a new entity.
This enables a "Previewer" which allows you to switch streams locally, without changing the site settings.
Paves the way for future UI to a) pick a stream based on what it looks like on your site; b) editing and creating custom streams through the UI (AKA "Customiser").
Before
riverlea.phpAfter
CRM.riverlea.previewer()to open a previewer widget, which allows you to switch between streams on the flycustom_css, which allows for easy adding fixes. these are then cached via assetbuilder (essentially using the stream name and last modified as key) which overcomes the performance concerns with previous attempt at Customiservarsdefined using php, which could then be validated/updated automatically etcScreencast.from.2025-02-18.14-27-34.mp4
(note all previewer changes are on the frontend and local to your current session - the site theme setting isn't touched. It does require starting with a Riverlea theme selected)
Work in progress
Need to add upgrader to create the new table on existing installs. I think this goes in the core upgrade step for core extensions?
Would be good to get some feedback on how it's working / overall schema.
Known Limitation
civicrm.cssoverride in Thames and Walbrook (it can only switch the var values on the fly). At this stage it's a dev tool, so I think it's reasonable. (I also think the overrides in Thames and Walbrook don't need to be incivicrm.css- they could be moved into the stream specific css file)river.csswill only track changes to the entity, but if you usecss_fileand modify the file it won't necessarily know. Again, I think this is reasonable. It's not expected to edit css files directly in production - and you (will soon) be able to editcustom_csson the entity if you need to.Technical Details
<civi-riverlea-previewer>. I'm not sure how we feel about these but I think it's very nice for a self contained component that can use the API and talk to the browser.