From addd18adbf58825b37bcbd400557572b8e138b27 Mon Sep 17 00:00:00 2001 From: Tim Jacomb Date: Thu, 26 May 2022 21:45:52 +0100 Subject: [PATCH] Add docs --- docs/creating-a-theme.md | 41 ++++++++++++++++++++++++++++++++++++ docs/developer-guide.md | 42 ++++--------------------------------- docs/theme-properties.md | 45 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 90 insertions(+), 38 deletions(-) create mode 100644 docs/creating-a-theme.md create mode 100644 docs/theme-properties.md diff --git a/docs/creating-a-theme.md b/docs/creating-a-theme.md new file mode 100644 index 0000000..fecea6b --- /dev/null +++ b/docs/creating-a-theme.md @@ -0,0 +1,41 @@ +# Creating a theme + +A theme is a Jenkins plugin that includes: + +* 0 or more CSS files +* 0 or more JavaScript files + +Theme discovery in Jenkins uses the [ThemeManagerFactory](https://github.com/jenkinsci/theme-manager-plugin/blob/master/src/main/java/io/jenkins/plugins/thememanager/ThemeManagerFactory.java) +extension point. + +## Getting started + +Create a plugin from the `empty plugin` [Jenkins archetype](https://github.com/jenkinsci/archetypes/). + +You will need to extend/implement: + +* [ThemeManagerFactory](https://github.com/jenkinsci/theme-manager-plugin/blob/master/src/main/java/io/jenkins/plugins/thememanager/ThemeManagerFactory.java) +* [ThemeManagerFactoryDescriptor](https://github.com/jenkinsci/theme-manager-plugin/blob/master/src/main/java/io/jenkins/plugins/thememanager/ThemeManagerFactoryDescriptor.java) +* [UnprotectedRootAction](https://github.com/jenkinsci/jenkins/blob/master/core/src/main/java/hudson/model/UnprotectedRootAction.java) + +Take a look at the [dark-theme-plugin](https://github.com/jenkinsci/dark-theme-plugin) for a sample implementation. + +You can find all the available variables provided by Jenkins core in [theme.less](https://github.com/jenkinsci/jenkins/blob/master/war/src/main/less/abstracts/theme.less). Plugins may also define their own variables so this list may not be complete, but it should cover most of them. + +Don't forget to add `@Extension` to your `descriptor` and `UnprotectedRootAction`. + +Add a symbol to your `descriptor` for a nice short name when using configuration-as-code, e.g. `@Symbol("neo2")`. + +## Testing your theme + +Run `mvn hpi:run` from your plugin directory, that will startup a test instance of Jenkins. + +Visit http://localhost:8080/jenkins in your browser and configure your theme from there. + +### Host your plugin + +Follow the [hosting guide](https://www.jenkins.io/doc/developer/publishing/requesting-hosting/). + +### Let others know about it + +Send a pull request to this plugin's README to add it to the known plugins list (once the plugin is in the Jenkins update center). diff --git a/docs/developer-guide.md b/docs/developer-guide.md index 5d9074e..7596805 100644 --- a/docs/developer-guide.md +++ b/docs/developer-guide.md @@ -1,41 +1,7 @@ -# How to create a theme +# Developer guides -A theme is a Jenkins plugin that includes: +Step-by-step guides to implementing extension points of the Theme Manager plugin. -* 0 or more CSS files -* 0 or more JavaScript files +- [Creating a theme](./creating-a-theme.md) +- [Theme properties](./theme-properties.md) -Theme discovery in Jenkins uses the [ThemeManagerFactory](https://github.com/jenkinsci/theme-manager-plugin/blob/master/src/main/java/io/jenkins/plugins/thememanager/ThemeManagerFactory.java) -extension point. - -## Getting started - -Create a plugin from the `empty plugin` [Jenkins archetype](https://github.com/jenkinsci/archetypes/). - -You will need to extend/implement: - -* [ThemeManagerFactory](https://github.com/jenkinsci/theme-manager-plugin/blob/master/src/main/java/io/jenkins/plugins/thememanager/ThemeManagerFactory.java) -* [ThemeManagerFactoryDescriptor](https://github.com/jenkinsci/theme-manager-plugin/blob/master/src/main/java/io/jenkins/plugins/thememanager/ThemeManagerFactoryDescriptor.java) -* [UnprotectedRootAction](https://github.com/jenkinsci/jenkins/blob/master/core/src/main/java/hudson/model/UnprotectedRootAction.java) - -Take a look at the [dark-theme-plugin](https://github.com/jenkinsci/dark-theme-plugin) for a sample implementation. - -You can find all of the available variables provided by Jenkins core in [theme.less](https://github.com/jenkinsci/jenkins/blob/master/war/src/main/less/abstracts/theme.less). Plugins may also define their own variables so this list may not be complete but it should cover most of them. - -Don't forget to add `@Extension` to your `descriptor` and `UnprotectedRootAction`. - -Add a symbol to your `descriptor` for a nice short name when using configuration-as-code, e.g. `@Symbol("neo2")`. - -## Testing your theme - -Run `mvn hpi:run` from your plugin directory, that will startup a test instance of Jenkins. - -Visit http://localhost:8080/jenkins in your browser and configure your theme from there. - -### Host your plugin - -Follow the [hosting guide](https://www.jenkins.io/doc/developer/publishing/requesting-hosting/). - -### Let others know about it - -Send a pull request to this plugin's README to add it to the known plugins list (once the plugin is in the Jenkins update center). diff --git a/docs/theme-properties.md b/docs/theme-properties.md new file mode 100644 index 0000000..bf7b4cd --- /dev/null +++ b/docs/theme-properties.md @@ -0,0 +1,45 @@ +# Theme properties + +Themes can set properties giving information about themselves. + +This can be useful when interfacing with other libraries like Prism or CodeMirror that have their own theming capability but need to know which theme to use. + +Instead of making a user select their theme for each library, themes can say which ones work best for them + +## Provider guide + +Inside your `#getTheme` method of your `ThemeManagerFactory` call: + +`builder#withProperty(artifactId, propertyName, propertyValue)` + +```java +public class YourThemeManagerFactory { + public Theme getTheme() { + return Theme.builder() + .withCssUrl(getCssUrl()) + .withProperty("prism-api", "theme", "tomorrow") + .build(); + } +} +``` + +The artifactId will be prepended to the property name with a : separator, this is to prevent any clashes between plugins. + +## Consumer guide + +Retrieve the active theme from `ThemeManagerPageDecorator`, a `NoOp` theme will be provided if none is selected. + +```java + +public class YourPluginCode { + public String getThemeName() { + Theme theme = ThemeManagerPageDecorator.get().findTheme(); + return theme.getProperty("prism-api", "theme").orElse("prism"); + } +} + +``` + +## Existing implementations + +- [Prism API](https://github.com/jenkinsci/prism-api-plugin/pull/41) - Uses the `theme` property to select which prism theme should be used by default \ No newline at end of file