Populating the User Guide with dynamic and static content
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:
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:
will be extended with a few additional items:
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:
The following dialog appears:
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:
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):
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:
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:
The new topic page is created and opened. Let’s edit it and add some static description:
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:
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”/]
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:
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