Home > Code Samples, Components, Essentials > Populating the User Guide with dynamic and static content

Populating the User Guide with dynamic and static content

June 17th, 2011

IDE Tools User Guide supports static and dynamic content. The static text is stored inside the “*.htm” files, and the pictures are stored in the independent files in the appropriate format (gif, jpeg, png, etc). The static content can be manually edited right inside of the User Guide. There are also two DXCore controls useful for population dynamic content. These controls are the Tutorial Page Provider and Tutorial Content Provider. In this article, we’ll add some static content to the built-in CodeRush Documentation shown inside User Guide, and provide some dynamic content using the Tutorial Content Provider component.

The User Guide has an ability to edit its documentation content, which is disabled, by default. To enable it, go to the User Guide options page inside the Options Dialog and click the “Show page editing items in tutorial context menu” check box:

IDE Tools User Guide options page

If you had the User Guide opened when changing this option, you might have to reopen it to apply changes. After that, the usual context menu of the User Guide:

IDE Tools User Guide context menu simple

will be extended with a few additional items:

DXCore User Guide context menu advanced

Here they are:

Item Name Description
Edit Page Open an HTML file for editing which represents the selected page in the tree list.
Add Topic Adds a new topic (an HTML page) to the selected category in the tree list.
Add Root Topic Adds a new root topic (an HTML page) into the tree list.
Delete Topic Completely removes the selected topic.
Edit Topic Product Allows you to select another IDE Tools Product where the selected topic will be located.
Copy topic path (for technical support) Copies the selected topic path into Clipboard.
Copy topic link Copies the selected topic link wrapped with an ‘a’ HTML tag into Clipboard.
Copy page link Copies the selected page link wrapped with an ‘a’ HTML tag into Clipboard.
Move topic up Changes the order of the topic – moves it one position up.
Move topic down Changes the order of the topic – moves it one position down.

Every IDE Tools product has its own root topics. DXCore has the Welcome, Tool Windows, Reference and Extend topics; other products such as CodeRush, Refactor! Pro and free alternatives have topics of the same name, e.g. “CodeRush“, “Refactor! Pro“, etc.

Imagine we are going to document the CR_TemplateGoto plug-in from the CodeRush Shared Source solution inside the User Guide. First of all, let’s add a new root topic by clicking “Add Root Topic” context menu item:

User Guide Add Root Topic context menu item

The following dialog appears:

User Guide New Root Topic dialog

In the Product Module list choose the product to which your topic relates, e.g. CodeRush. Topic name can be something like “Shared Source Plug-ins“. The HTML file name text box will be automatically filled for you; let’s leave it as is:

User Guide New Root Topic dialog edited

Now we have a new root topic called “Shared Source Plug-ins“. This is going to be a common “folder” for all plug-ins we will document in the future, so we can point it on this page by editing it. The corresponding HTM file will be opened automatically inside Visual Studio for editing (click the image to enlarge):

IDE Tools Topic Page html file preview

Add some description inside the body tag (e.g. “CodeRush Pro Shared Source solution plug-ins information.” and save it. The content is changed immediately:

DXCore New Root Topic in the User Guide preview

Now let’s add a new page describing our plug-in. Right-click on the newly created topic and choose “Add Topic” and fill the “Topic name” text box:

CodeRush New User Guide Topic dialog

The new topic page is created and opened. Let’s edit it and add some static description:

User Guide Plug-in topic html code

That’s it for the static content – it is stored on the disk inside your installation folder and will appear every time you open the User Guide. Now it’s time to add some dynamic content. As an example we will use the CR_TemplateGoto plug-in that has the Member Sections options page, which we will document in the User Guide. The options page contains the text that appears before and after each of the specified sections:

CodeRush Member Sections (CR_TemplateGoto) options page

To show the options of the plug-in, follow the following steps:

  • open the CR_TemplateGoto plug-in project;
  • open the designer for the Standard plug-in file;
  • drop the TutorialContentPeovider component into it;
  • set the ContentName property of the control to the “TemplateGotoOptions“, for example;
  • subscribe to the GetContent event.

In the GetContent event, we should pass a content (HTML formatted) through the Result property of the TutorialContentEventArgs like this:

private void tutorialContentProvider1_GetContent(object aSender, TutorialContentEventArgs ea)
{
  string result = String.Empty;

  result += Html.h1("Headers") + Html.br();
  result += DumpOptions(_Headers);

  result += Html.h1("Footers") + Html.br();
  result += DumpOptions(_Footers);

  ea.Result = result;
}

private string DumpOptions(Dictionary<string, Dictionary<Section, string>> dictionary)
{
  string result = String.Empty;
  foreach (KeyValuePair<string, Dictionary<Section, string>> languageSectionsPair in dictionary)
  {
    string languageName = languageSectionsPair.Key;
    result += Html.h2(languageName) + Html.br();
    foreach (KeyValuePair<Section, string> sectionValuePair in languageSectionsPair.Value)
    {
      string sectionName = sectionValuePair.Key.ToString();
      string sectionValue = sectionValuePair.Value;
      result += Html.p(Html.Bold(sectionName) + " - " + Html.BlueText(sectionValue) + Html.br());
    }
  }
  return result;
}

And we have to edit the page topic, describing the plug-in to use the content coming from our TutoralContentProvider control. Inside the tag of the topic page, place the special [content] tag, specifying the name of the Tutoral Content control:

[content name=”TemplateGotoOptions”/]

CodeRush Plug-in topic html code edited

Parameters for the TutoralContentProvider can be passed as attributes to the tag, if necessary:

[content name=”TemplateGotoOptions” param1=”value1″ param2=”value2″/]

After the plug-in is compiled, we can see the dynamic content inside the User Guide:

IDE Tools User Guide dynamic content result

If you have any questions with the sample or populating the User Guide content, post them inside the Comments sections of this post.

—–
Products: DXCore, CodeRush, Refactor!
Versions: 11.1 and up
VS IDEs: any
Updated: Jun/18/2011
ID: D091

Similar Posts: