Update README and Wiki pages

[guywillis]

Subject of the issue

The current README and Wiki pages for the Vanilla plugin are out of date and require updating to be in sync with the current theme implementation.

[kirsty-hames]

Perhaps we should be more vigilant and ask for documentation to be updated before merging PR's. At least that way the documentation is always up to date. If adding new classes/config etc...

[kirsty-hames]

Hey @guywillis, can this issue be closed now (README and example.json updated in e8e935f) or do you still have more to do on this?

[guywillis]

Hey @kirsty-hames

Whilst the readme and example.json files are more up to date the Wiki pages do still need going through. There is a question over how useful the Wiki pages actually are or what their purpose should be. A lot of the information between the readme and Wiki pages is duplicated for example.

I'm musing over whether the Wiki should be more geared towards detailing the theme's variable structure and the AT theme config.

[kirsty-hames]

That makes sense thanks. Always good to avoid any duplication.

[kirsty-hames]

Hey @guywillis, I'm just coming back to your suggestion on this and gearing it towards AT users. I think the README and example.json is substantial enough for those who are developing within the FW. I propose the following amends to the wiki:

• remove any README duplication
• overview of AT Theme picker
• overview of AT Theme settings
• overview of AT Theme presets

The overviews can include some 'how to' and screenshots to make it more AT user friendly.

It would be good if we could add help links into the AT at the relevant points that direct you to the wiki also... I'll mention this in the next AT development chat.

[guywillis]

I propose the following amendments to the vanilla repo to improve documentation:

• Remove custom class definitions from example.json and move to wiki page. Add link in readme and example.json to wiki page
• Remove json property explanations from readme and move to wiki page. Add link in readme and example.json to wiki page
• Remove json config comments from example.json
• Overhaul vanilla wiki home page, remove out of date content, convert it to be a menu to improve wiki UX
• Update wiki custom classes page to reflect recent amendments
• Update visual enhancements page to reflect recent json configuration amendments
• Remove usage and tips page

[jroed]

Thank you for working on improving the documentation. I'm a new user, much appreciated!

I would like to propose the following:

• Common classes:
  • I understood that the classes work only with bg-color, such as bg-color black. May be by adding some more structure to reflect the syntax it would become clearer that the other classes are values for bg-color. Otherwise people think that they can use them on their own.
  • Also add a sentence that common classes can be used everywhere, e.g. in pages, articles, blocks, components.
  • Add types and acceptable values of the classes as in the README
• _isDividerBlock: The wiki mentioned before that @background-color-inverted and @foreground-color-inverted are used "but there is no styling attached to this class". This is irritating. Could defaults be defined in _colors.less or better explained how to use _isDividerBlock?
• Add a reminder about example.json in wiki page
• Visual Enhancements:
  • Add related file names that should be edited in the framework (contentObjects.json etc.)

Version
FW 5.22.8 Vanilla 7.1.1

[guywillis]

Thank you for your comments and feedback, @jroed

I've been going through the documentation in Vanilla and the wiki and it would be great to get your feedback on the changes and any comments you may have for further improvements you would recommend.

[jroed]

@guywillis sure thing. I have the following suggestions.

Custom Classes

• Add a notice that classes need to be added to _classes or _htmlClasses with syntax example.

Global common classes

• In what sense are the optional classes optional? Without them bg-color does nothing right? Maybe they could be called differently.
• Regarding background colors you mentioned 'blocks' but they can also be applied to content objects, articles and components. Is there a general term for all content objects, articles, blocks, and components?
• Different spelling of 'color' and 'colour' in file names and documentation. I would prefer a coherent convention.

Content Object

• Add notice that contentObjects.json file needs to be edited.
• header-color and hide-page-header did not work for me when I added them to contentObjects.json. Can you confirm that the commands are correct? Can you test if they work for you?
• header-color black might be missing.

Block

• Add notice that blocks.json file needs to be edited.
• If classes are mutually exclusive, there are limitations on how they can be combined, how classes take precedence over each other (e.g. extend-container and extend-content-container) or there are any restrictions in the order of arguments that need to be considered please mention them.

Component

• Add notice that components.json file needs to be edited.
  Columns:
• Add generic syntax in the beginning, something like 'col-<size>-<n> where <size> is xs, sm, md, lg or xl and <n> is an integer number between 1 and 12'.
• Add notice that user shall use 12 for full width.
• Describe how classes interact with "_layout".
• Change sentence 'Multiple column classes can be defined on a singular component...' to mean multiple column classes with different sizes. So not col-lg-8 col-lg-7 but rather col-md-8 col-lg-7.
  Common:
• comp-header-bg-color does extend to all of the component instead of just the header for me. Can you confirm that the commands are correct? Can you test if they work for you?
• Other optional classes such as comp-header-bg-color background might be missing.

Content

• Add syntax example.

[jroed]

This wiki page about styling your course mentions the Vanilla theme and might also need a revision.

[guywillis]

Great suggestion @jroed

A couple of comments to highlight:

Content Object

• header-color and hide-page-header did not work for me when I added them to contentObjects.json. Can you confirm that the commands are correct? Can you test if they work for you?
  • Both classes did work for me in the latest version. How are you applying these in your build?
• header-color black might be missing.
  • It is missing, new issue created

Components

