eregsplatformthoughts.md

This is a rough outline of how I envision the plugin implementation for eRegs, sans parser. There’s plenty here that is just a starting point, and that I have not thought through fully. The main point that I want to make is that we can reuse patterns and code that we already have to give plugin writers the option to add their own content in ways that have been validated by user feedback.

I’m thinking about a first implementation, not a final vision. The idea is to rework code we have, add foundational plugin code, and document how we expect people to write a plugin and what controls they have available to them. The motivation is to be able to relatively quickly and cleanly spin up instances of eRegs, with an eye toward many agencies having instances in the future. Each agency seems to have its own specific set of documents that are important to them, and my hope is that we can identify a set of feature types that match content we have now and will meet many of the immediate needs that agencies have.

Using modules we have for the current UI, give a plugin writer the ability to:

• add a drawer tab link
• add a drawer pane
• associate supplemental content with reg
  • insert below reg text in an expandable (like the CFPB interpretations)
  • insert into the sidebar (like definitions or section by section)
• open supplemental content in the breakaway view

Maybe the plugin writer defines something like a content type and configures how it behaves - I can add a drawer pane plugin that gives me the option to add a tab link. Or I have a new reference content type that I want to bring into the expandable and contextually link to in a sidebar module.

Implementation of a feature plugin (includes the theming process):

Plugin:

• potentially stuff that goes further back in the stack that I haven't even attempted to think about.
• CM, please help
• Django view implementation
  • is it possible to live in Adam's world where an eRegs instance repo can be the theme, and in this one where, I would assume, plugin development has to happen in Django and back?

Theme:

• create template if needed
  • can we template only some things in JS? how ugly would it be to insert features defined by custom plugins, while the rest is served from django?
  • what is adam's idea here?
• JS view implementation
  • add a *-view.js to the right dir and it will be included in build
• CSS implementation
  • add a less file to the right place, build will pick up on it and include it to override core classes
  • insert takeaways from John's findings here

We would translate the conventions in place, with some polishing, into a process and documentation. As suggested above, should we rely on file naming and placement convention as the way for plugin writers to extend eRegs?

Types of things people will most want to do:

• lists of links to supplemental content
• bringing other documents into eRegs

Does narrowing this down help to give us an initial technical approach? My guess is that it does. Is there more that belongs on this list? Am I wrong about what is on this list?

What this doesn’t handle:

• overriding core functionality
• layout changes

We should do the quickest useful thing that addresses our semi-immediate needs, and ship it ASAP. We can learn from it and then take on these bigger challenges, if the need exists. We should also be sure we're not letting folks too easily create bad experiences - part of the promise of eRegs is a pleasant experience.

add a less file to the right place, build will pick up on it and include it to override core classes

I think this could be a compiled CSS file in a certain locating with a specific name (something like theme.css?). That would allow the plugin author to use vanilla CSS, or their own build process with Less, Sass, PostCSS, whatevs. Also, it would be possible in this scenario to not require any build step for the theme author if they do choose to use Less.

create template if needed

• can we template only some things in JS? how ugly would it be to insert features defined by custom plugins, while the rest is served from django?
• what is adam's idea here?

Could we do something similar to the eregs-ip directory that CFPB eRegs uses? The app includes default templates but those templates are overriden by anything placed in the theme directory.

This would not account for new routes, views, etc. however.

My thoughts on a very preliminary test of this workflow:

1. Rename Less color variables to be more generic (may require some Jen reconnaissance to determine color roles)
2. Add the above described theme setup to the regulations-site grunt task so that it consumes those color variables
3. Create a "theme" with an alternate color scheme

Could we do something similar to the eregs-ip directory that CFPB eRegs uses? The app includes default templates but those templates are overriden by anything placed in the theme directory.

I forgot that templates are included in that. Yeah, on the theming front (as opposed to plugin front), that sounds good to me. I'm still wondering about how this would work in a world where we provide a way for people to extend the functionality, which leads to...

This would not account for new routes, views, etc. however.

I imagine routes being generated from whatever plugins are present? Might we pull in views, etc files from the eregsip-like directory?
Although, this gets back to an issue where the functionality for most cases, it seems to me, will have to be split across -site and -core as things are. Is there a sane way to manage this?

