Appkit SDK 4.2.0 Release Notes

Release date: 28 February 2019

Appkit SDK 4.2.0 is the version of Appkit that is included in Fusion App Studio 4.2.0.

Upgrading to this version

Appkit 4.2.0 is the version of Appkit that is included in Fusion App Studio 4.2.0.

In apps created with prior versions of Fusion App Studio, you can upgrade the Appkit version to 4.2.0.

New features

The following are new features in this release.

Social module

  • Single response processor for social module – You can now configure a single response processor for the Social module, instead of having to configure separate ones for likes, comments, bookmarks, and so forth.

Fusion

  • Query against the Fusion Analytics Catalog – A Fusion Analytics Catalog platform has been added to query against the Fusion Analytics Catalog collection. This platform translates Appkit queries into SQL statements which are executed against a Fusion query pipeline that includes an Analytics Catalog Stage. The Fusion Analytics Catalog platform uses the Fusion Catalog API.

    For more information, see the Fusion Analytics Catalog platform.

  • Fusion platform supports index profiles – The Fusion platform adds the ability to use an index profile to index data into Fusion. When a read/write Fusion platform is present and an index profile is specified, then Appkit can store, update, and delete data in the Fusion index.

    To use an index profile, put index-profile: my-index-profile-name in your Fusion platform configuration, replacing my-index-profile-name with the index profile Appkit will use. Index profiles take precedence over index pipelines.

  • Use Fusion preauthentication – Fusion preauthentication is now available in the Fusion Security Provider module. By default, if an app is detected as having been uploaded to Fusion and the user has already logged into Fusion, then the user won’t need to log into the app.

Miscellaneous

  • Render facets in tabular format – A new web service lets you render facets in a tabular format.

    A new API endpoint, /core/services/platform/table, lets you retrieve the output of a Fusion/Solr pivot query.

    The endpoint renders the data as a set of headers and a set of rows. The output looks like this:

    {headers: [h1,h2,h3,h4]; rows: [c11,c12,c13,c14], [c21,c22,c23,c24] }

    You can leverage the endpoint in pivot:table elements.

  • Satellite platform can delegate search requests – A Satellite Platform can delegate search requests to any underlying platform.

    To use a satellite platform, place a new platform configuration file under the app’s resources; for example, a satellite.conf configuration file in conf/platforms/satellite/. Set these parameters in your platform configuration file:

    • name: twigkit.search.satellite.Satellite (required)

    • host: URL of the host for the underlying platform. It must begin with http or https.

    • platform-config: Platform configuration being delegated to

    • username: Username for authentication on the underlying platform

    • password: Password for authentication on the underlying platform. It is the encoded output of the Appkit twigcrypt utility.

    The username and password are required if Basic authentication is required to request search results from the underlying platform, for example, as is the case with Solr.

    For example:

    name: twigkit.search.satellite.Satellite
    platform-config: platforms.fusion.data
    username: search-user
    password: Enc(hfuqeif894732)
  • Query parameters are included in tab links – Query parameters are now included automatically in the links for tab names.

  • Query by drawing rectangles on ESRI maps – Users of Appkit web apps that display ESRI maps can now make geospatial queries by drawing rectangles on maps. The control for drawing rectangles is between the plus and minus signs.

    Google Maps has had this feature previously.

  • Specify date formats – The Date Format processor DateFormatProcessor lets you specify the format for the display value of a date field.

    For more information, see DateFormatProcessor.

  • Use JSP tag library utility functions – A JSP tag library and utility functions within the library are available to JSP pages.

    A dependency on twigkit.fusion.ui-jsp provides a JSP tag library. Adding <%@ taglib prefix="app" uri="/lucidworks/app" %> to the top of a JSP page exposes utility functions within that library. Adding ${app:contextPath(pageContext.request)} sets the context path of the app on that page, taking into account the Fusion webapps proxy.

Improvements

