HelpBrowser openOn:topic page:????

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
5 messages Options
tty
Reply | Threaded
Open this post in threaded view
|

HelpBrowser openOn:topic page:????

tty
Hi all,

I would like to access a particular page on one of my custom HelpTopics.

Browsing the HelpAPI help, I see several ways to open on a HelpTopic but no way to open a help browser on a HelpTopic at a particular page.


This functionality (or the "link" functionality I see on the Help search results) would be very helpful in the custom Help I am working on for CMakeVMMakerSqueak.


Does this exist?

thanks for your time.

tty





Reply | Threaded
Open this post in threaded view
|

Re: HelpBrowser openOn:topic page:????

marcel.taeumel
Hi Timothy,

this help system consists of help topics, which form a hierarchy. Each such topic has text content. Given this, there is no distinction between "topic" and "page". There are just topics.

As you have correctly found out, you can open any help topic via HelpBrowser class >> #openOn:. This works with all arguments that understand #asHelpTopic and are hence able to represent themselves in the right format. You can browse implementors of #asHelpTopic for more details.

While you can open any help topic (in any tree of topics) with the help browser, you are right, it might be helpful to open some "root topic" and select some sub topic in it. I guess that's the "page" you are referring to. :-)

Here is an example on how to do that:

(HelpBrowser openOn: HelpOnHelp) model
   showTopicThat: [:topic | topic title beginsWith: 'API'].

This iterates the help structure until one topic returns "true". It's like #detect:. It selects the result.

However, there can be a problem with writing such code because display strings tend to be translated and changed. Therfore, help topics can have a #key property to encode an id to refer to in that block. If there is no key, you have to check for another property.

You might wonder, why this is so. Well, the creation of help topics is a dynamic process. There is, for example, SWikiHelp, which fetches Web content and parses sub-topics. So, we have to search for the topic to show, instead of directly referring to it object-wise. If you get access to an instance of HelpTopic, you can read it, but it might not be valid for a long time because the Help Browser can update its caches.

Best,
Marcel
tty
Reply | Threaded
Open this post in threaded view
|

Re: HelpBrowser openOn:topic page:????

tty
Hi Marcel,

Thank you for your time and reply.

I understand what the openOn: method does.

Here is what I would like to do...

In my  

CustomHelp subclass: #CMakeVMMakerSqueakHelp

I have the class side method

pages
    ^#(overview  prerequisites  namingConventions  )


When I run

HelpBrowser openOn: CMakeVMMakerSqueakOverviewHelp

it opens the HelpBrowser just fine and the pages appear in the left hand panel.


What I would like to do is have it select the namingConventions page
Something like:

HelpBrowser openOn: CMakeVMMakerSqueakOverviewHelp page: #namingConventions


If the functionality does not exist, so be it. I may try adding it at another time.

cheers,

tty




---- On Mon, 16 May 2016 14:16:46 -0400 marcel.taeumel <[hidden email]> wrote ----
Hi Timothy,

this help system consists of help topics, which form a hierarchy. Each such
topic has text content. Given this, there is no distinction between "topic"
and "page". There are just topics.

As you have correctly found out, you can open any help topic via HelpBrowser
class >> #openOn:. This works with all arguments that understand
#asHelpTopic and are hence able to represent themselves in the right format.
You can browse implementors of #asHelpTopic for more details.

While you can open any help topic (in any tree of topics) with the help
browser, you are right, it might be helpful to open some "root topic" and
select some sub topic in it. I guess that's the "page" you are referring to.
:-)

Here is an example on how to do that:

(HelpBrowser openOn: HelpOnHelp) model
showTopicThat: [:topic | topic title beginsWith: 'API'].

This iterates the help structure until one topic returns "true". It's like
#detect:. It selects the result.

However, there can be a problem with writing such code because display
strings tend to be translated and changed. Therfore, help topics can have a
#key property to encode an id to refer to in that block. If there is no key,
you have to check for another property.

You might wonder, why this is so. Well, the creation of help topics is a
dynamic process. There is, for example, SWikiHelp, which fetches Web content
and parses sub-topics. So, we have to search for the topic to show, instead
of directly referring to it object-wise. If you get access to an instance of
HelpTopic, you can read it, but it might not be valid for a long time
because the Help Browser can update its caches.

Best,
Marcel



--
View this message in context: http://forum.world.st/HelpBrowser-openOn-topic-page-tp4895008p4895185.html
Sent from the Squeak - Dev mailing list archive at Nabble.com.





Reply | Threaded
Open this post in threaded view
|

Re: HelpBrowser openOn:topic page:????

marcel.taeumel
Hi Timothy,

for this case, this should work:

(HelpBrowser openOn: CMakeVMMakerSqueakOverviewHelp) model
   showTopicThat: [:topic | topic key = #namingConventions].

Yes, you can add a shortcut like #openOn:page: if you want to. :-)

Best,
Marcel
tty
Reply | Threaded
Open this post in threaded view
|

Re: HelpBrowser openOn:topic page:????

tty
Hi Marcel,

My apologies I replied before trying your code.


(HelpBrowser openOn: CMakeVMMakerSqueakOverviewHelp) model
showTopicThat: [:topic | topic key = #namingConventions].

Is exactly what I am looking for.



If you are the maintainer of the Help System then this information would be useful in one of the pages in this section here:

(HelpBrowser openOn: HelpHowToHelpTopics) model
showTopicThat: [:topic | topic key = #page5].



Since the functionality exists, I will look into (when I get time) creating the functionality that exists in the Search Results where  (open topic) "hyperlinks" are created.


thank you for your time.

tty






---- On Tue, 17 May 2016 04:54:26 -0400 marcel.taeumel <[hidden email]> wrote ----
Hi Timothy,

for this case, this should work:

(HelpBrowser openOn: CMakeVMMakerSqueakOverviewHelp) model
showTopicThat: [:topic | topic key = #namingConventions].

Yes, you can add a shortcut like #openOn:page: if you want to. :-)

Best,
Marcel



--
View this message in context: http://forum.world.st/HelpBrowser-openOn-topic-page-tp4895008p4895307.html
Sent from the Squeak - Dev mailing list archive at Nabble.com.