Rfc/issue 570 context and theme packs #669

thescientist13 · 2021-07-16T17:58:58Z

Related Issue

resolves #570

Summary of Changes

Introduced the concept of a context Plugin type. as an Array
Those template paths are then used as part of getAppTemplate and getPageTemplate in plugin-standard-html
Also supports template from front matter
Added test cases emulating a "theme pack" like package
Created developer docs for Context plugin as well as a guide on Creating a Theme Pack
Allowed for customizing default location for pages and templates from greenwood.config.js

Example Usage

module.exports = (options = {}) => [{
  type: 'context',
  name: 'my-theme-pack:context',
  provider: (compilation) => {
    return {
      templates: [
        path.join(compilation.context.projectDirectory, 'node_modules/my-theme-pack/dist/layouts')
      ]
    };
  }
}];

Then in a template called layouts/title.html you can "share" a template like so

<html>

  <head>
    <script type="module" src="/node_modules/my-theme-pack/dist/components/greeting.js"></script>  
  </head>

  <body>

    <h2>This is a custom page template called title from the layouts directory.</h2>
    <x-greeting></x-greeting>
    <content-outlet></content-outlet>

  </body>

</html>

Use it in frontmatter in your own workspace

---
template: 'title'
---

### Title Page

#### Some content from my own title.md page.

Even combine it with a custom app template too, using layouts/app.html

<html>

  <head>
    <link rel="stylesheet" href="/node_modules/my-theme-pack/dist/styles/theme.css"></link>
  </head>

  <body>
    <h1>This is a custom app template from the custom layouts directory.</h1>
    <page-outlet></page-outlet>
  </body>

</html>

Greenwood will automatically handle all the node resolution for that JS and CSS!!! 🏆 🙌

TODO

Add example of using components (footer / header) - using ResourceInterface?
- don't even need a ResourceInterface, just point everything to node_modules and Greenwood will take care of the rest! Brings up another question though... 👇
How to resolve these files for development though, where they will not be in node_modules? 🤔
- should validate by merging Chore/issue 47 test coverage develop and serve commands #670 and writing some tests
Should we suggest using require.resolve for finding the right node levels directory, a la leverage NodeJS resolve logic for looking up location of paths for node modules #557
- I think as long as users use /node_modules/<package_name> convention, and Greenwood uses require.resolve correctly, then users can depend on Greenwood doing all the heavy lifting, which makes sense for such a fundamental mechanism like resolve node_modules.
Should make sure we can override a page, like an index.html so users can provide a complete "interface" as part of their theme pack
- see discussion section below
- make a follow up issue to close this one out 👇
- support custom pages through theme packs #681
Address discussion points
- ~~add a greenwood.config.js option for context for overriding templates and pages dir (nice to have, might make separate issue)~~ - implemented!
- ~~additional input formats (array vs. string)~~ - not needed at this time
- ~~use an interface?~~ - doesn't seem warranted
- ~~helpful utils for plugin authors?~~ - defer to the discussion and until we have a little more experience building these - Improve the developer experience for theme pack / context plugins #682
- ~~best practices / naming conventions for users~~ - I think by virtue of having to have a unique package name on npm anyway, there would be automatic namespacing?
Update documentation
Create a guide for creating a "theme pack"

Discussion

I think we should we support being able to specifically configure pages and templates directory from greenwood.config.js as well. The plugin approach is likely going to be more applicable to plugin authors, but for users, a "direct" configuration option, should they need it, seems best, so they can easily rename pages/ or templates/ directory name if they want to (without having to write a plugin just to do that)
- well, one thing I realize now with pages is that those actually need to be pushed onto the graph and resolved. Greenwood scans all pages first to build, so basically we also would need to incorporate [RFC] External Data (Graph) Sources #21 as well. Since getting templates in is already a good start, I think we can / should at least merge what we have and make a new issue tracking support for pages via context and link to [RFC] External Data (Graph) Sources #21 and maybe they can both be done together?
Further API considerations
- should we support more than just pages and templates?
- should everything just be an array
- should we have an interface
Documentation
- encourage namespacing for template and file names?

thescientist13 · 2021-07-27T23:57:11Z

Development v Publishing

So a couple thoughts here around handling developing a theme pack vs. distributing a theme pack since the location and paths of files would be different when develop (e.g. src/some/path/) as opposed to where they will ultimately be published to (e.g. /path/to/node_modules/< package-name >/dist/etc).

I think we can establish a couple ground rules here

Greenwood is likely going to be used (or will want to be used) in a development capacity by the plugin author (naturally)
Paths in templates should ideally not have to change from one context to the other if so (e.g. always assume node_modules/ in <script> or <link> tags)

In other words, it's probably a bit easier to bend Greenwood to make it easier for local development in a one-off fashion for a plugin author, rather than forcing them to have jump through a bunch of hoops or extra build steps when wanting to publish their templates. Ideally when everything looks good, then can just publish everything as is and it will "just work". 🤞 ™️

So here are my thoughts 👇

Templates Location

