New KB plug-in and Code Assist in JBoss Tools 3.1.0.M3

Version 9

    Since JBoss Tools 3.1.0 M3 there is a new KB (abbreviation from knowledgebase) plug-in which is responsible for providing information about JSF components. This information is used by Code Assist, Validators, DnD dialogs, etc in JSP/XHTML editors.

     

    1. Types of resources that used to provide information about components.

     

    - TLDs
    - Facelet libs.
    - faces-config.xml's
    - KB custom schemas.

     

    This list could be extended by adding new resource types.

     

    1.1. TLD Resources.

     

    TLD is the most useful resource for KB plug-in. There is info about tag names and attributes in particular component library. Code assist provides proposals for tag/attributes names which are picked from TLDs.

     

    1.2. Facelet libs.

     

    Facelet libs is not as useful as TLD because the is not any info about tag attributes. But in case there is only Facelet lib in class path without corresponded TLD we will able to provide tag names at least.

     

    1.3 faces-config.xml's

     

    If faces config file contains info about possible facet names for particular component we will pick this info there.

     

    1.4 KB custom schemas.

     

    TLD/Facelet libs/faces-config.xml is not enough to provide Code assist for attributes values. So we use custom XMLs to describe meta information for possible types of proposals for attribute values.

     

    Here is an example of custom KB schema:

     

    <tag-lib>

     

        <component name="extendedDataTable">
            <attribute name="align">
                <proposal type="enumeration">
                    <param value="left" />
                    <param value="center" />
                    <param value="right" />
                </proposal>
            </attribute>
        </component>

     

        <component closeTag="true" name="graphicImage">
            <attribute name="url">
                <proposal type="file">
                    <param name="extensions" value="%image%" />
                </proposal>
            </attribute>
        </component>

     

        <component-extension>
            <attribute name="reRender">
                <proposal type="id"/>
            </attribute>
            <attribute name="for">
                <proposal type="id"/>
            </attribute>
        </component-extension>

     

    </tag-lib>

     

    <component> tag describes a JSF component.
    By default KB plug-in uses info from this tag only if such tag or attribute are described in corresponding TLD or Faces lib. So there is not any need to keep a schema synchronized with TLD. Meta info from a schema supplements TLD/Faces lib. If a schema is the only source where the tag/attribute is described then this tag/attribute info will be ignored by KB. If we want to add some tag/attribute anyway, even if TLD knows nothing about them, we can use extended="false" attribute.

     

    <component-extension> is used to describes proposal types for particular attributes of any component if such attribute described in corresponded TLD.
    In example above we added meta info for all attributes with name "for" and "reRender" of the component library.
    For example in editor it will works as: <any_tag_name_within_lib for="we will propos all component IDs available here" />

     

    If we want to add proposal types for attributes for all component libs we have some special XML - componentExtension.xml:

     

    <component-extension>
        <attribute name="action">
            <proposal type="view-actions" />
        </attribute>
        <attribute name="immediate">
            <proposal type="enumeration">
                <param value="true" />
                <param value="false" />
            </proposal>
        </attribute>
        <attribute name="rendered">
            <proposal type="enumeration">
                <param value="true" />
                <param value="false" />
            </proposal>
        </attribute>
    </component-extension>

     

    Here is a list of possible proposal types for attributes:

     

    bundleName - Names of message resource bundles which are available in JSF project (e.g. <f:loadBundle basename="..." />)

    viewActions - JSF Actions from faces-config.xml (e.g. <h:commandBundle action="..." />)

    file - Path to a resource. E.g. following proposal type is used in <h:commandButton image="..."/>:

             <attribute name="image">
                <proposal type="file">
                    <param name="extensions" value="%image%" /> <!-- %image% for "gif", "jpeg", "jpg", "png", "wbmp", "bmp". And %page% for "jsp", "htm", "html", "xhtml", "xml" -->
                    <param name="pathType" value="absolute" /> <!-- absolute means relative to WebContent and starts with "/". relative means relative to the page -->
                </proposal>
            </attribute>

     

    enumeration - A list of strings. For example

             <attribute name="rendered">
                 <proposal type="enumeration">
                     <param value="true" />
                     <param value="false" />
                 </proposal>
             </attribute>

     

    faceletsJsfCTags - Used to propos a list of available JSF components for jsfc attributes in facelet pages. (e.g. <input jsfc="h:commandButton" />)

    id - Component ID within the page. (e.g. <a4j:commandButton reRender="...">)

    converterID - Converter ID

    validatorID - Validator ID

     

    For more details about KB schema format see https://anonsvn.jboss.org/repos/jbosstools/trunk/jst/plugins/org.jboss.tools.jst.web.kb/resources/kbCustomTagLibSchema-1.0.dtd

     

    Custom schemas are added to KB plug-in by extension point org.jboss.tools.jst.web.kb.tagLib
    For example plugin.xml:
       <extension
             point="org.jboss.tools.jst.web.kb.tagLib">
          <tag-lib
                location="taglibs/Richfaces.xml"
                name="JBoss RichFaces"
                uri="http://richfaces.org/rich"/>
          <tag-lib
                location="taglibs/JBossSeam.xml"
                name="JBoss Seam"
                uri="http://jboss.com/products/seam/taglib"/>
          <component-extension
                location="taglibs/componentExtension.xml"/>
       </extension>
    </plugin>

     


    2. KB Builder.

     

    KB builder is used to pick up KB resources (TLD/Facelets/...) from a project. If there is a resource in classpath then it will be loaded and added to KB model. It's important change from previous version of JBoss Tools. Some TLDs are bundled with JBT and will be avaliable even if they are not in project classpath (see https://jira.jboss.org/jira/browse/JBIDE-5650). An user can add any KB resource (TLD or Facelet lib) via XML Catalog if he doesn't want to add them to the project classpath. See http://screencast.com/t/ZjdkODBiZmEt

     

    Old projects which was created by previous JBoss Tools don't have such builder. Imported projects may not have it as well.

    JBoss tools checks if there is not KB builder in a project when user invokes Code assist first time.
    In this case KB model is built in background thread and stays in static state until the KB-builder is installed and invoked.
    A warning about missing KB builder with a quick fix is added to the project as well. So user can fix the problem by couple of clicks.

    See https://jira.jboss.org/jira/browse/JBIDE-4762 for details.

    Also user can add KB builder/nature in .project manually. See http://www.jboss.org/index.html?module=bb&op=viewtopic&p=4247996#4247996

     

    All our wizards which create projects or add seam/jsf support to a project, add KB builder automatically.

     

    Not all information about tags/attributes which is used in Code Assist picked up by KB builder. KB custom schemas worked without project builders because they don't depend on particular project. So if a project doesn't have KB builder installed then Code assist will show proposals from custom schemas anyway. For example HTML tags/attributes or <ui:* tags from facelets lib will work in JBoss Tools XHTML editor for any projects.

     

    3. EL resolvers.

     

    We use system of EL resolvers to provide Code assist for EL in jsp/xhtml editors. Each EL is pluged in by extension point org.jboss.tools.common.el.core.elResolver and should implement org.jboss.tools.common.el.core.resolver.ELResolver interface.

     

    For example:

     

       <extension
             point="org.jboss.tools.common.el.core.elResolver">
             <el-resolver id="seamELResolver">
                 <project-nature id="org.jboss.tools.seam.core.seamnature"
                     resolver-class="org.jboss.tools.seam.internal.core.el.SeamELCompletionEngine"/>
             </el-resolver>
             <el-resolver id="customELResolver">
                 <factory class="org.jboss.tools.customELResolverfactory"/>
             </el-resolver>
       </extension>