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 notifications@github.com 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 https://github.com/Microsoft/vscode/issues/272#issuecomment-169033971.

Raymond Camden, Developer Advocate for MobileFirst at IBM

Email : raymondcamden@gmail.com 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 MarkdownEditor and a HTMLEditor 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.

[daviwil]

I might have misunderstood the intent of this feature. After re-reading your initial comments, it seems like this is to allow an extension to provide a new text editor buffer with dynamically-generated, read-only content, sort of like how Visual Studio can give you a C# buffer with class shapes from an assembly generated from its metadata.

I think I was looking at this as a rendered document buffer which appears to be a different thing entirely. It seems that @cfjedimaster's initial request was along these lines as well if I'm understanding it correctly. I suppose we'd need a different API for that?

[cfjedimaster]

Basically, I want to create a panel of content. For my purposes, the content would be something I'd then copy and paste into a blog. So for example, take my source code of and convert it to <html>.

The actual "panel" could be read only or not - it doesn't really matter to me. If it was a basic web view then it should support form fields which in theory makes it writeable, but it wouldn't be an "editor" though.

Does that make sense?

[cfjedimaster]

Btw, if you get Brackets and my HTMLEscape extension, you can see an example of this in action. I don't expect it to work exactly like Brackets of course. :)

[jrieken]

@cfjedimaster Ok, the HTMLEscape extension should be possible with it. The flow could be like so:

(1) register content provider for html-escape-scheme (2) register command that (2.1) takes html from an (active) editor (2.2) generates escaped plain text & stores it along an uri with the afore scheme, like html-escape://this/and/that, (2.3) tells vs code to open that document workbench.openTextDocument(Uri.parse('html-escape://this/and/that'))

[cfjedimaster]

"stores it along an uri" - does this mean I need to take the string and escape it for a URL before doing so? Would I have the limit that URLs normally have in browsers (I forget the exact length).

[jrieken]

It's just that you are responsible for relating the uri to the string content. You don't need to encode it in the uri (for which btw no length contains apply locally), but you could for instance encode an array index, or the uri of the document to generate from etc. Since the uri travels between the main thread and the extension host short is obviously better. Tho, we might derive a UI label from it (TBD).

[cfjedimaster]

Ok. Don't think I grok that 100% quite yet, but when available, I can test. :) As an aside, I'm also happy to test this on a dev build of Code, just let me know. When I was a Brackets user, I used the heck out of my extension as I blog quite a bit.

[jrieken]

In theory you can use it off the PR but I'll ping you once it's in master.

[cfjedimaster]

Thanks!

On Wed, Jan 6, 2016 at 10:14 AM, Johannes Rieken notifications@github.com wrote:

In theory you can use it off the PR but I'll ping you once it's in master.

— Reply to this email directly or view it on GitHub https://github.com/Microsoft/vscode/issues/272#issuecomment-169373515.

Raymond Camden, Developer Advocate for MobileFirst at IBM

Email : raymondcamden@gmail.com Blog : www.raymondcamden.com Twitter: raymondcamden

[fforjan]

so potentially I can reuse the same to have an extension which provide a UML view or any other graphical view of my workspace (as long as it's HTML content)?

[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 notifications@github.com 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 https://github.com/Microsoft/vscode/issues/272#issuecomment-180258436.

Raymond Camden, Developer Advocate for MobileFirst at IBM

Email : raymondcamden@gmail.com 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 notifications@github.com 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 https://github.com/Microsoft/vscode/issues/272#issuecomment-182108020.

Raymond Camden, Developer Advocate for MobileFirst at IBM

Email : raymondcamden@gmail.com 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 raymondcamden@gmail.com wrote:

Thank you - will give this a shot!

On Tue, Feb 9, 2016 at 4:30 PM, Erich Gamma notifications@github.com 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 https://github.com/Microsoft/vscode/issues/272#issuecomment-182108020.

Raymond Camden, Developer Advocate for MobileFirst at IBM

Email : raymondcamden@gmail.com Blog : www.raymondcamden.com Twitter: raymondcamden

Raymond Camden, Developer Advocate for MobileFirst at IBM

Email : raymondcamden@gmail.com 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 raymondcamden@gmail.com 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 : raymondcamden@gmail.com 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 notifications@github.com wrote:

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

— Reply to this email directly or view it on GitHub https://github.com/Microsoft/vscode/issues/272#issuecomment-182388477.

Raymond Camden, Developer Advocate for MobileFirst at IBM

Email : raymondcamden@gmail.com 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