Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: for the plan.

Jump to: navigation, search

WTP 30 Facets Usability


Two of the major active themes for WTP 3.0, as outlined in the Web Tools Platform Release 3.0 Requirements, are "Improve the 'Out of the box' Experience" and "Ease of Use". To that end, one of the most widespread and initial actions a WTP user will perform is faceted project creation. It is always worth taking a step back and asking ourselves if there is room for usability improvements in this functional area. The following is one such proposal.

A Proposal...

Imagine a scenario where the generic user never needs to go the facet selection panel. Imagine a scenario, where out of the box, the user just picks a pre-canned product project configuration and then hits finish from the first page of the new project wizard. Imagine a scenario where an advanced user maybe could have a team with one facet guru, who would be responsible for defining the custom configurations his team would use on a day to day basis to create faceted projects. This guru would open a configurations editor in the workbench preferences, select the facets he wants, save that configuration, and then export it using workbench preferences. Other team members could then import the configurations and decide which ones they want to show up in their new project wizards. Then, all they ever need to do is select the appropriate configuration from the first page of the project wizard and theoretically, hit finish right from there.

Please note the following screen mock-ups are not meant to be of pristine quality, but rather general thoughts on direction to take the wizards. It is understood visual clean up is necessary.

The Configuration Editor

The pre-defined "typical" configurations will be key. Adopter products could extend and ship with additional configurations, but WTP should have just enough base configurations. The idea is that the configuration editor really does stay an advanced option. But, we do want to make the configuration editor as easy to use as possible because we cannot assume everyone will have a "facet guru".


  • This is a mock up of what the facet configuration could look like. This is a familiar look and feel based on the eclipse run/debug page.
  • The facet configuration editor could create new configurations, edit existing ones, and they will show nested under the primary project type for ease of use. For usability when creating a new configuration, the facet list is filtered by what is applicable to the primary project type.
  • These configurations would then be exported for use by each team member to import to their own workspaces. So, the idea is not every user would have to use this editor and be worried about such details.
I think this editor ought to take runtimes into account. For several reasons:
  1. For information purposes, users might want to know what runtimes support the current set of facets/versions in the configuration definition. For example, they may want to define a "Faces JPA" configuration that is available to both J2EE 1.4 and JEE5 servers. If the list of runtimes is there they would immediately realize that selecting JSF version "1.2" would make it unsupported on J2EE 1.4 servers.
  2. To drive the facets display. Imagine users want to define a configuration for J2EE 1.4 servers only but not JEE 5, because that's what their production level is. It'd be very helpful if they can select the "target runtimes" to filter out any JEE5 only facets, like Axis2, JPA, etc. and have a much shorter list to work with.

Simplified Faceted Project Creation Wizard

Our goal is to hide the user from ever having to worry about facets. All they have to know is which type of project they want to create and away they go. This is the reasoning behind removing the facet selection page out of the wizard flow and into an advanced dialog.
I generally agree with the premise of making the facets page be less prominent. It's not that users will be able to never worry about facets, but there is no reason to force everyone to interract with advanced configuration. There are two ways of taking this basic idea on. You either use a separate dialog or a checkbox that hides/shows the page in the wizard flow. I think the separate dialog approach is cleaner from UI perspective, but it's more work than the hide/show page approach. The hide/show page approach has an existing enhancement request: 143075

Can we come up with a better name for "Add/Modify Facets"?
How about "Modify..." or "Modify Configuration..."?


  • User enters project name first.
  • Project location would now hidden by default, and can be expanded by clicking the "Project Location Details..." button.
I am worried a bit about making this standard section different from other Eclipse wizards.
  • The primary facet version for the type of faceted project would now be set on the first page by the user.
