You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@felix.apache.org by Felix Meschberger <fm...@adobe.com> on 2013/01/30 19:56:51 UTC
[WebConsole] Help/Doc Links
Hi all,
Let me shed some light on bugs FELIX-3879 and FELIX-3880: The goal is be able to link to more detailed information from the configuration (and other) pages. For example we have the Web Console configuration with some terse description of the properties. It would be helpful if we could draw a help button which leads the administrator to a web page providing more in-depth information about the configuration, the configured service or such.
IMHO the solution proposed by FELIX-3879 and FELIX-3880 is too complicated and out-of-band, particularly because it uses additional requests to load potential data. It also opens up for breaking the web console alltogether.
How about a different approach:
(1) We define a service interface
public interface HelperProvider {
public String getHelp(String topic);
}
The service returns an URL pointing to a web page providing more information.
(2) Topics are just strings consisting of a domain (e.g. bundle, configuration, component) and an identification (e.g. bundle symbolic name, configuration PID, component name) separated by a slash:
configuration/org.apache.felix.webconsole.internal.servlet.OsgiManager
bundle/org.apache.felix.webconsole
(3) Multiple service can be registered which are queried in service.ranking order. The first non-null response is used.
(4) That URL is the used as a link behind the help button. If there is no URL, the link button is disabled.
Only "high-level" help is supported for configuration, bundles, etc. Property level (in the case of configuration) information is available in the descriptions with more details to be provided by the configuration-level page.
WDYT ?
Regards
Felix
Re: [WebConsole] Help/Doc Links
Posted by Justin Edelson <ju...@justinedelson.com>.
I would suggest naming the method getHelpUrl(). getHelp() makes it seem
like the help text is intended to be returned.
Otherwise, LGTM
Regards,
Justin
On Wed, Jan 30, 2013 at 1:56 PM, Felix Meschberger <fm...@adobe.com>wrote:
> Hi all,
>
> Let me shed some light on bugs FELIX-3879 and FELIX-3880: The goal is be
> able to link to more detailed information from the configuration (and
> other) pages. For example we have the Web Console configuration with some
> terse description of the properties. It would be helpful if we could draw a
> help button which leads the administrator to a web page providing more
> in-depth information about the configuration, the configured service or
> such.
>
> IMHO the solution proposed by FELIX-3879 and FELIX-3880 is too complicated
> and out-of-band, particularly because it uses additional requests to load
> potential data. It also opens up for breaking the web console alltogether.
>
> How about a different approach:
>
> (1) We define a service interface
>
> public interface HelperProvider {
> public String getHelp(String topic);
> }
>
> The service returns an URL pointing to a web page providing more
> information.
>
> (2) Topics are just strings consisting of a domain (e.g. bundle,
> configuration, component) and an identification (e.g. bundle symbolic name,
> configuration PID, component name) separated by a slash:
>
> configuration/org.apache.felix.webconsole.internal.servlet.OsgiManager
> bundle/org.apache.felix.webconsole
>
> (3) Multiple service can be registered which are queried in
> service.ranking order. The first non-null response is used.
>
> (4) That URL is the used as a link behind the help button. If there is no
> URL, the link button is disabled.
>
> Only "high-level" help is supported for configuration, bundles, etc.
> Property level (in the case of configuration) information is available in
> the descriptions with more details to be provided by the
> configuration-level page.
>
> WDYT ?
>
> Regards
> Felix
Re: [WebConsole] Help/Doc Links
Posted by Felix Meschberger <fm...@adobe.com>.
Hi,
Yes, two arguments sounds usefull. And we could predefine two or three well-known domains like bundle, configuration.
Regards
Felix
Am 01.02.2013 um 07:09 schrieb Carsten Ziegeler:
> 2013/1/30 Felix Meschberger <fm...@adobe.com>:
>> Hi all,
>>
>> Let me shed some light on bugs FELIX-3879 and FELIX-3880: The goal is be able to link to more detailed information from the configuration (and other) pages. For example we have the Web Console configuration with some terse description of the properties. It would be helpful if we could draw a help button which leads the administrator to a web page providing more in-depth information about the configuration, the configured service or such.
>>
>> IMHO the solution proposed by FELIX-3879 and FELIX-3880 is too complicated and out-of-band, particularly because it uses additional requests to load potential data. It also opens up for breaking the web console alltogether.
>>
>> How about a different approach:
>>
>> (1) We define a service interface
>>
>> public interface HelperProvider {
>> public String getHelp(String topic);
>> }
>>
>> The service returns an URL pointing to a web page providing more information.
>>
>> (2) Topics are just strings consisting of a domain (e.g. bundle, configuration, component) and an identification (e.g. bundle symbolic name, configuration PID, component name) separated by a slash:
>>
>> configuration/org.apache.felix.webconsole.internal.servlet.OsgiManager
>> bundle/org.apache.felix.webconsole
>
> I think we should use two arguments for the method - one for the
> domain and one for the identification - otherwise the caller needs to
> concat the string and the implementor needs to parse the string and
> create substrings. This makes it a little bit easier to call and
> implement.
>
> Carsten
>
>>
>> (3) Multiple service can be registered which are queried in service.ranking order. The first non-null response is used.
>>
>> (4) That URL is the used as a link behind the help button. If there is no URL, the link button is disabled.
>>
>> Only "high-level" help is supported for configuration, bundles, etc. Property level (in the case of configuration) information is available in the descriptions with more details to be provided by the configuration-level page.
>>
>> WDYT ?
>>
>> Regards
>> Felix
>
>
>
> --
> Carsten Ziegeler
> cziegeler@apache.org
Re: [WebConsole] Help/Doc Links
Posted by Carsten Ziegeler <cz...@apache.org>.
2013/1/30 Felix Meschberger <fm...@adobe.com>:
> Hi all,
>
> Let me shed some light on bugs FELIX-3879 and FELIX-3880: The goal is be able to link to more detailed information from the configuration (and other) pages. For example we have the Web Console configuration with some terse description of the properties. It would be helpful if we could draw a help button which leads the administrator to a web page providing more in-depth information about the configuration, the configured service or such.
>
> IMHO the solution proposed by FELIX-3879 and FELIX-3880 is too complicated and out-of-band, particularly because it uses additional requests to load potential data. It also opens up for breaking the web console alltogether.
>
> How about a different approach:
>
> (1) We define a service interface
>
> public interface HelperProvider {
> public String getHelp(String topic);
> }
>
> The service returns an URL pointing to a web page providing more information.
>
> (2) Topics are just strings consisting of a domain (e.g. bundle, configuration, component) and an identification (e.g. bundle symbolic name, configuration PID, component name) separated by a slash:
>
> configuration/org.apache.felix.webconsole.internal.servlet.OsgiManager
> bundle/org.apache.felix.webconsole
I think we should use two arguments for the method - one for the
domain and one for the identification - otherwise the caller needs to
concat the string and the implementor needs to parse the string and
create substrings. This makes it a little bit easier to call and
implement.
Carsten
>
> (3) Multiple service can be registered which are queried in service.ranking order. The first non-null response is used.
>
> (4) That URL is the used as a link behind the help button. If there is no URL, the link button is disabled.
>
> Only "high-level" help is supported for configuration, bundles, etc. Property level (in the case of configuration) information is available in the descriptions with more details to be provided by the configuration-level page.
>
> WDYT ?
>
> Regards
> Felix
--
Carsten Ziegeler
cziegeler@apache.org
Re: [WebConsole] Help/Doc Links
Posted by Carsten Ziegeler <cz...@apache.org>.
+1, that's basically what I proposed in one of the issues (not that
detailed though) :)
I personally would separate the topic from the identication by a
colon, llike bundle:org.apache.felix.webconsole... but that's not that
important
Carsten
2013/1/30 Felix Meschberger <fm...@adobe.com>:
> Hi all,
>
> Let me shed some light on bugs FELIX-3879 and FELIX-3880: The goal is be able to link to more detailed information from the configuration (and other) pages. For example we have the Web Console configuration with some terse description of the properties. It would be helpful if we could draw a help button which leads the administrator to a web page providing more in-depth information about the configuration, the configured service or such.
>
> IMHO the solution proposed by FELIX-3879 and FELIX-3880 is too complicated and out-of-band, particularly because it uses additional requests to load potential data. It also opens up for breaking the web console alltogether.
>
> How about a different approach:
>
> (1) We define a service interface
>
> public interface HelperProvider {
> public String getHelp(String topic);
> }
>
> The service returns an URL pointing to a web page providing more information.
>
> (2) Topics are just strings consisting of a domain (e.g. bundle, configuration, component) and an identification (e.g. bundle symbolic name, configuration PID, component name) separated by a slash:
>
> configuration/org.apache.felix.webconsole.internal.servlet.OsgiManager
> bundle/org.apache.felix.webconsole
>
> (3) Multiple service can be registered which are queried in service.ranking order. The first non-null response is used.
>
> (4) That URL is the used as a link behind the help button. If there is no URL, the link button is disabled.
>
> Only "high-level" help is supported for configuration, bundles, etc. Property level (in the case of configuration) information is available in the descriptions with more details to be provided by the configuration-level page.
>
> WDYT ?
>
> Regards
> Felix
--
Carsten Ziegeler
cziegeler@apache.org