Aurelia 2 Script Example

``` ## Observable Properties ```typescript import { observable } from '@aurelia/runtime'; export class MyComponent { @observable searchText = ''; @observable selectedItem = null; // Automatically called when searchText changes searchTextChanged(newValue, oldValue) { this.filterItems(newValue); } // Automatically called when selectedItem changes selectedItemChanged(newItem) { if (newItem) { this.onItemSelected(newItem); } } } ``` ## Templating syntax ```html

Hello, ${firstName} ${lastName}

``` ## Animation ### CSS Animations ```typescript import { AnimationEvent } from '@aurelia/runtime-html'; export class FadeInOut { enter(element: Element): void { element.classList.add('fade-in'); } leave(element: Element): Promise { return new Promise(resolve => { element.classList.add('fade-out'); element.addEventListener('animationend', () => resolve(), { once: true }); }); } } ``` ### Web Animations API ```typescript export class SlideAnimation { enter(element: Element): Animation { return element.animate([ { transform: 'translateX(-100%)' }, { transform: 'translateX(0)' } ], { duration: 300, easing: 'ease-out' }); } leave(element: Element): Animation { return element.animate([ { transform: 'translateX(0)' }, { transform: 'translateX(100%)' } ], { duration: 300, easing: 'ease-in' }); } } ``` ### Router Transition Animations ```typescript @route({ routes: [ { path: '/page1', component: () => import('./page1'), transitionPlan: { enter: 'slide-in-right', leave: 'slide-out-left' } } ] }) export class AppRoot {} ``` ### Programmatic Animations ```typescript export class MyComponent { async animateElement() { const element = document.querySelector('.my-element'); await element.animate([ { opacity: 0, transform: 'scale(0.5)' }, { opacity: 1, transform: 'scale(1)' } ], { duration: 500 }).finished; } } ``` ## UI Composition ### au-compose ```html

``` ### Programmatic Composition ```typescript import { ICompositionRoot } from '@aurelia/runtime-html'; export class MyComponent { constructor(private compositionRoot: ICompositionRoot = resolve(ICompositionRoot)) {} async composeComponent() { const composition = await this.compositionRoot.compose({ component: MyDynamicComponent, host: this.containerElement, model: { data: 'example' } }); return composition; } } ``` ## Synthetic Views ### Creating Synthetic Views ```typescript import { IViewFactory, IRenderLocation, ISyntheticView } from '@aurelia/runtime-html'; export class MyComponent { constructor( private viewFactory: IViewFactory = resolve(IViewFactory), private renderLocation: IRenderLocation = resolve(IRenderLocation) ) {} createView(): ISyntheticView { const view = this.viewFactory .create() .setLocation(this.renderLocation); view.activate(this, null); return view; } } ``` ### Template Controllers with Synthetic Views ```typescript import { templateController, IViewFactory, IRenderLocation } from '@aurelia/runtime-html'; @templateController('my-repeat') export class MyRepeat { items: any[] = []; constructor( private viewFactory: IViewFactory = resolve(IViewFactory), private renderLocation: IRenderLocation = resolve(IRenderLocation) ) {} itemsChanged() { // Create views for each item this.items.forEach(item => { const view = this.viewFactory.create().setLocation(this.renderLocation); view.activate(item, null); }); } } ``` ## Shadow DOM & Slots ### Shadow DOM Setup ```typescript @customElement({ name: 'my-card', template: `

Default Content

`, shadowOptions: { mode: 'open' } }) export class MyCard {} ``` ### Using Slots ```html

Custom Header

Custom content goes here

``` ### Replaceable Parts ```typescript @customElement({ name: 'data-table', template: `

${column.title}
${row[column.key]}

` }) export class DataTable { @bindable columns: Column[] = []; @bindable rows: any[] = []; } ``` ## UI Virtualization ### Virtual Repeat ```html

${item.name}

``` ### Virtual Repeat Configuration ```typescript export class VirtualList { items: any[] = []; // Configure virtual repeat virtualRepeatConfig = { itemHeight: 60, bufferSize: 10, scrollingEnabled: true }; } ``` ```html

${item.name}

``` ## Testing ### Component Testing ```typescript import { TestContext } from '@aurelia/testing'; import { MyComponent } from './my-component'; describe('MyComponent', () => { it('should render correctly', async () => { const { startPromise, tearDown, component } = TestContext.create( '', MyComponent, { name: 'Test' } ); await startPromise; expect(component.name).toBe('Test'); await tearDown(); }); }); ``` ### Integration Testing ```typescript import { TestContext } from '@aurelia/testing'; import { IRouter, IRouteContext } from '@aurelia/router'; import { AppRoot } from './app-root'; describe('App Integration', () => { it('should navigate between routes', async () => { const { startPromise, tearDown, app } = TestContext.create( '', AppRoot ); await startPromise; // Test navigation const router = app.container.get(IRouter); const routeContext = app.container.get(IRouteContext); await router.load('/products'); expect(router.isActive('/products', routeContext)).toBe(true); await tearDown(); }); }); ``` ## Internationalization (i18n) ### Basic Setup ```typescript import { I18N } from '@aurelia/i18n'; export class MyComponent { constructor(private i18n: I18N = resolve(I18N)) {} created() { this.i18n.setLocale('en'); } } ``` ### Template Usage ```html

${'hello' | t}

${'welcome' | t: { name: user.name }}

${date | df}

${amount | nf}

``` ### Programmatic Usage ```typescript export class MyComponent { constructor(private i18n: I18N = resolve(I18N)) {} getTranslation() { const message = this.i18n.tr('hello'); const parameterized = this.i18n.tr('welcome', { name: 'John' }); return { message, parameterized }; } changeLanguage(locale: string) { this.i18n.setLocale(locale); } } ``` ## State Management ### Observable State ```typescript import { observable } from '@aurelia/runtime'; export class AppState { @observable user: User | null = null; @observable isLoading: boolean = false; @observable items: Item[] = []; userChanged(newUser: User | null) { // React to user changes console.log('User changed:', newUser); } } ``` ### Store Pattern ```typescript import { resolve, IEventAggregator } from '@aurelia/kernel'; export class UserStore { private users: User[] = []; constructor(private eventAggregator: IEventAggregator = resolve(IEventAggregator)) {} async loadUsers() { this.users = await this.userService.getUsers(); this.eventAggregator.publish('users:loaded', this.users); } addUser(user: User) { this.users.push(user); this.eventAggregator.publish('user:added', user); } getUsers(): User[] { return [...this.users]; } } ``` ```typescript import { resolve, IEventAggregator } from '@aurelia/kernel'; export class UserList { users: User[] = []; constructor( private userStore: UserStore = resolve(UserStore), private eventAggregator: IEventAggregator = resolve(IEventAggregator) ) {} binding() { this.users = this.userStore.getUsers(); this.eventAggregator.subscribe('users:loaded', (users: User[]) => { this.users = users; }); } } ``` ## Dialog & Modal ### Dialog Setup ```typescript import { IDialogService } from '@aurelia/dialog'; export class MyComponent { constructor(private dialogService: IDialogService = resolve(IDialogService)) {} async openDialog() { const result = await this.dialogService.open({ component: () => import('./my-dialog'), model: { title: 'Confirm Action' } }); if (!result.wasCancelled) { console.log('Dialog result:', result.output); } } } ``` ### Dialog Component ```typescript import { IDialogController } from '@aurelia/dialog'; @customElement({ name: 'my-dialog', template: `

\${model.title}

Are you sure you want to continue?

` }) export class MyDialog { constructor(private controller: IDialogController = resolve(IDialogController)) {} activate(model: any) { this.model = model; } cancel() { this.controller.cancel(); } confirm() { this.controller.ok('confirmed'); } } ``` ## HTTP Client ### Basic Setup ```typescript import { resolve } from '@aurelia/kernel'; import { IHttpClient } from '@aurelia/fetch-client'; export class ApiService { constructor(private http: IHttpClient = resolve(IHttpClient)) {} async getUsers(): Promise { const response = await this.http.fetch('/api/users'); return response.json(); } async createUser(user: User): Promise { const response = await this.http.fetch('/api/users', { method: 'POST', body: JSON.stringify(user), headers: { 'Content-Type': 'application/json' } }); return response.json(); } } ``` ### Service Usage ```typescript export class UserManager { users: User[] = []; constructor(private apiService: ApiService = resolve(ApiService)) {} async loadUsers() { try { this.users = await this.apiService.getUsers(); } catch (error) { console.error('Failed to load users:', error); } } async addUser(userData: Partial) { try { const newUser = await this.apiService.createUser(userData as User); this.users.push(newUser); } catch (error) { console.error('Failed to create user:', error); } } } ``` ### HTTP Client Configuration ```typescript import { HttpClientConfiguration } from '@aurelia/fetch-client'; export const HttpConfig = { register(container: IContainer) { container.register( HttpClientConfiguration.customize(config => { config .useStandardConfiguration() .withBaseUrl('/api') .withDefaults({ headers: { 'Content-Type': 'application/json', 'Accept': 'application/json' } }) .withInterceptor({ request(request) { console.log('Request:', request); return request; }, response(response) { console.log('Response:', response); return response; } }); }) ); } }; ``` ## Integration (plugins, shared components, etc) ### Migrating from v1 One of the biggest differences compared to Aurelia v1 is the way integrations work. In v1, you would have a `configure` function like so: **index.ts** (producer) ```typescript export function configure(config: FrameworkConfiguration) { config.globalResources(['./my-component', './my-component-2']); } ``` Which would then be consumed as either a `plugin` or a `feature` like so: **main.ts** (consumer) #### consumer ```typescript aurelia.use.plugin('producer'); // or aurelia.use.feature('./producer'); ``` In v2 the string-based conventions are no longer a thing. We use native ES modules now. And there are no more different APIs for resources, plugins and features. Instead, everything is a dependency that can be registered to a container, its behavior may be altered by specific metadata that's added by framework decorators. The most literal translation from v1 to v2 of the above, would be as follows: **index.ts** (producer) ```typescript import { MyComponent } from './my-component'; import { MyComponent2 } from './my-component-2'; export const Producer = { register(container: IContainer) { container.register(MyComponent, MyComponent2); }, }; ``` **main.ts** (consumer) #### consumer ```typescript au.register(Producer); ``` ### The `register` method In Aurelia v2, everything (including the framework itself) is glued together via DI. The concept is largely the same whether you're building a plugin, a shared component or a service class. The producer (or the `export`ing side) exposes an object with a `register` method, and the consumer (the `import`ing side) passes that object into its `au.register` call (for global registration) or into the `dependencies` array of a custom element (for local registration). The DI container calls that `register` method and passes itself in as the only argument. The producer can then register resources / components / tasks to that container. Internally, things like resources and tasks have special metadata associated with them which allows the framework to discover and consume them at the appropriate times. Below are some examples of how integrations can be produced and consumed: #### 1.1 Simple object literal with a register method **index.ts** (producer) ```typescript export const MyPluginConfiguration = { register(container: IContainer) { container.register( ...PluginResources, ...PluginComponents, ); }, }; ``` **main.ts** (consumer) ```typescript import { Aurelia } from 'aurelia'; new Aurelia().register(MyPluginConfiguration).app(...); ``` #### 1.2 A function that returns an object literal with a register method (to pass in e.g. plugin options) **index.ts** (producer) ```typescript function configure(container: IContainer, config: MyPluginConfig) { switch (config.storageType) { case 'localStorage': container.register(LocalStorageProvider); break; case 'indexedDB': default: container.register(IndexedDBProvider); break; } } export const MyPluginConfiguration = { register(container: IContainer) { configure(container, MyPluginConfig.DEFAULT); }, customize(config: MyPluginConfig) { return { register(container: IContainer) { configure(container, config); }, }; }, }; ``` **main.ts** (consumer) ```typescript import { Aurelia } from 'aurelia'; new Aurelia().register(MyPluginConfiguration).app(...); // OR new Aurelia().register(MyPluginConfiguration.customize({ storageType: 'localStorage' })).app(...) ``` #### 1.3 An interface **index.ts** (producer) ```typescript export const IStorageClient = DI.createInterface('IStorageClient', x => x.singleton(LocalStorageClient)); ``` Interfaces and classes do not need to be registered explicitly. They can immediately be injected. The container will "jit register" them the first time they are requested. #### 1.4 A class (typically a resource) **index.ts** (producer) ```typescript @customElement({ name: 'name-tag', template: `\${name}` }) export class NameTag {} ``` **main.ts** (consumer) To register it as a global resource (available in all components) ```typescript import { Aurelia } from 'aurelia'; new Aurelia().register(NameTag).app(...); ``` OR: **name-list.ts** (consumer) To register it as a local resource (available only in that specific custom element) ```typescript export class NameListCustomElement { static dependencies = [NameTag]; } // OR @customElement({ ..., dependencies: [NameTag] }) export class NameListCustomElement {} ``` #### 1.5 A (module-like) object with any of the above as its properties **resources/index.ts** (producer) ```typescript export * from './my-button'; export * from './my-input'; export * from './my-nav'; ``` **main.ts** (consumer) ```typescript import { Aurelia } from 'aurelia'; import * as GlobalResources from './resources'; new Aurelia().register(GlobalResources).app(...); ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.aurelia.io/migrating-to-aurelia-2/cheat-sheet.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.