Releases: eclipsesource/tabris-js
Version 3.3.0
UI
Widget "Row" and Layout "RowLayout"
These are exact analogues to the existing Stack widget and StackLayout.
The Row widget is a composite that is automatically arranges its children in one horizontal line, like a single-row table. The corrosponding layout manager RowLayout may also be used on Composite, Canvas, Page and Tab via their layout property.
The default vertical layout of each child is controlled by the alignment property which can be set to 'top', 'bottom', 'centerY', 'stretchY' or 'baseline'. Individual child elements can be layouted different from the default via their own layout properties.
A very simple example:
<Row alignment='top' padding={4} spacing={24} >
<TextView>lorem</TextView>
<TextView>ipsum dolor</TextView>
<TextView>sit amet</TextView>
</Row>A more elaborate example can be found here.
Canvas Method "toBlob"
This new method on the Canvas widget creates a Blob object containing the image drawn on the canvas as a compressed image file. This can be a JPEG, PNG or WebP file. (WebP is only supported on Android).
It's really simple to use:
canvas.toBlob(blob => doSomething(blob), 'image/jpeg');The resulting image may be written to disk via the fs service or sent to a server via fetch(). It can also be set on any widget property that supports the ImageValue type.
Function "createImageBitmap" supports Canvas instances
The createImageBitmap() method can now create ImageBitmap instances from a Canvas instance. This recommended over canvas.toBlob() if the image is only used as an ImageValue on some widget and no access to the raw data is needed.
Button property "autoCapitalize"
The new property autoCapitalize controls how the button text is capitalized with the following options:
'default'- The platform decides on the capitalization'none'- The text is displayed unaltered'all'- Every letter is capitalized
Data Binding
New Components "ListView" and "ItemPicker"
ListView is an extension of CollectionView that adds high-level convinience API suitable for data binding. The ItemPicker does the same for Picker. Both provide an items property that take instance of List, which is provided by the tabris-decorators module. List features a subset of the standard Array interface, but unlike arrays it can be observed. This means any change to the list is immediately applied to the widget. In case of ListView the change is even animated. Scoll position (for ListView) and selection state (for ItemPicker) are preserved if possible.
The items properties also accept arrays, but in that case changes are not tracked. Instead of modifying the array the property needs to be set to a new array instance.
Both widgets also feature new selection API that directly provide the selected item value instead of just a selection index. Callbacks are not needed anymore either, meaning ListView and ItemPicker can now be more conviniently created in JSX. To do so the <ListView> element needs to contain a<Cell> element which is duplicated as often as needed. Multiple <Cell> elements may be given to display different item types.
Example:
<ListView stretch items={generate(20)}>
<Cell padding={8} height={52}>
<TextView centerY template-text='The color of ${item.text}:' font='24px'/>
<Composite stretchY left='prev() 24' width={80} bind-background='item.color'/>
</Cell>
</ListView>Services
Event "keyPress"
On app there now is a keyPress event fired when a hardware key is pressed. Note that these events stem from physical hardware, not from the virtual keyboard. The event object provides the keys' character, keycode and various meta data. The events prevendDefault() method can be used to prevent the default action of the key so the application may define it's own behavior.
Service "sizeMeasurement"
This is a service object that can measure the size of a given text in device independent pixel (DIP). Both synchroneous and asynchroneous API is available.
Other
New CLI "serve" options
The tabris serve command has some minor new features:
- The
--externaloption allows to define an URL as the only availble external address, which will then also be encoded in the QR code. - The
--portoption allows to define the actual port of the HTTP server so it matches the one given via--external. - With the
--no-introoption the QR code is not printed to the console. However, the QR code is now always available on the HTML site served by the CLI on the default URL with no path. So if the CLI runs on port 8080, enteringhttp://localhost:8080in a browser will still display the code.
Repository "tabris-decorators" supports GitPod
GitPod is an online IDE that can instantly provide a ready-to-code dev environment for any GitHub repository. Thanks to the CLI updates mentioned above it is now possible to side-load a tabris project in the developer app directly from a running GitPod instance.
The "tabris-decorators" repository has been pre-configured for this use case. Upon opening the repository in GitPod a script will launch that install the tabris CLI and print a list of available examples that can be launched via npm start <example>. It is also possible to directly launch a specific example using a custom URL. For the example labeled-input this would be:
Version 2.9.0
iOS 13 Compatibility
Fixed crash on startup when running on iOS 13
Backports
The following properties have been backported from the 3.x branch:
TextInput: "keyboardAppearanceMode"
app: "idleTimeoutEnabled"
Version 3.2.1
This patch release fixes compatibility with cordova plug-ins and a bug in the image scaling logic on Android.
Version 3.2.0
UI
New Widget "CameraView"
Tabris.js 3.2 adds the ability to take images via the devices camera. In order to so so, the tabris.Device object provides a list of cameras, which can be set on CameraView to show a live preview feed. To capture
an image, simply call the asynchrenous camera.captureImage() method, which returns a Blob containing a JPEG. The existing permissions API can be used to obtain access to the camera.
Minimal Example:
const camera = device.cameras[0];
permission.withAuthorization('camera',
() => camera.active = true,
() => console.log('"camera" permission is required.'),
(e) => console.error(e));
contentView.append(
<Stack stretch>
<CameraView stretchY camera={camera}/>
<Button text='Take picture' onSelect={captureImage}/>
</Stack>
);
async function captureImage() {
const {image} = await camera.captureImage({flash: 'auto'});
// do something with the "image" blob...
}Blob and BitmapImage as Generic Images
A compressed image (jpeg, png) obtained as a Blob object - for example via fetch or Camera - can now used anywhere the existing API accepts an ImageValue.
Minimal Example:
const response = await fetch('http://foobar/image.png');
const blob = await response.blob();
contentView.append(<ImageView stretch image={blob}/>);The same is true for BitmapImage objects, which can be created from Blob and ImageData. That way the the image is already in memory and its size already known before it is used in the UI.
This feature will become much more powerful when the BitmapImage API is extended in future Tabris.js releases.
New TextInput properties
The messageColor property lets you control the color of the message placeholder text independently from the input text.
On Android only keyboardAppearanceMode can be used to prevent the onscreen keyboard from popping up when a TextInput is focused, or only when it is focused by touch.
Option to control CollectionView.reveal() animation
Previously it was not possible to control whether a CollectionView.reveal() operation would be executed in an animated fashion or not. Now there is parameter a parameter which allows to control this behavior. The default is to animate the reveal operation.
Data Binding
The JSX/decorators based Data Binding API (TypeScript only) has been extended to allow bindings between widgets and non-widget ("plain") objects, including change detection. Previously this was only possible in a very limited manner. This feature was added to properly support the MVVM (Model-View-ViewModel) programming pattern.
Any instance of a class using the @property decorator on its properties can be used for bindings. One-way bindings to such an object are declared via JSX. The syntax for this remains unchanged, except that it is now also possible to bind to deeply nested properties:
@component
export class ExampleComponent extends Composite {
@property public myObject: Model;
constructor(properties: Properties<ExampleComponent>) {
super();
this.set(properties).append(
<Stack stretch>
<ProgressBar bind-selection='myObject.someNumber'/>
<TextView bind-text='myObject.otherModel.someString' text='Placeholder'/>
</Stack>
);
}
}The above example applies values of myObject properties to ProgressBar and TextView properties. If the source values are changed, or the entire myObject object is replaced, the widget properties are updated accordingly. Should the widget properties change for some other reason the source properties keep their value.
Two-way bindings to plain objects are declared via the @bind or the @bindAll decorator (which is a shorthand). The decorators take a parameter object mapping the property of the object to any property of any component-internal child (identified via its id):
@component
export class ExampleComponent extends Composite {
@bindAll({
myText: '#input1.text',
myNumber: '#input2.selection'
})
public model: Model;
constructor(properties: Properties<ExampleComponent>) {
super();
this.set(properties).append(
<Stack>
<TextInput id='input1' text='Fallback Text'/>
<Slider id='input2'/>
</Stack>
);
}
}This applies values of model properties to TextInut and Slieder properties and vice versa. Of course, if the widget property can't change by itself (i.e. TextInput's message instead of text) this is effectively a one-way binding.
Other
CLI
The tabris init command can now also create projects with MVVM example code, including unit tests.
New Event Handling Method "triggerAsync"
This method is an asynchronous alternative to trigger(). When called with await it pauses for all listener to resolve, including those marked async. This can be desirable - for example - to propagate errors from async listeners to the code that triggers the event, or when writing unit tests that need to verify the behavior of asynchronous code.
Internal Change: Property System Reworked
The internal property system has been partially re-written, which may cause minor differences in behavior. Most notably, properties should now behave more consistently regarding value checking and conversion/normalization. Also, properties that take objects/arrays no longer operate with safe copies. Instead they now keep the exact instance that was set (if no conversion is necessary), but makes them immutable if appropriate.
Due to this change Tabris Plug-Ins targeting 3.0 or 3.1 do not work with 3.2. New compatible versions have been released for the following plug-ins:
- tabris-plugin-maps (6.0.0)
- tabris-plugin-firebase (4.0.0)
- tabris-plugin-barcode-scanner (3.0.0)
Documentation Update
The documentation has been slightly revised, most noteably featuring a more structured table of contents in the left sidebar. Also, the presentation of type information in API documents has been tweaked and now always links to the type in question, either within the Tabris.js documentation or to MDN.
Version 2.8.1
v2.8.1 Update Version to 2.8.1
Version 3.1.0
New Permissions API
In order the access features like the devices location or camera, the user has to grant corresponding permissions to the app. Tabris 3.1 introduces the permission object that allows the app to check and request these permissions at runtime.
FormData support
Tabris.js now provides the FormData class (including related classes Blob and File) as it is specified by the W3C. It can be used in conjunction with fetch() or XMLHttpRequest to upload data in the "multipart/form-data" encoding.
Widgets API
New CanvasContext method "drawImage"
Until now the CanvasContext class implemented by Tabris.js lacked the W3C standard method drawImage. It has now been added with support for instances of the ImageBitmap class, which represent uncompressed in-memory images. ImageBitmap objects are created with the asynchronous createImageBitmap method using a Blob (containing a .jpg or .png image), ImageData or another ImageBitmap instance as the source.
New property "imageTintColor" on Button
This new property allows to tint the image displayed on a Button widget.
New property "scrollbarVisible" on CollectionView
The property works in the same fashion as scrollbarVisible on the ScrollView by showing or hiding the scroll bar.
New property "maxChars" on TextInput
Allows to limit the maximum number of characters that the user can enter into a TextInput.
New events "select" and "reselect" on Tab
The new "select" event on the Tab fires in tandem with the "select" event on the parent TabFolder, while "reselect" on the Tab fires when the tab is tapped by the user while it is already visible.
Infinite Animations
The animate method now allows Infinity as a value for the repeat option.
Version 2.8.0
This relase adds some features introduced in Tabris.js 3.0 and 3.1 to Tabris.js 2.x. Like usual it also includes some minor bugfixes.
ImageBitmap and drawImage
Until now the ConvasContext class implemented by Tabris.js completely lacked the w3c standard method drawImage. The new drawImage method takes instances of ImageBitmap, which represent uncrompressed in-memory images. ImageBitmap objects can be created with the asynchronous createImageBitmap method from a Blob contining a JPEG or PNG image.
ImageBitmap is a W3C standard and supported by all three Tabris.js 2 platforms.
Widget property "absoluteBounds"
The new property absoluteBounds provides widget bounds relative to the tabris.ui.contentView widget instead of the direct parent like bounds does.
ScrollView properties "scrollXState" and "scrollYState"
The ScrollView adds the properties scrollXState and scrollYState which indicate whether the view is currently, dragging, scrolling or in a resting position. Matching change events are available to observe these state changes while in motion.
Version 3.0.1
v3.0.1 Correct cordova versions in FAQ
Version 3.0.0
Adjust console snippet for better stack trace on iOS Unfortunately iOS stack traces skip arrow functions, which is why the cleaned-up stack trace was empty in this snippet. (The trace function falls back to the original stack trace.) Add a intermediate named function to the function so we get a clean trace on iOS. Change-Id: I86db8a64cc4bb7bfa2c2587a701d251608ca91c5
3.0.0-rc1
General
App
The new read-only property debugBuild can be queried to find out if the app is build in debug mode or release mode as given by the Tabris.js CLI to the tabris build command.
UI
CollectionView
The CollectionView no longer provides a select event as it worked unreliable across platforms. Interactions with a cell have to be handled directly by listeners attached to the cell. The new method itemIndex(cell) may be used to determine the index associated with a cell:
collectionView.createCell = () => {
const cell = new SomeWidget();
cell.onTap(() => {
const index = cell.parent(CollectionView).itemIndex(cell);
// do something with the item...
});
return cell;
}The method cellByItemIndex(index) was added to allow the reverse - getting the cell widget currently associated with the given index. Can be null when the cell at the given index is currently not displayed.
TextInput
On Android the TextInput appearance can now be customized via the new properties style, and floatMessage. The new properties allow to support the design style guide outlined in the material design specs.
Picker
The Picker now allows to show an empty state. This unselected state can be filled with a new message text property similar to a TextInput. The empty state has the selectionIndex of -1. Setting the selectionIndex to -1 reverts to the empty state and shows the message if available.
On Android the Picker can now be customized via the new properties style, and floatMessage similarly to the new properties introduced on TextInput.
With the introduction of the new style property on Picker, the iOS only property fillColor became redundant and was removed. Previously the fillColor was required to separate the Android underline colorization from the ios picker background color. Setting the Picker style to underline on Android now ignores the background and only applies the borderColor property.
In addition the font property (previously available on Widget in Tabris.js 2.x) has now been added on the Picker explicitly. It changed the appearance of the text shown in the Picker box.
ScrollView
The ScrollView adds the properties scrollXState and scrollYState which indicate whether the view is currently, dragging, scrolling or in a resting position. Matching change events are available to observe these state changes while in motion.
StackLayout and StackComposite
The StackComposite widget introduced in 3.0.0-beta2 was renamed to just Stack and now respects the layoutData of its children. Details can be found in the revised Layout documentation.
TabFolder
The TabFolder has a new property selectionIndex to set the active Tab without having an instance of it. This is especially useful when using JSX where the Tab children are created declaratively and no instance is immediately available.
The badge and badgeColor property are now also supported on Android. The expected type of the badge is now a number instead of a string.
Widget
The padding property is now available on all widgets, not just Composite. It also supports shorthand syntax like [1, 10, 4, 8], '1 10 4 8' or simply 16, in place of {top: 1, right: 10, bottom: 4, left: 8}.
The layoutData preset "fill" was renamed "stretch" and presets "stretchX" and "stretchY" have been added.
A new property excludeFromLayout was added that can be set to true to make the widget not just invisible (like visible = false) but to also make the layout behave as though the widget does not exist. That way there is no empty space where the widget would have been displayed.
The new property absoluteBounds provides widget bounds relative to the tabris.contentView instead of the direct parent like bounds does.
tabris.ui
The tabris.ui object which was already deprecated is now completely removed.
TextView
The TextView alignment value 'center' was renamed to 'centerX'.
AlertDialog
The AlertDialog property texts has been replaced with a ContentView object. Any TextInput instances are appended to it. The ContentViews layout can not be changed and it will position to TextInput objects from top to bottom, similar to replaced texts property.
NavigationView and Actions
Removed properties placementPriority from Action and navigationAction from NavigationView: These properties are replaced by a new property placement on the Action widget. It accepts the values 'default' (same as placementPriority = 'normal'), 'overflow' (same as a placementPriority = 'low') and 'navigation', which puts the action in the place usually reserved by the drawer icon.
Selector API
Introduced global function $() as an alias for tabris.contentView.find(). This especially makes small snippets more readable.
On WidgetCollection the new only() method works like first(), but throws if there is more than one match. It's therefore more secure than first() when selecting a single widget.
The parent() method now also takes a selector, returning the nearest parent that matches.
Removed method find() due to its ambiguous nature. This does not affect composite.find() which still exists.
JSX Stateless Functional Components (i.e. factories) can now be used as selectors, just like widget constructors can.
JSX
All popups now support JSX, i.e. Popover, DateDialog and TimeDialog, in addition to the already supported AlertDialog.
Markup elements: JSX elements can now directly contain tags like <b> and <i>.
Element <$>: This is a globally available element that may be used to group widgets (instead of <WidgetCollection>). It can also contain text, in which case it returns a string.
Almost all layout properties (e.g. left, top, centerY...) now accept true as an alias (usually for 0) which allows a shorter syntax in JSX, e.g. <TextView centerY> instead of <TextView centerY={0}>.
All layoutData preset values ('center', 'stretch', 'centerX', 'stretchY') can now be used as JSX shorthands, e.g. <TextView stretchY> instead of <TextView layoutData='stretchY'>.
TypeScript
Widgets TabFolder, NavigationView and CollectionView are now generic, allowing to narrow down the type of accepted children. The feature already existed on Composite.
The pseudo-property "jsxProperties" that is used to define which JSX attributes are supported in .tsx files was renamed to "jsxAttributes". However, due to changes in the type declaration files of tabris this property should rarely be needed anyway.
Developer Experience
Most Developers Guide articles have been re-written for clarity, links fixed, code examples and images added.
Various internal/low-level APIs have been documented for better extendability/hackability.
The tabris module now includes a sub-module 'ClientMock' that can be used to initialize the tabris module outside of a native Tabris environment, e.g. in node. When generating a new (compiled) Tabris 3.x project via the Tabris CLI (or the yeoman generator) the option to generate such a test setup based on mocha is given. This feature is not yet documented in the developers guide.
The global $() method can be used in the developer console (or CLI with interactive mode) to access any widget (or NativeObject) via its cid number. The cid is usually given in log messages/warning.