This is an important usecase, but there are a lot of technical details to work out. I'd change the order and present the target runtime first and let that influence the supported spec version. Users are typically constrained by a particular runtime. Currently the defaultFacets extension point lets runtime author specify the versions of facets that are selected by default. If we add spec version as an extra bit in the equation, the extension point would need to be revised to be able to handle this case. There is not enough information currently in the model to implement this UI. Need to think more about this.
I think it would be better this drop down box to contain the available Java EE spec versions supported by the selected runtime. It would be easier for the novice user to select the desired Java EE spec version (J2EE 1.4, Java EE 5, ...) rather to decide which project version matches which Java EE spec version. There should be no technical issue for this, because Java EE spec versions and primary facet versions match one to one.
  • The user would then select a target runtime, with option to create a new one.
  • The user would then select a pre-canned product configuration or a configuration given to them by their organization. If an advanced user wanted to modify the facets for _this project_, they would select "Add/Modify Facets". This would take them to the facet selection page in a dialog. This facets page would no longer be the second page in the wizard flow. Once a user changes the facets, we would switch the configuration to "Custom". If the user were to then switch to a different configuration, they would lose the previous changes and get the default for that newly selected configuration. The user would have an option in the advanced dialog to open a link to the configuration editor, where the current selections would be defaulted in, and they could give the new configuration a name and save it from there.
  • The configurations drop down would have hover help descriptions to the right of it like the JDT content assist does. Once selected, a detailed description will display under the combo box. The hover help is meant to display a few sentences about what support that configuration will give the project. It will not go into specific facet details, but be user understandable features or higher order descriptions.
I am not sure i understand this suggestion. Is the idea that we would replace the paragraph beneath the drop down with a fancier UI? I heard a comment at the meeting that we would make the allocated space larger for longer descriptions. The existing UI will already resize the space if more than two lines are necessary.
  • The user could then select to add to an EAR.
The "EAR project name" should contain only EAR projects that can include the selected version of the project under creation. For example an EAR 1.4 project cannot include Web 2.5 project.
  • The next pages in the wizard would be the facet install pages for the selected facets in the new project. The complex facet selection page will not be in this page flow. Optionally, a novice user could just hit finish from the first page.

Here is an updated screenshot


Suggestions for the Facets Panel on a Project's Properties

  • Can we rename the option to view/modify facets to be something like "Project Support (Facet Details)"?
Why is that better?
  • In the current project properties dialog page, the "add/remove project facets" button seems unnecessary. The display/information/features in the “Add/Remove Project Facets” window, should replace the “Project Facets” shown on the main page. (196484)
This is one that's made frequently, but is not feasible technically. When a user changes facets, wizard pages related to those facet actions need to be displayed. You cannot displayed wizard pages while embeded inside a property page.
  • The right side of the facets panel should be a paragraph description for the currently selected facet. The runtimes could then optionally pop out like a drawer on top of the descriptions.
An alternative or maybe in addition to this is to integrate with dynamic help so that selecting a facet and hitting F1 will display help content for that facet... 135950
If we do end up going the suggested route, there is enough real estate there to display more than just description. What else could we put there that would be valuable. Facet constraints is a valuable piece of information, but that takes a lot of real estate (maybe we could have a link that pops up the existing constraint display dialog).
Does it make sense to keep the drawer construct or would it be better to switch to tabs?

Discussion Notes 07/19/07

  • Basing off configurations is a valid approach, however there are potential usability concerns like the number of configurations that get created, the length of their names, and the ability to properly describe what facet capabilities are included.
  • Fixed facets are what the facet framework is aware of, not project types or spec type.
  • Dynamic configurations are new in WTP 2.0 and add the flexibility to morph what facets and versions are selected based on what project type and runtime selected. Also, new in WTP 2.0, static configurations can extend another configuration, either dynamic or static.
  • Exporting configurations and sharing between workspaces is a good idea.
  • On the configuration editor, the runtime selection is missing, because some facets may be constrained by runtime, and we don't want the user to create an invalid configuration for their runtime.
  • Any thoughts on tackling after a project is created, maybe trying to apply a configuration? This would invove proper facet uninstalls and version change operators which we currently don't have.
  • There is a default facet extension pt which is associated with a runtime type and version, and picks what is selected by default.
  • On the wizard page, runtime composite should go before project version, because users are typically locked into a runtime. If we tie this now to the fixed facet version, by putting version on first page, how do we weave in facet version into the default configuration without breaking current extensions?
  • We should select the JDK used by what the runtime has. I think we do this today?
  • Project version is tricky, this is a key piece of information, so it should be on first page, but facet framework knows nothing of project types or spec versions so how do we come up with new default configurations ext pt to drive the screen flow properly?
  • EAR Membership also presents another interesting problem because it drives facet and runtime chages. When it gets switched, it can change a bunch of stuff, would need to revisit so that it doesn't mess up the new flow? Maybe move to the J2EE facet install page and remove from first page?
  • We should allow the changing of spec version levels on J2EE projects.
  • Is it worth showing the current UI and ideas to the Foundation's UI Best Practices Group? The implementation details maybe too complex?

