Tip #162: write plugin with explorer like interfaces

Several plugins use a text base interface based on a special buffer, this is the case of the standard explorer plugin, several bufexplorer plugins, the option buffer and others...
Here is a quick guide in how to do this


Writing a special buf script
| using a special buffer is a common technic when writing Vim scripts, it is used by
| explorer, bufexplorer, DirDiff...
| I'm currently writing one for TagsBase.vim
| http://vim.sourceforge.net/scripts/script.php?script_id=100
| and I'll use this document to take notes on how to do it.
|

Setting up the buffer
Opening the window TODO

Using a setup function
Principle
| we can use a specific function to open and setup the special buffer. s:SetupBuf()
Setup Function advantage
| since the command will be defined in the main script you
| can use script local functions
Using a special filetype
Principle
| we can also use a new filetype and distribute a syntax and an ftplugin for this
| filetype, the only thing needed in this case is to set the
| filetype after creating the buffer
Filetype advantage
| better separations of different parts of your script. If
| the main function of your plugin is not to have this
| special buffer then it is nice to avoid clutering it.
Things which needs to be done to setup the buffer
The buffer should not be listed and does not correspond to a file
* setlocal buftype=nofile
- options always local to buffer
* set nobuflisted
* set bufhidden=delete
* set nomodifiable
Setup the syntax for this buffer
| see :help syntax
| This is usually done in two steps, first describe the
| syntax groups using :syn commands then setup the
| hilighting using :hi def link commands.  Usually it is
| best to link the newly defined groups to predefine ones in
| order to make the coloring work fine with colorschemes.
| You'll find the list of predefined group by doing:
| :help group-name
Setup the special mappings
| since we have chosen to use the set nomodifiable option
| our buffer will never be in insert mode. All our mapping
| are in Normal, Visual or operator pending, they should
| therefore use the map, nmap, vmap and omap mapping command
| plus the associated 'nore' version.  I usually find it
| better to use the 'nore' version to avoid surprises due to
| mapping in the user configuration.
|
| We also want our mappings to be local to the special
| buffer so all the commands will use the <buffer> modifier.
|
| Finally we want our mappings not to polute the status bar
| so we use the <silent> modifier
|
| Putting all this together we end up with mapping commands
| which look like:
| noremap <buffer> <silent> {lhs} {rhs}
Setup the special command
| we will then setup special commands for this buffer.  Like
| for the mapping there are some precautions to take:
| we don't want an error message if the command is defined
| twice so we use the command! variant.
| We want a command local to our buffer wo we use the
| -buffer attribute.  The rests of the command attributes
|  and options depend on the actual command.
|  So our commands look like:
|  command! -buffer {attr} {cmd} {rep}
|  where attr is optional.


<<Dutch spelling checker | Toggle Search Highlighting >>

Additional Notes