Adding, Editing, and Managing Help Items

Applies to: VisualSP On-Premises
Print Friendly, PDF & Email

Overview

Any site collection in which the VisualSP Help Provider Feature has been activated may be a place where Help Items can be added, edited, and managed.

 The Manage VisualSP Help Items page

A Help Content Manager will find a complete suite of tools for managing help items on the Manage VisualSP Help Items page

Take a video tour of the Manage Help Items Tab:
Manage Help Items Ribbon Tour

To access the Manage VisualSP Help Items page, go to Site Actions > Site Settings and click Manage VisualSP Help Items.

There is even a Help tab on the Manage VisualSP Help Items page! This tab includes videos and resources to aid your Help Content Managers as they maintain help content in all your site collections. Your SharePoint administrators will find resources here to aid them as they manage the VisualSP system.

Adding Help Items

Help Items can be managed in the VisualSP Help Items list in the VisualSP Farm Hub, a VisualSP Web Application Hub, or at any site collection in which the VisualSP Provider Feature has been activated. The process for adding and editing Help Items is the same, regardless of where it is stored or where it is provided to. However, it is very important to make sure that you are managing content in the correct place, based on where you want the Help Item to be displayed.

  • If you want the Help Item to be displayed in any or all site collections across the entire farm, make sure you are in the VisualSP Farm Hub.
  • If you want the Help Item to be displayed in any or all site collections within a particular Web Application, make sure you are in the correct VisualSP Web Application Hub.
  • If you want the Help Item to be displayed in only one particular site collection, make sure you are in the correct site collection.

Note: The functionality to control Help content across a farm is not available in the VisualSP Express system. In the Express system, all Help items must be maintained at the site collection level.

Reference video tutorial to configure Help items:
Configure Help

To add new Help Items, navigate to the correct site collection then go to Site Actions à Site Settings. Click on Manage VisualSP Help Items.

In the Manage Help Items ribbon, click Add Help Item.

You will be taken to a page displaying a long form where you will add the details about the new Help Item. We will look at each section of this form and explain how each field is used by the VisualSP Help System.

Enter a Title and Description for the Help Item

Note: A few of the items on the Manage VisualSP Help Item form will be discussed out of the order they are listed on the form. At this point, we will skip Locale ID and Group; those fields will be explained later in this document.

The Title and Description can be anything you want it to be. As a best practice, we recommend that the Title be a short ‘active voice’ phrase for what the Help Content will instruct the user to do, instead of a ‘passive voice’ explanation (for example, use “Add a Column” instead of “Adding a column”).  For the description, a short one sentence summary is usually sufficient. We also recommend indicating to the user the type of media the Help Item will link to.

The following image shows where the Title and Description will appear in the Help Item Ribbon, the Inline Help Menu, and the Help Item Viewer dialog.

Enter the Help Content Properties for the Help Item

Help Content, or Help Assets, is the instructional content and resources that users need. The VisualSP Help System supports a variety of different media types such as: videos, images, documents, web pages, and Adobe Flash. You can even use custom EMBED or OBJECT tags to display content from sites like YouTube, Vimeo, and many other sites. Help content can live in any location that your users can access whether within your local internal network or anywhere on the Internet. If your employees can access it, it can be used as help content.

The three bottom fields in the Help Item Details section tell VisualSP where it can find the Help Content for this Help Item and how it should be rendered to the user.

 

The Link field is an http or https link to the Help Asset.

Check the Show In New Window box if you want the Help Content to be displayed in an external browser window instead of in the pop-over dialog box.

Finally, select the Media Type and the Viewer to be used to render this Help Asset. Although Document, Image, Web Page, and Custom EMBED or OBJECT tag have only one option, there are multiple options for video, Silverlight, and Flash asset types. Most video content renders well with the Default Video Player, but depending on the encoding of the video, or your particular environment and standards, one of the other players may be more appropriate.

Select an Icon for the Help Item

VisualSP always uses an icon as the action target for a Help Item. You will find more than 125 icons to choose from for Existing Icon URL. You will see a preview of the selected icon so you will know exactly what it will look like.

If you select  <Custom>, the Custom Icon URL field will appear. Here you can enter the full URL path to any icon you may have created yourself. Make sure that it is either 16×16 pixels or 32×32 pixels and store it in a SharePoint library to which all users have read access. Then copy and paste the URL here. VisualSP will still show a preview of the icon. This is confirmation that the URL was entered correctly.

