Community
Participate
Working Groups
Attached is a zip containing our initial contribution for Cheatsheets.
Created attachment 5105 [details] Zip of source plus icons for cheatsheets
Created attachment 5487 [details] Updated source for plugin
Created attachment 6299 [details] Updated plugin with docs This is the cheat sheet plugin with the javadoc tags updated and more supporting schema documentation.
Created attachment 6595 [details] cheat sheet plugin with updated legal statements in source.
Created attachment 6596 [details] updated legal statements in code.
I'm reviewing the API for the cheatsheet contribution and have some questions. But first I'll summarize what's in the contribution. The cheatsheet facility has the following basic capabilities: - allows a cheatsheet to be contributed by an extension point - a cheatsheet is named and categorized - a cheatsheet is a series of steps; each step is something for the user to do, in order - system actions are ones the user asks to do and the system does it - user actions are something the user does manually and informs the system when they've done it - steps may be marked as optional, meaning the user can skip them if they want - steps may be broken down into substeps (depth 2 max) - cheatsheet view presents a cheatsheet to the end user and walks them through the steps - API action for launching a cheatsheet, either by extension id or from external cheatsheet file - live help action for launching a cheatsheet by extension id ability to define actions that get passed string parameters specified in the cheatsheet step The basic facilities require the following things to be exposed as API: - cheatSheetContent extension point (cheatSheet and category elements) - ICheatSheetAction - so your actions can be passed parameters from the cheatsheet - LaunchCheatSheetAction - starts running the specified cheat sheet - OpenCheatSheetFromHelpAction - starts running the specified cheat sheet from inside help - ICheatSheetManager - so that cheatsheet actions can associate data with the execution of a cheatsheet The cheatsheet facility has the following advanced capabilities: - dynamic steps in a cheatsheet which can be modified programmatically cheatsheet listeners which can be added via extension point (only) to particular cheatsheets - add controls via an extension point (only) to the cheatsheet view The advanced facilities require the following things to be exposed as API: - IAbstractItem, IItem, IItemWithSubitems, ISubItem - for describing and manipulating cheatsheet steps - cheatSheetListener element of cheatSheetContent extension point - for contributing listeners - ICheatSheetEvent, ICheatSheetItemEvent, ICheatSheetViewEvent, ICheatSheetListener, ICheatSheetItemListener, ICheatSheetViewListener - for describing cheatsheet events and reacting to them - ICheatSheetItemExtensionElement - for adding controls to cheatsheet view The APIs for the basic facilities are a small subset of what is needed to support the advanced capabilities. The API would be very much simpler if the basic cheatsheets were sufficient. So I'd like to understand why the advanced cheatsheet capabilities are considered necessary. Dynamic steps - What is the usecase for having a cheatsheet with steps that get modified dynamically? Does it add sufficient value to warrant the more complicated API? Cheatsheet listeners - What is the usecase for listening to a cheatsheet as it's being carried out? (The cheat sheet view itself does not need this mechanism.) And it seems odd that these listeners are contributed via an extension point rather than programmatically. Cheatsheet view decorations - What is the usecase for adding new controls to a step showing in the cheatsheet view? I'd also like to understand why the steps of a cheatsheet are specified in a separate XML contents file, rather than as part of the extension markup.
I found contentFile.xsd, but was unable to locate the spec for what the markup in the cheatsheet content file means. This is needs to be spelled out (somewhere) for people that create cheatsheets.
Jim, here are the answers to your questions to the best of my abilities: ADVANCED CAPABILITIES The APIs for the basic facilities are a small subset of what is needed to support the advanced capabilities. The API would be very much simpler if the basic cheat sheets were sufficient. So I'd like to understand why the advanced cheat sheet capabilities are considered necessary. Dynamic steps - What is the usecase for having a cheat sheet with steps that get modified dynamically? Does it add sufficient value to warrant the more complicated API? The use case for having a cheat sheet with steps that get modified dynamically is: Use Case for steps modified dynamically 1) User Action User opens a dynamic cheat sheet. System response cheat sheet is opened in the fast view. 2) User Action User "kicks off" cheat sheet using intro step. System response cheat sheet is started, the intro "click to begin" icon changes to the "click to restart" icon. The intro step is collapsed and the next step is expanded and highlighted with buttons available for user to click on. 3) User Action User performs the next step which has a choice between two options. One option is selected. System response The choice that the user made is recorded and possibly stored in the CheatSheetManager, steps that follow in the cheat sheet are dynamically accessed and modified to launch the appropriate actions for the choice that the user made. Depending on the scenario, the buttons that are available in the steps that follow are adjusted from the defaults that were initially in the cheat sheet content xml file for the items and sub items. 4) The user continues through the rest of the cheat sheet that reflects the choice that they made in their "choice" step. This dynamic modification functionality adds a lot of value to the cheat sheet, one cheat sheet can be used to perform different functions depending on user choices. For example, if there were a cheat sheet to guide a user through building a web service, one cheat sheet could be used to build a web service from a Java Class, or from an EJB. Depending on which scenario the user chooses, (Java Class or EJB) the appropriate wizards and actions can be launched to help a user build that service from their Java Class, or if the choice was EJB the same cheat sheet could launch the EJB wizards. The author of the cheat sheet would not have to create two separate cheat sheets, one for the Java scenario, one for the EJB scenario, as most of the steps for each are very similar the cheat sheet could be composed once to handle both scenarios. Furthermore, steps and sub steps can be added dynamically to the cheat sheet "on the fly". Consider this scenario, building a struts application and being guided through the process by a cheat sheet. The user begins by launching a cheat sheet step that launches the web project wizard, and they create a web project. Following that step, they create a web diagram containing each of the java classes, jsp's, servlets that they will create. The cheat sheet advanced functionality is then used to add sub steps to the next cheat sheet item, providing an action to launch the appropriate wizard for creating each of the elements that they outlined in their web diagram. The cheat sheet becomes very helpful to the user providing quick actions to launch the wizards for each of the elements that they have to create. Without this functionality, the user's cheat sheet step may be only "Now create the elements from your web diagram and click to continue when you have created each element". The user's work at building this struts application would become far more complicated and up to them to find and launch the appropriate wizards from the workbench to create each element. LISTENERS cheat sheet listeners - What is the usecase for listening to a cheat sheet as it's being carried out? (The cheat sheet view itself does not need this mechanism.) And it seems odd that these listeners are contributed via an extension point rather than programmatically. Use Case for adding a listener to a cheat sheet: 1) User Action The user begins by creating Class that implements IcheatsheetViewListener or IcheatsheetItemListener and implementing the appropriate methods for the cheat sheet events they are interested in. System response A class is created. 2) User Action The user registers their class with the cheat sheetListener extension point to listen for events from a particular cheat sheet. System response The class is registered in the plugin registry for use by the cheat sheet framework. 3) User Action The user opens the cheat sheet that the listener is registered against. System response The cheat sheet framework initializes any listener classes that are registered to listen to the cheat sheet opened. A cheat sheet view opened event is fired to any IcheatsheetViewListeners. 4) User Action The user continues through the cheat sheet steps, happy to have a cheat sheet to guide them through these steps. System response As the cheat sheet steps are performed, different events are fired off to any and all listeners of that cheat sheet. Why register the cheat sheet listeners through an extension point? Ease of use and implementation. The implementor of a cheat sheet listener does not have to do any work to listen for the cheat sheet view to open to register to listen for events from it. They don't have to worry about instantiating their classes, the cheat sheet framework handles it all for them. This cuts the work of the implementor to basically two steps. First creating the class implementing one of the two cheat sheet listener interfaces. Secondly, they register this class using the cheat sheet listener extension point. VIEW DECORATIONS cheat sheet view decorations - What is the usecase for adding new controls to a step showing in the cheat sheet view? Use case for adding a control to a step showing in the cheat sheet view. 1) User action The user registers a new attribute for the <item> tag in their cheat sheet content xml file using the cheatsheetItemExtension point such as: <extension point="org.eclipse.ui.cheat sheets.cheatsheetItemExtension"> <itemExtension itemAttribute="itemControl" class="org.xyz.AddItemControl"> </itemExtension> </extension> In this case the attribute that the user will add to their <item> tag in their cheat sheet content xml file is itemControl. System response The extension point is added to the plugin.xml file. 2) User action The user creates a class (AddItemControl in this example) that implements IcheatsheetItemExtensionElement and names it the same thing as they specified when registering this Class in the itemExtension's class attribute. The user implements the method handleAttribute(Node) to parse the VALUE of their attribute from the cheat sheet content xml file. The user implements createControl(Composite) to add their control to the provided Composite. System response A Class is created. 3) User action With the class created and registered with an item attribute using the extension point in step 1 above, the user chooses which item in their cheat sheet they want the control to appear on, and adds the attribute itemControl to that <item> tag in their cheat sheet content xml file. System response The users cheat sheet content xml file is updated with a new attribute in an <item> tag. 4) User action The user launches the cheat sheet that corresponds to the cheat sheet content xml file that they just modified. System response The cheat sheet is opened, the cheat sheetItemExtension point is registered from the plugin registry, and the users AddItemControl class is instantiated. The method setAttributeName is called on the class setting the name to "itemControl". As the items are parsed from the cheat sheet content xml file, when the item that has the itemContro attribute in it's <item> tag is reached by the parser, the method handleAttribute is called on the AddItemControl class and passes it the attribute itemControl and it's value in a org.w3c.dom.Node object. After the content xml file is parsed and the cheat sheet view begins to render the items, when the item containing the itemControl attribute is being rendered, the createControl method is called on the AddItemControl class. A Composite object is passed as well as the background color of the item that the new control will be added to. The AddItemControl method adds an icon to the Composite and registers a mouse click event listener on it to trigger an event when/if the user clicks on it. The cheat sheet view is rendered and displayed to the user with an extra control added to an item, provided by the AddItemControl class. SEPARATE CONTENT FILE I'd also like to understand why the steps of a cheat sheet are specified in a separate XML contents file, rather than as part of the extension markup. There are several reasons why the cheat sheet content xml file should appear in a separate file rather than as part of the plugin extension markup. 1) algins itself with the current Eclipse welcome page 2) easier to provide a small, simple xml based document to translation then a plugin.xml 3) there are usually ID people involved in writing a cheat sheet and they can author the content xml and a developer can write the actions and other pieces that may be required for a given cheat sheet
Jim Wrote: I found contentFile.xsd, but was unable to locate the spec for what the markup in the cheatsheet content file means. This is needs to be spelled out (somewhere) for people that create cheatsheets. Jim, any thoughts on how/where I can include this information?
Re: comment #8 - usecase for dynamic cheatsheets Thanks Geoff for the detailed and explanation of how the dynamic cheatsheet feature would be used. There are clearly a lot of cases where the steps to be presented to the user should vary as the cheatsheet is carried out. The proposed mechanism of allowing the cheatsheet to be changed on the fly reminds me of self-modifying machine code: while you can do most anything with it, it is not necessarily the easiest programming model to use. The syntax for basic cheatsheets is analogous to a simple programming language that can only express sequences of atomic steps. The usescase you've described suggests to me there is a need for some kind of "if" statement to allow steps to appear conditionally; e.g.: <cheatsheet> <intro> <when intro is done> <item title="Choose A or B"/> <when choice is A> <item title="A1"/> <item title="A2"/> <when/> <when choice is B> <item title="B1"/> <item title="B2"/> <when/> <when/> <cheatsheet/> Have you considered something along these lines? It feels like it would be easier to program than having to write Java code that modifies the cheatsheet on the fly.
Re: comment #8 - usecase for cheatsheet listeners Re: comment #8 - usecase for view decorations It's still unclear to me what problem these features are attempting to solve. Re: comment #8 - separate content file Ack. Allowing the cheatsheet to be authored or translated separate from the plug-in manifest makes good sense. The help system does the same. re: comment #9 - good location for spec for cheatsheet content file An HTML file at the root of the project would suffice at this stage. Eventually the info should end up in the Platform ISV doc. Examples would also be helpful.
Re: <A HREF="#c10">comment #10</A> - usecase for dynamic cheatsheets - to be honest with you, this was mentioned at one point during the initial development but we did not look into it any further. - the conditions used to determine which choice was made would still need to be described and executed, I would presume this would be done via Java - one goal of the cheat sheets was to allow non programmers to author the content xml files and have a Java developer fill in the missing pieces. With the current approach this is achieved Re: <A HREF="#c11">comment #11</A> - usecase for view listeners Another component such as an editor could provide a cheat sheet listener and launch a cheat sheet from their code. Once the cheat sheet is launched, the listener would be informed giving it a chance to prepopulate the cheat sheet and/or customize the actions within the cheat sheet to match the current state of the component. From an end user perpective it would appear that the component/cheat sheet are working together to aid them along. I guess this could be somewhat analogous the OnStar feature. Re: <A HREF="#c11">comment #11</A> - usecase for view decorations The problem that the view decorations solves is if someone wants to launch additional help tools, such as a viewlet to assist with the user's understand of a given item. There could be other examples and instead of the framework defining each one, the developer can decide to add them as required. Re: <A HREF="#c11">comment #11</A> - good location for spec for cheatsheet content file See attached CheatSheetXML.zip Re: <A HREF="#c11">comment #11</A> - examples - we have an example plugin which I will attach - this example plugin contains a few of cheat sheets that demonstrate the basics, view decorations and advanced functionality(dynamic items, listeners, etc)
Created attachment 7674 [details] HTML file that describes the content XML
Created attachment 7675 [details] Sample plugin containing a few cheat sheets
Is there any additional (up to date) documentation for the new Cheat Sheets? Do the M8 cheat sheets differ from this contribution?
The most current information on the Eclipse 3.0 cheat sheets can be found here: http://dev.eclipse.org/viewcvs/index.cgi/~checkout~/org.eclipse.ui.cheatsheets/s chema/ Take a look at the cheatSheetContentFileSpec.html file to see how to author a cheat sheet using the latest markup. Also, the APIs are documented in the JavaDocs of the org.eclipse.ui.cheatsheets package, which can be viewed online here: http://dev.eclipse.org/viewcvs/index.cgi/~checkout~/org.eclipse.ui.cheatsheets/s rc/org/eclipse/ui/cheatsheets/ There are some tests/samples but they have not be released to CVS yet. The project org.eclipse.ui.tests.cheatsheets exists and will be updated soon.
A few questions: - How to open a cheatsheet from the help system? - How to open a cheatsheet from the intro page? - Is it possible to refer to a cheatsheet from a problem in the problems view? - Is it possible to use cheatsheet for complex conditional error resolutions? Use case for a complex error resolution: The user wants to compile a program and start the debugger. Suppose he needs to add something to $PATH for the compiler and start a debugger server. And there are some possible problems with his setup: - $PATH may not be set - there is an incompatible version of the compller in the path - the server is not running - an incompatible version of the server is running - the server is hanging and has to be restarted - ... Can a cheatsheet be setup conditionally before it is run by programatically removing some steps or seting some conditions (because we can programatically determine that they don't apply) in the cheetsheet?
I tried to create some cheat sheets and it seems that it's not possible to attach sheets to a sub category (a category with a parent category). Is this a known limitation of the current implementation?
Using the following XML snippet, the parent/sub cateory works. I think you might have missed including the "parent cat id/sub cat id" when specifing category for the cheatsheet. <extension point="org.eclipse.ui.cheatsheets.cheatSheetContent"> <category name="Sub Cat" id="org.eclipse.ui.examples.cheatsheets.subCat" parentCategory="org.eclipse.ui.examples.cheatsheets.cheatSheetsCat"> </category> <cheatsheet name="Sub Hello World" category="org.eclipse.ui.examples.cheatsheets.cheatSheetsCat/org.eclipse.ui.exam ples.cheatsheets.subCat" contentFile="cheatsheets/examples/part1/HelloWorld.xml" id="org.eclipse.ui.examples.cheatsheets.SubHelloWorld"> <description> This cheat sheet will guide you through building a hello world Java application and testing it. Uses only the basic cheat sheet features. </description> </cheatsheet> </extension>
Now that cheatsheets contributed to Eclipse as of 3.0, I'm closing this bug report.
These bugs were modified after M1 had shipped. I'm attaching them to the 3.1 M2 milestone so that they are picked up for the test pass. If they were fixed earlier, please feel free to remove the target milestone.
Cheat sheets shipped with Eclipse 3.0
This sample does not compile on Eclipse 3.x.x and is not compatible with 3.x.x.
