Skip to content

Commit

Permalink
Add vim documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@jaxbot
jaxbot committed Jan 20, 2015
1 parent 606378e commit 7434836
Showing 1 changed file with 236 additions and 0 deletions.
236 changes: 236 additions & 0 deletions doc/browserlink.txt
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,236 @@
*browserlink.txt* Browserlink.vim

===============================================================================
Contents ~

1. Introduction |browserlink-introduction|
2. Live edit CSS |browserlink-live-edit-css|
3. Live evaluate JavaScript |browserlink-live-evaluate-javascript|
4. New: Keep in sync with Chrome Inspector |browserlink-new-keep-in-sync-with-chrome-inspector|
5. How it works |browserlink-how-it-works|
6. Installation and Setup |browserlink-installation-setup|
7. Usage |browserlink-usage|
8. Options |browserlink-options|
9. Notes |browserlink-notes|
10. Shameless plug |browserlink-shameless-plug|
11. References |browserlink-references|

===============================================================================
*browserlink-introduction*
Introduction ~

Browserlink is a live browser editing plugin for Vim. Formerly **brolink.vim**.
Image: (see reference [1])

===============================================================================
*browserlink-live-edit-css*
Live edit CSS ~

Browserlink allows you to live edit CSS files, which are sent to the browser on
change, without reloading or changing the state of the page.

Image: (see reference [2])

===============================================================================
*browserlink-live-evaluate-javascript*
Live evaluate JavaScript ~

Browserlink allows you to evaluate buffers or selections of JavaScript
directly, or even call individual functions within the buffer, for instant
feedback in the browser.

Image: (see reference [3])

===============================================================================
*browserlink-new-keep-in-sync-with-chrome-inspector*
New: Keep in sync with Chrome Inspector ~

The Chrome inspector allows you to set source maps from network resources to
the local filesystem. In the latest version of Browserlink, you can set
>
window.__BL_OVERRIDE_CACHE = true
<
to disable the cache breaker. After setting up Chrome as desired, enable ':set
autoread' and you'll get results like this:

Image: Browserlink.vim staying in sync with Chrome inspector (see reference
[4])

I

===============================================================================
*browserlink-how-it-works*
How it works ~

Browserlink is very simple. The plugin itself hooks autocommands for file
changes (and other things) to the provided functions. The functions connect
through HTTP to a node.js backend, which your webpage connects also to. The
entire process happens extremely fast.

===============================================================================
*browserlink-installation-setup*
Installation and Setup ~

To install, either download the repo, or as I would recommend, use Pathogen
[5].
>
git clone git://github.com/jaxbot/browserlink.vim.git
<
If you haven't already, you'll need to install Node.js [6] (Node is used to
send refresh commands to your page(s))

Lastly, you need some javascript on your page(s) to listen for the refresh
commands. For this there are two options:

1. Add this script to your page(s)
>
<script src='http://127.0.0.1:9001/js/socket.js'></script>
<
1. **OR** Use a GreaseMonkey script to inject the javascript into your
project:

Userscript injection extensions/solutions: _Chromium's built in support [7]_
TamperMonkey Chrome extension [8] * Greasemonkey Firefox extension [9]

Userscript template (update the @match rule [10] to the url of your local
project):
>
// ==UserScript==
// @name Browserlink Embed
// @namespace http://use.i.E.your.homepage/
// @version 0.1
// @description enter something useful
// @match http://localhost/*
// @copyright 2012+, You
// ==/UserScript==
var src = document.createElement("script");
src.src = "http://127.0.0.1:9001/js/socket.js";
src.async = true;
document.head.appendChild(src);
<
I prefer the GreaseMonkey/Userscript method, as it's more universal and I don't
have extra development junk in my projects. But it's totally up to you.

===============================================================================
*browserlink-usage*
Usage ~

Once set up, Vim should now call the Node server whenever you save a .html,
.js, .php, or .css file. Then just load up your web project like normal, and
Vim should send signals over the websocket to reload the pages automatically.
Nifty.

In addition:

':BLReloadPage'

will reload the current pages

':BLReloadCSS'

will reload the current stylesheets

':BLEvaluateBuffer'

will evaluate the current buffer

You can also use be to evaluate selections or buffers,br to reload, andbc to
reload stylesheets manually.

':BLConsole'

An experimental feature that will print out 'console.log' results from the
webpage into a buffer. When in console mode:

- 'i' - shortcut to ':BLEval'
- 'cc' - clears console buffer
- 'r' - refreshes console buffer
- '<CR>' - attempts to load the highlighted trace line

If you want to disable the overriding of 'console.log' on your page, set:
>
window.__BL_NO_CONSOLE_OVERRIDE = true
<
':BLErrors'

Load accumulated Javascript errors of the current session into the quickfix
list

':BLClearErrors'

Reset the error list.

If you want to get super efficient, you can hook an autocmd to when you leave
insert mode (or other times) to reload, say, the stylesheets:

'au InsertLeave *.css :BLReloadCSS'

This function can be easily tweaked to fit your needs/workflow, and I highly
recommend you do so to maximize your utility from this plugin.

===============================================================================
*browserlink-options*
Options ~

'g:bl_no_autoupdate'

If set, Browserlink won't try to reload pages/CSS when you save respective
files.

'g:bl_no_eager'

If set, Browserlink won't autostart the server when a command is run and the
server does not respond.

'g:bl_no_mappings'

If set, Browserlink won't map be, br, and bc commands.

'g:bl_serverpath'

Set if your server is not hosted on 127.0.0.1:9001. You will also need to
change the socket.js file.

'g:bl_urlpaths'

A dictionary defining mappings from URLs to filesystem paths. Set this if you
want to use the quickfix list for pages not accessed via a file://-URL.

'g:bl_pagefiletypes'

A list of filetype strings that should trigger automatic page reloads on write.
Defaults to "['html', 'javascript', 'php']".

===============================================================================
*browserlink-notes*
Notes ~

This is an experimental project, but it works really well for me, and I hope
you enjoy it! I kept the source as simple as possible, and it's pretty easy to
edit to your needs. I'm open to any suggestions, too, so let me know.

===============================================================================
*browserlink-shameless-plug*
Shameless plug ~

I hack around with Vim plugins, so follow me [11] if you're into that kind of
stuff (or just want to make my day) ;)

===============================================================================
*browserlink-references*
References ~

[1] http://jaxbot.me/pics/browserlink_html.gif
[2] http://jaxbot.me/pics/brolinkcss.gif
[3] http://jaxbot.me/pics/brolinkjs.gif
[4] http://jaxbot.me/pics/vim/vim_brolink_sync.gif
[5] https://github.com/tpope/vim-pathogen
[6] http://nodejs.org/
[7] http://www.chromium.org/developers/design-documents/user-scripts
[8] https://chrome.google.com/webstore/detail/tampermonkey/dhdgffkkebhmkfjojejmpbldmpobfkfo
[9] https://addons.mozilla.org/firefox/addon/greasemonkey/
[10] https://developer.chrome.com/extensions/match_patterns
[11] https://github.com/jaxbot

vim: ft=help

0 comments on commit 7434836

Please sign in to comment.