After selecting the icon, select the appropriate Icon Size option.

The image below shows you where the icon is displayed to the end user.

Note: For Inline Help Items, large, 32×32 icons usually render better than Small icons. In the Help Tab, users usually find a mixture of large and small icons easier to use than if they are all the same size.

Enter a Sequence Number to Change the Display Order of the Help Item

Sequence is not required, but it is very helpful when you want your Help Items to display in a specific order.

Understand the Default Order

In the Help Tab Ribbon, Help Items are displayed in Ribbon Groups. Within each Ribbon Group, the Help Items are ordered from left to right, first by icon size, then in alphabetical order. The alphabetical sort can be overridden by entering a Sequence value.

In the Inline Help Menu, Help Items are displayed in alphabetical order from top to bottom. The alphabetical sort can be overridden by entering a Sequence value.

The sequence field is blank by default. Help Items with sequence numbers are always displayed before Help Items with blank sequence numbers. Help Items with a blank sequence, as well as Help Items that share the same sequence number, will appear alphabetically.

Sequence numbers can be any number between 1 and 9999. As a best practice, we suggest that you assign sequence numbers in a manner that will allow for flexibility in customization later. For example, if you begin by using sequence numbers that end in zero, such as 10, 20, 30, etc., and you later decide that another Help Icon should appear between 10 and 20, you can assign it a sequence of 15.

You can quickly see the sequence numbers of all items in a particular group by using the By Group view of the Manage VisualSP Help Items list. This can be very helpful when you need to set a custom sort order or when you are trying to figure out why a certain sort order isn’t working the way you expect.

Select a Group for the Help Item

At the beginning of this section on Adding Help Items, we skipped the Group setting near the top of the form.

A ribbon group is a group of related help items. They can be easily identified by the vertical dividers between them and the ribbon group names that appear below the icons in that group.

Click on the Existing Group drop-down menu to select an existing Ribbon Group. The list will be populated with the names of all the Groups that are currently in use. If you want this Help Item to appear in one of these Groups, simply select the appropriate group from the list.

If you want it to appear in a Ribbon Group that isn’t in the list, select the <new> option. In the New Group field, type the name you want to give the new group. When you are finished creating the Help Item and Save it, the new Group will be created and this Help Item will be added to the group.

Note: By default, groups are displayed in alphabetical order from left to right on the ribbon. See the Help article Managing Ribbon Groups for information regarding how to rename, delete and change the order of Ribbon Groups.

Select a Help Tab Scope for the Help Item

VisualSP provides two ways of setting the context for a particular help item: Help Tab Scopes and Inline Help Targets (which will be discussed in the next section).

A Help Tab Scope is a specific type of content, list, library, or system page on which the help items should appear in the Help Tab Ribbon. A user accesses the help items for that particular context by exposing the Help ribbon.

To set the Help Tab Scope for a Help Item, scroll down to the Help Tab Scope section on the Manage VisualSP Help Item page. The tabs at the top for Lists, Libraries, Pages, Settings, and Other, allow you to quickly select the scope, or scopes, you need. In the example below, the Settings tab has been selected and the Site Settings Page has been checked. This selection will cause the help item to appear in the Help ribbon on the Site Settings page. Multiple scopes can be selected, even across tabs.

When a user visits the Site Settings page on any site that displays Help Items from this Help Items list, the Help item will appear in the Help Tab ribbon along with all the other Help Items that have the Site Settings scope.

The Custom Scopes section allows you to enter your own scopes. Custom scopes are used by the VisualSP Web Part and will be discussed in a later section of this document.

Setting a URL Defined Scope in the Help Tab Scopes section will cause the help item to appear on the Help Ribbon when a user visits a page that matches the pattern you enter here. There are several things to keep in mind when using URL Defined Scopes:

  • If NO Help Tab Scopes are checked, the help item will only appear on pages that match the URL Defined Scope. If ANY Help Tab Scopes are checked, the help item will appear in the pages for the checked scopes and also appear on pages that match the URL Defined Scope.
  • You can enter multiple URL Defined Scopes by separating them with a vertical bar ‘|’ character. Example:
    /salesteam/SitePages/Home\.aspx|/hr/SitePages/Home\.aspx
  • If a particular page doesn’t display a ribbon toolbar at all, then it won’t display a VisualSP Help tab, even if defined here.
  • If multiple pages match the pattern you enter here, the Help Item will appear on every page that matches the pattern.