Meeting 07/27/07

Added new enhancement request:

  • 197859 - Add ability for facet framework to support dynamic servers

Possible enhancement:

No facet validation after the fact, meaning the framework does a great job up front, but once you get a project in a bad state for whatever reason, there is not much validation and not much you can do. Sometimes, the easiest thing to do is to just create a new project. This seems like a bad workaround.

What's Next

  • Let's still stay high level and not worry about implementation details yet.
  • Do we have enough resources? What can we contain?
  • Review existing bugzilla enhancement requests and those described here and break down the lists.
  • Draft long term plan and goals. Prioritize set of proposed usability line items.

Implementation Details

  • Come up with obstacles to make these ideas possible. A big obstacle is the spec version on first page and how we map data flow as it relates among these four main fields. Can ear membership be removed from first page?
  • Ensure the runtime, facet version, and configuration are remembered after project creation and defaulted in for every subsequent project creation.

Outstanding Bugzilla Enhancements

All Open Facet Enhancements

General Overview of Enhancements in this Proposal

  • Remove second page in project creation wizard flow into a dialog
  • Move fixed facet version to first page of project creation wizard
  • Remove EAR selection to j2ee facets page
  • Create a workspace preferences page for editing and sharing configurations

All Enhancement Requests Related to UI and Usability

  • [P1] De-emphasize the facets selection panel for basic cases.
  • 143075 - Allow the user to bypass facets page if preset is selected
The prevalent thinking is that the dialog approach presented elsewhere in this wiki is better than the "suppress the page via a checkbox" approach suggested in this bug
  • 191715 - Facet configurations are not explained or presented well. Any improvements to how configurations are created and managed, such as the suggestion to let user manage configurations at the workspace level which is discussed here.
Consider integrating user-defined configurations with Eclipse preferences export/import mechanism.
  • [P1] Allow "spec version" to be selected on the first page of WTP wizards. This is a requirement on Faceted Project Framework in that it likely requires a redesign of the "defaultFacets" extension point which handles specifying which facets should be selected by default for a runtime component. The new facility would have to be able to take the spec version into account. This is challenging in that the Faceted Project Framework knows nothing of WTP constructs such as module spec versions. The solution would have to be more generic than that.
  • [P1] Improve the way information about a facet is presented. Make necessary information available and easily accessible. Remove unnecessary information where possible. The current proposal is to center these improvements around using the space on the RHS of the facets selection panel to present facet information. The targeted runtimes panel would then slide over that.
  • 135950 - Support dynamic help for individual facets.
  • 191712 - Facets description hover help is not sufficient
  • 198116 - Facet constraint display issues
  • [P2] Improve the behavior of the facets selection panel.
  • 115892 - Need Auto-selection of facet dependencies
This one is an open question. Ease cases are easy hard cases are very complicated. Does it make sense to implement this for easy cases and leave the current behavior in place for complicated cases or would that only add to use confusion (ui that behaves unpredictably from user's perspective)?
  • 186171 - Add filter field to the facets selection panel
  • [P2] Misc. Improvements
  • 191714 - Add ability to hide version of "unversioned" facets
  • [P3] Misc. Improvements
  • 116469 - jst.web facet install page should not have java source directory field
  • 136008 - Facets selection panel should filter out unselectable facet versions.
168538 - "Convert to a Dynamic Web Project" should work for Java projects
  • 165994 - Improve the story around the no runtime case

Back to Web Tools Wiki Home

Back to the top