The following are improvements in existing features in this release.

  • Date formats – Date formats are applied to date ranges in facet series in charts.

  • Range values – The numberFormat and dateFormat value filters now handle range values automatically by formatting the endpoints of a range individually. With this change, you must remove any special handling of range values in individual widgets.

  • Multiselection of highmaps regions – A new select attribute has been added to the geo:highmaps tag, which takes these values:

    • click (default) – User selects a filter by clicking a region.

    • multiselect – Select multiple filters that get combined with a logical disjunction (OR). Shows an Apply button that is enabled if and only if one or more checkboxes have been ticked.

    • multiselect-instant – Select multiple filters that get combined with a logical disjunction (OR). Filters are applied immediately when a checkbox is ticked.

  • Tag search:dropdown renamed – The search:dropdown tag has been replaced with the facet:dropdown tag. All functionality from the prior tag exists in the new one.

  • Control filter selection for facet:dropdown – A new select parameter has been added to the facet:dropdown tag, which takes these values:

    • toggle (default) – Only allows one filter to be selected at a time, but shows unselected filters and counts.

    • multiselect – Select multiple filters that get combined with a logical disjunction (OR). Shows an Apply button that is enabled if and only if one or more checkboxes have been ticked.

    • multiselect-instant – Select multiple filters that get combined with a logical disjunction (OR). Filters are applied immediately when a checkbox is ticked.

  • Pass options to geo:highmaps – The new options parameter lets you pass other options to geo:highmaps.

  • Show more values for search:filter – A new show-more-values parameter has been added to the search:filter tag.

    • When show-more-values is specified without an assignment (e.g. <search-field show-more-values …​>) or with the value -1, then Appkit shows all additional values for the field when the user clicks the "Show more" link.

    • When show-more-values is assigned a positive integer value (e.g. <search-field show="5" show-more-values="10" …​>), then Appkit shows that number of additional values of the field when the user clicks the "Show more" link (or all remaining values if there are fewer values than the number requested).

    • In both cases, Appkit doesn’t show a "Show more" link when there are no additional values to be shown.

      Example usage

      <search:result-list results="results">
          <search:result>
              <search:field name="multivalued-1" show="2" show-more-values></search:field>
              <search:field name="multivalued-2" show="2" show-more-values="10"></search:field>
          </search:result>
      </search:result-list>
  • New parameters for facet:dropdown – A number of additional parameters are now available in the facet:dropdown tag:

    facet-name
    title
    show
    show-more
    max-characters
    select
    show-empty
    show-more-label
    show-less-label
    show-count
    action
    order
    count-number
    date-format
    measure

    These parameters were previously available in the search:filter-list tag. They have the same uses.

  • Track clicks for any clickable elements – You can add click tracking to any clickable element on a page, including clicks on elements that aren’t anchor elements (and not even hyperlinks). To configure click tracking on custom elements, include your block of trackable elements in a <track-clicks> element, as before, and add one or more of the following attributes to the DOM elements for which you want to intercept click events:

    • trackable – Clicks are tracked for all DOM elements with a trackable attribute, in the scope of a <track:clicks> element.

    • data-click-type (optional) – Specify a custom click type for a trackable DOM element. If data-click-type is not specified, the click type defaults to the type argument specified in the <track:clicks> tag.

    • data-click-url (optional) – Specify a custom URL to track for a trackable DOM element.

  • Deleting annotations is tracked – Annotation deletions are now tracked (they generate signals).

  • Restrict tk.session cookie to HTTPS channels – You can now configure whether or not the tk.session cookie should be restricted to HTTPS channels over "SSL" (actually TLS). By default, the cookie is sent over all channels (the prior behavior).

    To restrict the cookie to HTTPS channels, include this entry in conf/activity/activity.conf:

    session-secure:true
  • Set the hover timeout of a widget popover – You can set the hover timeout of the widget popover. This is the amount of time in milliseconds that the popover is displayed after the user leaves the popover trigger. The optional parameter is hover-timeout. The default is 1000 (1 second). Here is an example that sets the hover timeout to 1/10th of a second:

    <widget:popover mode="hover" hover-timeout="100">
     <popover-trigger><button styling="button">Hover with a short timeout></popover-trigger>
     <popover-content>
        <h1>Hover</h1>
        <p>The hover timeout of the button you are hovering over is set to 1/10th of a second.</p>
     </popover-content>
    </widget:popover>
  • Customize icons for facet lists – You can customize the icons used to expand and collapse a facet list.

    1. In the project-name/assets/styles.css file, define CSS class selectors for the collapsed (the first of these) and expanded (the second) icons, for example:

      .custom-collapse-facet .collapsed a.facet-toggle:after {
          content: '\e817';
       *  font-family: "twigkit-basic";
      }
      
      .custom-collapse-facet a.facet-toggle:after {
          content: '\e815';
          font-family: "twigkit-basic";
      }
    2. Reference the CSS classes in the search:facet tag, for example:

      <search:facet-list response="response" styling="facet-list facet-list-step facet-list-wrappedheader facet-list-wrappedheader-noborder">
          <search:facet class="custom-collapse-facet" facet-name="test1" title="First Pass Files" collapsible="true" show="1" show-more="10">
          </search:facet>
      </search:facet-list>
  • Press Enter to save a search query – After entering a name for a saved search, a user can now press Enter to save the search query.

  • Number formatting for widget:slider – The widget:slider element now supports number formatting. Use a number-format parameter to specify a format using the Java DecimalFormat.

    For example, for a Cost facet:

    <widget:slider response="response" facet-name="Cost_i" number-format="$#,###.00"></widget:slider>
  • Performance improvement for search-enabled facets – Performance has been improved for search-enabled facets, that is, search:facet elements with search-enabled set to true.

  • Choose fonts to include in web apps – You can choose among three Less stylesheet language files for including fonts in web apps.

    • phoenix.all.less (available prior to 4.2.0) – This stylesheet uses custom fonts fetched from a content delivery network by the browser. If a web app is hosted on a secure site with no Internet access, this stylesheet can have font loading errors that will manifest as "using different fonts" and as an eternally loading spinner in the browser somewhere.

    • phoenix.all.local-fonts.less (new in 4.2.0) – This stylesheet includes custom fonts that are hosted in the Appkit web app. However, you can’t use this stylesheet when a web app is accessed via the Fusion Proxy and Web Apps services.

    • phoenix.all.no-fonts.less (new in 4.2.0) – This stylesheet excludes all custom fonts.

    Suggested usage:

    • Normal client, not using the Fusion Web Apps and Proxy services – phoenix.all.local-fonts.less

    • Normal client, using the Fusion Web Apps and Proxy services – phoenix.all.less

    • Secure client – phoenix.all.no-fonts.less

    To change the Appkit Less file in an app:

    Find the reference to the stylesheet in wro.xml or twigkit.less. After the appkit-ui Node module is installed, the Less stylesheets are found in node_modules/appkit-ui/dist/less/.

  • jQuery 3.3.1 support – Appkit upgraded its use of jQuery to version 3.3.1

  • Performance improvement for loading comments – Loading times for comments in app UIs have been reduced significantly.

  • Configuration property passthrough for Elastic X-Pack – For the Elastic 6 platform, any configuration properties that start with xpack are passed through to the Elastic X-Pack client.

  • Modify path of app URL – To make your app available at a different URL than http://hostname:*port*/ (for example, http://localhost:8080/), use the -Dtwigkit.http.context command-line parameter when starting the app to specify a path component to append to the URL. This can make using a reverse proxy easier.

    For example, -Dtwigkit.http.context=search would start the app at http://hostname:*port*/search (for example, http://localhost:8080/search)

    Each app must use a different HTTP port.

  • License restriction in Fusion – The Appkit Fusion platform is now license-restricted. Using the Fusion platform now requires this license property in the Fusion license.properties file:

    property_social: *
  • Sort Solr facets by count – Previously, in the SolrHierarchicalFacetService and GreedySolrHierarchicalFacetService services, you could only sort by name. Now, you can also sort by count.

  • Where to enable tracking – The determination of whether tracking should be enabled is now made in ActivityModule instead of in individual trackers.

    Note
    Tracking is either enabled (the default) or disabled for all trackers.

    Upgrade information: To upgrade a project in which tracking is disabled to the 4.2.0 version of Appkit, migrate the enable: false configuration parameter from activity/tracking/tracker.conf to activity/tracking.conf.

  • Redirection to logout page when in HTML5 mode – The security:user-actions tag has been improved to redirect to the logout page when the application is in HTML5 mode.

  • Specify hidden fields in search:fields – In addition to specifying user selectable fields, the search:fields element now lets you use the new attribute hidden-fields to specify a set of fields that will always be requested, whether or not the user selects them.

