Install the styleguide module

[clarkepaul]

As we don't have a good view of all the produced styles of the theme, installing this module might be able to help us identify which styles are not working properly.

My alternative to the style guide would be to create a test page with raw bootstrap example code to see how it generates. If the style guide is fairly automatic (?) then that would be my preference.
cc @chillu

Overview

• As a member of the PUX team, I want to be able to quickly glance at most styles in the Bambusa theme to identify possible shortcomings
• As a content editor, I want to know the bambusa theme correctly styles a variety of elements when writing my content.

Acceptance Criteria

• A "style guide" page is automatically generated by the bambusa site
• All Common elements are displayed in the style guide
• The page can be reach via the site navigation.
• The styleguide only shows elements that are included in the theme (and don't look broken)

Notes

• Excludes more complex components such as the Carousel
• Excludes any React Storybook compilation shenanigans
• If the styleguide uncovers current theme issues, log them separately
• Commonly used module: https://github.com/benmanu/silverstripe-styleguide/
• Not using bespoke setup for now (https://github.com/silverstripeltd/project-skeleton/tree/master/.storybook)

Pull requests

• Add style guide template #8
• Add style guide bambusa-installer#18
• Update SimpleStyleguideController to use dynamic asset url resolution benmanu/silverstripe-simple-styleguide#11 (Patch against the original module ... nice to have, but not essential)

• Add requires_dev config benmanu/silverstripe-simple-styleguide#12 add dev toggle
• Better styleguide template bambusa-installer#25 better styleguide template
• Do not require dev mode for styleguide bambusa-installer#26 disable dev require
• Make sure the style guide is always accessible to all users bambusa-installer#39
• FIX Don't use actual page instance benmanu/silverstripe-simple-styleguide#13

[maxime-rainville]

I believed we're talking about this module. https://github.com/benmanu/silverstripe-styleguide

[maxime-rainville]

Made up some ACs and added an overview

[maxime-rainville]

https://github.com/benmanu/silverstripe-simple-styleguide looks like it's more recent and better supported.

[maxime-rainville]

Done. I've moved to peer review. We'll need to add a menu entry for it, because the guide is on its own controller.

Couple extra point we might want to consider:

• the module support a colour section that list a predefined list of colour, we could hook our dynamic colour in there. I've disabled it for now.
• There a TOC at the top of the page, I would want to move that to the side bar.

[chillu]

we could hook our dynamic colour in there

Yeah, nah.

[bergice]

Moving to content for the menu entry to be added.

[chillu]

@bergice Looks OK, but since the styling wasn't shown in the actual container of the theme, it looked quite off - no left padding, and some styles only apply within that container. I've spent five minutes to fix this, can you please review? silverstripe/bambusa-installer#25

[chillu]

@clarkepaul @Karlstir Probably not super obvious unless you hit the module README - the styleguide is accessible through the /_styleguide URL, which you can link from other places - it won't be "discoverable" unless it's explicitly linked.

I've added an intro to make the intent of this page a bit clearer:

This view is only accessible to developers and admin users. It demonstrates styling variations, and can be used to test styling changes.

@maxime-rainville @bergice You've both missed that there's a isDev() check in the controller, so this styleguide won't fulfill it's purpose - it's not available on a demo which runs in isLive() mode. Can you please submit a PR to the module to make this check configurable, and opt out of it for Bambusa? Keep the ADMIN check in place.

[bergice]

@bergice Looks OK, but since the styling wasn't shown in the actual container of the theme, it looked quite off - no left padding, and some styles only apply within that container. I've spent five minutes to fix this, can you please review? silverstripe/bambusa-installer#25

Looks good. I'm guessing you want this merged in bambusa-theme instead of bambusa-installer?

[bergice]

@clarkepaul @Karlstir Probably not super obvious unless you hit the module README - the styleguide is accessible through the /_styleguide URL, which you can link from other places - it won't be "discoverable" unless it's explicitly linked.

I've added an intro to make the intent of this page a bit clearer:

This view is only accessible to developers and admin users. It demonstrates styling variations, and can be used to test styling changes.

@maxime-rainville @bergice You've both missed that there's a isDev() check in the controller, so this styleguide won't fulfill it's purpose - it's not available on a demo which runs in isLive() mode. Can you please submit a PR to the module to make this check configurable, and opt out of it for Bambusa? Keep the ADMIN check in place.

That's added to the PR's.

[chillu]

Looks good. I'm guessing you want this merged in bambusa-theme instead of bambusa-installer?

No, since the theme doesn't require the style guide, the "app" does (bambusa-installer) - so it's in the right place.

[chillu]

benmanu/silverstripe-simple-styleguide#12 add dev toggle

That's a blocker now, unless we run a fork. The module isn't operational in the way we need it to be without this in place, right?

[maxime-rainville]

We could just extend that class and run our own index method with a more permissive check.

[maxime-rainville]

I'm moving this to block since we're waiting for the module maintainer to action our pull requests.

If we get to the end of the project and they still haven't approved our PRs we can look at ways of bypassing those issues.

[chillu]

@silverstripeux This is on UAT now: http://bambusad-uat.sites.silverstripe.com/styleguide/. Had a quick check and the styleguide looks OK to me, but you might be able to spot more issues with your eagle design eyes 🦅

[clarkepaul]

Installation of the module is fine and I've added some links to it from various places with the content:

• CMS component library and website style guides, http://bambusad-prod.sites.silverstripe.com/empower-development-teams/
• The second paragraph on this page http://bambusad-prod.sites.silverstripe.com/what-you-get/content-authoring-flexibility/

There are still styling issues still with spacing and image alignment but they are outside of this issue.