Eclipse Community Forums: ServerTools (WTP) » Creating a new StructuredEditor

Home » Language IDEs » ServerTools (WTP) » Creating a new StructuredEditor(Looking for directions on how to build an editor for a JSP-like language)

Show: Today's Messages :: Show Polls :: Message Navigator

Creating a new StructuredEditor [message #1027839]

Wed, 27 March 2013 13:34

Iulian Dragos

Messages: 23
Registered: July 2009

Junior Member

I'd like to write an editor for Play2 template files. They have a simple structure, similar to JSP: it's HTML with escapes into Scala code (between `@{ .. }`).

It looks like WTP structured editors are the right way to go about it (I'd like to reuse the HTML functionality such as validation and content assist), but I can't seem to find the Developer's Guide for WTP.

I found this document, but it's almost 8 years old:

http://www.eclipse.org/webtools/wst/components/sse/overview.html

Is there anything else I could look at, besides the source code?

thanks

Report message to a moderator

Re: Creating a new StructuredEditor [message #1028918 is a reply to message #1027839]

Thu, 28 March 2013 23:22

Nick Sandonato

Messages: 126
Registered: July 2009

Senior Member

Hi Iulian,

I'm glad that you have an interest in using the Structured Editor for your implementation. Most of the core information you're looking for is linked from within the overview page that you've already found. As you've noticed, it's a little old. A lot of the core concepts, however, remain intact.

A few years back, we gave a presentation (Building the XML Editor that you've always wanted) at Eclipsecon that you may find useful as a starting point [1]. It has some slides and samples to work with.

I'd start with the page on Editor Configuration [2], which will let you customize the editor you've defined for a specific content type.

Hopefully this helps you in getting started. Please follow up with any questions you may have.
- Nick

[1] http://www.eclipsecon.org/2009/sessions?id=371
[2] http://www.eclipse.org/webtools/wst/components/sse/designs/EditorConfiguration.html

Report message to a moderator

Re: Creating a new StructuredEditor [message #1031857 is a reply to message #1028918]

Tue, 02 April 2013 09:36

Iulian Dragos

Messages: 23
Registered: July 2009

Junior Member

Thank you, I will start with the EclipseCon tutorial (somehow I missed this one).

I already have a question: I'd like to associate my new editor to "*.scala.html", but it looks like the HTML editor (associated to *.html) takes precedence (we have an editor built using jface). Is there a way to change it? The content-type declaration in plugin.xml looks like this:

      <content-type
            base-type="org.eclipse.core.runtime.text"
            file-extensions="html"
            file-names="*.scala.html"
            id="org.scalaide.play2.templateSource"
            name="%templateSourceName"
            priority="high">

Report message to a moderator

Re: Creating a new StructuredEditor [message #1032865 is a reply to message #1027839]

Wed, 03 April 2013 14:31

Iulian Dragos

Messages: 23
Registered: July 2009

Junior Member

I got stuck quite quickly Sad

.

I am familiar with jface editors, and I need a bit of help to map that to the new structured editor terminology.

* what is the relation between content types and partitions?
* what is the relation between document regions, text regions and partitions?

I am also lost on how to provide my own partitioner (or equivalent), for parsing the document into HTML and Scala regions. I'd like to start by having an editor with the default HTML capabilities, and my own syntax highlighter in the Scala areas (for the moment, the delimiters are `@{` and `}`, so parsing would be very easy).

Thanks!

Report message to a moderator

Re: Creating a new StructuredEditor [message #1037857 is a reply to message #1032865]

Wed, 10 April 2013 05:02

Nick Sandonato

Messages: 126
Registered: July 2009

Senior Member

Hi Iulian,

In terms of your content type, you may be able to add a content describer to your content type that might help it with precedence, by returning IContentDescriber.VALID, whereas the content describer for HTML returns IContentDescriber.INDETERMINATE.

> * what is the relation between content types and partitions?

If you're wondering about how a partitioner is chosen based on content types, that comes down to an implementation of org.eclipse.wst.sse.core.internal.document.IDocumentLoader returning a org.eclipse.jface.text.IDocumentPartitioner for getDefaultDocumentPartitioner(). An example of this is org.eclipse.wst.html.core.internal.encoding.HTMLDocumentLoader. The content type is used to find a related org.eclipse.wst.sse.core.internal.ltk.modelhandler.IModelHandler when creating the IDocument in org.eclipse.wst.sse.core.internal.filebuffers.BasicStructuredDocumentFactory. The model handler is what has an association to the document loader.

If you're wondering more about the targets for the extension point "org.eclipse.wst.sse.ui.editorConfiguration", then it's more about how broad the configuration is supposed to cover. Something like the Outline makes sense for it to be associated with the content type for the entire model. On the other hand, content assist or hover information may be more dependent on the particular region of the document. So in this case, we'd associate it with particular partitions.

> what is the relation between document regions, text regions and partitions?

The document is partitioned into regions are given a type, offset, and length. These regions are different from each other for reasons decided by the partitioner. For example, with the HTML partitioner, we have several partitions for things like typical markup (HTML_DEFAULT), JavaScript (SCRIPT), and CSS (Style). By spliting the document up as such, we can define different syntax coloring and content assist providers for those areas. org.eclipse.wst.html.core.internal.text.StructuredTextPartitionerForHTML is the partitioner for HTML documents. Document regions and Text regions are largely independent of partitions, though they tend to fall within a partition. Document regions are the larger semantic unit of the structured document. They might contain something like the entirety of a start tag. Then that document region is made up of text regions. These provide more fine-grained information and notification about the text. An example of this is that a start tag <div> is one document region and it is made up of 3 text regions: tag open, tag name, and tag close. There's no strict rule about how one should structure the document, but there are performance benefits to breaking things up into reasonable regions.

There is a debug tool that is enabled in development mode that might help visualize how a document is split up. If you open a structured text editor on an HTML document, there will be an item in the status line with brackets surrounding the offset of the cursor in the document. Double clicking that will bring up the dialog. It provides all kinds of information about partitions, document regions, content types, and indexed regions.

Hopefully this is helpful. Sorry for the delayed response.

Report message to a moderator

Re: Creating a new StructuredEditor [message #1038008 is a reply to message #1037857]

Wed, 10 April 2013 09:26

Iulian Dragos

Messages: 23
Registered: July 2009

Junior Member

Nick Sandonato wrote on Wed, 10 April 2013 01:02

Hi Iulian,

In terms of your content type, you may be able to add a content describer to your content type that might help it with precedence, by returning IContentDescriber.VALID, whereas the content describer for HTML returns IContentDescriber.INDETERMINATE.

Thanks, I will try that.

Quote:

> * what is the relation between content types and partitions?

If you're wondering about how a partitioner is chosen based on content types, that comes down to an implementation of org.eclipse.wst.sse.core.internal.document.IDocumentLoader returning a org.eclipse.jface.text.IDocumentPartitioner for getDefaultDocumentPartitioner(). An example of this is org.eclipse.wst.html.core.internal.encoding.HTMLDocumentLoader. The content type is used to find a related org.eclipse.wst.sse.core.internal.ltk.modelhandler.IModelHandler when creating the IDocument in org.eclipse.wst.sse.core.internal.filebuffers.BasicStructuredDocumentFactory. The model handler is what has an association to the document loader.

This could be what I was looking for. Basically, I wanted to know how to "tie the knot". What I need to do is fairly simple:

- open a document that contains HTML with escape sequences
- partition it according to my rules in HTML and "scriptlets"
- re-use the syntax coloring/content assist/validation for the HTML regions
- implement syntax coloring/content assit/validation for my scriptlets

If I understand correctly, the document loader lets me define a partitioner that "understands" my document. This partitioner should return the HTML "content-type" for the HTML partitions (using the exact same names as the WTP HTML partitioner), and new partition types for my scriptlets. Later on, I can associate them with my own implementations of semantic actions.

I am still fuzzy about IModelHandler. What is it about?

Quote:

> what is the relation between document regions, text regions and partitions?

The document is partitioned into regions are given a type, offset, and length. These regions are different from each other for reasons decided by the partitioner. For example, with the HTML partitioner, we have several partitions for things like typical markup (HTML_DEFAULT), JavaScript (SCRIPT), and CSS (Style). By spliting the document up as such, we can define different syntax coloring and content assist providers for those areas. org.eclipse.wst.html.core.internal.text.StructuredTextPartitionerForHTML is the partitioner for HTML documents. Document regions and Text regions are largely independent of partitions, though they tend to fall within a partition. Document regions are the larger semantic unit of the structured document. They might contain something like the entirety of a start tag. Then that document region is made up of text regions. These provide more fine-grained information and notification about the text. An example of this is that a start tag <div> is one document region and it is made up of 3 text regions: tag open, tag name, and tag close. There's no strict rule about how one should structure the document, but there are performance benefits to breaking things up into reasonable regions.

I see, but I'm less clear about where does this division play a role? I understand that text regions are used for coloring, am I correct? I'd like to understand the rationale for having two different concepts. Right now, I see things like:

- partitions: used mainly to associate content assist, auto-edits, hovers, etc. with that part of the document
- document regions: when are they used?
- text regions: used for syntax coloring (?). Anything else?

Looking at WTP as a platform/framework, I imagine that the way I partition and divide my document in regions and text regions will affect how the framework operates. I'm still trying to grasp what should I do to be a well-behaved participant.

I've been reading a lot of code, but I'm still not seeing clearly how all the pieces fit together. Sorry for bombarding you with questions.

Quote:

There is a debug tool that is enabled in development mode that might help visualize how a document is split up. If you open a structured text editor on an HTML document, there will be an item in the status line with brackets surrounding the offset of the cursor in the document. Double clicking that will bring up the dialog. It provides all kinds of information about partitions, document regions, content types, and indexed regions.

I was using the debug tool, and it is indeed very helpful. Thank you for your patience, and I hope to have something to share very soon!

iulian

Report message to a moderator

Re: Creating a new StructuredEditor [message #1039889 is a reply to message #1038008]

Fri, 12 April 2013 19:07

Nick Sandonato

Messages: 126
Registered: July 2009

Senior Member

Quote:

If I understand correctly, the document loader lets me define a partitioner that "understands" my document.

Correct.

The content types that the partitioner talks about are a bit different than a file's content type. So when the partitioner talks about content types, it means the region types, and there can be many of these. Whereas, a file's content type is an attribute of that file and there is one. Also the partitioner doesn't have to be bound to a particular file content type. An example of this is org.eclipse.jst.jsp.core.internal.text.StructuredTextPartitionerForJSP, which has an embedded partitioner utilizing the HTML Partitioner. This might be a particularly useful example for you, since it sounds similar to what you're trying to accomplish.

Quote:

I am still fuzzy about IModelHandler. What is it about?

The model handler is responsible for making sure the appropriate document and model loaders are associated with a particular content type. There is a registry that maps content types to these handlers. They also handle initialization of your model's INodeAdapterFactory, but that might be a topic for later down the road.

Quote:

I see, but I'm less clear about where does this division play a role? ...

I think it largely comes down to how abstract or specific you want to be about the information in your document. You could certainly have one document region that covered the entirety of your source, and have that split up into text regions. But that may hinder things that require interpreting your document. Maybe an example is the best way to explain this. Let's say that I'm looking all attribute names in an XML document. I could walk each individual text region in the document looking for those that have the ATTR_NAME type. It would work, but I'd be spending a lot of time looking at other regions to. Now if I had these more abstract document regions, I could iterate over those, which there will be fewer of. If I see that it's anything other than a start-tag region, I'd move on; otherwise, I could look through its list of text regions to find ATTR_NAME regions.

It can also be helpful to have these higher-level regions when it comes to associating your model with the document structure. For example, our implementation of the DOM Element node has fields for both document regions that are its start and end tags in the source document.

And as mentioned before, there are performance benefits because we send out notifications when structured document regions change. It may affect the amount of work that the listener has to do if one giant document region is used.

Quote:

I understand that text regions are used for coloring, am I correct?

Both the document region and its text regions are used for coloring. The text region determines the color attribute, but the document and text regions are used to determine the offset and length that needs to be highlighted. This is because the offsets of the text regions are relative to their position within the document region.

No worries about asking questions. Questions are good! Hopefully you've found the information helpful.

[Updated on: Mon, 15 April 2013 00:28]

Report message to a moderator

Previous Topic:	javax.servlet.ServletException
Next Topic:	resolveBinding return null

Goto Forum:

-=] Back to Top [=-

[ Syndicate this forum (XML) ] [

]

Current Time: Thu Apr 25 13:31:30 GMT 2024

.:: Contact :: Home ::.

Breadcrumbs

Sign up to our Newsletter