This Bugzilla instance is a read-only archive of historic NetBeans bug reports. To report a bug in NetBeans please follow the project's instructions for reporting issues.

Bug 27892 - [2004-04-30] open help viewer link in external browser
Summary: [2004-04-30] open help viewer link in external browser
Status: RESOLVED FIXED
Alias: None
Product: platform
Classification: Unclassified
Component: Help System (show other bugs)
Version: 3.x
Hardware: All All
: P2 blocker (vote)
Assignee: mslama
URL:
Keywords: API, UI
Depends on:
Blocks:
 
Reported: 2002-10-09 17:18 UTC by John Jullion-ceccarelli
Modified: 2008-12-22 23:34 UTC (History)
2 users (show)

See Also:
Issue Type: ENHANCEMENT
Exception Reporter:


Attachments
screenshot of external link (1.47 MB, image/png)
2004-04-30 14:22 UTC, John Jullion-ceccarelli
Details
screenshot in the correct format (24.81 KB, image/png)
2004-04-30 14:23 UTC, John Jullion-ceccarelli
Details

Note You need to log in before you can comment on or make changes to this bug.
Description John Jullion-ceccarelli 2002-10-09 17:18:51 UTC
Presently any link in the help viewer to an
external web page opens the page in the help
viewer. Could we write a lightweight component or
<OBJECT> tag that would open the page in the IDE's
external browser?
Comment 1 Patrick Keegan 2004-04-09 13:30:52 UTC
raising to P2 and changing target milestone to reflect it's target
status for promo D
Comment 2 _ tboudreau 2004-04-09 14:42:56 UTC
FYI, I'm not sure if this is even possible - javahelp gets first crack at URLs that are clicked, 
so it depends how flexible it is.
Comment 3 Patrick Keegan 2004-04-09 14:59:32 UTC
When we ask for the feature in JH, Binky usually replies with "create
a lightweight component" for it, so it's possible, I think. The key is
that we probably couldn't use a simple <a href> tag in the files. We'd
have to use JavaHelp's <OBJECT> tag, which already enables such things
as displaying little popups (like for glossary items) in the help.
Comment 4 Jesse Glick 2004-04-14 01:36:37 UTC
Do you really want an <object> tag in your HTML for every external
link?? This sounds extremely ugly to me.
Comment 5 Patrick Keegan 2004-04-14 23:41:28 UTC
I don't *want* an OBJECT tag, per se, but that would be better than
not having the feature at all.
Comment 6 mslama 2004-04-26 15:05:29 UTC
Could it be that external browser would be opened when protocol is
http (ie. link points to external web page) or am I missing some other
possibility?
Comment 7 Patrick Keegan 2004-04-26 15:09:20 UTC
This is what I'm thinking, but I could also be missing another
possibility. :-)
Comment 8 Jesse Glick 2004-04-26 20:21:16 UTC
"Could it be that external browser would be opened when protocol is
http (ie. link points to external web page) or am I missing some other
possibility?" - well that's we want, obviously. How to make it happen,
I don't know. You can listen to URL changes in the JHelp object and
open the external browser if the user clicks on an http: URL, but it
will still show the page in the JHelp. Whether you can override the
link activation handler in JavaHelp (without nasty hacks), I don't know.
Comment 9 mslama 2004-04-27 14:34:25 UTC
I checked JHelp -> JHelpContentViewer -> BasicContentViewerUI and
unfortunately we cannot detect activation of hyperlink in content
viewer. Handling of hyperlink activation is done purely in UI class
BasicContentViewerUI. There is private class JHEditorPane - subclass
of JEditorPane. UI class listens to this editor pane using
HyperlinkListener and updates its content as event is fired. This is
purely private in UI class so we cannot detect that hyperlink is
activated (ie. link is clicked in content viewer - right part of help
window).

I can retrieve content viewer from JHelp and UI from content viewer
but not editor pane from UI.

Jesse what did you mean by link activation handler in
org.org.netbeans.modules.javahelp.JavaHelp? I did not find anything
like that. There is only AWTEventListener to handle
activation/deactivation.

Here is part of call stack what happens when I click on hyperlink in
content viewer (JEditorPane is actually subclass used privately in
BasicContentViewerUI):
## linkActivated
u:nbdocs://org.netbeans.modules.web.monitor/org/netbeans/modules/web/monitor/docs/monitor/ctx_monitorintro.html
java.lang.Exception: Stack trace
        at java.lang.Thread.dumpStack(Thread.java:1064)
        at
