Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/buschtoens/ember-link
Link primitive to pass around self-contained route references. It's {{link-to}}, but better!
https://github.com/buschtoens/ember-link
ember ember-addon ember-routing emberjs
Last synced: 3 days ago
JSON representation
Link primitive to pass around self-contained route references. It's {{link-to}}, but better!
- Host: GitHub
- URL: https://github.com/buschtoens/ember-link
- Owner: buschtoens
- License: other
- Created: 2019-03-11T14:32:22.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2024-09-24T06:32:21.000Z (9 days ago)
- Last Synced: 2024-09-25T20:21:25.376Z (8 days ago)
- Topics: ember, ember-addon, ember-routing, emberjs
- Language: TypeScript
- Homepage: https://buschtoens.github.io/ember-link/
- Size: 4.69 MB
- Stars: 54
- Watchers: 5
- Forks: 12
- Open Issues: 28
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
# ember-link
[](https://github.com/buschtoens/ember-link/actions)
[](http://badge.fury.io/js/ember-link)
[](http://badge.fury.io/js/ember-link)
[](https://emberobserver.com/addons/ember-link)
Introduces a new `Link` primitive to pass around self-contained references to
routes, like URLs, but with state (`isActive`, ...) and methods (`open`,
...). Also brings along an accompanying template helper for easy
usage in templates.
> `ember-link` does to routing what `ember-concurrency` did to asynchrony!
— [/r/whatjawsdid](https://www.reddit.com/r/whatjawsdid/)
## Installation
Install `ember-link` with:
```sh
ember install ember-link
```
## Usage
You can use `ember-link` in a declarative form with a [`(link)`
helper](https://buschtoens.github.io/ember-link/helper.html) or imperatively with the [`LinkManager`
Service](https://buschtoens.github.io/ember-link/service.html).
### `(link)` Helper Example
Use the `(link)` helper to create a link primitive and attach it to an element.
```hbs
{{#let (link "about") as |l|}}
About us
{{/let}}
```
### `LinkManager` Service Example
Use the `LinkManager.createLink()` method to create a link programmatically.
```ts
import Contoller from '@ember/controller';
import { service } from '@ember/service';
import type { LinkManagerService } from 'ember-link';
export default class PageHeader extends Controller {
@service declare linkManager: LinkManagerService;
aboutUsLink = this.linkManager.createLink('about');
}
```
### Working with Primitives
The idea of `ember-link` is to be able to create link primitives, that you can
pass around. Create links at route level and then pass them into components.
A more in-depth guide is available at [using primitives](https://buschtoens.github.io/ember-link/using-primitives.html).
## Testing
[ember-link has testing support](https://buschtoens.github.io/ember-link/testing.html) on board, preparing the environment with
`setupLink()` and `linkFor()` to create a link to a route on the fly:
```ts
import { click, render } from '@ember/test-helpers';
import { hbs } from 'ember-cli-htmlbars';
import { module, test } from 'qunit';
import { setupRenderingTest } from 'ember-qunit';
import { linkFor, setupLink } from 'ember-link/test-support';
import type { TestContext as BaseTestContext } from '@ember/test-helpers';
import type { TestLink } from 'ember-link/test-support';
interface TestContext extends BaseTestContext {
link: TestLink;
}
module('`setupLink` example', function (hooks) {
setupRenderingTest(hooks);
setupLink(hooks);
test('using link in render tests', async function (this: TestContext, assert) {
// arrange
this.link = linkFor('some.route');
this.link.onTransitionTo = () => assert.step('link clicked');
await render(hbs`
{{#let this.link as |l|}}
Click me
{{/let}}
`);
// act
await click('a');
// assert
assert.verifySteps(['link clicked']);
});
});
```
## Related RFCs / Projects
- [`ember-engines-router-service`](https://github.com/villander/ember-engines-router-service):
Allows you to use `ember-link` inside engines
- [`ember-router-helpers`](https://github.com/rwjblue/ember-router-helpers)
- [RFC 391 "Router Helpers"](https://github.com/emberjs/rfcs/blob/master/text/0391-router-helpers.md)
- [RFC 339 "Router link component and routing helpers"](https://github.com/emberjs/rfcs/pull/339)
- [RFC 459 "Angle Bracket Invocations For Built-in Components"](https://github.com/emberjs/rfcs/blob/angle-built-ins/text/0459-angle-bracket-built-in-components.md#linkto)