Themes

[jimafisk]

Picking up the discussion on themes started here: #19

It would be nice to have a command for adding themes, for example: plenti new theme [email protected]:jimafisk/my-theme.git. This should download the git repo into a themes/ folder and could even make an entry in plenti.json in order to keep track of what theme is currently being used + could allow checking for updates on the remote repo.

Maybe also add a flag to the new site command, e.g. plenti new site MY_SITE --theme=REPO.git. This should run the --bare flag in the background.

[jimafisk]

Whiteboard sketches

[jimafisk]

If anyone wants to bring the themes PR down locally and do some testing that would be awesome. A theme should function like any other plenti site, so just pop it in your themes folder and reference it in the parent plenti.json config file. Your project will inherit everything from the theme: assets, content, and layout so if you don't want any of those, either delete them in the theme or overwrite them in your project. You can also nest themes infinitely so you can pull in a theme that in turn pulls from another theme and so on. Here's a quick example project in case anyone is interested: https://github.com/jimafisk/plenti-nested-themes-test

[jimafisk]

I've been going back and forth in my head quite a bit on how we should manage themes through the CLI tool. I wanted to provide a way to manage versions, however I knew most people creating simple sites would probably not git tag or create releases for different versions. In order to allow the maximum number of standard sites to be able to be used as themes (with no special setup on the maintainers part), I decided git commits could be used as version substitute. So I started updating the siteConfig struct to keep track of this info, which would look like this in your plenti.json config file:

{
  "build": "public",
  "theme": {
    "name": "plenti.co",
    "url": "[email protected]:plentico/plenti.co",
    "commit": "3c931c6d75e2a92fdaada896c5307c0845b2a74e"
  },
  "local": {
    "port": 3000
  },
  "types": {
    "pages": "/:filename"
  }
}

That led me to thinking that maybe we should update the command from something like plenti new theme [email protected]:plentico/plenti.co to plenti theme add [email protected]:plentico/plenti.co. That would open us up to other commands like:

• plenti theme remove plenti.co
• plenti theme update plenti.co

However, after starting to implement this and talking through it some more with @stephanieluz, we've decided this is a lot of added complexity for minimal value. First, I want to keep the plenti.json config file as simple as possible to make it less intimidating for new devs. Second, if someone was creating a nested theme from scratch they would not have the commit hash or url information. The same would go for someone pulling down a zip file from dropbox or gdrive, etc. We could make the additional keys optional, but the best way to enforce consistency is to limit options entirely. So my new plan is to revert this back to a flat theme: <theme_name> API. If someone wants to update a previously downloaded theme to a newer version, they can simply run the original plenti new theme <git-url> command they ran originally to get the newest version. I do however still see a scenario where someone will need a specific version of a theme to work with their project, so I still plan on allowing the command to target a specific commit like plenti new theme <git-url> --commit=<hash>, however once the theme has been downloaded, it's on you to keep track of version and source if that info is important to you.

I'm sure some folks may hate this decision and nothing is ever final, but we're trying to emphasize simplicity and productivity over order and perfection. If we can make something more accessible for the most common use-case, we're ok with it not being as robust in the edge cases as a tradeoff.

[jimafisk]

I've been thinking more on this, so I figure I'll keep using this issue to think out loud in case anyone has thoughts they'd like to add. It would be helpful to add options to allow people to turn off inheritance on a particular aspect of a theme (assets, content, or layout). For example someone might want to leverage templates from a parent theme, but not have to override every single content page in that theme (or delete them in the parent theme every time they update). It would be nice to allow adding an option for this to plenti.json which would require the theme value to be an object anyways:

"theme": {
  "name": "plenti.co",
  "url": "[email protected]:plentico/plenti.co",
  "commit": "0eff8c7",
  "content": false
},

I'm going to work this a bit more to hopefully see if I can find a good compromise between features and ease of use.

I've added a way to resolve long or short commit hashes. It might also be nice to be able to pull zip files that aren't git versioned at all, although I'm not sure how necessary that would be.

[jimafisk]

What about multiple themes?

