The Help Guy

February, 2010

  • The Help Guy

    Clever workaround for getting dynamically inserted javascript or stylesheets to work in Help Viewer 1.0

    • 0 Comments

    Working with our Visual Studio 2010 (and earlier!) partners, I'm frequently impressed with the ingenuity they demonstrate in just getting things to work. Even though Help systems these days are generally HTML based, there are often some gotchas that come up that are generally limitations due to an implementation.

    With Help Viewer 1.0, one of the current limitations is that when .js or .css files (and other resources in general) are referenced, they essentially need to be hard coded in the topic in order for them to work. The reason for this is that just prior to loading and rendering the topic, the Help runtime does some transforms on the content to fix up the paths so that they are able to be extracted from our MSHC file format. (Just renamed .zip files.)

    What if you want to dynamically reference a .css or .js file depending on the context of the topic itself? For example, suppose the exact same topic is meant to be used in a .CHM or .HxS file, or even possibly on a website? In general, this is currently not supported in Help Viewer 1.0. The reference that would be inserted would not happen until after our transforms are applied, and therefore the path to the .css would not express the full path into the MSHC. It would just not get used at all.

    Richard Sloggett at Innovasys worked out an ingenious solution that he is leveraging in their Document!X and HelpStudio Pro authoring tools, and has kindly agreed to let me share it with the community. Here's what he writes:

    Here’s the core function to get the resource base url - it relies on having a named script element – e.g.

     

    <script id="mshs_support_script" src="scripts/mshs.js" mce_src="scripts/mshs.js" type="text/javascript"></script>

     

    That script element can be anything – it’s just there to discover the store root. Just then append the relative bit (e.g. ResourceBaseUrl + ‘myscript.js’) when adding the new script. 

    /* Gets the MSHS base url for resources */

    function ResourceBaseUrl() {

     

        if (isDesignTime) {

            return '';

        }

        else {

            // Get the first script tag

            var script = document.getElementById('mshs_support_script');

     

            // Extract the src which is a full resource url to within our origin .mshc

            var scriptSrc = script.src;

     

            // Get the portion up to the ; (the base url for resource references)

            var startIndex = scriptSrc.indexOf(';') + 1;

            var scriptUrl = scriptSrc.substring(0, startIndex);

     

            return scriptUrl;

        }

    }

    Brilliant! Thanks Richard, for allowing me to share this with the community.

  • The Help Guy

    Partner Content Discoverability Options in Visual Studio 2010, Part II: Shortcuts

    • 0 Comments

    One of the side benefits of the F1 feature I wrote about the other day is that vendors can effectively create VS IDE Help menu and Start menu shortcuts to their own documentation that will always work, regardless of the end-user's online/offline preference.

     

    The VS 2010 Documentation shortcut looks something like this:

     

    ms-xhelp:///?method=f1&query=msdnstart&product=vs&productVersion=100&locale=en-us

     

    This is just a call to our query API and can be used anywhere once Help Viewer 1.0 is installed.

     

    3rd party integrators can essentially replace that ‘msdnstart’ keyword highlighted above with an F1 keyword that maps to perhaps a portal page in their own content. This would then result in Help being opened up to the Partner content page, again regardless of the end-user’s online/offline state.

     

    Creating an item on the Help menu in the IDE is accomplished by using the method described in VSPackage Tutorial 1: How to Create a VSPackage.

     

    The wizard will result in creating a menu item on the Tools menu and will be defined in a MenuCommandsPackage.vsct file. To get your menu item to show up on the Help menu, look for the following item in this file:

    <Group guid="guidMenuCommandsPackageCmdSet" id="MyMenuGroup" priority="0x0600">

    <Parent guid="guidSHLMainMenu" id="IDM_VS_MENU_TOOLS"/>

    </Group>

    and replace the Parent element with:

     

    <Parent guid="guidSHLMainMenu" id="IDM_VS_MENU_HELP"/>

      

    You can also adjust the string that is used for your menu item and the bitmap that is displayed through entries in this same file.

     

    Finally, to hook up the menu item to your help topic, there should have been a MenuCommandsPackage.cs (or similarly named file) added to your solution after completing the wizard. The methods are stubbed out with message box code to help you prove to yourself that your menu is running. After following the steps I described on this page for adding references for the IVsHelp interfaces, you can add a pretty straightforward call to a page in your content.

    private void MenuItemCallback(object sender, EventArgs e)
    {

    Help help = (VsHelp.Help)GetService(typeof(SVsHelp));

    help.DisplayTopicFromF1Keyword("VS.DevPartner.ReportGen.Settings");

    }

  • The Help Guy

    Partner Content Discoverability Options in Visual Studio 2010, Part I: Context Sensitive Help (F1)

    • 0 Comments

    If you haven't seen the announcement about the Visual Studio 2010 RC release - check out this page. The Visual Studio 2010 RC is immediately available to all comers.

    As we’ve been working our way towards RTM we’ve had lots of invaluable feedback from our partners and our Help Authoring Tool vendors that have had keen eyes toward partner scenarios.

     

    With Visual Studio 2010 and Help Viewer 1.0 we made a conscious decision to make Online the default for most Help related scenarios. In this scenario, we make the calls and experience as efficient as possible by pushing the query directly to our online query service and hosting the entire Help experience from MSDN Online.

     

    Since partner content is not available in MSDN we needed to work out a means to make partner content discoverable, which by definition would be offline content (at this time) when the user’s default was set to Online.

     

    The scenario can be summarized:

    1. an end-user installs a 3rd party component or add-in along with its help content, and
    2. the end-user's default for Help and F1 lookups is set to Online
    3. What happens when a user presses F1 when a partners control or add-in is in focus?

    Since the entire Online Help experience is managed directly from MSDN Online, that experience inherently has no knowledge of a user's local machine state. The end-user would effectively never see or know that there was Help content available for the 3rd party component or add-in.

     

    We clearly wish to enable partner content to be accessible in all contexts, and you all have helped us think through ways we could enable this.

     

    As of this RC build, we will do a very quick query on local *vendor* content to determine whether there is a topic that matches the F1 keyword query. If there is a hit, then we will take the user directly to the local vendor content rather than looking on MSDN Online and giving a 404. 

     

    We manage content from all vendors (including Microsoft) separately. This will potentially enable a number of useful Online content scenarios in the future, but the fortunate benefit *now* is that we are able to distinguish between Microsoft and non-Microsoft content. And therefore, enable a different behavior for partner content.

     

    I plan to post a discussion on how we’re beginning to look at partner content discoverability scenarios moving forward from Visual Studio 2010. Look for this in the next few weeks.

     

    Thanks again to all our partners and HAT vendors who have helped us to think this through!

     

    Download the RC and let us know what you think!

     

  • The Help Guy

    Some updates

    • 0 Comments

    I added a few more items to the Known Issues page.

    Also, a new page added: Calling Help Viewer 1.0 from VS add-in code. If you're developing add-ins for Visual Studio 2010 (or earlier actually), you may find this information handy. It describes the references necessary and basic steps for launching F1 help, whether with Help 2.x or Help Viewer 1.0.

Page 1 of 1 (4 items)