First pass at customization docs, most of themeing done

cloudfoundry · richard-cox · Aug 7, 2020 · Jul 13, 2020 · Jul 13, 2020 · Jul 20, 2020
commit 092bf5f1129606e4a1ba6f4c4ae468e75403f0ad
diff --git a/src/frontend/packages/example-theme/package.json b/src/frontend/packages/example-theme/package.json
@@ -6,7 +6,7 @@
       "assets/core": "core/assets",
       "assets/favicon.ico": "favicon.ico"
     },
-    "theme":{
+    "theme": {
       "loadingCss": "loader/loading.css",
       "loadingHtml": "loader/loading.html"
     }

diff --git a/website/docs/extensions/customizing.md b/website/docs/extensions/customizing.md
@@ -4,6 +4,7 @@ title: Customizing Stratos
 sidebar_label: Customizing Stratos 
 ---
 
+// TODO: RC REMOVE
 
 > This document is out of date and is in the process of being refreshed.
 

diff --git a/website/docs/extensions/frontend.md b/website/docs/extensions/frontend.md
@@ -269,3 +269,48 @@ You should now be able to run Stratos locally and see this new tab on the applic
 
 ![Example tab extension](../images/extensions/tab-example.png)
 
+
+
+
+
+// TODO: RC
+### Adding new Features
+
+Code for new features should be placed within the `custom-src/frontend/app/custom` folder. You can create any sub-folder structure within this folder.
+
+When you perform an `npm install` or explicitly run `npm run customize`, the customize script is run and will symlink the folder `custom-src/frontend/app/custom` to `src/frontend/app/custom`. It will also create a module to import your custom code - this is placed in the file `src/frontend/app/custom/custom-import.module.ts`. You should _not_ edit this file.
+
+Within the `custom-src/frontend/app/custom` folder you must create a module in the file `custom.module.ts` named `CustomModule` - this will be imported into the Stratos application and is the mechanism by which you can add custom code to the front-end.
+
+We currently expose the following extension points in Stratos:
+
+- Changing the component to use for the login screen
+- Adding new items to the side navigation menu
+- Adding new tabs to the Application, Cloud Foundry, Organization and Space views
+- Adding new action buttons to the Application Wall, Application, Cloud Foundry, Organization and Space and Endpoint views
+
+We use Decorators to annotate components to indicate that they are Stratos extensions.
+
+See [Extensions](../extensions/frontend) for more detail and examples of front-end extensions.
+
+// TODO: RC      "assets/core/custom/acme_logo.png": "core/assets/nav-logo2.png"
+
+
+### Changing the Initial Loading Indicator
+
+On slower connections, it can take a few seconds to load the main Javascript resources for Stratos.
+
+In order to give the user some initial feedback that Stratos is loading, a loading indicator is included in the `index.html` file. This gets shown as early as possible, as soon as this main html file has loaded. Once the main code has been fetched, the view refreshes to show the application.
+
+A default loading indicator is provided that can be changed. To do so, create the following two files:
+
+- `custom-src/frontend/loading.css` - CSS styles to be included in a style block in the head of the index page
+- `custom-src/frontend/loading.html` - HTML markup to be included the the index page to render the loading indicator
+
+The files for the default indicator can be found in the `src/frontend/packages/core/misc/custom` folder.
+
+An example of a different loading indicator is included with the ACME sample in `examples/custom-src/frontend`.
+
+The customization task will insert the appropriate CSS and HTML files into the main index.html file when it runs.
+
+Take a look at the template for the `index.html` file in `src/frontend/packages/core/misc/custom/index.html`. The CSS file is inserted where the marker `/** @@LOADING_CSS@@ **/` is and the HTML file where `<!-- @@LOADING_HTML@@ -->` is.
diff --git a/website/docs/extensions/introduction.md b/website/docs/extensions/introduction.md
@@ -2,4 +2,32 @@
 title: Extending Stratos
 sidebar_label: Introduction
 ---
-This document is in progress
+
+Stratos can be customized in a number of ways, from custom branded themes to additional functionality. 
+
+// TODO: RC intro
+// TODO: RC stratos.yaml
+// TODO: RC custom theme
+// TODO: RC custom styles
+// TODO: RC custom assets
+
+> Note - For those with existing customization and are migrating to 4.0 please see our [upgrade guide](/docs/extensions/v4-migration).
+
+## Approach
+
+In order to customize Stratos, you will need to fork the Stratos GitHub repository and apply customizations in your fork. Our aim is to minimize any merge conflicts that might occur when re-basing your fork with the upstream Stratos repository.
+
+Frontend Customizations are placed in angular packages in the folder named `src/frontend/packages`. In the future you will be able to host these packages in npm and bring them into Stratos in the usual npm dependency way. There are no additional processes or build steps required for Stratos to then integrate these packages, all steps will be automatically applied during `npm install` and when `ng build`/`ng serve` run under the hood.
+
+Backend (Jetstream) Customizations are written in go and can be added in `src/jetstream/plugins`. In the future we hope to combine this work with the frontend changes, such that all functionality for
+a feature can be applied to Stratos in a similar way.
+
+## Examples
+
+Basic examples can be found in the Cloud Foundry Stratos repository for [theming](https://github.com/cloudfoundry/stratos/tree/master/src/frontend/packages/example-theme) and [functionality](https://github.com/cloudfoundry/stratos/tree/master/src/frontend/packages/example-extensions).
+
+More advanced, real world examples can be found the in SUSE Stratos repository, again for [theming](https://github.com/SUSE/stratos/tree/master/src/frontend/packages/suse-theme) and [functionality](https://github.com/SUSE/stratos/tree/master/src/frontend/packages/suse-extensions).
+
+## Further Reading
+
+Detailed instructions on how to customize the [theme](/docs/extensions/theming), [frontend functionality](/docs/extensions/frontend) and [backend](/docs/extensions/backend) can be found in this section.
diff --git a/website/docs/extensions/theming.md b/website/docs/extensions/theming.md
@@ -2,13 +2,274 @@
 title: Theming Stratos
 sidebar_label: Theming Stratos
 ---
-This document is in progress
 
 Stratos provides a mechanism for customizing the theme, including:
 
 - Changing the theme colors
 - Changing image assets (favorite icon, login background and logo)
 - Overriding styles
 - Changing the initial loading indicator
+- Applying theme colors to components
 
-The easiest way to create a theme is to create a folder in the `src/frontend/packages` folder.
+Theme's are best encapsulated in a new stratos package, for example like [this](https://github.com/cloudfoundry/stratos/tree/master/src/frontend/packages/example-theme). It should contain a `package.json` file with a `stratos` section which will contain some of the customization hooks (more on this later).
+
+## Colors
+Stratos uses Material Design and the [angular-material](https://material.angular.io/) library. It uses the same approach to theming.
+
+To create your own theme you will need to create a color pallet and provide it to Stratos as a material theme. This theme can also contain
+additional colors that customize core parts of the page (header, side navigator menu, avatar, etc).
+
+To do this create the file `_index.scss` in the root of your theme package. This should contain a Stratos scss function that will return a `theme`
+object via the Stratos helper function `stratos-theme-helper`, for [example](https://github.com/cloudfoundry/stratos/blob/master/src/frontend/packages/example-theme/_index.scss). 
+
+### Core Pallet
+In most cases you will probably want to generate a palette for the primary color for your version of Stratos - an example `custom.scss` for this is shown below:
+
+```
+$acme-primary: (50: #e8eaf6, 100: #c5cbe9, 200: #9fa8da, 300: #7985cb, 400: #5c6bc0, 500: #3f51b5, 600: #394aae, 700: #3140a5, 800: #29379d, 900: #1b278d, A100: #c6cbff, A200: #939dff, A400: #606eff, A700: #4757ff, contrast: (  50: #000000,  100: #000000,  200: #000000,  300: #000000,  400: #ffffff,  500: #ffffff,  600: #ffffff,  700: #ffffff,  800: #ffffff,  900: #ffffff,  A100: #000000,  A200: #000000,  A400: #ffffff,  A700: #ffffff, ));
+$mat-red: ( 50: #ffebee, 100: #ffcdd2, 200: #ef9a9a, 300: #e57373, 400: #ef5350, 500: #f44336, 600: #e53935, 700: #d32f2f, 800: #c62828, 900: #b71c1c, A100: #ff8a80, A200: #ff5252, A400: #ff1744, A700: #d50000, contrast: ( 50: $black-87-opacity, 100: $black-87-opacity, 200: $black-87-opacity, 300: $black-87-opacity, 400: $black-87-opacity, 500: white, 600: white, 700: white, 800: $white-87-opacity, 900: $white-87-opacity, A100: $black-87-opacity, A200: white, A400: white, A700: white, ));
+
+// Create palettes
+$acme-theme-primary: mat-palette($acme-primary);
+$acme-theme-warn: mat-palette($mat-red);
+
+// Create a theme from the palette (secondary theme is the same as the primary in this example)
+$stratos-theme: mat-light-theme($acme-theme-primary, $acme-theme-primary, $acme-theme-warn);
+
+// Create a similar theme but make it for dark mode
+$stratos-dark-theme: mat-dark-theme($acme-theme-primary, $acme-theme-primary, $acme-theme-warn);
+
+```
+
+### Stratos Colors
+
+Additional Stratos colors can be customized by supplying more colors to the `theme` object. Defining these colors here helps reduce the amount of custom SCSS overrides the theme has to use.
+
+> Note - You do not have to specify all of these - defaults will be used if they are not set.
+
+|Property|Description|
+|---|---|
+|app-background-color| Base color to show in the background of the application |
+|app-background-text-color| Color of text when placed on the basic background |
+|side-nav| See [below](/docs/extensions/theming#side-nav-colors) |
+|status| See [below](/docs/extensions/theming#status-colors)|
+|subdued-color| Lighter color meant to be a subdued version of the primary color |
+|ansi-colors| See [below](/docs/extensions/theming#ansi-colors)|
+|header-background-color| Background color for the main stratos header|
+|header-foreground-color| Foreground color for the main stratos |
+|stratos-title-show-text| Boolean - Show `Stratos` or provided title with the large logo in the about page, default log in page, etc |
+|header-background-span|Does the header background color span across the top, or is the sidenav background color used for the top-left portion|
+|underflow-background-color|Background colors to use for things like the about page header (underflow)|
+|underflow-foreground-color|Background colors to use for things like the about page header (underflow)|
+|link-color| Color for hyperlinks|
+|link-active-color| Color of visited hyperlinks|
+|user-avatar-background-color| Background color of the default avatar in the main header|
+|user-avatar-foreground-color| Foreground color of the default avatar in the main header|
+|user-avatar-underflow-invert-colors| Boolean - Invert the user-avatar colors|
+|user-avatar-header-invert-colors| Boolean - Invert the user-avatar colors in the main header|
+|intro-screen-background-color| Color of the background to introduction style screens (log in, log out, etc)|
+
+
+#### Side Nav Colors
+Colors that define how the top level navigation menu on the left of Stratos appears.
+
+|Property|Description|
+|---|---|
+|background| Background color of the side nav|
+|text| Color of text when menu item is not selected|
+|active| Color of background of a selected item|
+|active-text| Color of text of a selected item|
+|hover| Color of background of an item when hovered on|
+|hover-text| Color of text of an item when hovered on|
+
+#### Status Colors
+Colors that are associated with the standard levels of statuses.
+
+|Property|Description|
+|---|---|
+|success||
+|info||
+|warning||
+|danger||
+|tentative||
+|busy||
+|text||
+
+#### Ansi Colors
+Terminal style set of colors to show for logging output.
+
+|Property|Description|
+|---|---|
+|default-foreground||
+|default-background||
+|black||
+|red||
+|green||
+|yellow||
+|blue||
+|magenta||
+|cyan||
+|white||
+
+
+### Dark theme
+
+By default the theme will not contain a dark mode and the UX for enabled/disabling will be hidden.
+
+In order to add a dark mode to your theme an additional `dark` color theme should be provided by the `stratos-theme` theme function in your
+theme's `_index.scss`, for example 
+in [_index.scss](https://github.com/cloudfoundry/stratos/blob/master/src/frontend/packages/example-theme/_index.scss).
+
+```
+@function stratos-theme() {
+  $theme: stratos-theme-helper($stratos-theme);
+  @return (
+    default: create-custom-theme($stratos-theme),
+    dark: create-dark-theme()
+  );
+}
+```
+
+Within the dark theme the default theme's additional Stratos colors can be overwritten.
+
+
+## Images
+
+### Replace Stratos Images
+
+
+
+
+Images that Stratos uses can be overwritten by a theme. To do so the new images should be added to the package and then referenced
+in the theme's `package.json` including the path of the image they overwrite. Below are some prominent examples.
+
+
+|File name|Path|Description|
+|---|---|---|
+|`favicon.ico`|`favicon.ico`|Favorite icon to use|
+|`logo.png`|`core/assets/logo.png`|Logo to use on login screen and about page|
+|`nav-logo.png`|`core/assets/nav-logo.png`|Logo to use in the top-left side navigation for the application logo|
+
+
+> NOTE: The `nav-logo.png` logo should have a height of 36px and a maximum width of 180 pixels. -->
+
+> NOTE: Files written to `core/assets` should be done in one line, see below
+
+Example `package.json`
+
+```
+  "stratos": {
+    ...
+    "assets": {
+      "assets/core": "core/assets",
+      "assets/favicon.ico": "favicon.ico",
+    },
+    ...
+  },
+```
+
+### New Images
+
+When images are used by custom components they should also be referenced in the theme's `package.json`. Whole folders can be included and should
+be written to `core/assets`. When references by the components they use that path `src="/core/assets/custom_image.png"`
+
+```
+  "stratos": {
+    ...
+    "assets": {
+      "local/assets": "core/assets",
+    },
+    ...
+  },
+```
+
+## Fonts
+Any custom fonts used by the theme or extensions can be provided in a similar way to images, the files should be added to the theme's package
+and then referenced in the theme's `package.json`.
+
+```
+  "stratos": {
+    "assets": {
+      ...
+      "assets/fonts": "suse/fonts"
+      ...
+  },
+```
+
+## Styles
+
+We don't generally recommend modifying styles, since from version to version of Stratos, we may change the styles used slightly which can mean any modifications you made will need updating. Should you wish to do so, you can modify these in the same `_index_.scss`. For example the Acme[_index.scss](https://github.com/cloudfoundry/stratos/blob/master/src/frontend/packages/example-theme/_index.scss) imports a file that adds a text color 
+
+```
+body.stratos {
+  .favorite-list {
+    .app-no-content-container {
+      color: $acme-dark-blue;
+    }
+  }
+}
+```
+
+Note that the class `stratos` has been placed on the `BODY` tag of the Stratos application to assist with css selector specificity.
+
+## Loading Indicator
+
+The loading indicator is a page shown immediately when Stratos is visited and before any Angular loads. This helps on slow connections where
+the bulk of content may take longer to download.
+
+To add a loading indicator create a `html` and `css` file in your theme package and then reference them from your theme's `package.json`.
+For example
+
+```
+  "stratos": {
+    ...
+    "theme": {
+      "loadingCss": "loader/loading.css",
+      "loadingHtml": "loader/loading.html"
+    }
+    ...
+  },
+```
+
+## Components
+
+Angular components in your packages can be themed, which provides them access to the theme's colors. To do this, in your extensions package that contains
+the components (this may be different to your theme package), add a `_all-theme.scss` file containing a scss function. This function should be
+referenced in the package's package.json and is called by the Stratos extension mechanism.
+
+The `_all-theme.scss` and `package.json` content may look like below
+
+```
+@mixin apply-theme-suse-extensions($stratos-theme) {
+
+  $theme: map-get($stratos-theme, theme);
+  $app-theme: map-get($stratos-theme, app-theme);
+
+}
+```
+
+```
+  "stratos": {
+    ...
+    "theming": "sass/_all-theme#apply-theme-suse-extensions",
+    ...
+  }
+```
+
+Component theme files can then be defined and their own scss functions being called from `_all-theme.scss`
+
+```
+@mixin apply-theme-suse-extensions($stratos-theme) {
+  ...
+  @include kube-analysis-report-theme($theme, $app-theme);
+  ...
+}
+```
+
+```
+@mixin kube-analysis-report-theme($theme, $app-theme) {
+  $backgrounds: map-get($theme, background);
+  $background: mat-color($backgrounds, card);
+  $background-color:  map-get($app-theme, app-background-color);
+}
+```
diff --git a/website/docs/extensions/v4-migration.md b/website/docs/extensions/v4-migration.md
@@ -7,6 +7,7 @@ In version 4 of Stratos there are breaking customization changes from previous v
 
 These changes allow a much improved approach to extensions by opening the door to npm style plugins.
 
+## Basic Migration Steps
 To aid in migrating we've provided these instructions.
 
 1. Before updating to the latest code...
@@ -28,3 +29,8 @@ To aid in migrating we've provided these instructions.
     - During build time the custom packages will be discovered and output, see section starting `Building with these extensions`. These should contain the modules your require.
 1. Run Stratos your usual way. Ensure you can navigate to all your custom parts.
 1. Once you are happy everything works as intended remove the old `./custom-src` directory and commit you changes.
+
+
+## Custom Theme Colors
+There's now easier ways to customize colors. Previously a lot of custom scss was required to change things like header color, now these
+are included in the core stratos theme as properties. See docs [here](/docs/extensions/theming#customize-theme-colors).
-Original file line number
+Diff line change
@@ Expand Up / @@ -4,6 +4,7 @@ title: Customizing Stratos @@
     sidebar_label: Customizing Stratos
     ---
+    // TODO: RC REMOVE
     > This document is out of date and is in the process of being refreshed.
@@ Expand Down @@