Document! X & HelpStudio Bundle 2022.1
Creating and Editing Content / Widgets / Widget Content From a File
In This Topic
    Widget Content From a File
    In This Topic

    Several of the standard Widget types allow you to use the content from an external file (e.g. a source code file) as the source in order to avoid duplicating content that already exists in source files. The Widget types that support using an external file as the source are:

    Using Widget Content from an External Source File

    1. Open a Topic or Content File for edit.
    2. On the Content Authoring tab, click the Widget dropdown button.
    3. From the list of Widgets, choose a Widget Type from the list above.
    4. The Widget will be inserted into the active editor ready for you to fill in the Widget Properties.
    5. Type the name of the external source file you want to use as the content for this Widget in the File Name field. The path and filename can either be an absolute (fully qualified) path and filename (e.g. c:\myexamples\example1.cs) or a path relative to the project directory (e.g. examples\example1.cs).
    6. If your example file contains more than one named section, marked up using the section marking scheme outlined below, type the section name in the Section Name field.
    7. When you preview or build the output the Widget now derives its content from the external source file.

    Marking Up One or More Named Regions Within a Source File

    If you are using content from source files, you may wish to only use a portion of the file; for example if the source file is part of a complete sample project and contains code that is outside the scope of a specific example.

    To use just a portion of a source file, you can mark up regions of the file using specifically formatted marker text to identify the start and end of a region, as well as the region name. By default the start marker should be of the format '#region {Name}#' or '#Region "{Name}"' where {Name} is the name of the region. The end region marker should be '#endregion' or '#End Region'. The start and end region markers can appear anywhere on a line, typically a comment line, so they can be used in any source file regardless of the language.

    Here are a few examples of region markup: 

    /// Retrieves any new RssItem objects for this feed.
    public void UpdateFeed()
    {
        if (!string.IsNullOrEmpty(Url))
        {
            XElement RssXml = GetRssXml(Url);
    
            foreach (XElement Item in RssXml.Descendants("item"))
            {
    // #region CreateNewRssItem
                RssItem NewRssItem = new RssItem(Item.Element("title").Value,
                                                  Item.Element("description").Value,
                                                  Item.Element("link").Value,
                                                  DateTime.Parse(Item.Element("pubDate").Value),
                                                  RssItemState.New);
    // #endregion
                RssItems.Add(NewRssItem);
            }
    
            _ModifiedOn = DateTime.Parse(RssXml.Element("channel").Element("lastBuildDate").Value);
        }
    } 
    ''' Retrieves any new RssItem objects for this feed.
    Public Sub UpdateFeed()     
        If (Not String.IsNullOrEmpty(Url)) Then
            Dim RssXml As XElement = GetRssXml(Url)
            For Each Item As XElement In RssXml.Descendants("item")
    ' #Region "CreateNewRssItem"
                Dim NewRssItem As New RssItem(Item.Element("title").Value,
                                      Item.Element("description").Value,
                                      Item.Element("link").Value,
                                      DateTime.Parse(Item.Element("pubDate").Value),
                                      RssItemState.New)
    ' #End Region
                RssItems.Add(NewRssItem)
            Next Item
            _ModifiedOn = DateTime.Parse(RssXml.Element("channel").Element("lastBuildDate").Value)
        End If
    End Sub
    <html>
        <body>
    <!-- #Region "Section1" -->
            <h2>Chapter 1</h2>
            <p>An introduction.</p>
    <!-- #End Region -->
    <!-- #Region "Section2" -->         
            <h2>Chapter 2</h2>
            <p>More information</p>
    <!-- #End Region -->
        </body>
    </html>
    <note>
    <!-- #region NoteToAndFrom -->
        <to>John</to>
        <from>Bill</from>
    <!-- #endregion -->
        <heading>Reminder</heading>
    <!-- #region NoteBody -->
        <body>Don't forget the appointment</body>
    <!-- #endregion -->
    </note>
    The default format of start and end region markers can be customized in the Document! X and HelpStudio Bundle Options. For example, if you have an existing body of code with some other scheme in use to markup named regions of code.
    See Also