Skip to content

Commit fbe0b86

Browse files
machtymachty
authored
Add Glint / template import docs (#561)
* Add Glint / template import docs * fix typo
1 parent e48a7aa commit fbe0b86

File tree

5 files changed

+97
-40
lines changed

5 files changed

+97
-40
lines changed

‎packages/test-app/app/docs/controller.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ export const TABLE_OF_CONTENTS = [
2222
{ route: 'docs.derived-state', title: 'Derived State' },
2323
{ route: 'docs.events', title: 'Awaiting Events / Conditions' },
2424
{ route: 'docs.testing-debugging', title: 'Testing & Debugging' },
25-
{ route: 'docs.typescript', title: 'TypeScript' },
25+
{ route: 'docs.typescript', title: 'TypeScript / Glint' },
2626
{ route: 'docs.faq', title: 'FAQ & Fact Sheet' },
2727

2828
{ section: 'Advanced' },

‎packages/test-app/app/docs/installation/template.hbs

+7-1
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,6 @@
1414
<ul>
1515
<li>At least <code>ember-cli-babel@^7.7.2</code></li>
1616
<li>At least <code>@babel/core@^7.5.0</code> (as a transitive dependency via <code>ember-cli-babel</code>)</li>
17-
<li>At least <code>ember-cli-typescript@^2.0.0</code> and TypeScript 4.2+, if you want to use it with TypeScript</li>
1817
</ul>
1918
</p>
2019

@@ -29,3 +28,10 @@
2928

3029
<CodeSnippet @name="babel-transform-config.js" />
3130

31+
<h4>Typescript and Glint</h4>
32+
33+
<p>
34+
<LinkTo @route="docs.typescript">Typescript and Glint docs</LinkTo> for setting up / using
35+
Ember Concurency with TypeScript / Glint.
36+
</p>
37+

‎packages/test-app/app/docs/typescript/template.hbs

+46-38
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,66 @@
1-
<h3>Using ember-concurrency with TypeScript</h3>
1+
<h3>TypeScript and Glint</h3>
22

33
<p>
4-
The documentation below covers how to use ember-concurrency v2.3+
5-
with Ember Octane. For older versions of ember-concurrency (or pre-Octane Ember),
6-
<a href="https://v221.ember-concurrency.com/docs/typescript">please see the old guides</a>.
7-
</p>
8-
9-
<p>
10-
ember-concurrency tasks play nicely with TypeScript and all of the APIs covered in these docs.
11-
Here is an example of a TypeScript component with an ember-concurrency task:
4+
Ember Concurrency tasks play nicely with TypeScript and all of the APIs
5+
covered in these docs. Here is an example of a TypeScript component with an
6+
ember-concurrency task:
127
</p>
138

149
<CodeSnippet @name="ts/basic-example.ts" />
1510

16-
<h4>Typing <code>Task</code> objects</h4>
11+
<h4>Glint Template Registry</h4>
1712

1813
<p>
19-
In most cases, you don't need to provide type annotations for your task, but when you do
20-
(such as when <a href="https://docs.ember-cli-typescript.com/ember/components?q=component#giving-args-a-type">
21-
specifying the Args of a Glimmer component</a>), you can use the Task type:
14+
Ember Concurrency provides a template registry for using the
15+
<code>perform</code>,
16+
<code>cancel-all</code>, and
17+
<code>task</code>
18+
helpers within handlebars templates in Glint "loose mode". See the example
19+
below for how to include Ember Concurrency's template registry in your Glint
20+
configuration.
2221
</p>
2322

24-
<CodeSnippet @name="ts/typing-task.ts" />
23+
<CodeSnippet @name="ts/template-registry-example.ts" />
2524

26-
<h4>Version 2.2 and older</h4>
25+
<h4>Ember Template Imports (.gts/.gts) Files</h4>
2726

2827
<p>
29-
Support for TypeScript in ember-concurrency was recently greatly improved and simplified
30-
with the release of version 2.3, largely due to the introduction of the new
31-
async arrow task function syntax (e.g. <code>myTask = task(async () => {})</code>),
32-
which alleviated most / all of the prior challenges with getting ember-concurrency tasks
33-
to play nicely with TypeScript.
28+
Here is an example of a modern .gts file in "strict mode" which imports the
29+
classic
30+
<code>perform</code>
31+
helper from Ember Concurrency.
3432
</p>
3533

36-
<ul>
37-
<li>
38-
<strong>
39-
<a href="https://github.com/chancancode/ember-concurrency-async">ember-concurrency-async</a>
40-
</strong>
41-
is no longer necessary
42-
</li>
43-
<li>
44-
<strong>
45-
<a href="https://github.com/chancancode/ember-concurrency-ts">ember-concurrency-ts</a>
46-
</strong>
47-
and the <code>taskFor()</code> function it provides is no longer necessary
48-
for interacting with tasks declared using the new syntax. See <a href="https://github.com/machty/ember-concurrency/releases/tag/2.3.0">v2.3.0</a> and <a href="https://github.com/machty/ember-concurrency/releases/tag/2.3.2">v2.3.2</a> release notes.
49-
</li>
50-
</ul>
34+
<p>
35+
Note: while you can import and use the
36+
<code>perform</code>
37+
helper, it is actually recommended to use the
38+
<code>.perform()</code>
39+
method on each task, which is internally bound to the task (similar to methods
40+
decorated with
41+
<code>@action</code>). One of the benefits of using the
42+
<code>.perform()</code>
43+
method is that it can be used with modern idiomatic patterns like using the
44+
<code>fn</code>
45+
helper to curry additional args when performing the task.
46+
</p>
5147

5248
<p>
53-
If you would like to see the TypeScript guides for older versions of ember-concurrency
54-
(or pre-Octane Ember), please
55-
<a href="https://v221.ember-concurrency.com/docs/typescript">see the old guides</a>.
49+
<em>Pardon the lack of syntax! PR's welcome to improve our syntax
50+
highlighting!</em>
5651
</p>
5752

53+
<CodeSnippet @name="ts/template-import-example.txt" />
54+
55+
<h4>Typing <code>Task</code> objects</h4>
56+
57+
<p>
58+
In most cases, you don't need to provide type annotations for your task, but
59+
when you do (such as when
60+
<a
61+
href="https://docs.ember-cli-typescript.com/ember/components?q=component#giving-args-a-type"
62+
>
63+
specifying the Args of a Glimmer component</a>), you can use the Task type:
64+
</p>
5865

66+
<CodeSnippet @name="ts/typing-task.ts" />

‎packages/test-app/snippets/ts/template-import-example.txt

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
import GlimmerComponent from "@glimmer/component";
2+
import { task } from "ember-concurrency";
3+
import perform from "ember-concurrency/helpers/perform";
4+
import { on } from "@ember/modifier";
5+
import { fn } from "@ember/helper";
6+
7+
export default class Demo extends GlimmerComponent {
8+
taskNoArgs = task(async () => {
9+
console.log("Look ma, no args!");
10+
});
11+
12+
taskWithArgs = task(async (value: string) => {
13+
console.log(value);
14+
});
15+
16+
<template>
17+
<button type="button" {{on "click" this.taskNoArgs.perform}}>
18+
Task with no Params (.perform method) (RECOMMENDED)
19+
</button>
20+
21+
<button type="button" {{on "click" (perform this.taskNoArgs)}}>
22+
Task with no Params (with classic perform helper)
23+
</button>
24+
25+
<button type="button" {{on "click" (fn this.taskNoArgs.perform '123')}}>
26+
Task with Params (currying with fn helper) (RECOMMENDED)
27+
</button>
28+
29+
<button type="button" {{on "click" (perform this.taskWithArgs '123')}}>
30+
Task with Params (currying with classic perform helper)
31+
</button>
32+
</template>
33+
}

‎packages/test-app/snippets/ts/template-registry-example.ts

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
// e.g. types/glint.d.ts
2+
import '@glint/environment-ember-loose';
3+
import type EmberConcurrencyRegistry from 'ember-concurrency/template-registry';
4+
5+
declare module '@glint/environment-ember-loose/registry' {
6+
export default interface Registry
7+
extends EmberConcurrencyRegistry /* other addon registries */ {
8+
// local entries
9+
}
10+
}

0 commit comments

Comments
 (0)