oh-my-posh/website/docs/contributing/segment.mdx

175 lines
4 KiB
Plaintext
Raw Normal View History

2020-10-06 12:01:42 -07:00
---
2022-04-20 09:43:59 -07:00
id: segment
2020-10-06 12:01:42 -07:00
title: Add Segment
sidebar_label: Add Segment
---
## Create the logic
2022-01-26 06:54:36 -08:00
Add a new file in the `./src/segments` folder: `new.go`.
Ensure `New` is a single verb indicating the context the segment renders.
2020-10-06 12:01:42 -07:00
You can use the following template as a guide.
```go
2022-03-10 07:59:42 -08:00
package segments
2020-10-06 12:01:42 -07:00
import (
"oh-my-posh/environment"
"oh-my-posh/properties"
)
type New struct {
props properties.Properties
env environment.Environment
2021-11-22 04:27:04 -08:00
Text string
2020-10-06 12:01:42 -07:00
}
const (
2021-11-22 04:27:04 -08:00
//NewProp enables something
NewProp properties.Property = "newprop"
2020-10-06 12:01:42 -07:00
)
func (n *new) Enabled() bool {
2022-03-10 07:59:42 -08:00
return true
2020-10-06 12:01:42 -07:00
}
func (n *new) Template() string {
2022-02-01 05:07:58 -08:00
return " {{.Text}} world "
2020-10-06 12:01:42 -07:00
}
func (n *new) Init(props properties.Properties, env environment.Environment) {
2020-10-06 12:01:42 -07:00
n.props = props
n.env = env
2022-03-10 07:59:42 -08:00
n.Text = props.GetString(NewProp, "Hello")
2020-10-06 12:01:42 -07:00
}
```
When it comes to icon Properties, make sure to use the UTF32 representation (e.g. "\uEFF1") rather than the icon itself.
2020-10-16 11:07:38 -07:00
This will facilitate the review process as not all environments display the icons based on the font being used.
You can find these values and query for icons easily at [Nerd Fonts][nf-icons].
2020-10-06 12:01:42 -07:00
For each segment, there's a single test file ensuring the functionality going forward. The convention
2022-01-26 06:54:36 -08:00
is `new_test.go`, have a look at [existing segment tests][tests] for inspiration. Oh My Posh makes
2021-11-22 04:27:04 -08:00
use of the test tables pattern for all newly added tests. See [this][tables] blog post for more information.
2020-10-06 12:01:42 -07:00
## Create a name for your Segment
[`segment.go`][segment-go] contains the list of available `SegmentType`'s, which gives them a name we can map from the
`.json` [themes][themes].
Add your segment.
```go
// NEW is brand new
NEW SegmentType = "new"
2020-10-06 12:01:42 -07:00
```
## Add the SegmentType mapping
Map your `SegmentType` to your Segment in the `mapSegmentWithWriter` function (respect the alphabetical order).
2020-10-06 12:01:42 -07:00
```go
NEW: &New{},
2020-10-06 12:01:42 -07:00
```
## Test your functionality
2021-02-27 07:41:50 -08:00
Even with unit tests, it's a good idea to build and validate the changes:
2020-12-22 10:31:20 -08:00
2020-10-06 12:01:42 -07:00
```shell
go build -o $GOPATH/bin/oh-my-posh
```
## Add the documentation
2022-04-20 09:43:59 -07:00
Create a new `markdown` file underneath the [`docs/docs/segments`][docs] folder called `new.md`.
2020-10-06 12:01:42 -07:00
Use the following template as a guide.
````markdown
---
id: new
title: New
sidebar_label: New
---
## What
Display something new.
## Sample Configuration
```json
{
"type": "new",
"style": "powerline",
2020-10-15 23:37:43 -07:00
"powerline_symbol": "\uE0B0",
2020-10-06 12:01:42 -07:00
"foreground": "#193549",
"background": "#ffeb3b",
"properties": {
2020-10-16 11:07:38 -07:00
"newprop": "\uEFF1"
2020-10-06 12:01:42 -07:00
}
}
```
## Properties
2020-10-16 11:07:38 -07:00
- newprop: `string` - the new text to show - defaults to `\uEFF1`
2020-10-06 12:01:42 -07:00
````
## Map the new documentation in the sidebar
Open [`sidebars.js`][sidebars] and add your document id (`new`) to the items of the Segments category.
2020-12-06 13:03:40 -08:00
## Add the JSON schema
Edit the `themes/schema.json` file to add your segment.
At `$.definitions.segment.properties.type.enum`, add your `SegmentType` to the array:
```json
new,
```
At `$.definitions.segment.allOf`, add your segment details:
2020-12-14 03:09:23 -08:00
2020-12-06 13:03:40 -08:00
```json
{
"if": {
"properties": {
"type": { "const": "new" }
}
},
"then": {
"title": "Display something new",
"description": "https://ohmyposh.dev/docs/new",
"properties": {
"properties": {
"properties": {
2022-03-10 07:59:42 -08:00
"newprop": {
2022-03-10 12:08:19 -08:00
"type": "string",
2021-11-22 04:27:04 -08:00
"title": "New Property",
"description": "the default text to display",
"default": "Hello"
2020-12-06 13:03:40 -08:00
}
}
}
}
}
}
```
2020-10-06 12:01:42 -07:00
## Create a pull request
And be patient, I'm going as fast as I can 🏎
2021-02-15 23:36:37 -08:00
[segment-go]: https://github.com/JanDeDobbeleer/oh-my-posh/blob/main/segment.go
[themes]: https://github.com/JanDeDobbeleer/oh-my-posh/tree/main/themes
2022-05-12 22:54:59 -07:00
[docs]: https://github.com/JanDeDobbeleer/oh-my-posh/tree/main/website/docs/segments
[sidebars]: https://github.com/JanDeDobbeleer/oh-my-posh/blob/main/website/sidebars.js
2020-10-16 11:07:38 -07:00
[nf-icons]: https://www.nerdfonts.com/cheat-sheet
2022-01-27 03:15:53 -08:00
[tests]: https://github.com/JanDeDobbeleer/oh-my-posh/blob/main/src/segments/az_test.go
2021-11-22 04:27:04 -08:00
[tables]: https://blog.alexellis.io/golang-writing-unit-tests/