Practical Demonstration

Now let’s put theory to practice with a concrete example. For this, I shall provide a condensed walkthrough that’ll highlight the key steps involved in creating my own layer for CtrlSpace, a project navigation and workflow management plugin.

1. Create layer source

First and foremost, you need to create the vimscript source for the new layer under ../layers/ . So for our example, that would be ../layers/ctrlspace.vim .

2. Define layer callback

SpaceVim#layers#ctrlspace#plugins for specifying the plugin included in this layer

for specifying the plugin included in this layer SpaceVim#layers#ctrlspace#set_variable for retrieving layer-local options set by the user

for retrieving layer-local options set by the user SpaceVim#layers#ctrlspace#config for configuring key aspects of the plugin and layer

And now we shall implement them one by one.

3. Specify layer plugins

The CtrlSpace layer contains the single plugin, “vim-ctrlspace”, so we can directly return it.

function! SpaceVim#layers#ctrlspace#plugins() abort

return [ ['vim-ctrlspace/vim-ctrlspace', {'merged': 0}], ]

" 'merged' is an optimization flag used by the plugin manager

endfunction

For layers with more than one plugin, you’d add all of them to the return list. Note: the second element in each plugin-list is a table of some flags understood by the plugin manager, which we need not be concerned with for this guide.

4. Get layer-local options

In our layer example, the option home-mapping-key , which defaults to <C-Space> , sets the main keybinding for invoking CtrlSpace. Because for many users <C-Space> may already be occupied, especially if they hail from a non-English speaking part of the world, this option allows them to change their home-mapping-key to something more suitable, such as <C-p> .

The get function looks for a string name matching home-mapping-key (2nd arg) in the list of layer-local variables (1st arg) set by the user in their init.toml . If it exists, it will set s:home_mapping_key to the value defined by the user in their TOML config; if not, it will fall back to an appropriately initialized default value passed as the 3rd argument to get .

5. Final layer configurations

a) main plugin settings

With the plugin made available, and user configurations parsed, the plugin can finally be appropriately configured.

Often times, layer options are made available to user to begin with due to the existence of the corresponding settings in your layer plugin(s) of choice. So in such cases, just hook them up directly like we did above.

b) other plugin settings

An important setting for CtrlSpace is its glob command, which determines how it collects and populates the files list for new projects.

The above snippet also conveniently showcases SpaceVim’s logging API, which has 3 levels: info , warn and error . The runtime log (shown below) can be viewed with the command :SPRuntimeLog or with the SPC h L keybinding.

SpaceVim Runtime Log (lines 9–11 logged by the CtrlSpace layer)

c) SpaceVim keybindings

Here’s also a good place to configure keybindings to integrate your plugins’ functionalities into SpaceVim.

To define a SPC -prefixed keybinding for some functionality of your layer, SpaceVim#mapping#space#def is used. This function takes 5 arguments:

the mapping type

the input keys to follow the SPC -prefix

-prefix the command to be executed

a description for the key-mapped command, which will be displayed in SpaceVim’s discoverable guide prompt

an integer flag specifying the type of command (i.e. a : command, <plug> mapping, etc.) of the 3rd argument

The most commonly used function you’ll be using will be SpaceVim#mapping#space#def . But mapping APIs for other prefixes (such as <Leader> ) also exist under SpaceVim#mapping# .

6. Test the new layer

To enable your newly created layer, just add in in your init.toml . For my example, the name of the layer to be enabled is of course "ctrlspace" . I change the main mapping key for invoking the plugin from its default of <C-Space> to <C-p> , and also enable the SpaceVim styled keybindings, some of which you saw defined above.

If all went well, then you should have just created a fully functional new SpaceVim layer, much like the CtrlSpace example we went through above.