001: /***************************************************************************************************
002: * Copyright (c) 2006 IBM Corporation and others. All rights reserved. This program and the
003: * accompanying materials are made available under the terms of the Eclipse Public License v1.0
004: * which accompanies this distribution, and is available at
005: * http://www.eclipse.org/legal/epl-v10.html
006: *
007: * Contributors: IBM Corporation - initial API and implementation
008: **************************************************************************************************/package org.eclipse.ui.intro.config;
009:
010: import java.util.Map;
011:
012: import org.eclipse.ui.internal.intro.impl.IntroPlugin;
013: import org.eclipse.ui.intro.IIntroSite;
014:
015: /**
016: * Classes that extend this abstract class are used to configure <code>CustomizableIntroPart</code>.
017: * Since it is possible for multiple products to use the same intro configuration, this class allows
018: * them to customize some aspects of the intro content so that it looks different for different
019: * products even though they all share the same intro implementation and content.
020: *
021: * @since 3.2
022: */
023:
024: public abstract class IntroConfigurer {
025:
026: /**
027: * The identifier of the named group where the configurer can contribute local tool bar actions.
028: *
029: * @see #init(IIntroSite, Map)
030: */
031: public static final String TB_ADDITIONS = "additions"; //$NON-NLS-1$
032:
033: protected Map themeProperties;
034: protected IIntroSite site;
035:
036: /**
037: * Provides the opportunity for the configurer to contribute to the action bars and to fetch
038: * presentation theme properties.
039: *
040: * @param site
041: * the intro part's site
042: * @param themeProperties
043: * properties of the current theme that can be used by the configurer, or
044: * <code>null</code> if no theme is currently active or the active theme has no
045: * properties.
046: */
047: public void init(IIntroSite site, Map themeProperties) {
048: this .themeProperties = themeProperties;
049: this .site = site;
050: }
051:
052: /**
053: * Returns the value of the theme property with a given name.
054: *
055: * @param name
056: * the theme property name
057: * @return the value of the property or <code>null</code> if property is not found, the theme
058: * does not have properties or no theme is currently active.
059: */
060:
061: protected String getThemeProperty(String name) {
062: if (themeProperties == null)
063: return null;
064: String value = (String) themeProperties.get(name);
065: if (value != null)
066: value = IntroPlugin.getDefault().getIntroModelRoot()
067: .resolveVariables(value);
068: return value;
069: }
070:
071: /**
072: * Returns the value of the variable defined by the configurer. This variable can appear in XML
073: * content files in attribute names and values of elements. Whenever $variable$ is encountered
074: * in the content, it is evaluated using this class by passing 'variable' to this method and
075: * substituting the result in the content.
076: *
077: * @param variableName
078: * the name of the substitution variable
079: * @return the value to substitute in place of a variable or <code>null</code> if the variable
080: * cannot be resolved.
081: */
082: public abstract String getVariable(String variableName);
083:
084: /**
085: * Returns the children of computed groups. Groups marked as computed will be completed at run
086: * time when the group is asked to provide children.
087: *
088: * @param pageId
089: * the identifier of the page in which this group appears
090: * @param groupId
091: * the identifier of the group group within the page
092: * @return an array of intro elements for this group. Each intro element should contain only
093: * legal elements and attributes according to the intro content schema. Returns an empty
094: * array for no children.
095: */
096: public abstract IntroElement[] getGroupChildren(String pageId,
097: String groupId);
098:
099: /**
100: * Returns an array of elements that will be used to build launch bar short cut links. Override
101: * this method if the intro launch bar has been marked as computed.
102: *
103: * @return an array of elements that will be used to dynamically build shortcut links.
104: */
105: public IntroElement[] getLaunchBarShortcuts() {
106: return new IntroElement[] {};
107: }
108:
109: /**
110: * Resolves an incomplete path in the form "page_id/@" where page_id represents the identifier
111: * of the target page. The configurator should complete the path according to its internal
112: * resolution mechanism. The final path must point at an anchor in the referenced page.
113: *
114: * @param extensionId
115: * the id specified for the config extension
116: * @param path
117: * the incomplete path specified for the config extension
118: * @return the complete path that points at the anchor element in the referenced page, or
119: * <code>null</code> if the path cannot be resolved or the extension should be hidden.
120: */
121: public abstract String resolvePath(String extensionId, String path);
122:
123: /**
124: * Returns the style value that will be mixed in with the original style of the extension.
125: * Themes can use this feature to render certain extensions differently.
126: *
127: * @param pageId
128: * the identifier of the target page that this extension is contributed into
129: * @param extensionId
130: * the identifier of the extension to provide the mixin style for.
131: * @return the style to add to the original extension style or <code>null</code> if no mixin
132: * style is found for this extension.
133: */
134: public String getMixinStyle(String pageId, String extensionId) {
135: return null;
136: }
137: }
|