DataFormsJS v5.0.0 Release Notes

Release Date: 2020-11-19 // over 3 years ago
  • Credits / Thanks!

    • Thanks ElevateBart for helping with the idea and API proposal related to jsxLoader updates with this release: https://github.com/elevatebart
      • https://github.com/dataformsjs/dataformsjs/issues/16
      • The result is that jsxLoader can not be used from both node and webpack without side effects. Originally jsxLoader was intended only for browser use and it would always check if polyfills or babel standalone were needed based on the browser environment. Now this can be turned off.

    ๐Ÿš€ Release Overview

    • โšก๏ธ Many updates have been made for overall improvement of DataFormsJS Web Components

      • The updates are significant and make using the Web Components much easier for complex apps and sites; and provide for wider browser support.
      • The new features make for an easier to use API for customizing content on page after data is displayed. Previously the places demo required a lot of custom JavaScript on the page in order to display flag icons, format table data, and additional items.
      • Added ability to polyfill Web Components for older browsers using the standard Framework that gets loaded from a single file and then that file polyfill.js loads additional framework files as needed.
      • Web Components have been updated for full support with React (16 and 17) and React Router. Additionally Web Components have been tested and have partial support for Vue 2 and Vue 3 when using Vue Router.
      • Web Component Examples:
      • https://www.dataformsjs.com/examples/hello-world/en/web.htm
      • https://www.dataformsjs.com/examples/hello-world/en/web-url-router.htm
      • https://www.dataformsjs.com/examples/places-demo-web.htm
      • https://www.dataformsjs.com/examples/log-table-web.htm#/10
      • https://www.dataformsjs.com/examples/countries-no-spa-web.htm
      • https://www.dataformsjs.com/examples/image-gallery-web.htm
      • http://127.0.0.1:8080/image-classification-web
      • http://127.0.0.1:8080/web-components-with-react
      • http://127.0.0.1:8080/web-components-with-vue
      • http://127.0.0.1:8080/web-components-template
      • http://127.0.0.1:8080/web-components-data-list
      • http://127.0.0.1:8080/web-components-format
      • http://127.0.0.1:8080/hacker-news-web
      • Added new easier to use API for <url-router> and <json-data> Web Components
      • Added ability to define custom <template> for table <tr> in <data-table>
      • Improvements for <json-data>
      • Added option for formatting text from (date, time, number, custom functions, etc)
      • Added ability to use new attribute click-selector for search forms similar to the main Framework.
      • Added data-show="js-expression" to show or hide items. It works similar to Vue v-show.
      • Added ability to include global variables from window scope using {variable} syntax
        • <json-data url="{rootApiUrl}/web-service">
        • window.rootApiUrl = 'http...';
        • This allows an SPA site that contains many different HTML files with the same Root URL to point to the server from one location rather than updating each file.
        • Any variable name can be used as long as it is defined. This allows for rapid testing or changes to point to a different server when using <json-data>.
        • The actual update exists in [utils.js].buildUrl().
        • A similar update has been made for the main DataFormsJS Framework app.buildUrl().
      • Added new attribute [transform-data] that allows for a JavaScript function to be specified and used to transform the downloaded data before it is passed to other elements.
      • Added new Web Component <nav is="spa-links">. Previously SPA Nav Links were handled from custom JavaScript code on the page. Now this functionality is much easier for a site to include as only HTML is needed.
      • <url-router> and <url-hash-router> are now combined into one component <url-router> and <url-hash-router> has been removed.
      • <url-router> now has the ability to lazy load scripts (CSS and JavaScript) per route in a similar manner to the main framework using the new window.lazyLoad option and related HTML Attributes.
      • New Class WebComponentService which can be used to define "service" Web Components
      • The term "service" is used here because the intended use is that components created with this class do not render content but rather provide a service that updates other elements on the page based on HTML attributes element class names, etc. and that the service needs to run when content on the page changes from SPA routes or JSON Services.
      • This is a similar concept to the DataFormsJS Framework Plugins feature allowing for custom functionality to be defined easily and with little API code outside of standard DOM and JavaScript.
      • This will be used by all DataFormsJS Web Components that end with "service" in the component name.
      • Added new Web Component <data-view> and related Framework JavaScript Control for viewing data from <json-data> or other web components.
      • Added new Web Component <keydown-action-service>. Based on Framework Plugin js/plugins/keydownAction.js
      • Added new Web Component <html-import-service>. Based on standard framework features for [data-template-url] and [data-template-id].
      • Added new Web Component <show-errors-service>. Based on standard framework features for <html data-show-errors>.
      • Added new Web Component <prism-service>. Based on Framework Plugin js/plugins/prism.js
      • Added ability to style errors using CSS from utils.js when calling showError(element, message) or showErrorAlert(message).
      • New functions in utils.js: loadCss(id, css), isAttachedToDom(element)
      • Added [X] Close Button for js/web-components/old-browser-warning.js so that users can close the alert. With the new close button using js/web-components/safari-nomodule.js is no longer needed, however the file is still being kept for reference and sites that want to customize and use it.
      • js\web-components\data-list.js
      • Added HTML attribute root-attr which allows for any attribute to be set on the root element. Previously only the class could be set from root-class. The attribute root-class is still supported.
      • For <url-router> and DataFormsJS Framework when using HTMl5 History Mode (pushState, popstate) the Mac Command Key is now supported so users can open SPA links in a separate tab. Previously the only the {Control} key worked which is used on Windows for new tags and on Mac for a context menu (right-click menu).
    • โšก๏ธ DataFormsJS React Components and jsxLoader Updates

      • Minor bug fix where empty data props were not parsed correctly in a specific condition if this previous prop was not empty; this was found when updating Web Components for full React Support.
      • Added Node Support for jsxLoader
      • Added ability for jsxLoader to run from webpack (or in a browser) without any side effects if only the compiler is needed. Documentation will be updated after npm release on how this can be handled.
      • Previously jsxLoader only worked in a browser.
      • jsxLoader is now available as a node API and it works in the browser.
      • Added new compiler settings and options: ~~~js jsxLoader.compiler.pragma = 'React.createElement'; jsxLoader.compiler.pragmaFrag = 'React.Fragment'; jsxLoader.compiler.maxRecursiveCalls = 1000; // The above setting replaces jsxLoader.maxRecursiveCalls so it's a breaking // change, however it's mostly just an internal property for unit testing and // for safety in the event of an unexpected error.

    jsxLoader.compiler.addUseStrict = true; // By default "use strict"; is now added to the top of compiled JS code if // does not already exist. This can be turned off by setting addUseStrict = false. // This behavior is similar to the latest version of Babel 7.

    // Added new code hint that is supported by Babel: /* @jsxFrag Vue.Fragment */

      * Updated the CDN version of Babel Standalone used for old browsers from `7.10.4` to `7.12.6`
      * Added improved error message for compile errors where the number of opening tags did not match the number of closing tags. Previously some of these errors were only caught at runtime and not compile time.
      * Updated `.eslintrc.js` for improved syntax validation when using VS Code with `*.jsx` example and test files
      * When calling `jsxLoader.usePreact` a global `React` variable pointing to `preact` will be assigned to `window` by default if not already set and Preact is loaded.
      * ES6 `*.min.js` Components can now be loaded in a web browser using `[type="module"]`. Previously only the ES5 min files could be loaded in a browser.
      ~~~html
      <!-- Previous Release typical CDN usage -->
      <script src="dataformsjs/js/react/es5/DataFormsJS.min.js"></script>
    
      <!--
        With the latest release of DataFormsJS modern browsers can use the smaller files with
        modern code syntax while legacy browsers still the es5 build.
      -->
      <script type="module" src="dataformsjs/js/react/es6/DataFormsJS.min.js"></script>
      <script nomodule src="dataformsjs/js/react/es5/DataFormsJS.min.js"></script>
    
    • Format class has several functions added that were previously private scoped in the module:

      • isNumber(n)
      • formatDateTime(dateTime, options)
      • formatNumber(value, options)
      • They are mostly internal so for usage view the source code.
      • โœจ Enhancements for DataFormsJS Framework files and general updates:
    • Added app.updateTemplatesForIE(rootElement). IE 11 considers <template> elements as valid elements so it applies querySelector() and related methods to elements under <templates>'s so replace with them <script type="text/x-template">. This avoids issues of <template> elements that contain embedded content. Previously this was only handled once per page load but now is handled (for IE only) when views are rendered.

    • Added features in js/plugins/dataBind.js based on the Web Components version.

    • New file js/extensions/format.js which is used with the Web Components Polyfill

    • Updated js/plugins/filter.js so that it shows 0 count for empty tables. Previously it expected the table to have at least one <tbody> element. A similar update was made for js/web-components/input-filter.js

    • Previously if using <template> with jsonData page types all .is-loading, .has-error, .is-loaded elements could quickly flash on screen during page changes. This has been fixed.

    • Routes and JavaScript controls will have empty data HTML attributes mapped to true by default instead of an empty string. Previously data-load-only-once="true" was used on many pages but now only data-load-only-once is required. Additionally null is now supported as an option.

    • js/plugins/i18n.js

      • Added app.plugins.i18n.getUserDefaultLang()
      • The following global API was added so that it can be used easily with templating or by app custom logic. This was based on the Web Component verison which uses simple JavaScript templating and basic functions. ~~~js window.i18n_Locale = 'en|fr|es|zh-CN'; // Selected language, updated on each page change window.i18nText(key) // Returns I18n content for the current page ~~~
    • data-load-only-once="true"

      • โœจ Enhancements for "JavaScript Controls" in the standard Framework. The Framework JavaScript Controls are a similar concept to Web Components but work with all Browsers.
    • Added ability to easily reload by calling app.activeJsControls(control). Updating already loaded controls is not common but can be used in very specific scenarios. For example the new Web Components Polyfill uses it.

    • Update API to include model as a parameter in control.onLoad(element, model)

    • Specific controls <data-table> and <data-list> have significant new functionality based on the matching Web Components that allows for basic templating from HTML. The template syntax is based on JavaScript template literals (template strings) and with the new features basic sites or apps that previously required Handlebars or Vue for templating could possibly use these instead. Use of templating requires using a new file js/extensions/jsTemplate.js.

    • Data Attributes for JavaScript controls will not use boolean data types when "true" or "false" are specified. This was created for the new data-load-only-once attribute added to js/controls/json-data.js for compatability with the Web Components version. A new fromCache option was added as a parameter to onFetch based on this change.

    • Added new functions app.unloadUnattachedJsControls() and app.unloadJsControl(jsControl). They are mostly for internal use but are available for advanced usage if needed.

      • โšก๏ธ Image Gallery Update for Overlay when title/alt is not used:
    • All versions updated (Web Component, Framework Plugin, React)

    • By default if title is not used the position {index}/{end} is displayed. Previously it aligned to the left of the screen. Now it will be aligned in the right of the screen only if title is missing which matches the behavior if the title is included

    • To change position see the following CSS examples (works in all browsers included IE):

      • .image-gallery-overlay div.no-title { justify-content: flex-start; }
      • .image-gallery-overlay div.no-title { justify-content: center; }
      • ๐Ÿ› Bug fix for js/pages/entryForm.js where the saveUrl did not allow for variables from the model if the URL of the page did not include any URL parameters.
      • โšก๏ธ All Leaflet code has been updated to download map images using https instead of http; originally when DataFormsJS was published https was not available as a free option for leaflet.
    • Additionally error messages have been improved for Leaflet.

    • Files updates:

      • <leaflet-map> Web Component
      • LeafletMap React Component and main DataFormsJS.js React file
      • leaflet Framework plugin.
      • โšก๏ธ Updated dependencies used for building the *.min.js files
    • @babel/standalone updated from 7.7.7 to 7.12.6, used to build es5 version of React Components

    • uglify-js updated from 3.7.3 to 3.11.6

    • eslint updated from 7.3.1 to 7.13.0

      • ๐ŸŒ Replaced uglify-es with terser for the minification of React Components and Web Components
    • *.min.js files are generated from npm run build. Only changed files get updated

    • Build Script scripts/build.js

    • uglify-es is an abandon projects and terser is a widely used fork.

    ๐Ÿ’ฅ Breaking Changes

    โšก๏ธ For the standard Framework most breaking changes are minor and only expected to affect internal API's and examples. Several Framework "JavaScript Controls" were updated to match behavior of the Web Components in order to provide more features and so they can be used with the new Web Components Polyfill. If you developed a site or app with any of the breaking changes they are quick to update and if you need help please open an issue.

    ๐Ÿ— For React Components one component LeafletMap and one class I18n that would not be commonly used in most apps have been dropped from the core ES5 build file js/react/es5/DataFormsJS.js. However new options exist so they (along with all other components and classes) have improved options for loading.

    ๐Ÿš€ <!-- Previous Release included [I18n, LeafletMap] and was ES5 sytnax only for CDN -->
    <script src="../js/react/es5/DataFormsJS.min.js"></script>
    
    <!--
      In the places demo the above script was replaced with the following.
    -->
    <script type="module" src="../js/react/es6/DataFormsJS.min.js"></script>
    <script type="module" src="../js/react/es6/I18n.min.js"></script>
    <script type="module" src="../js/react/es6/LeafletMap.min.js"></script>
    
    <script nomodule src="../js/react/es5/DataFormsJS.min.js"></script>
    <script nomodule src="../js/react/es5/I18n.min.js"></script>
    <script nomodule src="../js/react/es5/LeafletMap.min.js"></script>
    
    <!--
      However for most sites this will be enough and it results in a smaller
      download size for the end user and modern code for most users.
    -->
    <script type="module" src="../js/react/es6/DataFormsJS.min.js"></script>
    <script nomodule src="../js/react/es5/DataFormsJS.min.js"></script>
    

    โšก๏ธ The Web Components have the most complex breaking changes related to API usage however due to the complexity of the earlier API it's unlikely to affect any site. If a site did use the earlier API it is generally quick to update as well.

    • โœ‚ Removed <url-hash-router>
      • This can now be replaced with <url-router>
      • <url-router> previously only worked with HTML5 History Routes pushState/popstate. To use history routes now use <url-router mode="history">
    • ๐ŸŒ js/web-components/utils.js
      • Removed showOldBrowserWarning(). The feature has been replaced with the new js/web-components/polyfill.js and also the file js/web-components/old-browser-warning.js now includes a [X] close button so it it runs on Safari 10.1 or an old Chromium browser that doesn't support [nomodule] the user can simply close the alert.
      • Removed componentsAreSetup(). This function is no longer needed and the logic related to it's usage prevented Web Components from working with React and was not fully valid based on Custom Element specs because elements were writing HTML attributes on their constructor().
    • ๐ŸŒ Web Components API for <json-data>, <url-router> have been changed significantly. Previously the API required async/await from module JavaScript and was complex to use. It has now been simplified so that events bubble up to the document can be handled easily from the root document event listener and so standard JavaScript functions can be called from HTML attributes.
    • Framework JavaScript Controls
      • Dropped support for replacing the control element with a basic element. Example, previously <json-data> would have been converted to <div data-control="json-data">. Now the data-control attribute is added but the element is not converted.
      • This behavior allows for easier to use API from sites and apps that use the <json-data> Web Component and Polyfill.
    • ๐Ÿšš js/plugins/filter.js - Removed error alert for text Column filter requires a table to be correctly defined that happened if a table was missing when the filter was loaded. The reason is that it makes sense for certain apps to have a defined filter and only optionally include the table.
    • ๐Ÿ‘ js/controls/data-table.js - Replaced data-source with data-bind and now <data-table> will be converted to a <div> with a <table> in the <div> instead of converting to a <table> directly. Additionally <template> support has been added.
    • js/controls/data-list.js
      • Replaced data-source with data-bind and now <data-list> will be converted to a <div> with a <ul> in the <div> instead of converting to a <ul> directly.
      • <template> support has been added.
    • ๐Ÿ”Œ Rename jsPlugins.js function refreshJsPlugins() to refreshPlugins() so it matches the standard Framework.
      • Affects Web Components and React
      • js/web-components/jsPlugins.js
      • js/react/jsPlugins.js
    • ๐Ÿ”Œ Combined Framework Plugins js/plugins/navList.js and js/plugins/navLinks.js
      • All demos used navLinks.js and only the main site used navList.js
      • navList.js has been deleted but the functionality can now be handled by using navLinks.js and setting the following option from JavaScript: app.plugins.navLinks.itemSelector = 'nav li';