Check out in this video about how to modify Help Tab Scopes:
Using Built-in Help Scopes

Select an Inline Help Target for the Help Item

VisualSP provides two ways of setting the context for a particular help item: Help Tab Scopes (which was discussed in the previous section) and Inline Help Targets.

An Inline Help Target is a section of a page in SharePoint where the help item will appear in the inline help menu. A help icon  will appear near the selected target. A user accesses the help items for that particular context by clicking on the help icon; a drop down menu will appear showing the help items for that particular context.

To set the Inline Help Target for a Help Item, scroll down to the Inline Help Target section on the Manage VisualSP Help Item page. The tabs at the top for Lists, Libraries, Pages, List Settings, Library Settings, Site Settings, and Other, allow you to quickly select the inline help target you need. In the example below, the Site Settings tab has been selected and the Site Look and Feel inline target has been checked. This option will cause the inline help icon to appear near the Site Look and Feel link on the Site Settings page.

Users who visit the Site Setting page will see the help icon on the Look and Feel group. Clicking on the icon will expose the drop-down menu where the help items for this Inline Target can be accessed.

You may want to display a VisualSP Inline Help Item in a place that has not been defined as an Inline Help Target. The Custom Inline Help Target field allows you to define any particular place on a page that you want the help item to appear. If you are not a web designer or developer with a good understanding of CSS, the HTML Document Object Model, and the JQuery JavaScript library, you will probably need a consultant to help you define the custom targets you need.

Setting a URL Defined Scope in the Inline Help Target section will cause the help item to only appear in the matching Inline Targets that appear on the pages that match the pattern you enter here. This can be very useful if a defined target exists on every SharePoint page, but you don’t want the Inline Help icon to appear in that spot on every page.

For a complete list of all out-of-the-box Inline Help Targets, with screenshots for each one, see our VisualSP On-prem Inline Help Targets Reference

Select Auto Load Settings

VisualSP allow you to have a help item auto load for users without the user having to click to launch the help item.

The Auto Show on Load value indicates on which page load this particular help item will automatically load for the user. If it is set to 0 (zero), the default, the help item will not auto load. If it is set to 1 (one), the help item will auto load on the first page visit; if it is set to 2 (two), the help item will auto load on the second visit; and so on.

A page load is counted any time the link to the help item is visible to a particular user either via the Help Tab Ribbon or via an Inline Help Target. Because of the number of options that are available, this may be easier to understand by considering a simple scenario and gradually making that scenario more complex. Consider this:

  • If this help item is set to appear on all wiki pages, and the Auto Load value is set to 10, then each time the user views a wiki page, the load counter will increment. The 10th time the user sees a wiki page, the help item will automatically load.
  • If this same help item is set to appear on both wiki pages and publishing pages, then the load counter will increment each time the user views either a wiki page or a publishing page. When the counter reaches 10, the help item will automatically load.
  • If this same help item has its Permissions filter set to Edit Items, then the load counter will only increment when the user visits a wiki page or publishing page on which the user has permission to enable edit mode. When the counter reaches 10, the help item will automatically load.

Each help item has its own unique load counter that is unaffected by other help items. There is no way to globally reset the load counter for a help item. If you need to do this, you will need to create a duplicate help item; the new duplicate help item will have its own load counter.

Each help item’s counter is stored in a cookie in the user’s browser. A user may see a single help item auto-load multiple times if the user clears cookies, uses a different browser, uses a different browser profile, or uses browsers on different computers.

When the Auto Show After date is set, load counts will not begin accumulating until the provided date.

Select User Permissions to Target the Help Item

You can customize which help items appear to which users, based on the user’s permissions. For example, you may only want to show how to create columns on a list, to those users who have permission to create columns.

Near the bottom of the Help Item form, click Permissions to expose the Permissions section.

The available permissions are grouped on the Help Item form, just as they are on the pages for creating or editing SharePoint Permission Levels. Below is a screenshot of the SharePoint Add a Permission Level page. It can be a valuable resource in determining what these permissions allow users to do.

