Supporting creating a new document virtually

[cfjedimaster]

Extensions should be able to create a new panel/document and open it in the editor, much like how markdown preview does.

[jrieken]

@cfjedimaster The idea is that you can register for a URI-scheme, like foo and that someone will ask you provide the contents for foo://something/anotherthing when a corresponding call to openTextDocument is made.

Those document must not be able to be saved and can be readonly by some mechanism (TBD). Will that be enough for your needs?

[cfjedimaster]

Sure.

[jrieken]

Idea is to allow to contribute content (?) provider, like so

interface TextDocumentContentProvider {
  open(uri:Uri):Thenable<string|Buffer>;
  close(uri:Uri):Thenable<any>;
}

registerTextDocumentProvider(scheme | pattern, provider);

[cfjedimaster]

Open would require a uri? Does that mean I'd need to save the text locally first?

[jrieken]

no, it's more to allow to define your own space using a scheme, like so myextension://project1/path/to/fake/resource would be a valid Uri and it would be up to you to resolve that somehow, like deriving info from a dll-file or generated markup.

[cfjedimaster]

Ok... I kinda get it. :) I'd love to test this when possible. Let me know.

[jrieken]

I will keep you in the loop once we sketch out the API for this.

[DickvdBrink]

I would love this feature as well :)

[jrieken]

Optimistically scheduling this for Jan ;-)

[daviwil]

I'd love to see this feature happen! Since the Markdown preview is being used as an example, does this mean we'd be able to return HTML as content and have it be rendered correctly for rich output?

cc @dfinke

[jrieken]

Unsure what you mean by output, but a goal is to allow others to generate markdown and have it shown/previewed in VS Code

[daviwil]

Sorry, the term 'output' was a little vague :) To rephrase, I'm asking if this would allow a content provider to return arbitrary (within reason) HTML to be rendered. For example, if I create a mode for editing TODO list files with a special text format, it'd be nice if I could register a content provider that can render some nicely-formatted overview details for the user's TODO items.

Returning Markdown to be rendered could also work but would be less flexible.

[cfjedimaster]

Hmm, I'd keep it "agnostic". Make the "view" a HTML view so I can send
whatever I want, but making it parse Markdown means I'd have to escape if I
didn't want the automatic conversion.

Basically - make it a web view and I can send whatever I want.

On Tue, Jan 5, 2016 at 9:25 AM, Johannes Rieken [email protected]
wrote:

Unsure what you mean by output, but a goal is to allow others to generate
markdown and have it shown/previewed in VS Code

—
Reply to this email directly or view it on GitHub
#272 (comment).

Raymond Camden, Developer Advocate for MobileFirst at IBM

Email : [email protected]
Blog : www.raymondcamden.com
Twitter: raymondcamden

[dfinke]

One possibility could be someone editing a CSV file and the VS Code extension would take it as input, render it through d3.js creating a visual and displaying the resulting HTML in the view

[jrieken]

Great ideas. I will spin it around with the team. We do have a Markdown_Editor_ and a HTML_Editor_ so it shouldn't be too hard.

[sergey-tihon]

It allows things like ionide-webview https://twitter.com/IonideProject/status/648945352100421632

[Krzysztof-Cieslak]

Ionide-webview is very naive - since Atom allows direct DOM access, it's just HTML iframe showing arbitrary webpage.

[tht13]

Being able to pass the view HTML to render would be great, as I'd like to make a extension similar to the Markdown one, which would render ReStructuredText in the preview mode just like parkdown does.

[daviwil]

One potential requirement for this feature is that the content provider should be able to get notifications to refresh itself. @jrieken's proposed API doesn't include that yet, but is it possible that this could be enabled as well?

[jrieken]

@daviwil that or the other way around where the provider emits an event to tell the editor to refresh. That would cover the case of virtual.md being generated from on_disk.file.

[jrieken]

The mechanics to create a virtual document are in, the preview/render html command is tracked in #1946

[siegebell]

Feature request: API support for making a virtual document preview-only.

This would allow extensions an easy way to provide a mostly-seamless GUI using an HTML preview and web sockets. (Allowing javascript calls directly between the HTML preview and extension might also be nice...)

[jrieken]

@siegebell If you mean 'readonly' by preview then you are ok

[siegebell]

@jrieken no, I mean preview-only: there is a "preview" button at the top-right of a document that allows the user to toggle between preview or code view. I am requesting that this button and its keybinding optionally be disabled so that a [virtual] document is stuck in preview mode.

Use case

I am developing a vscode extension for the Coq Proof Assistant, which allows the user to manually step through each line of their proof scipt and see how their hypotheses and proof obligations change. Such interaction falls outside the debug and compilation metaphor that vscode supports in its interface, so I need to write a custom interface to display this information.

Ideally, vscode would provide me an API to write my own interface extensions. Until it does, I've found a nearly sufficient alternative: display an HTML document in preview mode that interacts with my extension using web sockets to display information as the user steps through their proof. It is even interactive. Virtual read-only documents will make this easier.

But if "toggle preview" is still enabled, the user may accidentally switch to the HTML code and become confused. Since viewing the underlying code is of no use to the user, I am requesting that the API provide me a way of:

1. Turing preview on (versus toggling, which sometimes has strange behavior if the document is already loaded in preview mode from the last session before my extension starts up)
2. Preventing the user from toggling preview for virtual documents that my extension has created.

[jrieken]

no worries, with the new html preview part there is no toggle botton but it will show the path of the URI. having said that, the preview mechanism isn't designed to be a UI extension API. While you can render html and run scripts you should not go crazy in there. The updating (when a document emits a change event) is not built/tested for high frequency of changes

