From 96abc27993e15a9f3b10af0385bca2866fb0eb75 Mon Sep 17 00:00:00 2001 From: Chris Goldthorpe Date: Mon, 1 Feb 2010 23:33:05 +0000 Subject: Bug 76005 – [Help] Ability for users to filter what they see in the help system navigation acc to some criteria (all help modes) --- org.eclipse.help/META-INF/MANIFEST.MF | 5 ++ .../src/org/eclipse/help/ICriteria.java | 37 +++++++++ org.eclipse.help/src/org/eclipse/help/IToc2.java | 42 ++++++++++ org.eclipse.help/src/org/eclipse/help/ITopic2.java | 43 +++++++++++ .../src/org/eclipse/help/internal/Topic.java | 11 ++- .../eclipse/help/internal/UAElementFactory.java | 6 +- .../eclipse/help/internal/criteria/Criteria.java | 55 +++++++++++++ .../internal/criteria/CriteriaPreferences.java | 90 ++++++++++++++++++++++ .../help/internal/criteria/CriterionResource.java | 80 +++++++++++++++++++ .../src/org/eclipse/help/internal/toc/Toc.java | 90 ++++++++++++++-------- .../eclipse/help/internal/toc/TocAssembler.java | 26 ++++++- 11 files changed, 447 insertions(+), 38 deletions(-) create mode 100644 org.eclipse.help/src/org/eclipse/help/ICriteria.java create mode 100644 org.eclipse.help/src/org/eclipse/help/IToc2.java create mode 100644 org.eclipse.help/src/org/eclipse/help/ITopic2.java create mode 100644 org.eclipse.help/src/org/eclipse/help/internal/criteria/Criteria.java create mode 100644 org.eclipse.help/src/org/eclipse/help/internal/criteria/CriteriaPreferences.java create mode 100644 org.eclipse.help/src/org/eclipse/help/internal/criteria/CriterionResource.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 5952d467f..d553ef71a 100644 --- a/org.eclipse.help/META-INF/MANIFEST.MF +++ b/org.eclipse.help/META-INF/MANIFEST.MF @@ -20,6 +20,11 @@ Export-Package: org.eclipse.help, org.eclipse.help.ui, org.eclipse.ua.tests, org.eclipse.help.webapp", + org.eclipse.help.internal.criteria; + x-friends:="org.eclipse.help.base, + org.eclipse.help.webapp, + org.eclipse.ua.tests, + org.eclipse.help.ui", org.eclipse.help.internal.dynamic; x-friends:="org.eclipse.ua.tests, org.eclipse.help.ui, diff --git a/org.eclipse.help/src/org/eclipse/help/ICriteria.java b/org.eclipse.help/src/org/eclipse/help/ICriteria.java new file mode 100644 index 000000000..9e2fbd5a2 --- /dev/null +++ b/org.eclipse.help/src/org/eclipse/help/ICriteria.java @@ -0,0 +1,37 @@ +/******************************************************************************* + * Copyright (c) 2010 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; + +/** + * A directive indicating the criteria information of a Toc or Topic described in xml + * + * @since 3.5 + */ + +public interface ICriteria extends IUAElement { + + /** + * Returns the name of the criteria element, e.g. + * "Platform" + * + * @return the name of the criteria element + */ + public String getName(); + + /** + * Returns the value of the criteria element, e.g. + * "AIX,Windows" + * + * @return the value of the criteria element + */ + public String getValue(); +} diff --git a/org.eclipse.help/src/org/eclipse/help/IToc2.java b/org.eclipse.help/src/org/eclipse/help/IToc2.java new file mode 100644 index 000000000..1e3d27b00 --- /dev/null +++ b/org.eclipse.help/src/org/eclipse/help/IToc2.java @@ -0,0 +1,42 @@ +/******************************************************************************* + * Copyright (c) 2010 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; + +/** + * IToc2 extends IToc by adding methods to support functionality + * for criteria, topic sorting and custom icons + * @since 3.5 + */ +public interface IToc2 extends IToc{ + + /** + * Return the criteria information of this toc. + * + * @return array of CriterionResource + */ + public ICriteria[] getCriteria(); + + /** + * Toc elements can have non standard icons which are declared using a + * tocIcon element in the org.eclipse.help.toc extension point + * @return NULL if the standard icons are to be used, otherwise the name of + * an icon declared in an org.eclipse.help.toc extension + */ + public String getIcon(); + + /** + * Allows child elements to be sorted alphabetically regardless of their actual + * order in the list of children. + * @return true if the children should be sorted alphabetically + */ + public boolean isSorted(); +} diff --git a/org.eclipse.help/src/org/eclipse/help/ITopic2.java b/org.eclipse.help/src/org/eclipse/help/ITopic2.java new file mode 100644 index 000000000..9ccc9c9bb --- /dev/null +++ b/org.eclipse.help/src/org/eclipse/help/ITopic2.java @@ -0,0 +1,43 @@ +/******************************************************************************* + * Copyright (c) 2010 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; + + +/** + * ITopic2 extends ITopic by adding methods to support functionality + * for criteria, topic sorting and custom icons + * + * @since 3.5 + */ +public interface ITopic2 extends ITopic{ + + /** + * Return the criteria information of topic. + * @return array of CriterionResource + */ + public ICriteria[] getCriteria(); + + /** + * Toc elements can have non standard icons which are declared using a + * tocIcon element in the org.eclipse.help.toc extension point + * @return NULL if the standard icons are to be used, otherwise the name of + * an icon declared in an org.eclipse.help.toc extension + */ + public String getIcon(); + + /** + * Allows child elements to be sorted alphabetically regardless of their actual + * order in the list of children. + * @return true if the children should be sorted alphabetically + */ + public boolean isSorted(); +} 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 df3e34ad5..538dd7b69 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, 2009 IBM Corporation and others. + * Copyright (c) 2006, 2010 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 @@ -10,10 +10,12 @@ *******************************************************************************/ package org.eclipse.help.internal; +import org.eclipse.help.ICriteria; import org.eclipse.help.ITopic; +import org.eclipse.help.ITopic2; import org.w3c.dom.Element; -public class Topic extends UAElement implements ITopic { +public class Topic extends UAElement implements ITopic2 { public static final String NAME = "topic"; //$NON-NLS-1$ public static final String ATTRIBUTE_HREF = "href"; //$NON-NLS-1$ @@ -56,6 +58,10 @@ public class Topic extends UAElement implements ITopic { return (ITopic[])getChildren(ITopic.class); } + public ICriteria[] getCriteria() { + return (ICriteria[]) getChildren(ICriteria.class); + } + public void setHref(String href) { setAttribute(ATTRIBUTE_HREF, href); } @@ -63,4 +69,5 @@ public class Topic extends UAElement implements ITopic { public void setLabel(String label) { setAttribute(ATTRIBUTE_LABEL, label); } + } diff --git a/org.eclipse.help/src/org/eclipse/help/internal/UAElementFactory.java b/org.eclipse.help/src/org/eclipse/help/internal/UAElementFactory.java index b72b86569..112bd648a 100644 --- a/org.eclipse.help/src/org/eclipse/help/internal/UAElementFactory.java +++ b/org.eclipse.help/src/org/eclipse/help/internal/UAElementFactory.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2007, 2009 IBM Corporation and others. + * Copyright (c) 2007, 2010 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 @@ import org.eclipse.help.IAnchor; import org.eclipse.help.ICommandLink; import org.eclipse.help.IContentExtension; import org.eclipse.help.IContext; +import org.eclipse.help.ICriteria; import org.eclipse.help.IInclude; import org.eclipse.help.IIndex; import org.eclipse.help.IIndexEntry; @@ -29,6 +30,7 @@ import org.eclipse.help.IToc; import org.eclipse.help.ITopic; import org.eclipse.help.IUAElement; import org.eclipse.help.internal.context.Context; +import org.eclipse.help.internal.criteria.Criteria; import org.eclipse.help.internal.extension.ContentExtension; import org.eclipse.help.internal.index.Index; import org.eclipse.help.internal.index.IndexEntry; @@ -57,6 +59,7 @@ public class UAElementFactory { { ICommandLink.class, CommandLink.class }, { IIndex.class, Index.class }, { IContentExtension.class, ContentExtension.class }, + { ICriteria.class, Criteria.class }, }; private static final Map classByElementName; @@ -74,6 +77,7 @@ public class UAElementFactory { classByElementName.put(Link.NAME, Link.class); classByElementName.put(IndexSee.NAME, IndexSee.class); classByElementName.put(IndexSubpath.NAME, IndexSubpath.class); + classByElementName.put(Criteria.NAME, Criteria.class); classByElementName.put(ContentExtension.NAME_CONTRIBUTION, ContentExtension.class); classByElementName.put(ContentExtension.NAME_CONTRIBUTION_LEGACY, ContentExtension.class); classByElementName.put(ContentExtension.NAME_REPLACEMENT, ContentExtension.class); diff --git a/org.eclipse.help/src/org/eclipse/help/internal/criteria/Criteria.java b/org.eclipse.help/src/org/eclipse/help/internal/criteria/Criteria.java new file mode 100644 index 000000000..ac491ee02 --- /dev/null +++ b/org.eclipse.help/src/org/eclipse/help/internal/criteria/Criteria.java @@ -0,0 +1,55 @@ +/******************************************************************************* + * Copyright (c) 2010 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.criteria; + +import org.eclipse.help.ICriteria; +import org.eclipse.help.internal.UAElement; +import org.w3c.dom.Element; + +/** + * A directive indicating the criteria information of a Toc or Topic described in xml + * + * @since 3.5 + */ + +public class Criteria extends UAElement implements ICriteria { + + public static final String NAME = "criteria"; //$NON-NLS-1$ + public static final String ATTRIBUTE_NAME = "name"; //$NON-NLS-1$ + public static final String ATTRIBUTE_VALUE = "value"; //$NON-NLS-1$ + + public Criteria(ICriteria src) { + super(NAME,src); + setName(src.getName()); + setValue(src.getValue()); + } + + public Criteria(Element element) { + super(element); + } + + public String getName() { + return getAttribute(ATTRIBUTE_NAME); + } + + public String getValue() { + return getAttribute(ATTRIBUTE_VALUE); + } + + public void setName(String name) { + setAttribute(ATTRIBUTE_NAME, name); + } + + public void setValue(String value) { + setAttribute(ATTRIBUTE_VALUE, value); + } +} diff --git a/org.eclipse.help/src/org/eclipse/help/internal/criteria/CriteriaPreferences.java b/org.eclipse.help/src/org/eclipse/help/internal/criteria/CriteriaPreferences.java new file mode 100644 index 000000000..bf5a7b16c --- /dev/null +++ b/org.eclipse.help/src/org/eclipse/help/internal/criteria/CriteriaPreferences.java @@ -0,0 +1,90 @@ +/******************************************************************************* + * Copyright (c) 2010 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.criteria; + +import java.util.ArrayList; +import java.util.HashMap; +import java.util.HashSet; +import java.util.List; +import java.util.Map; +import java.util.Set; +import java.util.StringTokenizer; + +import org.eclipse.core.runtime.Platform; +import org.eclipse.help.ICriteria; +import org.eclipse.help.internal.HelpPlugin; + +/** + * Get criteria related parameter from preferences.ini + * + * @since 3.5 + */ +public class CriteriaPreferences { + + private final static String SUPPORTED_CRITERIA = "supportedCriteria"; //$NON-NLS-1$ + private final static String ENABLE_CRITERIA = "enableCriteria"; //$NON-NLS-1$ + + private List supportedCriteria; + private boolean criteriaEnabled; + private Map allCriteriaValues; + + static class InstanceHolder{ + static CriteriaPreferences instance = new CriteriaPreferences(); + } + + private CriteriaPreferences() { + criteriaEnabled = Platform.getPreferencesService().getBoolean(HelpPlugin.PLUGIN_ID, ENABLE_CRITERIA, false, null); + + supportedCriteria = new ArrayList(); + StringTokenizer criteria = new StringTokenizer(Platform.getPreferencesService().getString(HelpPlugin.PLUGIN_ID, SUPPORTED_CRITERIA, "", null), ",;"); //$NON-NLS-1$ //$NON-NLS-2$ + while (criteria.hasMoreTokens()) { + supportedCriteria.add(criteria.nextToken().toLowerCase().trim()); + } + + allCriteriaValues = new HashMap(); + } + + public static CriteriaPreferences getInstance() { + return InstanceHolder.instance; + } + + public boolean isSupportedCriterion(String criterion){ + if(null != criterion && supportedCriteria.contains(criterion.toLowerCase())){ + return true; + } + return false; + } + + public boolean isCriteriaEnabled(){ + return criteriaEnabled; + } + + public void addCriteriaValues(ICriteria[] criteria){ + CriterionResource[] resources = CriterionResource.toCriterionResource(criteria); + for(int i = 0; i < resources.length; ++ i){ + CriterionResource criterion = resources[i]; + String criterionName = criterion.getCriterionName(); + List criterionValues = criterion.getCriterionValues(); + + Set existedValues = (Set)allCriteriaValues.get(criterionName); + if (null == existedValues) + existedValues = new HashSet(); + existedValues.addAll(criterionValues); + allCriteriaValues.put(criterionName, existedValues); + } + } + + public Map getAllCriteriaValues(){ + return allCriteriaValues; + } + +} diff --git a/org.eclipse.help/src/org/eclipse/help/internal/criteria/CriterionResource.java b/org.eclipse.help/src/org/eclipse/help/internal/criteria/CriterionResource.java new file mode 100644 index 000000000..d70f39bfd --- /dev/null +++ b/org.eclipse.help/src/org/eclipse/help/internal/criteria/CriterionResource.java @@ -0,0 +1,80 @@ +package org.eclipse.help.internal.criteria; + +import java.util.ArrayList; +import java.util.Arrays; +import java.util.Iterator; +import java.util.List; + +import org.eclipse.help.ICriteria; + +/** + * A class represents one criterion, which has the name and values + * + * @since 3.5 + */ +public class CriterionResource { + + private String criterionName; + private List criterionValues; + + public CriterionResource(String criterionName){ + this(criterionName, null); + } + + public CriterionResource (String criterionName, List criterionValues){ + this.criterionName = criterionName; + this.criterionValues = new ArrayList(); + if(null != criterionValues) { + this.addCriterionValues(criterionValues); + } + } + + public String getCriterionName(){ + return this.criterionName; + } + + public List getCriterionValues(){ + return this.criterionValues; + } + + public void addCriterionValue(String criterionValue){ + if(null != criterionValue && 0 != criterionValue.length() && !criterionValues.contains(criterionValue)){ + criterionValues.add(criterionValue); + } + } + + public void addCriterionValues(List criterionValues){ + for(Iterator iterator = criterionValues.iterator(); iterator.hasNext();){ + String criterionValue = (String) iterator.next(); + this.addCriterionValue(criterionValue); + } + } + + public static CriterionResource[] toCriterionResource(ICriteria[] criteriaElements) { + List criteriaList = new ArrayList(); + outer: for (int i = 0; i < criteriaElements.length; ++i) { + String elementName = criteriaElements[i].getName(); + String elementValue = criteriaElements[i].getValue(); + if (null != elementName && 0 != elementName.length() && null != elementValue + && 0 != elementValue.length()) { + if (CriteriaPreferences.getInstance().isSupportedCriterion(elementName)) { + elementName = elementName.toLowerCase(); + List values = Arrays.asList(elementValue.split(",")); //$NON-NLS-1$ + for(int j = 0; j < criteriaList.size(); ++j){ + CriterionResource criterion = (CriterionResource) criteriaList.get(j); + if(elementName.equals(criterion.getCriterionName())){ + criterion.addCriterionValues(values); + continue outer; + } + } + CriterionResource criterionResource = new CriterionResource(elementName, values); + criteriaList.add(criterionResource); + } + } + } + CriterionResource[] criteria = new CriterionResource[criteriaList.size()]; + criteriaList.toArray(criteria); + return criteria; + } + +} 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 e1df434c2..c67e411bc 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 @@ -1,12 +1,10 @@ /******************************************************************************* - * 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 - * http://www.eclipse.org/legal/epl-v10.html + * Copyright (c) 2006, 2010 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 + * Contributors: IBM Corporation - initial API and implementation *******************************************************************************/ package org.eclipse.help.internal.toc; @@ -14,14 +12,17 @@ import java.util.HashMap; import java.util.Map; import org.eclipse.core.expressions.IEvaluationContext; +import org.eclipse.help.ICriteria; import org.eclipse.help.IToc; +import org.eclipse.help.IToc2; import org.eclipse.help.ITocContribution; import org.eclipse.help.ITopic; +import org.eclipse.help.ITopic2; import org.eclipse.help.IUAElement; import org.eclipse.help.internal.UAElement; import org.w3c.dom.Element; -public class Toc extends UAElement implements IToc { +public class Toc extends UAElement implements IToc2 { public static final String NAME = "toc"; //$NON-NLS-1$ public static final String ATTRIBUTE_LABEL = "label"; //$NON-NLS-1$ @@ -29,8 +30,8 @@ public class Toc extends UAElement implements IToc { public static final String ATTRIBUTE_TOPIC = "topic"; //$NON-NLS-1$ 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$ + 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; @@ -46,11 +47,11 @@ public class Toc extends UAElement implements IToc { } appendChildren(src.getChildren()); } - + public Toc(Element src) { super(src); } - + /* * Creates a mapping of all topic hrefs to ITopics. */ @@ -60,31 +61,31 @@ public class Toc extends UAElement implements IToc { map.put(topic.getHref(), topic); } ITopic[] topics = getTopics(); - for (int i=0;i= 0) { //anchor exists, drop it and add href again to map + if (anchorIx >= 0) { // anchor exists, drop it and add href again to map String simpleHref = href.substring(0, anchorIx); if (!map.containsKey(simpleHref)) { map.put(simpleHref, topic); } - } + } } ITopic[] subtopics = topic.getSubtopics(); if (subtopics != null) { - for (int i=0;i