From 039a7fe0df957563c310c507b897bb1e1118fcd7 Mon Sep 17 00:00:00 2001 From: Chris Goldthorpe Date: Tue, 23 Jun 2009 21:00:26 +0000 Subject: Bug 38052 – [Help] Add alphabetical ordering attribute to TOC DTD --- org.eclipse.help/META-INF/MANIFEST.MF | 2 +- org.eclipse.help/schema/toc.exsd | 66 ++++++++++------- .../src/org/eclipse/help/internal/Topic.java | 8 +- .../src/org/eclipse/help/internal/toc/Toc.java | 9 ++- .../org/eclipse/help/internal/toc/TocManager.java | 4 + .../org/eclipse/help/internal/toc/TopicSorter.java | 85 ++++++++++++++++++++++ 6 files changed, 142 insertions(+), 32 deletions(-) create mode 100644 org.eclipse.help/src/org/eclipse/help/internal/toc/TopicSorter.java (limited to 'org.eclipse.help') diff --git a/org.eclipse.help/META-INF/MANIFEST.MF b/org.eclipse.help/META-INF/MANIFEST.MF index e1ed481b6..f84ae5de1 100644 --- a/org.eclipse.help/META-INF/MANIFEST.MF +++ b/org.eclipse.help/META-INF/MANIFEST.MF @@ -2,7 +2,7 @@ Manifest-Version: 1.0 Bundle-ManifestVersion: 2 Bundle-Name: %help_plugin_name Bundle-SymbolicName: org.eclipse.help; singleton:=true -Bundle-Version: 3.4.0.qualifier +Bundle-Version: 3.5.0.qualifier Bundle-Activator: org.eclipse.help.internal.HelpPlugin Bundle-Vendor: %providerName Bundle-Localization: plugin diff --git a/org.eclipse.help/schema/toc.exsd b/org.eclipse.help/schema/toc.exsd index 10c0d7704..2c72d2627 100644 --- a/org.eclipse.help/schema/toc.exsd +++ b/org.eclipse.help/schema/toc.exsd @@ -2,9 +2,9 @@ - + - + For registering an online help contribution for an individual plug-in. @@ -26,9 +26,9 @@ point and specify TOC file(s).</li> - + - + @@ -56,9 +56,9 @@ point and specify TOC file(s).</li> - + - + @@ -81,10 +81,14 @@ point and specify TOC file(s).</li> <br><tt>&nbsp;&nbsp;&nbsp; &lt;!ATTLIST toc link_to CDATA #IMPLIED ></tt> <br><tt>&nbsp;&nbsp;&nbsp; &lt;!ATTLIST toc label CDATA #REQUIRED ></tt> <br><tt>&nbsp;&nbsp;&nbsp; &lt;!ATTLIST toc topic CDATA #IMPLIED ></tt> +<br><tt>&nbsp;&nbsp;&nbsp; &lt;!ATTLIST toc sort CDATA #IMPLIED ></tt> +<br><tt>&nbsp;&nbsp;&nbsp; &lt;!ATTLIST toc icon CDATA #IMPLIED ></tt> <p><tt>&nbsp;&nbsp;&nbsp; &lt;!ELEMENT topic (topic | anchor | link )* ></tt> <br><tt>&nbsp;&nbsp;&nbsp; &lt;!ATTLIST topic label CDATA #REQUIRED ></tt> <br><tt>&nbsp;&nbsp;&nbsp; &lt;!ATTLIST topic href CDATA #IMPLIED ></tt> +<br><tt>&nbsp;&nbsp;&nbsp; &lt;!ATTLIST topic sort CDATA #IMPLIED ></tt> +<br><tt>&nbsp;&nbsp;&nbsp; &lt;!ATTLIST topic icon CDATA #IMPLIED ></tt> <p><tt>&nbsp;&nbsp;&nbsp; &lt;!ELEMENT anchor EMPTY ></tt> <br><tt>&nbsp;&nbsp;&nbsp; &lt;!ATTLIST anchor id ID&nbsp; #REQUIRED ></tt> <p><tt>&nbsp;&nbsp;&nbsp; &lt;!ELEMENT link EMPTY ></tt> @@ -121,6 +125,9 @@ file as well. /></tt> <br><tt>&nbsp; ...</tt> <br><tt>&lt;/topic></tt> +<p> If the sort attribute is true child topics will be sorted alphabetically.</p><p> The +optional icon attribute allows the use of a different icon as defined by a +&lt; tocIcon &gt; element in an org.eclipse.help.toc extension.</p> <p><b>The link element</b> <p>The link element allows to link Table of Contents defined in another toc file.&nbsp; All the topics from the toc file specified in the toc attribute @@ -145,8 +152,11 @@ an anchor as follows: <p><b>The toc element</b> <p>The toc element is a Table of Contents that groups topics and other elements defined in this file.&nbsp; The label identifies the table of -contents to the user, when it is displayed to the user.&nbsp; The optional topic -attribute is the path to a topic file describing the TOC.&nbsp; The optional +contents to the user, when it is displayed to the user.&nbsp;</p><p> The optional topic +attribute is the path to a topic file describing the TOC.&nbsp; </p> +<p> If the sort attribute is true child topics will be sorted alphabetically.</p><p> The +optional icon attribute allows the use of a different icon as defined by a +&lt; tocIcon &gt; element in an org.eclipse.help.toc extension.</p><p>The optional link_to attribute allows for linking toc from this file into another toc file being higher in the navigation hierarchy.&nbsp; The value of the link_to attribute must specify an anchor in another toc file. To link toc from @@ -163,9 +173,9 @@ API"/></tt> </p> <br> - + - + @@ -205,9 +215,9 @@ or not primary and intended to be integrated into another table of contents. the implementation class for the toc provider. This class must implement the <samp>org.eclipse.help.AbstractTocProvider</samp> interface. - + - + @@ -249,9 +259,9 @@ or not primary and intended to be integrated into another table of contents. The path of an icon to be used for a toc or topic whose chidren have been expanded. - + - + @@ -259,9 +269,9 @@ or not primary and intended to be integrated into another table of contents. The path of an icon to be used for a toc or topic whose chidren have been expanded. If no provided openIcon will be used. - + - + @@ -269,9 +279,9 @@ or not primary and intended to be integrated into another table of contents. The path of an icon to be used for a toc or topic without children. If not provided openIcon will be used. - + - + @@ -279,18 +289,18 @@ or not primary and intended to be integrated into another table of contents. Text that will be used in the "alt" attribute for the img tag in the web presentation. - + - + - + - + The following is an example of using the <samp>toc</samp> extension point. @@ -378,9 +388,9 @@ to plugin directory. - + - + An implementation of <samp>org.eclipse.help.AbstractTocProvider</samp> must be supplied if a <samp>tocProvider</samp> is used. @@ -388,18 +398,18 @@ to plugin directory. - + - + The default implementation of the help system UI supplied with the Eclipse platform fully supports this extension point. - + - + Copyright (c) 2000, 2006 IBM Corporation and others.<br> All rights reserved. This program and the accompanying materials are made diff --git a/org.eclipse.help/src/org/eclipse/help/internal/Topic.java b/org.eclipse.help/src/org/eclipse/help/internal/Topic.java index 1e6125e83..df3e34ad5 100644 --- a/org.eclipse.help/src/org/eclipse/help/internal/Topic.java +++ b/org.eclipse.help/src/org/eclipse/help/internal/Topic.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2006, 2008 IBM Corporation and others. + * Copyright (c) 2006, 2009 IBM Corporation and others. * All rights reserved. This program and the accompanying materials * are made available under the terms of the Eclipse Public License v1.0 * which accompanies this distribution, and is available at @@ -19,6 +19,7 @@ public class Topic extends UAElement implements ITopic { public static final String ATTRIBUTE_HREF = "href"; //$NON-NLS-1$ public static final String ATTRIBUTE_LABEL = "label"; //$NON-NLS-1$ public static final String ATTRIBUTE_ICON = "icon"; //$NON-NLS-1$ + public static final String ATTRIBUTE_SORT= "sort"; //$NON-NLS-1$ public Topic() { super(NAME); @@ -30,10 +31,15 @@ public class Topic extends UAElement implements ITopic { setLabel(src.getLabel()); appendChildren(src.getChildren()); } + public String getIcon(){ return getAttribute(ATTRIBUTE_ICON); } + public boolean isSorted(){ + return "true".equalsIgnoreCase(getAttribute(ATTRIBUTE_SORT)); //$NON-NLS-1$ + } + public Topic(Element src) { super(src); } diff --git a/org.eclipse.help/src/org/eclipse/help/internal/toc/Toc.java b/org.eclipse.help/src/org/eclipse/help/internal/toc/Toc.java index 8ccd34378..e1df434c2 100644 --- a/org.eclipse.help/src/org/eclipse/help/internal/toc/Toc.java +++ b/org.eclipse.help/src/org/eclipse/help/internal/toc/Toc.java @@ -30,6 +30,7 @@ public class Toc extends UAElement implements IToc { public static final String ATTRIBUTE_LINK_TO = "link_to"; //$NON-NLS-1$ public static final String ATTRIBUTE_ID = "id"; //$NON-NLS-1$ public static final String ATTRIBUTE_ICON= "icon"; //$NON-NLS-1$ + public static final String ATTRIBUTE_SORT= "sort"; //$NON-NLS-1$ private ITocContribution contribution; private ITopic topic; @@ -98,6 +99,10 @@ public class Toc extends UAElement implements IToc { public String getIcon(){ return getAttribute(ATTRIBUTE_ICON); } + + public boolean isSorted(){ + return "true".equalsIgnoreCase(getAttribute(ATTRIBUTE_SORT)); //$NON-NLS-1$ + } /* * Returns a mapping of all topic hrefs to ITopics. @@ -135,10 +140,10 @@ public class Toc extends UAElement implements IToc { return getTopics(); } public boolean isEnabled(IEvaluationContext context) { - return isEnabled(context); + return Toc.this.isEnabled(context); } public IUAElement[] getChildren() { - return getChildren(); + return new IUAElement[0]; } }; } diff --git a/org.eclipse.help/src/org/eclipse/help/internal/toc/TocManager.java b/org.eclipse.help/src/org/eclipse/help/internal/toc/TocManager.java index 34424363b..56f7fac27 100644 --- a/org.eclipse.help/src/org/eclipse/help/internal/toc/TocManager.java +++ b/org.eclipse.help/src/org/eclipse/help/internal/toc/TocManager.java @@ -81,6 +81,10 @@ public class TocManager { } } tocs = (Toc[])orderedTocs.toArray(new Toc[orderedTocs.size()]); + TopicSorter topicSorter = new TopicSorter(); + for (int i = 0; i < tocs.length; i++) { + topicSorter.sortChildren(tocs[i]); + } tocsByLocale.put(locale, tocs); long stop = System.currentTimeMillis(); if (HelpPlugin.DEBUG_TOC) { diff --git a/org.eclipse.help/src/org/eclipse/help/internal/toc/TopicSorter.java b/org.eclipse.help/src/org/eclipse/help/internal/toc/TopicSorter.java new file mode 100644 index 000000000..5d90ec301 --- /dev/null +++ b/org.eclipse.help/src/org/eclipse/help/internal/toc/TopicSorter.java @@ -0,0 +1,85 @@ +/******************************************************************************* + * Copyright (c) 2009 IBM Corporation and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * IBM Corporation - initial API and implementation + *******************************************************************************/ +package org.eclipse.help.internal.toc; + +import java.util.Arrays; +import java.util.Comparator; + +import org.eclipse.help.ITopic; +import org.eclipse.help.internal.Topic; +import org.eclipse.help.internal.UAElement; + +import com.ibm.icu.text.Collator; + +/* + * Handles the "sort" attribute on topics and tocs + */ +public class TopicSorter { + + private Comparator comparator; + + public void sortChildren(Toc toc) { + if (comparator == null) { + comparator = new TopicComparator(); + } + if (toc.isSorted()) { + sort(toc, toc.getTopics()); + } + ITopic[] childTopics = toc.getTopics(); + for (int i = 0; i < childTopics.length; i++) { + sortChildren((Topic)childTopics[i]); + } + } + + private void sortChildren(Topic topic) { + if (topic.isSorted()) { + sort(topic, topic.getSubtopics()); + } + ITopic[] childTopics = topic.getSubtopics(); + for (int i = 0; i < childTopics.length; i++) { + sortChildren((Topic)childTopics[i]); + } + } + + private class TopicComparator implements Comparator { + Collator collator = Collator.getInstance(); + + public int compare(Object o1, Object o2) { + String label1 = ((ITopic)o1).getLabel(); + String label2 = ((ITopic)o2).getLabel(); + return collator.compare(label1, label2); + } + } + + /* + * Sort the given node's descendants recursively using the given + * Comparator. + */ + private void sort(UAElement element, ITopic[] children) { + // sort children + if (children.length > 1) { + for (int i=0;i