Fixed issues

The following issues are fixed in this release:

  • When CSRF security is enabled, the backend for Appkit Lightning social/collaboration widgets does’t pass the request token to the frontend.

  • Search query saved previously in the search:box component persists in the saved-search pane and must be cleared manually.

  • The widget:date-range component lets a user select a To date that precedes a From date.

  • Custom colors defined in @highchart-colors don’t work.

  • Clearing all breadcrumbs doesn’t clear the breadcrumb for the search query term.

  • Lucene index delete queue isn’t flushed after document deletion.

  • The chart:histogram element doesn’t display a histogram if there is only a single facet value.

  • The indicator of the sorting order for search results isn’t set when a new sort is performed.

  • For the search:box and advanced:button elements, pagination isn’t reset when a new search is performed.

  • The widget:date-range component uses a previously selected To date when reselecting dates.

  • When using both tabs and saved searches, sometimes selecting a saved search had no effect.

  • When doing partial updates using an Appkit Solr platform, the id field is modified incorrectly.

  • The suggester parameter in the SolrSuggestionsRetriever service is ignored, which prevents specification of multiple suggester dictionaries.

  • An OAuth filter conflicts with a Spring Security filter if the filters have the same name.

  • Logging about floating licenses isn’t correct.

  • It is impossible to use arrows to select typeahead results when a search:result-list element is nested inside an instant:result-list element.

  • A dependency conflict exists between the Elastic 6 adaptor and the Media module. It isn’t possible to use them together.

  • Track Clicks can’t calculate the offset if RPP (results per page) isn’t included in the query.

  • Hierarchical facet filters aren’t being fully cleared.

  • Attempting to connect to a Fusion data source using a query profile returns a 404 error if the Fusion collection has more than one shard.

  • The draw function in Google Maps creates the longitude filter incorrectly.

  • When using the facet:dropdown element and making more than one facet selection, incorrect facets are selected, highlighted, indicated in breadcrumbs, and used in queries.

  • Calling store on the Lucene platform doesn’t add new documents.

  • New bounds aren’t used for a Google Map when a user clicks a filter.

  • Documentation for the collaboration:comment-list tag mentions bookmarks instead of comments.

  • When no LDAP groups are found for a user, an invalid LDAP query cause an exception to be thrown.

  • Clicking outside a list of selectable fields displayed by a search:fields element doesn’t hide the list of fields.

