Code Assist in JBoss Tools XML and JSP/XHTML Editors

Version 6

    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).

    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 in 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 comes from JBoss Tools KB plug-in is 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 comes from than a new CA-selector window appears offering the possible attribute values to insert. This helps to accelerate the tags and values typing.

    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

    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) are searched, btained from the KB-plug-in and shown in the CA selector window.

    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 is 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.

    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>

    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 is invoked to show possible attribute names to be inserted.


    Depending on the document Content Type the possible attribute names is 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 is used as a filter.

    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 is 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 is used as a filter.

    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.

    Using the predicates for EL-expression proposals

    [Was bug:  https://jira.jboss.org/jira/browse/JBIDE-3290  sorting/filtering is not updating correctly in code completion of source page in VPE]

    User may use predicative CA for EL-expressions by typing a part of EL-variable name in attribute values of XHTML/JSP pages or text regions of XHTML pages and then pressing the Ctrl-Space key combination. In this case the EL proposals will be shown in CA selector window and the typed word will be used as a filter for EL proposals.

    For example, you may type "ap" and press Ctrl-Space key combination to be proposed with the EL variables whose names start with "ap" (f.e. "applicationContext" EL variable may be proposed). If you select one of these variable in CA selector window then the text "ap" will be replaced with EL variable name surrounded by the EL opening and closing character sequences (for example, "#{applicationContext}").

    Note, that for the text regions of XHTML pages the proposals ordering within the CA selector window will vary depending on the predicate existence. Thus if you press Ctrl-Space key combination when text cursor is placed after a space character or some another non-word character (for example, after a ">"-character - tag closing character), then the tag name proposals will be placed higher in the list of proposals due to allow a user to select faster some tag name to insert. Otherwise, if text cursor is placed right after some word (or placed inside a word within the text) then the EL proposals will be placed higher the list of proposals due to allow a user to select faster an EL-variable to insert.

    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.

    Tooltips

    [Was Feature Request:  https://jira.jboss.org/jira/browse/JBIDE-4946  Tool tip for tag/attributes in XHTML editor.]

    Now the Tooltip window is shown for tags/attributes. The hint text, if exists, is taken from according library.

    Known issues to implement