• comp-header-bg-color does extend to all of the component instead of just the header for me. Can you confirm that the commands are correct? Can you test if they work for you?
  • Should only apply to the component header. If this class is applied to a text component, however, it will appear as if the background colour applies to the entire component.
• Other optional classes such as comp-header-bg-color background might be missing.
  • This mixin only currently supports the black value. New issue has been created

I believe I have addressed the rest of your feedback from this comment but please do let me know if I can add further clarity to the wiki.

The framework wiki is definitely in need of an update.

[jroed]

@guywillis please see my comments below.

Content Object

header-color and hide-page-header: Both classes did work for me in the latest version. How are you applying these in your build?

I tested it again. First I thought that the classes would affect the box menu as described here. I understood now that the classes won't affect the box menu as it only lists the content objects but does not display them. Still it is confusing as there is seemingly some overlap for the classes for _classes in contentObjects.json. Maybe it could be clarified in the wiki what the classes affect and what not. hide-page-header and header-color background, transparent-dark and transparent-light worked for me but not header-color black.
Using FW 5.22.8.

Components

comp-header-bg-color: If this class is applied to a text component, however, it will appear as if the background colour applies to the entire component.

Yes, I tested it with a text component. Is that intended behavior? If I read header I think of headers in the sense of HTML headers. For that reason I expected comp-header-bg-color to only affect the header text. I understand that in most components the styling is also applied to the body. If that's what is intended then maybe a different name could be chosen to reflect what is affected by this class. Otherwise some screenshot might help to clarify. But for the text component I would expect in any case that only the header is affected as otherwise there is no difference to bg-color.

[jroed]

@guywillis I have the following suggestions.

Structure

Fonts

• Add reference to less file location in the following sentence 'and imported in _font-config.less' by something like 'and imported in _font-config.less (for its file location please see below in the Less section)'.

Less

• There are other files in the project folder next to theme-extras.less. Should they not also be listed? (BTW why is this folder called project?)

Templates

• The text for Templates should be expanded. I don't really understand what is meant with template here and how it works.

General comments

• What about the schema folder? If usually users should not need to edit these files I would still list it and add a similar notice as for the JS folder.

[guywillis]

@jroed

Content object

I understood now that the classes won't affect the box menu as it only lists the content objects but does not display them. Still it is confusing as there is seemingly some overlap for the classes for _classes in contentObjects.json

Agreed that it is confusing there's an overlap of the _classes property where it applies classes to both the menu item and the page. I will make this an action to improve.

header-color background, transparent-dark and transparent-light worked for me but not header-color black.

The header-color black combination was missing from the theme and only recently added in v8.1.1

Components

Is that intended behavior? If I read header I think of headers in the sense of HTML headers.

It is intended behaviour, yes. The components are split into a couple of sections, a component header template and a plugin widget contained within the associated template file. The {{> component this}} line within the Narrative template file renders the 'header' of the component using the component template.

But for the text component I would expect in any case that only the header is affected as otherwise there is no difference to bg-color.

There is a small but subtle difference between the two that's mainly exposed in full width components. This issue outlines the difference. I will add a task to the list to explain the difference between the two in the comp-header-bg-color custom class section.

Structure

There are other files in the project folder next to theme-extras.less.

Yes. A task has been added.

BTW why is this folder called project?

Predominately to suggest to users that this is the location to write project specific code. With the cascading nature of CSS overrides should preferably be written further down the folder tree to ensure they apply correctly. This name tries to subtlety promote this.

The text for Templates should be expanded. I don't really understand what is meant with template here and how it works.

Agreed that it can and should be expanded

What about the schema folder?

Agreed that it should be described

Task list:

• Custom classes - Clarify whether classes applied to contentObjects are directed at the menu item or the page
• Custom classes - Clarify comp-header-bg-color custom class effects
• Structure - Write up description regarding other files listed in project folder
• Structure - Expand on template section to add further clarification
• Structure - Provide a write up on schema files

[jroed]

@guywillis Thank you for your answers and your continuing efforts to create awesome wiki pages!

I have the following suggestions.

Icons

Adding icons inline

• Would it be possible to have an image next to the Lorem ipsum dolor sit amet <span class='icon icon-arrow-down-2 inline-icon' aria-hidden='true'></span> consectetur adipiscing elit. example to see the output?
• Can the color of the icon be modified via an inline class?
• The image does not seem to fit as it's about 'Presentation Components'.

Icon breakdown

• In the example code icon-arrow-down-2 is mentioned but in the icon list arrow-down-2 is provided as the icon name without the icon- prefix. Maybe it would be better to add the icon- prefix to all names in the list because then users can directly copy the names.
• Why is the Content ID relevant and how is it used?
• Currently the list is sorted by Content ID but it would be better to sort it by icon groups meaning having all types of arrows in one group together for example.
• It's fine to have the image of the icons on top of each section but even better would be to have the individual icon images next to the icon names.
• I'd suggest not to have two blocks of icons (each with the columns icon, CSS class name and content ID) in one table but rather have two separate tables. This would improve readability.

[guywillis]

Thank you for your comments above, @jroed

I have transplanted these into a new issue specifically for vanilla wiki updates as this issue is now closed.

[github-actions]

🎉 This issue has been resolved in version 9.3.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