platform-ui-home/object-aware-contributions/objCont.htm

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.1 - (download) (as text) (annotate)
Wed Dec 10 20:02:40 2003 UTC (5 years, 11 months ago) by tod
Branch: MAIN 
Added object aware contribution doc

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Untitled Document</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>

<body>
<h1>Content Sensitive Object Contributions</h1>
<p><em>Last modified December 10, 2003</em></p>
<p>Context menus for some applications have previously only been able to exclude 
  some menu options based on peripheral information known about the resources 
  selected (the number of resources selected, the physical name of the file, the 
  type of the resource, etc.). There are some cases where a restricted amount 
  of information, known about the contents of the resource would significantly 
  reduce unusable options from the menus. The first area targeted is that of XML 
  files. There are numerous situations where an action is applicable for one type 
  of XML file but not another. For example, some XML files contain Ant scripts. 
  The action &quot;Run Ant...&quot; makes sense in its context menu. But this 
  action is not applicable to an XML file used to define a plug-in.</p>
<p>It will now be possible to define object contributions which are specific to 
  an XML file with a given top level tag or which specify a given DTD. The objectState 
  key of an ActionExpression will be used to specify these values as follows:</p>
<p><font size="3">&lt;objectState name=&quot;xmlFirstTag&quot; value=&quot;<em>tagValue</em>&quot;/&gt;</font></p>
<p><font size="3">&lt;objectState name=&quot;xmlDTDName&quot; value=&quot;<em>dtdValue</em>&quot;\&gt;</font></p>
<blockquote>
  <p><font size="3">where <em>tagValue</em> represents the name of the top level 
    tag to match and</font></p>
  <p><font size="3"><em>dtdValue</em> represents the name of the DTD as seen in 
    the XML file.</font></p>
</blockquote>
<p><font size="3">Consider the following object contribution in a plugin.xml file:</font></p>
<pre>   &lt;extension point = &quot;org.eclipse.ui.popupMenus&quot;&gt;
     &lt;objectContribution
	    id=&quot;org.eclipse.ui.examples.objectContributions&quot;
		objectClass=&quot;org.eclipse.core.resources.IFile&quot;
		nameFilter=&quot;*.xml&quot;&gt;
		&lt;visibility&gt;
			&lt;or&gt;
			  &lt;objectState name=&quot;xmlFirstTag&quot; value=&quot;myTag&quot;/&gt;
			  &lt;objectState name=&quot;xmlDTDName&quot; value=&quot;myDTD.xml&quot;/&gt;
			&lt;/or&gt;
	    &lt;/visibility&gt;
		&lt;action id=&quot;org.eclipse.ui.examples.objectContributions.action1&quot;
		   label=&quot;%PopupMenus.action&quot;
		   icon=&quot;icons/ctool16/openbrwsr.gif&quot;
		   menubarPath=&quot;additions&quot;
		   class=&quot;org.eclipse.ui.examples.objectContributions.PopupMenuActionDelegate&quot;
		   enablesFor=&quot;1&quot;&gt;
		&lt;/action&gt;
	  &lt;/objectContribution&gt;
	&lt;/extension&gt;</pre>
<p>This will make action1 visible for any IFile with a name matching *.xml provided 
  it contains myTag as the top level XML tag or it uses the DTD called myDTD.xml. 
  So the following XML files will match:</p>
<blockquote>
  <pre>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;myTag
  id=&quot;org.eclipse.ui.workbench&quot;
  name=&quot;%pluginName&quot;
  version=&quot;3.0.0&quot;
  provider-name=&quot;%providerName&quot;
  class=&quot;org.eclipse.ui.internal.WorkbenchPlugin&quot;&gt;
&lt;/myTag&gt;</pre>
<p>Or</p>
  <pre>
&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;!DOCTYPE Book SYSTEM &quot;myDTD.xml&quot;&gt;
&lt;fragment
   id=&quot;org.eclipse.ui.workbench&quot;
   name=&quot;%pluginName&quot;
	version=&quot;3.0.0&quot;
	provider-name=&quot;%providerName&quot;
	class=&quot;org.eclipse.ui.internal.WorkbenchPlugin&quot;&gt;
	&lt;runtime&gt;
	   &lt;library name=&quot;workbench.jar&quot;&gt;
	      &lt;export name=&quot;*&quot;/&gt;
		  &lt;packages prefixes=&quot;org.eclipse.ui, org.eclipse.jface&quot;/&gt;
	   &lt;/library&gt;
	&lt;/runtime&gt;
&lt;/fragment&gt;</pre>
</blockquote>

<p>A new parser, called PropertyParser, will be used to collect this information. 
  This parser will be a SAX based parser as we don't necessarily need to parse 
  the entire file.</p>
<p>New persistent properties will be stored for any file that requires this information. 
  First, a property called &quot;xmlLastMod&quot; will be used to store the last 
  modified time of the file (as know by IResource). This will ensure that we don't 
  re-parse this file if it isn't necessary. Two other properties, &quot;xmlFirstTag&quot; 
  and &quot;xmlDTDName&quot; will be used to store the name of the root level 
  tag and a DTD file (if specified) respectively. Note that if the parser is called 
  for either one of these, both will be stored (if they exist). The structure 
  of XML dictates that the DTD specification, if it exists, must occur before 
  the root level tag. As a result, once PropertyParser has parsed to the root 
  level tag, it's work is done. At this point, all other parsing is stopped.</p>
<p>Any exceptions thrown by the parser are output to the .log file. PropertyParser 
  will explicitly test for an empty file as many SAX parsers will throw an exception 
  if they encounter an XML file without a root level tag.</p>
<p>It should be noted that if a DTD is specified in a file, Crimson, a commonly 
  used SAX parser in Eclipse, requires that the DTD file exists and is readable. 
  If this is not the case, a SAXException will be thrown. The PropertyParser does 
  not require the DTD to be present, but the underlying parser often does.</p>
<p>Related Bug Reports</p>
<p>33018 - [Contributions] plugin.xml context menu should not have &quot;Run Ant...&quot; 
  item</p>
<p>45024 - JAXP and old Xerces functionality</p>
</body>
</html>