It’s important to note that selecting permissions here does not set any particular permissions on the Help Item. Selecting Permissions here only causes the Help Item to display for users who have the selected permission, or permissions, in a particular scope. For example, you might only want users to see the Add users to a site help item if the user has permission to Manage Permissions. In sites where the user has Manage Permissions capability, the Add users to a site Help Item will appear in the places (Help Tab Scopes and Inline Targets) you have selected; in sites where the user does not have Manage Permissions capability, the Add Users to a site Help Item will not be displayed to the user.

You can quickly see what permissions are required for a user to see a particular Help Item on the Manage VisualSP Help Items page. If a group of permissions is selected (such as: all List Permissions, all Site Permissions, or all Personal Permissions), only the permission group will be listed. If all permissions are selected, as they are by default, the Permissions column will appear blank. At least one permission must be selected in order to save a permission item.

Note: If all permissions are selected for a Help Item, as they are by default, then all users will be able to see the Help Item in all selected Help Tab Scopes and Inline Targets. If individual permissions are selected, then a user must have all the selected permissions to see the Help Item.

Watch video on Help Item Permission Settings
Using Permissions to Control Help Ribbon Content

Save the Help Item

When you are finished entering all the information for the Help Item, click the Save button at either the top or bottom of the Manage VisualSP Help Item page.

You will be taken to the Manage VisualSP Help Items page where you should see the new help item you just created.

In the next two sections, we’ll walk you step-by-step through the process of creating two new Help Items.

Step-by-Step: Add a Custom Image as a Help Item

Reference video tutorial:
Adding a Custom Image

Any custom image, screenshot, or tip sheet can be added as a Help item in the system. The image can be of any type (.jpg, .gif, .png, etc.). It can be targeted contextually to show up within certain scopes. You can also apply security trimming to only show the image to appropriate users.

Start by uploading the image to the Site Assets library in the VisualSP Farm Hub site collection.

Note: The image can be added at any other location as well. However, it is recommended as a best practice to keep all Help content in the same location for easy management.

Once the image is in a repository available to SharePoint, you will now need to create a new Help item pointing to that image.

Navigate to VisualSP Farm Hub -> Site Actions -> Site Settings -> Manage VisualSP Help Items.

Click Add Help Item button in the ribbon.

At the Manage VisualSP Help Item page, fill in the Help item info as needed. Be sure to pick the Image selection for Viewer / Media Type as shown in image below.

Move down the page to pick the appropriate icon (or supply your own) and then the scope(s) at which you would like to see this custom image appear.

Below the Scope section, you will also find the Permissions section. Use the settings in that section as needed to specify what permission rights are needed by the user to be able to see this Help item.

Click OK at the bottom of the page to save this new Help item which points to your custom image.

The Help item should now be visible at the appropriate location.

Step-by-Step:  Add a Custom Video as a Help Item

Reference video tutorials:
Adding a custom video
Adding a YouTube video

Add a custom video as a Help item to any context in the ribbon. The video can be of any type (flash, .mp4, .avi, etc.). It can be targeted contextually to show up with certain scopes. You can also apply security trimming to only show the image to appropriate users.

Start by uploading the video to the Site Assets library in the VisualSP Farm Hub site collection.

Note: The video can be added at any other location as well. However, it is recommended as a best practice to keep all Help content in the same location for easy management.

Once the video is in a repository available to SharePoint, you will now need to create a new Help item pointing to that video.

Navigate to VisualSP Farm Hub -> Site Actions -> Site Settings -> Manage VisualSP Help Items.

Click Add Help Item button in the ribbon.

At the Manage VisualSP Help Item page, fill in the Help item info as needed. Be sure to pick the appropriate video selection for Viewer / Media Type as shown in image below.

Move down the page to pick the appropriate icon (or supply your own) and then the scope(s) at which you would like to see this custom video appear.

Below the Scope section, you will also find the Permissions section. Use the settings in that section as needed to specify what permissions users must have to see this Help item.

Click OK at the bottom of the page to save this new Help item which points to your custom video.

The Help item will now be visible at the appropriate location.

Editing Help Items on the Manage VisualSP Help Items Page

Before you can edit a Help Item, you must first locate the Help Item you want to edit. VisualSP makes this very easy to do, even if your environment has hundreds or thousands of Help Items.