"themes": {
  "plenti.co": {
    "url": "[email protected]:plentico/plenti.co",
    "commit": "0eff8c7"
  },
  "plenti-tags-example": {
    "url": "[email protected]:jimafisk/plenti-tags-example.git",
    "commit": "b8e6d17"
  }
}

Would we add an enabled: true key to the default theme? Or just have another theme key outside of the declaration that points to the name of the enabled theme (e.g. theme: plenti.co,). Or maybe just not track themes that aren't the enabled theme?

Basically this is all to avoid git submodules, but we don't want the solution to be more complicated than what we're initially trying to simplify.

Git submodule screenshot

[jimafisk]

I think there needs to be two independent processes here:

1. Pointing plenti to a theme within the local themes/ folder so it knows how to build the site. This process does not need to worry about what method was used to add the theme (git clone, zip download, start from scratch, etc)
2. Managing remote themes via the CLI (downloading new themes, getting updates, etc). This process does not need to be aware of what theme is currently enabled, it just needs to know information about which themes it has downloaded.

A site could simply use the first process and completely omit the second (an enabled theme that isn't managed via Plenti CLI). A site could also use the second process without the first (several themes managed through the CLI, but none are enabled). A site could also leverage both processes (several themes are managed through the CLI, one of which is enabled).

A plenti.json config file that is leveraging both 1 and 2 would look something like this:

"theme": "plenti.co",
"themes": {
  "plenti.co": {
    "url": "[email protected]:plentico/plenti.co",
    "commit": "0eff8c7"
  },
  "plenti-tags-example": {
    "url": "[email protected]:jimafisk/plenti-tags-example.git",
    "commit": "b8e6d17"
  }
}

If those keys are too similar / nondescript, we could potentially use enabled_theme, active_theme, default_theme for 1 (although I think this should be the more simple key of the two keys) or all_themes, available_themes, downloaded_themes, managed_themes, remote_themes for 2.

[jimafisk]

Considering the other options (like omitting assets, content, or the layout folder) for the 2nd process outlined above, maybe a better key name would be: theme_settings, theme_details, theme_config

We also might want flags in the CLI to automate this: plenti new theme [email protected]:plentico/plenti.co --commit=0eff8c7 --assets=false --content=false --layout=false

Edit: We're going with theme_config for now, to match naming conventions found elsewhere in the project.

[jimafisk]

Proposed commands:

• plenti theme add <url>: downloads a theme from a git repo and adds tracking info to plenti.json
• plenti theme enable <name>: enables a theme to be used by the site by adding an entry in plenti.json
• plenti theme disable <name>: disables a theme by removing entry in plenti.json
• plenti theme update <name>: tries to fetch new version of theme from upstream url specified in plenti.json
• plenti theme remove <name>: deletes the local version of theme and removes entry from plenti.json

[jimafisk]

Might be nice to eventually add promptui to allow folks to run commands without the theme argument and take user input (e.g. plenti theme update). The enable / update / remove commands would list all the themes in the /themes folder (there could be more themes there than are managed in theme_config). The disable command should just provide a confirmation to disable the currently enabled theme since there is only one option.

[jimafisk]

Needed to delete the .git/ folder of the theme in order to avoid submodules and allow cloning over an existing directory: src-d/go-git#755

[jimafisk]

The theme update command essentially just calls the theme add command: https://stackoverflow.com/questions/43747075/cobra-commander-how-to-call-a-command-from-another-command/64686822#64686822. The only difference is you don't need a URL since we already store that info. You can simply use the theme name.

[jimafisk]

There are some issues using the assets, content, and layout keys in theme_config. First these should have a default value of true, but naturally these will have a default value of false. You would also need to use pointers to track the false values (see https://stackoverflow.com/questions/37756236/json-golang-boolean-omitempty and https://stackoverflow.com/questions/30856454/how-to-unmarshall-both-0-and-false-as-bool-from-json), which isn't the end of the world, but it's working against the natural way marshal / unmarshal want to work in go. I think it would be better to instead use an omit (or exclude) key that you can pass an array of items to. This way you could pass assets, content, or layout, but you could also pass additional values to get rid of any custom folder that may have been added to the theme.

[jimafisk]

Themes are now out in the wild with the 0.3.x releases. It's a relatively untested feature, so please flag any bugs!