[jboss-user] [JBoss Tools] Document updated/added: "Code Assist in JBoss Tools XML and JSP/XHTML Editors"

[Max Andersen]

User development,

The document "Code Assist in JBoss Tools XML and JSP/XHTML Editors", was updated Jan 20, 2010
by Max Andersen.

To view the document, visit:
http://community.jboss.org/docs/DOC-14120#cf

Document:
--------------------------------------------------------------
h2. Versions
The following description relays on JBoss Tools v. 3.1.0.GA and some known issues to implement described in JBoss JIRA for JBoss Tools project (https://jira.jboss.org/jira/browse/JBIDE).
h2. Important things to understand…
The Content Assistant (CA) in JBoss Tools XML and JSP/XHTML Editors is based and fully developed using the WST content assistant functionality. So, there are not many differences on what you see for CA between WST/JST Text Editors and the JBoss ones. The main difference is the content for CA: remember that JBoss Tools Editors CA uses the Knowledge Base plug-in to retrieve the information on the tags, attributes, attribute values and even Expression Language (EL) expressions to be proposed in the CA selector window (See http://www.jboss.org/community/wiki/NewKBplug-inandCodeAssistinJBossTools310M3).

The CA consists of a number of CA-processors; each is responsible to retrieve the information for the dedicated Content Type. Yet another CA-processor (used to be a compound CA-processor) collects the proposals from all the connected CA-processors, merges and sorts the collected proposals to pass the result to the CA. The standard WTP (WST or JST) CA-processors are also connected to this base CA-processor, so the WST CA proposals are also presented in the CA. Due to the JBoss Tools specifics the proposals collected by JBoss Tools CA-processors are more prioritized then the WST ones and in case of having more than one source for the same proposal, for example, the one came from JBoss Tools KB plug-in will be shown rather than the WTP's one.

The CA in JBoss Tools Text editors could be invoked in three ways:
* Manually, by pressing the Ctrl-Space key combination.
* Automatically, by typing one of the characters predefined in the CA-processors loaded for the Content Type of the document is being edited.
* Automatically, by applying one of the numerous kinds of CA-proposals.
The third way is another improvement. For example, when you are selected and applied some attribute proposal n the CA-selector window and if he selected attribute has some predefined values declared in the schema or TLD where it came from than a new CA-selector window will appear offering the possible attribute values to insert. This helps to accelerate the tags and values typing.
h2. Kinds of Proposals
Because of XML nature of all the documents which are to be edited by the JBoss Tools Text Editors the CA is to show the following types of proposals:
* Tags
* Tag names
* Attribute names
* Attribute values
* Expression Language (plain JSF or Jboss EL-expressions)
* Other kinds of specific proposals depending on the context
h2. Proposals for XML/JSP/XHTML Tags
To invoke CA for the XML/JSP/XHTML tags you could press Ctrl-Space while the cursor is placed in text outside of any existing tags or declarations:

Depending on the document Content Type the possible tags (among the other possible proposals) will be search and obtained from the KB-plug-in and shown in the CA selector window.
h2. Proposals for XML/JSP/XHTML Tag Names
There are two ways to invoke the CA:
* Manual: You could press the Ctrl-Space key combination while the cursor is placed in text in tag name region (between the "<"-character and the space separating the tag name from its first attribute).
* Automatic: You could type the "<"-character in text outside of any existing tags or declarations. In this case the CA for tag name proposals will be invoked automatically.

Depending on the document Content Type the possible tags (among the other possible proposals) will be search and obtained from the KB-plug-in and shown in the CA selector window.
h2. Using the Namespaces to propose tag names
*+[Was feature request:  https://jira.jboss.org/jira/browse/JBIDE-4877  completion in xhtml should not require namespace to match on tag]+*
Depending for the Namespaces defined within the tag region visibility you may type "shortened" tag name (without a prefix) and then call the CA by pressing the Ctrl-Space key combination to be proposed with tag names filtered by typed part of tag name.
For example, if "h" prefix defined for tag library with URI "http://java.sun.com/jsf/html" in some rounding tag or in document root tag, you may type "<output" and press Ctrl-Space key combination to be proposed with the tags defined in JSF HTML library which names start with "output" word. If you select one of these tags in CA selector window then the text "output" will be replaced with a full name including prefix of the selected tag. I.e. if you select <h:outputText> tag in CA selector window the text  "<output"  (as described in the example above) will be replaced with the following text: "<h:outputText />".

*+[Was feature request:  https://jira.jboss.org/jira/browse/JBIDE-5381  CA doen't work for elements which defined using default namespace]+*
You may choose default namespace to use within a document or a tag by specifying "xmlns" attribute value. In this case the specified library becomes a "default" schema for the content of the root tag, so the tags defined in the library have to be used without specifying any prefix. For example, you may specify a default schema in tag: "<body xmlns="http://java.sun.com/jsf/html">". In this case you have to use tags from specified library without a prefix:

<body xmlns="http://java.sun.com/jsf/html">
     <f:view>
          <outputText value="Default namespace detection test page" />
      </f:view>
</body>
h2. Proposals for XML/JSP/XHTML Attribute Names
There are two ways to invoke the CA:
* Manual: You could place cursor into a text after a tag name region (but before the tag region ending) or into some attribute name region and then press the Ctrl-Space key combination.
* Automatic: For a numerous tags there are one or more required attributes defined in KB-plug-in. In case of you have selected and applied such kind of tag in the CA selector window a new CA will be invoked to show possible attribute names to be inserted.

Depending on the document Content Type the possible attribute names will be searched and obtained from the KB-plug-in and shown in the CA selector window. The text between the start of the attribute name and the cursor position will be used as a filter.
h2. Proposals for XML/JSP/XHTML Attribute Values
There are two ways to invoke the CA:
* Manual: You could place cursor into a text inside a value of some attribute and press Ctrl-Space key combination.
* Automatic: For a numerous tag attributes there are one or more predefined values defined in KB-plug-in or some kind of dynamic values are possible to use. In case of you have selected and applied such kind of tag attribute in the CA selector window a new CA will be invoked to show possible attribute values to be inserted.

In case of some value/part of value is entered the text between the attribute value start and the cursor position will be used as a filter.
h2. Proposals for XML/JSP/XHTML Expression Language (JSF and/or Seam EL-expressions)
Some Runtimes allow a user to use Expression Language inside the XML, JSP and XHTML pages. Depending on the Content Type of the page there are different regions where the EL-expressions can be used as:
* attribute values: in XML, JSP and XHTML files;
* part of text regions (Default Text): in XML and XHTML files.

The EL-expressions are to be surrounded either by "#{…}", or "${…}"  character sequence. In case of absent EL closing character sequence it will be added to the text automatically after some of EL proposals is applied to the text.

There are two ways to invoke the CA:
* Manual: You could place cursor into a text inside a text between the EL opening and closing character sequences and then press Ctrl-Space key combination.
* Automatic:  You could type one of the CA-auto start characters in inside the EL-expression (in a text or an attribute value region depending on the Content Type). The characters are ".", "[". In this case the CA for tag name proposals will be invoked automatically. Also the CA will be invoked automatically if you type the "{"-character right after the "$"-character or "#"-character.
h2. Other Kinds of Specific Proposals
There are some "utility" CA proposals shown in the CA depending on the Content Type and current context within the document due to help a user to support the document consistency. These are:
* The proposals for ending and closing for the tags have being edited.
* The proposals for insert a new empty EL-expression and to close the EL-expression have being edited (if it’s not closed yet).

These kinds of proposals are added to the CA-selector windows on its invocation by the CA-processors depending on the Content Type and current context.
h2. Known issues to implement
* https://jira.jboss.org/jira/browse/JBIDE-4946: Tool tip for tag/attributes in XHTML editor.
* https://jira.jboss.org/jira/browse/JBIDE-2318: Case Sensitive Code Completion in JSF page editor
* https://jira.jboss.org/jira/browse/JBIDE-3845: Code assist for #{messages['...']} should suggest properties when user types "[".

--------------------------------------------------------------