https://github.com/nativescript-community/xml-ui-loader
https://github.com/nativescript-community/xml-ui-loader
Last synced: about 1 year ago
JSON representation
- Host: GitHub
- URL: https://github.com/nativescript-community/xml-ui-loader
- Owner: nativescript-community
- License: apache-2.0
- Created: 2022-08-23T22:28:50.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2023-05-19T18:01:38.000Z (about 3 years ago)
- Last Synced: 2025-03-24T17:51:30.217Z (about 1 year ago)
- Language: TypeScript
- Size: 448 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# @nativescript-community/xml-ui-loader
[](https://www.npmjs.com/package/@nativescript-community/xml-ui-loader)
[](https://www.npmjs.com/package/@nativescript-community/xml-ui-loader)
[](https://github.com/nativescript-community/xml-ui-loader/network)
[](https://github.com/nativescript-community/xml-ui-loader/stargazers)
This is a [webpack](https://webpack.js.org) loader for [NativeScript](https://nativescript.org).
By default, NativeScript Core uses a builder to compile XML components at runtime and that happens every time there is a need to render views.
This new approach is meant to work as an ahead-of-time (AOT) compiler that turns XML content into JavaScript during the build phase.
It's meant to improve performance and allow developers to use XML files as modules.
## Table of Contents
- [Install](#install)
- [Setup](#setup)
- [TypeScript](#typescript)
- [Webpack](#webpack)
- [Usage](#usage)
- [Import as a module](#import-as-a-module)
- [Import as plain XML](#import-as-plain-xml)
- [Features](#features)
- [Data binding](#data-binding)
- [Custom components](#custom-components)
- [Script and Style](#script-and-style)
- [Slots](#slots)
- [Declaration](#declaration)
- [Targeting slots](#targeting-slots)
- [Slot fallback](#slot-fallback)
- [Using slots in JS/TS components](#using-slots-in-jsts-components)
- [License](#license)
## Install
```
npm install @nativescript-community/xml-ui-loader --save-dev
```
## Setup
### TypeScript
Add XML module declaration to your types:
`references.d.ts`
```ts
///
declare module '*.xml';
```
### Webpack
This loader requires a new configuration:
`webpack.config.js`
```javascript
const webpack = require('@nativescript/webpack');
const { getEntryDirPath, getPlatformName } = require('@nativescript/webpack/dist/helpers/platform');
const { chainLoaderConfiguration } = require("@nativescript-community/xml-ui-loader/dist/helpers");
module.exports = (env) => {
webpack.init(env);
// Learn how to customize:
// https://docs.nativescript.org/webpack
webpack.chainWebpack((config) => {
chainLoaderConfiguration(config, {
appPath: getEntryDirPath(),
platform: getPlatformName()
});
});
return webpack.resolveConfig();
};
```
There are also few preprocessing options that are useful for applying output customizations.
```javascript
chainLoaderConfiguration(config, {
appPath: getEntryDirPath(),
platform: getPlatformName(),
useDataBinding: false, // Set this to false if you don't want to use data binding system
preprocess: {
// Format attribute value
attributeValueFormatter: (value, attributeName, tagName, attributes) => value.toUpperCase(),
// Manage AST result
transformAst: (ast, generateFunc) => generateFunc(ast).code,
}
});
```
## Usage
### Import as a module
One can easily import an XML component just like any regular JS module using either a default or a named import.
Example:
```javascript
// Default import
import MyActionBar123 from "./components/my-action-bar.xml";
// Named import
import { MyActionBar } from "./components/my-action-bar.xml";
```
### Import as plain XML
To import the raw content of an XML file, append an XML declaration to it.
Example:
```xml
...
```
This will make sure import will resolve to plain XML string content.
## Features
### Data binding
Data bindings are supported using MVVM pattern by setting view's `bindingContext` property on JS side.
```xml
```
Note: Two-way binding is enabled by default. However, events, sub-properties and expressions that make use of `$value`, `$parent`, or `$parents` callers do not support it.
### Custom components
Regarding custom components, they can be used in markup by declaring namespaces.
A namespace works just like a named import.
A correct approach, supposing caller directory path is `app/views/home` and components directory path is `app/components`
```xml
```
### Script and Style
In general, one is able to create script and style files for an XML component provided that they use the same filename.
The first contains useful entities like events used by XML and the latter applies all CSS to it.
There is also a forgotten method to bind scripts or styles to XML.
It's `codeFile` and `cssFile` properties. These properties are assigned to top element inside an XML file and are especially useful when one wishes to bind a single script or style file with multiple components.
```xml
```
### Slots
Custom components can make one's code reusable but there is always the need to have total control over view nesting as they can be quite complex at times.
Here comes the concept of `slots`. Inspired from the web component [slot](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot) element, slots ensure that custom components can be extremely flexible on reusing at different cases that demand different view content.
For more information, see: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot
#### Declaration
A plain slot that behaves as default
```xml
```
A named slot
```xml
```
#### Targeting slots
In order to target slots and keep NativeScript existing nesting behaviour intact at the same time, one must declare slot views inside a `slotContent` element.
```xml
```
Named slots can be targeted using the `slot` attribute.
```xml
```
There is also the option of targeting a slot using multiple views.
```xml
```
or
```xml
```
Apart from views, slots can also target other slots.
```xml
```
#### Slot fallback
Fallback refers to the content (one or more views) that is rendered when no view(s) target the slot.
```xml
```
#### Using slots in JS/TS components
There is also the possibility of making use of slot functionality into script components.
```js
import { StackLayout } from '@nativescript/core';
class MyCustomView extends StackLayout {
// Constructor has sole access to slot views
constructor() {
super();
// $slotViews is an array of views
if (this.$slotViews['default']) {
for (const view of this.$slotViews['default']) {
this.addChild(view);
}
}
}
}
export {
MyCustomView
}
```
```xml
```
## License
Apache-2.0