Restructure to use template and component libraries
Closed this issue · 1 comments
Currently the frontend application for DKAN is split into the App and Component repos. If a new site is built using the system it will work with all the upstream repos only if no custom work is done on the site. The problems with current setup begin to appear when custom work is preformed on the site.
Current Build
The app comes with a dataset, search, home, about, and publisher page out of the box. If any of these pages are customized downstream and an upstream change is also made, they will now be out of sync and you can't easily pull in the upstream changes. We have gotten around this some by moving more of the pieces into the component library, so you can just pull in the pieces and put together your pages. This idea has worked well, but as more and more components are added the component library is growing bigger with templates and render components some client sites will never use. This extra bloat while fine now will add up as DKAN grows.
Restructured Build
data-catalog-app
Out of the box this will give a site that should work for most clients, but has very little logic or reusable elements. Once added to a site, there shouldn't be a need to ever pull from the upstream again. Since most builds include a frontend in the src/frontend folder of the DKAN site, this will be an easy place to do all custom work. Things like adding routes, styles, and new one off features.
data-catalog-components
This library should be universal reusable components. Things like React hooks and complicated functions for fetching data or storing state live here. What doesn't live in the library anymore are things like announcements or search list items. These are very subjective to the individual site's design. This library should be lean and very rarely dictate how something should be rendered.
data-catalog-template
This library should contain our rendered components. Things like search list items, tables, search facets and other useful reusable rendered DOM elements. Here we can work on best practices with UX or design to build the best catalog experience.
How does all this solve the current issue?
A default build of DKAN would load the data-catalog-app which has some basic routing in it. Those routes would load a template from data-catalog-templates. The DKAN team would mainly work in data-catalog-templates when fixing bugs at a theming level. Then DKAN sites would be able to test the changes and get the updates by increasing the version in their package.json. The templates would use the data-catalog-components for hooks and complex parts, but if a custom site wanted to do a completely custom design they could still use data-catalog-components to get the functionality but skip any of the additional render components.
What would an upgrade path for this look like?
To make sure we stay as backwards compatible, this isn't going to be a quick change. It's something that should be able to be adopted overtime and give plenty of lead time to make updates to current sites.
data-catalog-app v2.0.0 would no longer have the templates in the code base, they would all live in data-catalog-templates. It will just be an React app with an App.jsx file with routing and some styling.
data-catalog-components v2.0.0 would have all of it's render components moved to data-catalog-templates. It will be mostly React hooks/context components and fetch api classes.
data-catalog-templates v1.0.0 would be a full featured template library that should be able to build most out of the box DKAN sites. As a specific site developer, you should be able to just import a page, component, or section of a site with ease.
As components are moved to the templates library they would be marked for deletion using a console.error in the component letting developers know they should add the new data-catalog-templates library and update their import statements. Only when the 2.0.0 branch of components is released will things be deleted from data-catalog-components.
For the data-catalog-app, it would be a more gradual update that is only moved to v2.0.0 when it is feature complete using the new template library. Since this is built fresh on most new installs the switch to the template library shouldn't be an issue. And for sites that are currently live and have custom code, they wouldn't be pulling the data-catalog-app repo downstream anyways since it would most likely overwrite or break their custom code.
We're going in a different direction with this; focusing on separating logic into its own library and the component library will now serve .sass files instead of compiles css. See GetDKAN/data-catalog-components#106