Skip to content
This repository has been archived by the owner on Jan 24, 2023. It is now read-only.

Commit

Permalink
First pass at customization docs, most of themeing done
Browse files Browse the repository at this point in the history
  • Loading branch information
@richard-cox
richard-cox committed Jul 28, 2020
1 parent 8b9dc27 commit 092bf5f
Show file tree
Hide file tree
Showing 6 changed files with 345 additions and 4 deletions.
2 changes: 1 addition & 1 deletion src/frontend/packages/example-theme/package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
"assets/core": "core/assets",
"assets/favicon.ico": "favicon.ico"
},
"theme":{
"theme": {
"loadingCss": "loader/loading.css",
"loadingHtml": "loader/loading.html"
}
Expand Down
1 change: 1 addition & 0 deletions website/docs/extensions/customizing.md
View file
Original file line number Diff 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
45 changes: 45 additions & 0 deletions website/docs/extensions/frontend.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
30 changes: 29 additions & 1 deletion website/docs/extensions/introduction.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
265 changes: 263 additions & 2 deletions website/docs/extensions/theming.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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);
}
```
6 changes: 6 additions & 0 deletions website/docs/extensions/v4-migration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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...
Expand All @@ -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).

0 comments on commit 092bf5f

Please sign in to comment.