Better themes

[sbrl]

We need better themes for this thing. In particular, we need a better default theme.

I will probably need help with this.

Quote from reddit user /u/Theis:

But I really think a better userinterface is needed, maybe use something like Bootstrap. The thing is that regular non-technocal people get scared away from something that looks too bare. Or maybe just clone the look and feel from Githubs wiki.

Having the new theme based on GitHub's wiki theme seems like a good idea.

[sbrl]

Link to original reddit post: http://www.reddit.com/r/wiki/comments/37b003/pepperminty_wiki_a_markdownpowered_wiki_in_a/

[sbrl]

We have some serious progress on this. Here is what it looks like currently:

Note that it isn't finished (there quite a bit of work left to do!) - but feedback would be much appreciated.

Also note that this doesn't include the sidebar from issue #7 (I haven't started that yet!).

[sbrl]

The new theme is practically done! I am not going to close this issue just yet though - one theme doesn't really give the user a choice.

[ikisler]

I've been messing around with this a bit. Currently, I'm using a recolor of the default theme for my wiki at work, but I was thinking a second default with a different format might be nice:

What do you think? I can't decide if having the "More..." on the side menu is weird or not. I still gotta figure out where the sidebar goes as well.

[sbrl]

Ah, that's looking good! It might look a bit better with some additional colour might help? Yeah, I can totally agree about having a second different theme. Perhaps I should do some work on adding a 'theme selector' action for moderators?

And about the more button - what I've done before is move all the items in the more menu to a different menu and use CSS to hide the more menu.

I'm still indecisive about what I should do about the more menu.

[sbrl]

And hrm the sidebar! Yeah, I keep forgetting about that thing, as I don't use it personally :P Maybe the right-hand-side?

[ikisler]

Yeah, I was going to come up with some other color combos -- this tool has some nice ideas: https://material.io/color/#!/?view.left=0&view.right=0&primary.color=9E9E9E

I hadn't considered how to actually implement more than one theme. An option in the master config makes the most sense. In terms of code, I think if we gave each theme a name and stored that value in the css field in peppermint.json (so acceptable values would be "auto","second theme","third theme", or custom CSS). Then on the PHP side, we'd just have to include the theme's CSS, and expand this IF: if($settings->css === "auto") $settings->css = $defaultCSS; To include the other options

[sbrl]

Yeah! That tool looks good - I'll have to add it to my collection :smiley_cat:

Yeah, I can see how that would work. I've also been thinking about creating a special 'theme switcher' / 'theme gallery' action too, where additional themes are stored in this repository with an index file, and then Pepperminty Wiki fetches the index file and displays the different options, though it would be nice to allow anyone to maintain their own themes (such as yourself!), so maybe we could add gist support too - i.e. a theme can be stored in a gist with a metadata file that Pepperminty Wiki reads, and the theme owner just sends a PR against this repository to get it included.

I'm thinking out loud here - let me know your thoughts!

[ikisler]

Oooh, a theme gallery sounds cool. I haven't messed with gists before, but Roll20 does something similar with their character sheets -- they keep them in a separate repo, and you do a pull request with your new character sheet and meta file. If the changes are accepted, then the new character sheet gets pulled into the software itself for use by the community.

[ikisler]

Did you want to work on a theme gallery and switcher, or can I work on it?

[sbrl]

Did I forget to reply to your earlier comment? Oops! I certainly meant to :P

Hrm. Not sure! I'm still unsure as to what I'd like to do with it. How about we plan it out in the comments here first, and see where we go from there? This is a new experience for me :slightly_smiling_face: It'll go in a separate module for sure. The basic structure will probably be to have a json file in this repository that acts as an index - something like

[
    {
        "name": "A Cool Theme",
        "description": "An awesome theme based on bob's rockets' website.",
        "preview_url: "https://cdn.billsboosters.net/files/path/to/preview.png"
        "css_url": "https://billsboosters.net/files/path/to/theme.css"
    },
    ....
]

...and then the instance of Pepperminty Wiki downloads & caches this index json, with an option ($env->is_admin, yeah - I know I really need to rename that.... :P) to refresh the cache. Then perhaps a new action theme-chooser or something that shows the gallery, and another action like set-theme or something that downloads the theme content and sets $settings->css to the theme content.

We'll also need to think about updates to themes. Perhaps the theme setter should add a new theme_last_updated property to the settings, and then check use an if-modified-since to see if there's an update available? I'm not sure if github gists support that - we'll have to investigate methods of allowing for (auto?) updating before diving in.

Thoughts?

---

Oh, and also as a contributor, I've forgotten to ask - I assume you're ok with donating your code under the MPL-2.0?

[ikisler]

Yes, I'm fine donating my code -- I get to work on something interesting, and I get a tool out of it. Seems like a good tradeoff to me. :3