To access the Manage VisualSP Help Items page, go to Site Actions -> Site Settings and click Manage VisualSP Help Items.

Filtering, Sorting, and Grouping Help Items

There are several ways to locate existing Help Items based on information you already know about the Help Item, or Items, you are looking for.

Use the built-in VisualSP views to group help items. You will see the All Items view when you initially visit the Manage VisualSP Help Items page. The other four view options group items by the properties in that particular column. The By Group view will show you which help items will appear in each ribbon group the user sees in their help tab. Clicking By Scope will show you which help items appear based on the context of the page, site, or resources being accessed by the user. Selecting By Inline Help Target will show you which help items appear in each inline target. By Viewer will group all help items by the type of viewer that displays the help content.

You can also use the native sorting and filtering capability of SharePoint lists. Click on any of the column headings to sort by that column in ascending order. Click it a second time to sort by that column in descending order. Click the down arrow that appears when you move your mouse over a column heading to select and apply filters based on data in that column.

 

 

Explore different ways to locate Help items.
Finding Specific Items

To edit an item from the Manage VisualSP Help Items page, simply click on its Title. You will be taken to a page where you can change any of its properties.

Alternatively, you can also check the box beside the Help Item, and click the Edit Item icon in the Manage Help Items ribbon.

The form you will use to edit the Help Item is identical to the form you use to add a new one. When you are finished making the necessary changes, just click the Save button at the top or bottom of the page.

Edit Help Items with the In-Place Edit Mode

Managing help items in-place allows the Help Content Manager to make necessary adjustments without having to navigate back and forth between a page where the item will appear and the Manage VisualSP Help Items page. Users who have permission to edit Visual SP Help Items will see an Enable Edit Mode button on their Help Tab ribbon. When the user clicks this button, he or she can then edit existing help items by clicking on the help item they want to edit in either the Help tab ribbon, Inline Help, or the VisualSP Web Part.

Once you have enabled Edit mode you will remain in Edit Mode wherever you may go throughout the entire SharePoint Farm. A red bar will appear at the top of every page you visit as a reminder that you are in Edit Mode.

When you click on a help item while in Edit Mode, a dialog box will appear where you can change any of the settings for that particular help item. When you are finished making changes, click the Save button to save your changes. After the dialog box closes, you will have to refresh the page in your browser to see your changes.

While in Edit Mode, Inline Help Items will also open in the Edit VisualSP Help Item dialog.

You can even do in-place editing of help items displayed via the VisualSP Web Part.

Depending on your particular permissions, you may not be able to edit all help items. If you do not have permission to edit a particular help item, it will display the help content just as it would normally.

You can also create new help items while in edit mode. Just click on the Add Help Item links for the scope at which you want to create the new help item. Depending on your permission level in the VisualSP Help System, you may not see all three options. Although Edit Mode is in effect throughout the farm, when adding a local scoped help item or a web application scoped help item, it will be added the site collection or web application you are currently in.  To add a help item to a different site collection or web application, you will have to go to a site in that scope.

When you are finished making in-place changes to VisualSP Help Items, exit Edit Mode by clicking the Disable Edit Mode icon.

Make a Copy of a Help Item (Save As New)

When you are editing a VisualSP Help Item, you will see a button for Save As New. Clicking this button will add a new Help Item that is identical to the one you are currently editing. If you have made changes to the form, but have not yet clicked the Save button to save them, the new Help Item will have the changes you made and the original Help Item will be unchanged. This can save a lot of time if you are adding a new Help Item that will have most of the same properties as an existing Help Item.

Delete a Help Item

When you are editing a VisualSP Help Item, you will notice there is a Delete button. Be very careful when deleting Help Items as they DO NOT go into the Recycle Bin and cannot be restored.

If you think you may want to use this Help Item in the future, a better option is usually to:

  1. Edit the Help Item.
  2. Uncheck all Help Tab Scopes.
  3. Uncheck all Inline Help Targets.
  4. Type None in the Custom Scopes field.
  5. Save the Help Item.

This will keep the Help Item from displaying for end users, while still keeping it available for you to make changes to later. It isn’t necessary to use the Custom Scope of “None”. You can use any name you want. Some Help Content Managers Use a variety of custom scopes as an extra way to filter and group.

 

Updated on July 19, 2019

Related Articles