javax.help.plaf.basic.BasicContentViewerUI.linkActivated(BasicContentViewerUI.java:381)
        at
javax.help.plaf.basic.BasicContentViewerUI.hyperlinkUpdate(BasicContentViewerUI.java:362)
        at
javax.swing.JEditorPane.fireHyperlinkUpdate(JEditorPane.java:318)
        at
javax.swing.text.html.HTMLEditorKit$LinkController.activateLink(HTMLEditorKit.java:798)
        at
javax.swing.text.html.HTMLEditorKit$LinkController.mouseClicked(HTMLEditorKit.java:608)
        at
java.awt.AWTEventMulticaster.mouseClicked(AWTEventMulticaster.java:212)
Comment 10 Jesse Glick 2004-04-27 15:03:41 UTC
AFAIK you can listen to the HelpModel from the JHelp and if you get a
HelpModelListener.idChanged event, check the URL to see if it is
external. I think it works to *track* URL changes, but AFAIK you can't
cancel or intercept them.
Comment 11 mslama 2004-04-27 15:15:33 UTC
I have found that help model listener of content viewer works fine for
activation of hyperlink but in case of external link page cannot be
displayed due to IOException: Unknown host => model is not changed.
And there is no event like: We are going to display this URL. So I
cannot chekc URL before it is displayed or before it fails to invoke
external browser.
Comment 12 mslama 2004-04-27 15:17:21 UTC
If I set proxy it could work but as Jesse said link is displayed also
in Help window. And I do not think we can do anything with it. So
external link would be displayed both in external browser and in Help
window.
Comment 13 mslama 2004-04-27 15:55:39 UTC
As suggested above another possibility is to create lightweight
component invoked by <object> tag. Please Patrick or John what do you
preffer?
Comment 14 Patrick Keegan 2004-04-27 16:26:48 UTC
I tend to think that having to use the <OBJECT> tag is less ugly for
us than having web pages also open in JavaHelp.

Obviously, it would be best if we didn't have to use the <OBJECT> tag
since we might want to use the help topics as normal web pages also.
But I don't think  it's acceptable that links to outside web pages
would open in JavaHelp (at least not the currently implemented viewer,
which does not handle any modern web design gracefully).
Comment 15 John Jullion-ceccarelli 2004-04-28 09:58:25 UTC
I also agree that using the <OBJECT> tag is the cleanest from the
point of view of what the user sees, so we should go with that even
though it's uglier implementation-wise.
Comment 16 mslama 2004-04-29 10:26:33 UTC
I created lightweight component. It is very similar to
JHSecondaryViewer. Mouse enabled label (text) is displayed. When it is
clicked default IDE browser is invoked:
HtmlBrowser.URLDisplayer.getDefault().showURL(link) is called.

Example usage:
<OBJECT CLASSID="java:org.netbeans.modules.javahelp.BrowserDisplayer">
<param name="content" value="http://java.sun.com/downloads/ea/index.html">
<param name="text" value="Early Access">
<param name="textFontSize" value="medium">
<param name="textColor" value="blue">
</OBJECT>

Note: Undeline style is not supported.
Comment 17 Jesse Glick 2004-04-29 15:45:50 UTC
You need to mention this syntax in the JavaHelp module API
documentation. Can be marked <div class="nonnormative"> ... </div> if
you do not wish to support it indefinitely. Would be good to make a
note of it in the architecture summary too.

Re. the parameters syntax, probably you could dispense with
textFontSize and textColor and just let text use HTML? E.g.

<object classid="java:org.netbeans.modules.javahelp.BrowserDisplayer">
 <param name="content"
value="http://java.sun.com/downloads/ea/index.html">
 <param name="text" value="&lt;span class='hyperlink'&gt;Early