In terms of this enhancement, it looks like we're both on the same track -- I agree that this would be a new module, with a JSON file containing an object for each available theme, exactly like you have above. I hadn't considered caching the file on the wiki instance, rather I was thinking we'd fetch the list of available themes each time the page was loaded -- I could see caching it, but I'm a little concerned that people would be trying to set a theme using outdated info.

I don't think we should auto update themes -- I think that having the last updated date displayed would be useful, and an option to update, but I think admin or mods should have the choice to apply the updates or not. It looks like we can use the Gist API to grab the last updated date, and then we can check against our new theme_last_updated property.

[sbrl]

Thanks :smiley_cat:

Hrm. Now that you mention it, considering how often it'll be fetched, no caching should be ok for the theme index, yeah.

Perhaps the wiki could email the admin / the mods when there's an update available and give them a link to click to update, then? That would strike a better balance, I think.

You can? Awesome~ We shouldn't run into the rate limits of that API either, so that ought to work just fine :D

[sbrl]

The other thorny problem I thought of last night was templating. Currently, Pepperminty Wiki doesn't offer any way to customise the HTML generated for a page. To allow more diverse themes, we might want to consider some sort of api for that.

(Now that I think about it, I need to check and make sure the API docs are up to date! Note to self....)

[ikisler]

I like the idea of the email with link, but I'm not sure how to handle the trigger for the email. Like, what's the trigger to check for updates before determining to send the email? Do we check every time they log in? Scheduled once a week? We'll have to kinda balance the how often to check versus the limit for calls to the Gist API.

I'm not sure that I agree that there's no way to customize the HTML for a generated page -- you can customize the styles for the wiki and that also covers the generated HTML. Admittedly, I have not messed with that aspect much, but it seems pretty doable. Or am I misunderstanding?

[sbrl]

I think scheduled will be the way to go. Considering the limits, perhaps we can add a new setting, and set it to check every, say, 5 days by default? I've been doing some work with scheduling jobs on every page load with the stats I've been implementing (just got to tell it to do the calculations automagically now :smiley_cat:), so it's perfectly possible.

And yeah, while it is possible to customise the generated HTML, the HTML templates are currently hard-coded into page_renderer - see core.php:947. They should be fairly easy to extract into a pair of settings that are compatible with a theme - we'll just have to make sure that if their values aren't changed they get updated automatically by Pepperminty Wiki - i.e. have an "auto" setting.

Considering that they don't change much though (I haven't changed that line in ~2 years - the last time was during a nasty merge mess :P), we should be fine :P

[sbrl]

You can, however - if you create a module - alter all the parts that get substituted into the template with page_renderer::register_part_preprocessor(), which is insanely powerful :P

[sbrl]

I've got some time to sit down and build this with you, if you'd like, @ikisler, since you've expressed an interest :smiley_cat:

I've drawn up a diagram of how I think it'll work.

1. The pepperminty wiki instance fetches the theme index from the main repository
2. It uses it to render a theme gallery which is sent to the client
3. The client selects the theme that they want to download & install, and the pepperminty wiki instance installs it.

To that end, perhaps the theme index could look like this:

[
	{
		"name": "Carrot Theme",
		"summary": "A cool theme that reminds one distinctly of carrots.",
		"description": "Any additional notes / details",
		"css_url": "https://carrotcity.net/path/to/theme.css",
		"preview_urls": [
			"https://carrotcity.net/path/to/preview1.png",
			"https://carrotcity.net/path/to/preview2.png",
			"https://carrotcity.net/path/to/preview3.png",
		]
	},
	{
		"name": "Night time",
		"summary": "A darker theme for night owls who stay up late.",
		"description": "Details here",
		"css_url": "https://gist.github.com/bbb922142ff764678572303684d93e44d9239886/latest/or/something/theme.css",
		"preview_urls": [
			"https://gist.github.com/bbb922142ff764678572303684d93e44d9239886/latest/or/something/preview1.png",
			"https://gist.github.com/bbb922142ff764678572303684d93e44d9239886/latest/or/something/preview2.png"
		]
	}
]

I'd recommend requiring that the css file, at least, it hosted via https. It is going to be downloaded to the independent server, after all! There are still a few issues we have left to solve though:

• What about updates? Currently my plan is to show 'installed' and 'activated' buttons next the appropriate themes, so maybe we could add a further button that updates the theme?
• How do we detect an update? I guess we could rely on the last-modified http header, but it might be better to take a hash of each and compare.
• What about folder structure for the themes downloaded? How about storing theme data in ./.peppermint-themes/theme-name/?

What do you think? Which bits would you like to tackle?

[sbrl]

I've started work on a new theme gallery system. It's coming together, but there are a bunch of things left to do.