ClickHelp User Manual

Release Notes: December 2019 — Oasis

ClickHelp Oasis Update

This ClickHelp Oasis Update introduces significant improvements to such product functions like topic editing, branding, accessibility, Global Find and Replace, reporting, and security. We have also improved the performance and usability of the product to ensure better user experience for documentation authors. Check the list below to learn more about the changes we have made in ClickHelp Oasis.


    New Features

      Breaking Changes

      • Breadcrumbs and horizontal See Also blocks are now rendered as tags rather than unordered lists. This will help style those elements easier in the printed versions of your documentation. If you have custom styles for See Also blocks, please consider updating the styles. For example:
        CSS
        .CHSeeAlso li,
        .CHBreadcrumb li
        {
        color: red;
        }


        should now be replaced with:
        CSS
        .CHSeeAlso_item,
        .CHBreadcrumb_item
        {
        color: red;
        }
      • Custom CSS classes applied to breadcrumbs, See Also blocks and top/next/previous links are now combined with default classes. This way you can have both common styles shared between all navigation elements and specific styles customizing a single element. Previously, if a custom CSS class was specified, default classes were not applied.
      • The mobileView/desktopView class indicating the current state of UI is now added to the tag of customer-facing pages (was added to the tag previously). Consider reviewing your custom branding styles to update them accordingly.

      Global Find and Replace

      • It is now possible to find and replace:
        • Text (including source code)
        • Topic links
        • File links
      • The following entities can be searched in a single place across your entire portal:
        • Topics (title and source)
        • Styles
        • Scripts
        • ToDo items
        • Index keywords
        • TOC nodes (captions)
        • Unresolved/Resolved/Deleted review comments
      • It is possible to apply search filters (filter by entity type and by specific projects/publications).
      • While searching for text, it is also possible to use extra filters: match case, match the whole word, use regular expressions.
      • Search results can be exported and previewed with match highlighting.
      • It is possible to replace all matches automatically as well as to choose the specific matches you need to replace manually.
      • Replace logs can be exported as well to keep track of the changes.
      • When a document is updated via global replace, a version is created automatically for it in Version History, so it can be rolled back and there is an audit trail record on who made the replacement and when.
      • If a document is locked by another person and the current user has the permission to unlock documents locked by other users, the document will be unlocked automatically if needed.
      • Automatic link validation and update implemented: now, when a topic or file URL changes, the system looks for all links and suggests updating them automatically if some links are found.
      • The Global Find and Replace feature can also be useful for a great number of use cases:
        • Post-import cleanup of your content and styles (e.g. to remove third-party master page markup and scripts or to replace third-party navigation elements (like Next/Previous links) with their ClickHelp counterparts).
        • Find and replace all occurrences of a specific word/phrase/source code snippet and replace it with a variable, snippet or conditional block (convert to snippet).
        • Find and replace content styles (especially useful when importing from Word with automatic CSS class generation).
        • Find and replace all occurrences of an external URL (e.g. pointing to a YouTube video or to a page on your website).Find and replace colors and font names across all your style files (e.g. as a part of your company re-branding).
        • Find (and replace) variables and output tags - e.g. when you need to rename them.
        • Find all references to a JavaScript function or variable.
        • And much more - just turn on your imagination!

      Branding

      • Added dozens of new visual settings that allow you to configure the portal UI easily (no CSS knowledge required): selection and hover colors, header visibility and size, background images, text and link colors, etc. Also, you can now limit the maximum width of your content easily to give your topics an easy-to-read look.
      • New portal UI templates implemented: now, you can give your documentation a modern look with just one click. The templates cover multiple use cases (multi-project portal, public KB, API documentation, etc.) and vary by their layout and interface element locations based on our research results of user manual UX. Thanks to the new templates, you no longer have to include automatic navigation elements in your topic master pages since they're already included as parts of the templates. You can now have various combinations of sticky headers, sidebars, and navigation panels.
      • You can now add your own custom footer under all portal pages. Any custom markup allowed, so you can make it a copy of your website footer with all navigation links and elements you might need.
      • It is now possible to configure the main menu for readers visually. Menu items can have special CSS classes, navigate to topics, publications or any arbitrary URLs and have subitems (the setting affects Web Help as well).
      • It is now possible to specify icons and sort order for automatically generated publication lists on the Home page, in the topic viewer (if allowed by the chosen layout template) and in the publication filter on the Search page. The new settings are now available in the Basic Settings section of each project and publication. If two publications have the same ordinal number, they are sorted alphabetically (as it was previously).
      • Publication link template for the Home page now includes a placeholder for publication ID, which allows assigning unique styles to specific publication links.
      • Top-level CSS classes are now applied to the element of customer-facing pages: Home, Articles, Search and Login (the classes are Home_page, Articles_page, Search_page and Login_page). You can use the classes to introduce page-specific UI customizations with the Branding.css style.
      • Added top-level CSS classes indicating the current portal UI properties source to the element of the Home, Articles, Search and user profile pages. When using portal settings, the class is "portalUiSettings_portal", when using settings of a specific publication, the class is "portalUiSettings_pub_my-publication". These classes allow you to specify default and project-specific portal UI styles for readers.
      • A special CSS class is now applied to a page body when opening a broken article link, allowing custom branding of the master page in such cases.
      • A special CSS class (either "desktopView" or "mobileView") is now applied to the element of your topics allowing you to control mobile/desktop layouts for them.
      • With a new Reader Interface setting, you can now control whether the "Updated on" information will be rendered for topics.
      • Level-specific CSS classes are now assigned to different TOC levels, so you can have different styles for each TOC level nodes and their children if necessary.
      • Added a global JavaScript function available in the portal UI on all pages: getCurrentUserInfo (use window.parent to access it from project scripts). The function returns an object with the following fields which can be useful for branding scripts (e.g. to redirect or show different content to users based on their names or roles):
        • isInternalUser - true if the currently logged in user is an Author or a Reviewer. False if it's a Power Reader or an anonymous user.
        • curUserName - the current user login (null if the user is anonymous).
        • curUserRoles - an array of the current user's roles.
      • It is now possible to exclude specific publications from automatically generated publication lists on the Home page, in the topic viewer (if allowed by layout template) and in the publication filter on the Search page. The new setting is now available in the Basic Settings section of each project and publication.
      • It is now possible to add the "Time to read" metric to reader UI (included in layout templates).
      • It is now possible to customize separator styles for breadcrumbs and horizontal See Also blocks thanks to new CSS classes applied to them automatically: CHBreadcrumb_separator and CHSeeAlso_separator.
      • It is now possible to customize the last breadcrumb item referring to the current topic thanks to a new CSS class applied to it automatically: CHBreadcrumb_itemSelf.

      Accessibility

      • WCAG 2.0 Level AA compliance implemented for Reader UI and improved for Author UI.
      • Section 508 compliance implemented for Reader UI and improved for Author UI.

      Topic Editor

      • A new context menu item command "Find All References" was added. The feature allows finding all links to the selected entity quickly and can be used with:
        • Snippets and links
        • Images
        • Videos and Flash movies
        • Variables
      • It is now possible to specify custom separator HTML markup for breadcrumbs and horizontal See Also blocks.
      • It is now possible to add a Home link (with custom URL and text, if required) and a link to the current publication to breadcrumbs. The new elements style can be customized via their CSS classes: CHBreadcrumb_itemHome and CHBreadcrumb_itemPub.
      • It is now possible to specify custom caption HTML markup for Top/Next/Previous links, breadcrumbs, mini-TOC and See Also blocks. The caption will not be rendered if the element is empty (e.g. if there is no next topic or there are no headings for mini-TOC).

      Security

      • Added login tokens support for article URLs that contain hashbangs (.../articles/#!...).
      • Added more informative error messages for SSO authentication errors.

      Import

      • Cross-references in imported Word documents are now imported as links (were imported as plain text previously).

      Integrations

      • Added draw.io integration: you can now insert draw.io diagrams to help topics.
      • Added Lucidcharts integration: you can now insert Lucidcharts diagrams to help topics.

      Reporting

      • Search queries made in ClickHelp are now reported to your Google Analytics account if you configure Site Search properly in Google Analytics (see the documentation for details). Search queries performed by authors and reviewers are not reported to Google Analytics, so you don't have to filter them. Also, the information sent contains an additional parameter, "p", indicating the ID of the project for which the search operation was performed (when applicable).
      • It is now possible to filter out internal traffic from ClickHelp reports based on client IP address.

      Dashboard

      • Added links to help topics on project importing and publishing to the relevant wizards.

      Settings

      • Now, the selection of the current settings section is preserved (if applicable) when switching between project, publication and portal settings. This is especially useful when you need to update the same setting (e.g. Master Page) in multiple places in a row.
      • Portal settings re-organized and some of the categories renamed. Specifically, settings related to Power Readers, Full-Text Search, and Google Translate have been moved from the Reader Interface page to new separate setting pages. Settings of the "Was it Helpful?" reader feedback widget have been moved from the "Reader Interface" section to a new "Reader Feedback" settings section.
      • Reader Interface settings are now saved automatically when a new portal style/script file is created from the page.
      • The title of the global/project settings page now contains the name of the current settings section.

      Table of Contents

      • It is no longer possible to drop a node to any of its children (previously there was an error message indicating that a node could not become a child of itself).
      • It is now possible to collapse the left-hand navigation panel to free up more space for content on smaller screens.

      Other Improvements

      • Reader UI Performance improvements.

    Fixed Issues

      Topic Editor

      • Fixed the "open in new window" checkbox for article links pointing to other projects.

      Dashboard

      • Selecting the "Empty project, no styles" option in the Create Project wizard no longer makes the option to move to the right.
      • Fixed an issue with wizards skipping to the Finish step automatically even if there were warnings or errors in the log.

      Full-Text Search

      • Fixed full-text search not filtering results by the current project when the search is invoked from the mobile view.

      Login Page

      • Fixed the Password field not showing the fact that the password was already populated by browser auto completion unless the Password field is focused in the Login form.

      User Management

      • Fixed an issue with Power Readers that cannot be created if Reviewer roles are not allowed by license while Power Reader roles are allowed.
      • A user name is no longer marked as occupied after a failed attempt to create a user.

      Security

      • Removed an HTTP redirect (previously, if you opened http://company.clickhelp.co you were redirected to http://company.clickhelp.co/home/ first).

      Export

      • Breadcrumbs and horizontal See Also items are now exported to printed formats correctly.
      • Links to exported topics having long topic IDs (longer than ~30 characters) are now working correctly in printed formats.
      • The following CSS syntax elements are now handled correctly when exporting to Web Help:
        • The @namespace and @charset rules.
        • Curly brace characters located inside quotes.

      Reporting

      • Fixed some report columns not exported to Excel (XLS/XLSX) correctly from the Report Center and Users and Roles pages.

      Other Fixes

      • Index keywords are now displayed correctly in the mobile view for readers (the Index menu item was hidden for them previously).
      • When copying a topic to another project, the topic content is now copied as well (it could be copied with empty content previously).
      • The "Violation of PRIMARY KEY…” error no longer occurs when copying a project with review comments in it.