[cfjedimaster]

I believe that this is now implemented in the Insider build. By any chance is there a sample extension that demonstrates this?

[egamma]

@jrieken suggest to add a sample in https://github.com/Microsoft/vscode-extension-samples

[jrieken]

@cfjedimaster As long as we don't have a sample you should check with our api-test: https://github.com/Microsoft/vscode/blob/master/extensions/vscode-api-tests/src/commands.test.ts#L42

[cfjedimaster]

Hmm, I appreciate the link, but it doesn't make much sense to me yet how I
would use it. I'm willing to wait though till it is documented more. :)

On Fri, Feb 5, 2016 at 3:01 AM, Johannes Rieken [email protected]
wrote:

@cfjedimaster https://github.com/cfjedimaster As long as we don't have
a sample you should check with our api-test:
https://github.com/Microsoft/vscode/blob/master/extensions/vscode-api-tests/src/commands.test.ts#L42

—
Reply to this email directly or view it on GitHub
#272 (comment).

Raymond Camden, Developer Advocate for MobileFirst at IBM

Email : [email protected]
Blog : www.raymondcamden.com
Twitter: raymondcamden

[egamma]

I've added a sample that illustrates how to use TextContentProviders and the vscode.previewHtml commands.

Pls see: https://github.com/Microsoft/vscode-extension-samples/blob/master/textdocumentprovider-sample/README.md

[cfjedimaster]

Thank you - will give this a shot!

On Tue, Feb 9, 2016 at 4:30 PM, Erich Gamma [email protected]
wrote:

I've added a sample that illustrates how to use TextContentProviders and
the vscode.previewHtml commands.

Pls see:
https://github.com/Microsoft/vscode-extension-samples/blob/master/textdocumentprovider-sample/README.md

—
Reply to this email directly or view it on GitHub
#272 (comment).

Raymond Camden, Developer Advocate for MobileFirst at IBM

Email : [email protected]
Blog : www.raymondcamden.com
Twitter: raymondcamden

[cfjedimaster]

Should this work in the most recent mainline release? I'm getting errors
when I try it:

Activating extension eg2.vscode-css-properties failed: Cannot find module
'/Users/raymondcamden/Downloads/vscode-extension-samples-master/textdocumentprovider-sample/out/src/extension'.
Activating extension eg2.vscode-css-properties failed: Cannot find
module
'/Users/raymondcamden/Downloads/vscode-extension-samples-master/textdocumentprovider-sample/out/src/extension'

On Wed, Feb 10, 2016 at 7:17 AM, Raymond Camden [email protected]
wrote:

Thank you - will give this a shot!

On Tue, Feb 9, 2016 at 4:30 PM, Erich Gamma [email protected]
wrote:

I've added a sample that illustrates how to use TextContentProviders and
the vscode.previewHtml commands.

Pls see:
https://github.com/Microsoft/vscode-extension-samples/blob/master/textdocumentprovider-sample/README.md

—
Reply to this email directly or view it on GitHub
#272 (comment).

Raymond Camden, Developer Advocate for MobileFirst at IBM

Email : [email protected]
Blog : www.raymondcamden.com
Twitter: raymondcamden

Raymond Camden, Developer Advocate for MobileFirst at IBM

Email : [email protected]
Blog : www.raymondcamden.com
Twitter: raymondcamden

[cfjedimaster]

Forgot to run npm install - sorry about that.

On Wed, Feb 10, 2016 at 7:49 AM, Raymond Camden [email protected]
wrote:

Should this work in the most recent mainline release? I'm getting errors
when I try it:

Raymond Camden, Developer Advocate for MobileFirst at IBM

Email : [email protected]
Blog : www.raymondcamden.com
Twitter: raymondcamden

[egamma]

I've also published the sample to the market place just in case.

[cfjedimaster]

WOOT! I have it working. I'm kinda guessing at a few things and it is 99%
your code still, but it is there. I literally just need to polish it up a
bit and then I can publish mine too. :) Thank you so much.

Quick question. This line:

var previewUri =

vscode.Uri.parse('css-preview://authority/css-preview');

How would you describe that URI? This is what I went with but I was just
guessing:

let previewUri =

vscode.Uri.parse('html-escape://cfjedimaster/html-escape');

On Wed, Feb 10, 2016 at 8:04 AM, Erich Gamma [email protected]
wrote:

I've also published the sample to the market place just in case.

—
Reply to this email directly or view it on GitHub
#272 (comment).

Raymond Camden, Developer Advocate for MobileFirst at IBM

Email : [email protected]
Blog : www.raymondcamden.com
Twitter: raymondcamden

[cfjedimaster]

And here it is: https://marketplace.visualstudio.com/items?itemName=raymondcamden.htmlescape-vscode-extension

[egamma]

Cool that it worked for you.

vscode.Uri.parse('html-escape://cfjedimaster/html-escape');

This looks good to me, you define your own URI scheme html-escape and all the rest is yours.

[cfjedimaster]

So 100% of the string is - basically - whatever we want? Well, within reason, and named something at least similar to what it is doing?

[egamma]

Yes, as long as it properly identifies the resource and conforms to an URI.

[dfinke]

@cfjedimaster I ran yo code and updated the package devDependencies for ^0.11.x, also added a "postinstall": "node ./node_modules/vscode/bin/install". Ran npm install.

My extension stills says here is no exported member TextDocumentContentProvider.

I'm missing a step somewhere

[egamma]

Emphasized the missing step to update the engines field in the release notes.