Date Format processor

The Date Format processor DateFormatProcessor lets a user format the display value of a date field.

To enable DateFormatProcessor:
  1. Add the file data-format.conf under conf/processors/response. In the file add:

    name: twigkit.search.processors.response.DateFormatProcessor
    format: date-format

    For example:

    name: twigkit.search.processors.response.DateFormatProcessor
    format: dd-MM-yyyy

    The default format is yyyy-MM-dd.

  2. Add the processor to the relevant platform configuration. For example, in conf/platforms/fusion/data.conf add:

    workflow: processors.response.date-format

    When this platform is used to request search results, the Date Format processor is used to format dates in the response.

Fusion Analytics Catalog platform

A Fusion Analytics Catalog platform has been added to query against the Fusion Analytics Catalog collection. This platform translates Appkit queries into SQL statements which are executed against a Fusion query pipeline that includes an Analytics Catalog Stage. The Fusion Analytics Catalog platform uses the Fusion Catalog API.

The Analytics Catalog platform expects standard Fusion platform configuration parameters (for example, host and collection).

Note
The current implementation only supports fields and facets parameters in the <search:query> tag.

Get started with the Fusion Analytics Catalog platform

  1. Start Fusion Server: bin/fusion start

  2. Start the Fusion SQL service: bin/sql start

  3. Add a new platform configuration file, for example conf/platforms/fusion/analytics.conf. Include these properties:

    name: twigkit.fusion.analytics.FusionAnalytics
    resultIDField: ID-field
    userName: Fusion-user
    password: password
    host: host-name
    collection: Fusion-collection

    For example:

    name: twigkit.fusion.analytics.FusionAnalytics
    resultIDField: id
    userName: admin
    password: password123
    host: search.my.org
    collection: analytics
  4. Edit the configuration file conf/services/api/fusion.conf. Specify the catalog to use with the platform. The default catalog is fusion:

    catalog-project: fusion-catalog
  5. Use the platform in HTML pages. For example:

    <search:platform var="platform" conf="platforms.fusion.analytics"></search:platform>
    <search:query var="query" parameters="*"
                  fields="id,pdf_url_s,summary_t,published_dt pubdate,categories_s"
                  facets="categories_s,pdf_url_s"></search:query>
    <search:response var="response" platform="platform" query="query">
        <widget:spinner></widget:spinner>
    </search:response>