Enabling UI Elements Based on Project Facets

User interface elements often need to be selectively enabled based on the presence of a facet in a project. The two most common examples are project properties pages and menu actions associated with a facet. The Faceted Project Framework provides a way to do that via a property tester that can be used in any extension point that supports the Eclipse Platform's common expression language.

Property Name: org.eclipse.wst.common.project.facet.core.projectFacet
Property Value: [facet.id](:[version.expr])?

As you can see from the format of the property value, you can either test using just the project facet id or you can also include a version expression if only certain versions should be matched.

The following two examples demonstrate how the facets property tester can be used. To explore further, you can also download the complete runnable source of these examples.

Example 1

Enables a project properties page based on the presence of a facet. Note the use of the forcePluginActivation attribute. This attribute makes sure that the property tester will be invoked even if the Faceted Project Framework plugins have not been activated yet. Omitting this attribute will cause the test expression to return false in that situation. Also note the use of the adapt operator to adapt the object to IProject. This is necessary as some views may represent project entities using other types. For instance, in the JDT's Package Explorer the projects are instances of org.eclipse.jdt.core.IJavaProject.

<extension point="org.eclipse.ui.propertyPages">
  <page
    id="ExampleFacetPropertiesPage"
    objectClass="org.eclipse.core.resources.IProject"
    adaptable="true"
    name="Example Facet Properties"
    class="org.eclipse.wst.project.facet.examples.enablement.ExampleFacetPropertiesPage">
    <enabledWhen>
      <adapt type="org.eclipse.core.resources.IProject">
        <test 
          forcePluginActivation="true"
          property="org.eclipse.wst.common.project.facet.core.projectFacet"
          value="example.facet1"/>
      </adapt>
    </enabledWhen>          
  </page>
</extension>

Example 2

Enables a menu action if either one of the two facets specified is installed in a project. Note the use of a version expression to match only certain versions.

<extension point="org.eclipse.ui.popupMenus">
  <objectContribution
    id="exampleFacetPopup"
    objectClass="org.eclipse.core.resources.IProject"
    adaptable="true">
    <action
      id="exampleFacetPopupAction"
      label="Example Facet Popup"
      class="org.eclipse.wst.project.facet.examples.enablement.ExampleFacetPopupAction"
      menubarPath="additions"
      enablesFor="+">
    </action>
    <enablement>
      <adapt type="org.eclipse.core.resources.IProject">
        <or>
          <test 
            forcePluginActivation="true"
            property="org.eclipse.wst.common.project.facet.core.projectFacet"
            value="example.facet1:1.0"/>
          <test 
            forcePluginActivation="true"
            property="org.eclipse.wst.common.project.facet.core.projectFacet"
            value="example.facet2:[1.1-2.2]"/>
        </or>
      </adapt>
    </enablement>
  </objectContribution>  
</extension>