All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog and this project adheres to Semantic Versioning.
Guiding Principles
- Changelogs are for humans, not machines.
- There should be an entry for every single version.
- The same types of changes should be grouped.
- Versions and sections should be linkable.
- The latest version comes first.
- The release date of each versions is displayed.
- Mention whether you follow Semantic Versioning.
Types of changes
Changelog entries are classified using the following labels (from keep-a-changelog):
Addedfor new features.Changedfor changes in existing functionality.Deprecatedfor soon-to-be removed features.Removedfor now removed features.Fixedfor any bug fixes.Securityin case of vulnerabilities.
With the new context and templating capabilities it became quite necessary to access the context and the actual resulting object after template manipulation.
To easily access the banners configuration simply shift+click on your banner row, and the open the developer tools in vscode to see the latest console log with the banner details such as context and resulting row items.
You can now provide a sleep command to your click events.
Example:
explorer:
rows:
- items:
- type: text
text: Click me to run installation
click:
- command:workbench.action.terminal.newWithCwd # open a new terminal
- sleep:3000 # sleep for 3 seconds
- command:workbench.action.terminal.sendSequence:yarn install\u000D # run `yarn install`When passing click directive to an element in your rows and items, you can now pass an array of strings instead of just a string to invoke commands with sequentially.
Example:
explorer:
rows:
- items:
- type: text
text: Click me to run installation
click:
- command:workbench.action.terminal.newWithCwd # open a new terminal
- sleep:3000 # sleep for 3 seconds
- command:workbench.action.terminal.sendSequence:yarn install\u000D # run `yarn install`Fixed vscode.open command file URI
You can now refer to context:__dirname or ${__dirname} anywhere in your config to receive the relative file path - makes it easier to handle assets in included configs.
You can now use templates inside code banner configs to reuse throughout the config.
There are two ways to create templates in your configs: top-level templates, and row-level templates, both function the same way, and can inherit from top to bottom and reference templates inside other templates.
Example:
templates:
colorfulItem:
type: container
style:
display: flex
flex-direction: row
row-gap: 1em
items:
- type: text
text: This is a
- type: text
style:
color: ${color}
text: bright ${color}
- type: text
text: item!
explorer:
rows:
- context:
color: red
items:
- template:colorfulItem
- context:
color: blue
items:
- template:colorfulItemThe above config will be expanded to the following:
explorer:
rows:
- items:
- type: container
style:
display: flex
flex-direction: row
row-gap: 1em
items:
- type: text
text: This is a
- type: text
style:
color: red
text: bright red
- type: text
text: item!
- type: container
style:
display: flex
flex-direction: row
row-gap: 1em
items:
- type: text
text: This is a
- type: text
style:
color: blue
text: bright blue
- type: text
text: item!
In certain cases you'd want to expand the results of a template into the parent array/object.
To do so there are two ways depending on the type of the parent.
To expand the results of a template into an array, use the expand tag in combination with the each directive.
Example:
context:
names:
- Adam
- Bob
- Charlie
templates:
topTemplate:
context:
name: context:name,value
type: text
text: "My name is: ${name}"
explorer:
rows:
- items:
- context:
name: Eli
type: text
text: "My name is: ${name}"
- each:names:topTemplate|expandwill result in:
explorer:
rows:
- items:
- type: text
text: "My name is: Eli"
- type: text
text: "My name is: Adam"
- type: text
text: "My name is: Bob"
- type: text
text: "My name is: Charlie"
To expand the results of a template into an object, use the ... key in any object in combination with a template directive.
context:
colors:
- blue
- green
- red
templates:
colorItem:
style:
color: ${color}
type: text
text: "Color: ${color}"
colorRowItem:
context:
color: context:value
...: template:colorItem
explorer:
rows:
- items:
- context:
value: context:colors[0]
...: template:colorRowItem
- context:
value: context:colors[1]
...: template:colorRowItem
Will result in:
explorer:
rows:
- items:
- style:
color: blue
type: text
text: "Color: blue"
- style:
color: green
type: text
text: "Color: green"A context can be provided to your top-level config or almost anywhere in your config - including templates, and row and item configurations.
Context is provided by the context key in your config or any object in your config.
Context comes with a very simple and powerful way to load and manipulate data in the workspace code banner display.
Context values can be transformed into other values using the various directives available.
Directives are invoked by providing a string in the following format: directiveName:directiveArgument|directiveArgument|...
Available directives:
Read JSON/YAML data from a workspace file and load it or parts of it into the context.
-
json:path|key?|default? -
yaml:path|key?|default?
-
path:string -
key:string- optional -
default:string- optional
Read a text file or parts of it from the workspace and load it into the context.
Load plain-text file content. If line is provided, only that line will be loaded. If lineEnd is provided, all lines from line to lineEnd will be loaded.
file:path|line?|lineEnd?|default?
-
path:string -
line:number- optional -
lineEnd:number- optional -
default:string- optional
Example:
context:
readmeTitle: file:README.md|1
readmeContent: file:README.md|2|5
Read a list of files/folders from the workspace and load it into the context.
files:path|pattern?|default?
-
path:string -
pattern:string -
default:string- optional
The result is an array of objects with the following properties:
[
[name, vscode.FileType], ...
]Example:
context:
packages: files:packages|** # Loads all folders in the packages directory
template:
packageItem:
type: text
text: "Package: packages/${name}"
explorer:
rows:
- items:
- each:packages:packageItem|expand
Load environment variables into the context.
Note: These are VSCode environment variables - not your project's environment variables.
Directive:
env:variableName|default?
Arguments:
-
variableName:string -
default:string- optional
Context can be used to load data from JSON or YAML files, partially or in full.
Example:
context:
user: env:USER
home: env:HOME
defaultUser: env:DEFAULT_USER|defaultUser
Load environment variables from a file.
env-file:path|name?|default?
-
path:string -
name:string- optional -
default:string- optional
context:
env: env-file:.env
env-with-specific-path: env-file:.env|SOME_VAR
env-with-specific-path-and-default: env-file:.env|SOME_VAR|not-found
Include another configuration file.
include:path|key?
-
path:string -
key:string- optional
context:
data: include:other-config.cb
data-with-specific-path: include:other-config.cb|some.data.value
Iterate over an array or object keys and map their values to a template.
each:arrayOrObject:template|expand?
-
arrayOrObject:string -
template:string -
expand:boolean- optional
context:
packages: files:packages|**
template:
packageItem:
type: text
text: "Package: ${name}"
explorer:
rows:
- items:
- each:packages:packageItem|expand
Load a value from the context.
context:key|default?
-
key:string -
default:string- optional
Rows and items can be conditionally shown based on the viewport size.
You can declare a custom reposponive object anywhere in your config and use it in the if-responsive property of any row or item.
# Define a custom responsive object
responsive:
small:
max-width: 280
medium:
min-width: 280
max-width: 600
large:
min-width: 600
explorer:
rows:
- items:
- type: text
text: This will be shown on all viewports
- type: text
text: This will be shown on large viewports
if-responsive: large
- type: text
text: This will be shown small viewports
if-responsive: small
- type: text
text: This will be shown on medium and large viewports
if-responsive: medium,large
responsive object can be provided anywhere throughout your config - for example in rows and items - to override and define a custom responsive object.
Multiple values can be provide to the if-responsive property to match multiple viewports. The values can be comma separated or an array.
You can refresh the data in the configuration by providing an option.refresh property at the top-level of your configuration file.
The refresh property accepts a number in milliseconds or a string in the format of 1m 30s (1 minute and 30 seconds). Supported values are d for days, h for hours, m for minutes, s for seconds, and ms for milliseconds.
Example:
options:
refresh: 1m 30sRows and items can be conditionally shown based on the value of a context key.
You can use the if-context property of any row or item to conditionally show it based on the value of a context key - if the value is truthy the element will show, if the value is falsy the element will not be rendered.
context:
show:
first: truthy
third: truthy
explorer:
rows:
- items:
- type: text
text: This will be shown
if-context: show.first
- type: text
text: This will not be shown
if-context: show.second
- type: text
text: This will be shown
if-context: show.second,show.thirdMultiple values can be provide to the if-context property to match multiple values. The values can be comma separated or an array.
Added CHANGELOG.md to track extension version changes.
CHANGELOG.md is generated using eplog utility that reads version data from this notion notebook and database: https://sklar.notion.site/Code-Banner-Changelog-2e10cc49a57d4ad89fc191d3514f2b2a
Some text properties can now use Smart Text to replace parts of a text string with custom data; for example we can now read package.json values by using $(package.version) in a text property which will be replace with the actual version specified in package.json
Code Banner First Stable Version! 🥳🪅
Local images can be loaded by simply providing a path property