Access&lt;/span&gt;">
</object>
Comment 18 mslama 2004-04-30 11:20:12 UTC
It seems html for JButton does not work. I used even:<html><body><span
style="text-decoration: underline;">Early Access</span></body></html>
which is displayed as underlined text in Browser. (I also removed all
other params and checked that no other setter is called and text of
button label is NOT underlined.

I could use html renderer (According to Tim is should be available
next week.)

I could also paint undeline directly by overwriting paintComponent.
Comment 19 mslama 2004-04-30 12:28:02 UTC
I checked Java Tutorial and JButton supports html. This simple html
works: <html><u>Early Access</u></html>. I would keep additional
parameters for greater flexibility. Current example is:
<OBJECT CLASSID="java:org.netbeans.modules.javahelp.BrowserDisplayer">
<param name="content" value="http://java.sun.com/downloads/ea/index.html">
<param name="text" value="&lt;html&gt;&lt;u&gt;Early
Access&lt;/u&gt;&lt;/html&gt;">
<param name="textFontSize" value="medium">
<param name="textColor" value="blue">
</OBJECT>

and looks as other hyperlinks.

What doc people think? Do you prefer to set evrything using html and
keep just text parameter or leave other parameters too?
textFontFamily
textFontSize
textFontWeight
textFontStyle
textColor
Comment 20 mslama 2004-04-30 13:05:16 UTC
I tried again to be but class='hyperlink' does not work. (Text is not
underlined.)
Comment 21 John Jullion-ceccarelli 2004-04-30 14:20:47 UTC
The formatting looks fine on WinXP, only problem is that the text is
alligned in the center for some reason. See screenshot.
Comment 22 John Jullion-ceccarelli 2004-04-30 14:22:00 UTC
Created attachment 14641 [details]
screenshot of external link
Comment 23 John Jullion-ceccarelli 2004-04-30 14:23:29 UTC
Created attachment 14642 [details]
screenshot in the correct format
Comment 24 John Jullion-ceccarelli 2004-04-30 14:23:55 UTC
sorry, saved the screenshot in the wrong format, the .png is the
correct one.
Comment 25 mslama 2004-04-30 14:32:50 UTC
Center alignment is already fixed. I changed alignment inside button
to be LEFT.
Comment 26 John Jullion-ceccarelli 2004-04-30 14:38:48 UTC
Almost forgot. Is this button accessible? Meaning, is there a way for
people with screenreaders to get the link, something like alt text for
images? 
Comment 27 mslama 2004-04-30 14:48:30 UTC
No it is not accessible. Accessibility must be added.
Comment 28 Jesse Glick 2004-04-30 18:25:20 UTC
BTW just thought of an alternate possible implementation which might
be a lot simpler: a special URL protocol handler which would wrap an
external link, and when you try to open a connection on it it just
throws an IOException (I think this will make JavaHelp just beep and
do nothing else), but simultaneously show the real URL in the external
browser. E.g. in your JavaHelp page would have simply

---%<---
See <a href="external://http://ant.apache.org/">Apache Ant</a> for
more information.
---%<---

Then the text looks like a link because it is a link, accessibility
and CSS compliance comes for free, etc. etc. The only drawback is that
one beep. :-)
Comment 29 mslama 2004-05-03 08:33:40 UTC
Doc team what do you think? Should I check this possibility?
Comment 30 John Jullion-ceccarelli 2004-05-03 09:48:02 UTC
I would prefer to use the solution that works the best from the user's
point of view, which is the OBJECT solution. Docs don't mind putting
in the extra code for the OBJECT tag. If there's some limitation of
the OBJECT tag that the external protocol resolves (other than it's
simpler) then that's a different story.
Comment 31 mslama 2004-05-04 14:15:50 UTC
Jesse where shall I add documentation of this? Add paragraph to
http://www.netbeans.org/download/dev/javadoc/JavaHelpAPI/org/netbeans/api/javahelp/doc-files/help-guide.html
or elsewhere? Of course in addition to arch update.
Comment 32 mslama 2004-05-04 14:27:02 UTC
I will add some doc to reference
http://www.netbeans.org/download/dev/javadoc/JavaHelpAPI/org/netbeans/api/javahelp/doc-files/api.html.

Where is arch xml? Shall I also increase module spec version from 2.2
to 2.3 in manifest.mf? Anything else?
Comment 33 mslama 2004-05-04 14:35:14 UTC
I found arch.
Comment 34 Jesse Glick 2004-05-04 17:42:20 UTC
Would be good to update module spec version, and create an
apichanges.xml (currently there is none); mention apichanges.xml in
project.properties so it is included in Javadoc.
Comment 35 mslama 2004-05-05 16:59:55 UTC
Accessibility is added for button. Who will add accessible description?
Comment 36 mslama 2004-05-05 17:00:50 UTC
Also module spec version was increased and apichanges was added.
Comment 37 Patrick Keegan 2004-05-12 18:09:31 UTC
I'll add the accessibility description soon, but I'm not sure what I'm
describing. 

Would it be something like "Click here to open this link in a web
browser?"
Comment 38 mslama 2004-05-13 08:47:28 UTC
Yes I think so.
Comment 39 Patrick Keegan 2004-05-14 17:06:39 UTC
OK, let's use "Click here to open this link in a web
browser."
Comment 40 mslama 2004-05-17 11:57:29 UTC
Done. I added accessibility description.