Great stuff here.

is it possible to live in Adam's world where an eRegs instance repo can be the theme, and in this one where, I would assume, plugin development has to happen in Django and back?

I don't understand this sentence.

Plugin:

We're starting to cover the backend of this with eregs/regulations-site#56 and eregs/regulations-site#59 -- the basic idea is to add a setting where both built-in layers and sidebar elements can be swapped out or re-ordered (only relevant to the sidebar). Arbitrary agency-specific features can be added this way

can we template only some things in JS? how ugly would it be to insert features defined by custom plugins, while the rest is served from django?

There's no need to require JS :) As @ascott1 noted, there's already a good mechanism to replace (and add new) templates via Django

JS view implementation

Shouldn't this be part of "Plugin" instead of "Theme"? While JS views will sometimes be required, I think logic should be moved out of JS wherever possible. The majority of cases should use, e.g., a shared "breakaway.js" rather than an agency-specific "section-by-section.js".

I think this could be a compiled CSS file in a certain locating with a specific name (something like theme.css?). That would allow the plugin author to use vanilla CSS, or their own build process with Less, Sass, PostCSS, whatevs. Also, it would be possible in this scenario to not require any build step for the theme author if they do choose to use Less.

I like the flexibility, but the only implementation (short of re-working most of our templates) I can think of would require too much work per agency. The most common use-case we're considering is an agency wanting to change color schemes, fonts, logos, elements of that sort. Given how pervasive color schemes are (in terms of their presence in other style sheets), I don't think we could hit these simple use cases without recompiling the "common"/"base"/whatever styles or requiring each agency override dozens of classes.

@ascott1, looks like you came to the same conclusion in your suggested test of the workflow.

eregs-ip

As a general flag, I think the eregsip approach is backwards. Rather than having a regulations-site checkout and adding an eregsip directory within it, I think we should use the ATF approach, using -site as a library. So your X-agency project would include only X-agency plugins, themes, etc. and would reference -site. See https://github.com/18F/atf-eregs

Note that while this isn't how CMSes like Wordpress and Drupal currently operate, it is how Django and Rails CMSes work, and it's the direction Drupal is moving (now that PHP has a sane package management system).

Although, this gets back to an issue where the functionality for most cases, it seems to me, will have to be split across -site and -core as things are. Is there a sane way to manage this?

Ideally, we'll have no agency-specific features in -core (the data storage layer) or in -site (the shared UI). We'd be able to add arbitrary layer data and arbitrary, searchable document types to the "dumb" API. This future isn't too far off.

I think you're getting at functionality being split between the parser and the UI, which I'm not sure how we escape. As it stands, it looks like we'll have something like this:

atf-reg-parser: ATF-specific code to pull in Rulings, make consistent data changes (a la regconfig/regcontent), etc.
+--- regulations-parser (as a library)

atf-eregs: includes ATF-specific themes, UI functionality
+--- regulations-core: a generic API (as a library)
+--- regulations-site: shared regulation UI code (as a library)

Shouldn't this be part of "Plugin" instead of "Theme"? While JS views will sometimes be required, I think logic should be moved out of JS wherever possible. The majority of cases should use, e.g., a shared "breakaway.js" rather than an agency-specific "section-by-section.js".

Yup, I agree. I must have not very clearly explained. JS should be part of a plugin, not a theme. I am also hoping that we can use generic views that correspond to a type of feature rather than the specific implementation. So a section by section plugin would, by virtue of somehow specifying that a sxs should open in a breakaway and have a sidebar module, use the default breakaway and sidebar module views. I was thinking about a potential future where we may need to write very different features for an agency, which would necessitate more custom code, but maybe there's not a benefit to thinking about that at this point. Does that sound better?

More to come.

ETA: I see now where this came from. I'm not sure what I was thinking, putting that under theme.

is it possible to live in Adam's world where an eRegs instance repo can be the theme, and in this one where, I would assume, plugin development has to happen in Django and back?

I don't understand this sentence.

So, here I wasn't thinking of an agency's eregs instance being a Django project, and was trying to reconcile server side changes with front end ones in that scenario. In a world where an eregs instance is a Django project and we continue use of a front end compile of some sort, this problem goes away.