Least hackiest approach I could think of right now is simply to have the theme pack plugin accept a secret __isDevelopment only flag for the plugin author to use, such that special logic (using npm ls <dep-name> can be determined from a greenwood.config.js to tell if the plugin is installed or not, and use that to determine the route location for files.

Example

// _greenwood.config.js_
const packageName = require('./package.json').name;
const myThemePackPlugin = require('./theme-pack-context-plugin');
const { spawnSync } = require('child_process');
const ls = spawnSync('npm', ['ls', packageName]);

module.exports = {
  plugins: [
    ...myThemePackPlugin({
      __isDevelopment: ls.stdout.toString().indexOf('(empty)') >= 0
    }]
};

// in the theme pack plugin
const path = require('path');

module.exports = (options = {}) => [{
  type: 'context',
  name: 'my-theme-pack:context',
  provider: (compilation) => {
    const { context } = compilation;
    const templateLocation = options.__isDevelopment // eslint-disable-line no-underscore-dangle
      ? path.join(process.cwd(), 'src/layouts')
      : path.join(context.projectDirectory, 'node_modules/my-theme-pack/dist/layouts');

    return {
      templates: [
        templateLocation
      ]
    };
  }
}];

Paths in Templates

For paths in templates, e.g.

<!DOCTYPE html>
<html lang="en" prefix="og:http://ogp.me/ns#">

  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1"/>
    <link rel="stylesheet" href="/node_modules/my-theme-pack/dist/styles/theme.css"></link>
  </head>

  <body>
    <h1>This is a custom app template from the custom layouts directory.</h1>
    <page-outlet></page-outlet>
  </body>

</html>

This looks a little cleaner, we can just have plugin authors use a Resource plugin for this in their greenwood.config.js and never have to do anything in the plugin. We can even make this part of Greenwood's "standard lib".

class MyThemePackDevelopmentResource extends ResourceInterface {
  constructor(compilation, options) {
    super(compilation, options);
    this.extensions = ['*'];
  }

  async shouldResolve(url) {
    return Promise.resolve(url.indexOf('/node_modules/my-theme-pack/') >= 0);
  }

  async resolve(url) {
    return url.replace('/node_modules/my-theme-pack/dist/', path.join(process.cwd(), '/src/layout/'));
  }
}

With all that put together, and can pretty much keep the actual code the same, and still develop like a regular Greenwood "end user". (using develop command)

(so in this case, that URL doesn't actually exist 😉 )

thescientist13 added the RFC Proposal and changes to workflows, architecture, APIs, etc label Jul 16, 2021

thescientist13 self-assigned this Jul 16, 2021

thescientist13 added CLI discussion tied to an ongoing discussion or meeting notes documentation Greenwood specific docs Plugins Greenwood Plugins enhancement Improve something existing (e.g. no docs, new APIs, etc) labels Jul 16, 2021

thescientist13 mentioned this pull request Jul 24, 2021

Not Found (404) Page #240

Closed

5 tasks

thescientist13 mentioned this pull request Jul 30, 2021

Migrate / transition to a Greenwood Theme Pack thescientist13/greenwood-starter-presentation#13

Closed

16 tasks

thescientist13 added the Guide label Aug 3, 2021

thescientist13 added 8 commits August 3, 2021 12:26

intial example of providing custom template directories

62226c4

custom app and front matter templates

b608e6a

add specs for referencing JS and CSS from a theme pack

d523f7d

context plugin development workflow proposal

ca584de

commit package.json for spec

3350c84

handle npm for windows in spec

7f1f106

update mock example

8fd3970

develop specs for context plugin

748a178

thescientist13 force-pushed the rfc/issue-570-context-and-theme-packs branch from 86a0db3 to 748a178 Compare August 3, 2021 17:14

refeactor develop and build specs and handle local development context

512af41

thescientist13 mentioned this pull request Aug 3, 2021

support custom pages through theme packs #681

Open

5 tasks

developer docs for context and guide for creating a theme pack

bdfd299

thescientist13 requested a review from hutchgrant August 3, 2021 21:50

thescientist13 marked this pull request as ready for review August 3, 2021 21:52

thescientist13 added 4 commits August 4, 2021 09:44

fix command typos

c22375c

all for configuring templates and pages path from greenwood.config.js

8cd44a5

clarify resource plugin usage for theme pack development

1356362

Merge branch 'master' into rfc/issue-570-context-and-theme-packs

0fc2e5b

thescientist13 merged commit 4dbbd49 into master Aug 6, 2021

thescientist13 deleted the rfc/issue-570-context-and-theme-packs branch August 6, 2021 15:13

thescientist13 added v0.15.0 and removed v0.15.0 labels Aug 6, 2021

thescientist13 mentioned this pull request Aug 6, 2021

forgot to link to actual repo #688

Closed

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Rfc/issue 570 context and theme packs #669

Rfc/issue 570 context and theme packs #669

thescientist13 commented Jul 16, 2021 •

edited

Loading

thescientist13 commented Jul 27, 2021

Rfc/issue 570 context and theme packs #669

Rfc/issue 570 context and theme packs #669

Conversation

thescientist13 commented Jul 16, 2021 • edited Loading

Related Issue

Summary of Changes

TODO

Discussion

thescientist13 commented Jul 27, 2021

Development v Publishing

Templates Location

Paths in Templates

thescientist13 commented Jul 16, 2021 •

edited

Loading