Closed aboydnw closed 1 year ago
aboydnw
commented
1 year ago @danielfdsilva @hanbyul-here @ricardoduplos I know we have been referring to this as Story Configuration UI. It struck me when going through tickets today that configuring datasets would be equally as valuable. I realize that may be more complicated to accommodate, so maybe it's not part of our MVP solution here, but wanted to put that bug in your brain for potential future development.
hanbyul-here
commented
1 year ago @aboydnw For your points about story config vs dataset config, I think one system should work for every content (including story, dataset and thematic - I will just refer all of them as ‘posts’ here since it is more common term for Contents Management System) so I was reading this ticket more like just UI for general CMS purpose.
I tested Netlify CMS to see if it can be an option for configuration UI. I wrote down how it looks like in the PR that I linked: https://github.com/NASA-IMPACT/delta-ui/pull/224 . (I don't think you can sign up/log in since I made the registration invite only. I will be happy to demo if you want to see how whole things work live.) In short, NetlifyCMS offers user identification, UI widgets to configure meta information of the post, a primitive WYSWIG editor to preview, and publication workflow using gitflow git (Netlify CMS is going to commit the post directly to the designated branch.) I will break down each piece below.
Netlify CMS works like a micro service inside of your app. You make a static HTML (which is placed in /admin in dist folder)n and this HTML has css/Javascript that will power Netlify CMS. I used Javascripts from the CDN for simplicity, but we can have a separate pipeline for CMS script so we have more flexibility when we need to add features etc.
Another big piece for Netfliy CMS is config.yml file that specifies the metadata of the post. In this file, each attribute should be specified by its label (how it will be labeled in CMS UI), name, type, and UI widget. You can see how our dataset is configured in this file: https://github.com/NASA-IMPACT/delta-ui/blob/6785319f70974b2e2877ba2e536b52f07e5d71b7/static/admin/config.yml This file only has dataset in its collection (post type) but we can add more post types such as thematics, discoveries to 'collections'
Netlify CMS comes with several widgets embedded. Since Netlify CMS itself is open source built with React, there are widgets that were developed by communities too. For example, I used select-async widget to fetch available collections from our endpoint. It will be inevitable to develop our own widgets at some point, (One widget that I can think of immediately is an image/media widget, since we need a prefix that Parcel expects ::file) and it won’t be too difficult to set up the development environment.
Any data with an attribute of ‘body’ will be the contents of the post, and the widget for this looks like a basic WYSWIG editor in Netlify CMS. It offers several parsers including Markdown,but we are using MDX for our contents. Depending on what we want, (ex. Do we want elaborated UIs like editors can drag and drop? Or do we want something simpler?) this can be a whole other project to work on, or a few sprint’s worth of work.
Netlify CMS commits the change directly to the designated branch. We can’t change the branches dynamically, which means the change will go directly to staging. We already protected our production branch, but since the repo is open and anybody can figure out about Netlify CMS, we might want to be extra protective about who can make changes on GitHub. (We can design this CMS UI to run mainly on local, so the change doesn’t go directly to the staging environment? But this will require extra manual edits from users which is not ideal.)
We can use Netlify’s identity service to manage editors (who can log in to the admin panel and make changes.) If we want to make this system invite-only, Netlify will start charging from 5 users. If we make this system open (anybody who wants/can find admin url can join), Netlify will charge from 1,000 users.
Overall: I think Netlify CMS has potential to be our solution. It gives us a good balance between embedded functionality and customizability. I think we can achieve metadata configuration(frontmatter) fast with not much effort. WYSWIG + preview part can be challenging depending on what we want. We would need to have a clearer understanding of what is expected, and allocate an appropriate amount of resources to the task.
aboydnw
commented
1 year ago Thank you for the detailed writeup @hanbyul-here !
I created some stories based on your documentation here. Still some details to add to those stories that you called out above:
In general, we can always iterate after an initial build and we get some folks at NASA to test it out.
hanbyul-here
commented
1 year ago @aboydnw I realized that I used the term gitflow wrong. Netlify CMS uses Git, (Gitflow is a way of working with Git). I edited my original comment accordingly!
danielfdsilva
commented
1 year ago Thank you @hanbyul-here! This is great research. I think that for frontmatter configuration this will work well. I am a bit concerned about the MDX content part. I think the difficulty in writing the MDX is making sure that the blocks and its props are properly formatted/configured.
What could be the simplest form of MDX configuration we can come up with? I'd say we skip the preview for the time being, but could be good to know how netlify can helps us here. What do you think?
hanbyul-here
commented
1 year ago I talked with @aboydnw and Anthony mentioned that it will be more helpful to have these widgets inside of editor, so they can be used to configure MDX components. so I did a bit more research about it.
Netlify offers an official way to extend their editor: https://www.netlifycms.org/docs/custom-widgets/#registereditorcomponent Through editor widget api, we can set up what kind of fields the component needs, and how the output should be.
This is Chart component widget that I made by tweaking the code on the page:
In editors rich text view, custom widgets can be found by clicking + button.
Once component is clicked, UI widgets are going to show up in the editor asking required fields like below.
output from the widget will look like this (can see by switching a view from rich text to markdown). I configured in a way that the component is wrapped in required markups<Block><Figure>
danielfdsilva
commented
1 year ago Very cool!
hanbyul-here
commented
1 year ago My research ended up with weighing heavy on Netlify CMS (mainly because we are already using mdx file for contents).
When I was about to close this ticket, I thought.. maybe headless Wordpress can be an option? The new editor that Wordpress pushes (Gutenberg: https://wordpress.org/gutenberg/) is written in React. We can write customized blocks, editors can see these blocks rendered in the editor. I don't believe wordpress offers mdx format but output data was very customizable. (Development experience for Gutenberg was... bad and the team I was on ended up with reverting the editor to block editors -traditional wordpress editor- but the last time I checked was about 2 years ago so maybe it is better now.) This approach will require a wordpress instance and a separate development process dedicated to editor (which will require php knowledge - I have very little). So we should consider this option only when we are absolutely sure that we want to seriously invest in CMS.
Goal is to propose a solution for the story configuration UI. One that balances complexity/effort with reducing the level of effort or technical knowledge that a user needs to configure a discovery.
Acceptance Criteria
Meeting planned for Wed. 7/20