@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
Documentation: add article about Javelin DOM stuff
Summary:
Finally we know something about:
- how to get an element by id ($)
- how to find some children by a parent (scry)
- how to find an exact child by a parent (find)
- how to find a parent by a child (findAbove)
Closes T15870
Test Plan:
You read this article and you find something interesting and
probably also accurate.
Reviewers: O1 Blessed Committers, aklapper
Reviewed By: O1 Blessed Committers, aklapper
Subscribers: aklapper, tobiaswiese, Matthew, Cigaryno
Maniphest Tasks: T15870
Differential Revision: https://we.phorge.it/D25822
+145
-3
+2
-2
webroot/rsrc/externals/javelin/docs/concepts/behaviors.diviner
+2
-2
webroot/rsrc/externals/javelin/docs/concepts/behaviors.diviner
···
84
84
85
85
Another way to think about them is that you are defining methods which represent
86
86
the entirety of the API exposed by the document. The recommended approach to
87
-
glue code is that the server interact with Javascript on the client //only// by
87
+
glue code is that the server interact with JavaScript on the client //only// by
88
88
invoking behaviors, so the set of available behaviors represent the complete set
89
89
of legal interactions available to the server.
90
90
···
152
152
153
153
Javelin behaviors provide a more structured solution to some of these problems:
154
154
155
-
- All your Javascript code is in Javascript files, not embedded in strings in
155
+
- All your JavaScript code is in JavaScript files, not embedded in strings in
156
156
in some host language on the server side.
157
157
- You can use static analysis and minification tools normally.
158
158
- Provided you use a reasonable server-side library, you can't get escaping
+4
-1
webroot/rsrc/externals/javelin/docs/javelin.book
+4
-1
webroot/rsrc/externals/javelin/docs/javelin.book
···
2
2
"name" : "javelin",
3
3
"title" : "Javelin Documentation",
4
4
"short" : "Javelin Docs",
5
-
"preface" : "Documentation for developers using Javelin.",
5
+
"preface" : "Documentation for JavaScript developers using Javelin.",
6
6
"uri.source":
7
7
"https://we.phorge.it/diffusion/P/browse/master/%f$%l",
8
8
"rules": {
9
9
"(\\.diviner$)": "DivinerArticleAtomizer"
10
10
},
11
11
"groups": {
12
+
"introduction": {
13
+
"name": "Introduction"
14
+
},
12
15
"concepts": {
13
16
"name": "Concepts"
14
17
}
+139
webroot/rsrc/externals/javelin/docs/javelin_intro.diviner
+139
webroot/rsrc/externals/javelin/docs/javelin_intro.diviner
···
1
+
@title Javelin Introduction
2
+
@group introduction
3
+
4
+
Explore the Javelin framework to make your frontend "go brrrrr".
5
+
6
+
= Preamble =
7
+
8
+
As you know, Phorge is the fork of Phabricator. But, you may not know
9
+
that Phabricator was designed with a particular Open Source JavaScript
10
+
library called **Javelin**.
11
+
12
+
So, why I should master Javelin?
13
+
14
+
The Javelin APIs are un-documented, un-intuitive, and esoteric,
15
+
and you may prefer X / Y / Z framework instead.
16
+
But hey: Javelin will //not// be abandoned anytime soon.
17
+
Give Javelin a try, so you can make Phorge even better.
18
+
19
+
Some advantages of Javelin:
20
+
21
+
- Javelin encourages strong separation between CSS selectors and
22
+
business logic selectors
23
+
- Javelin un-minified is more lightweight than jQuery minified
24
+
- it starts with "Jav" like "JavaScript" so it's easy
25
+
26
+
= Concepts: DOM Traversing with Sigils =
27
+
28
+
Traversing the DOM using Javelin is simple... as long as
29
+
you know what a "sigil" is. In fact, Javelin is designed to avoid
30
+
finding something by CSS classes. Instead, Javelin introduced
31
+
"sigils" - that is, exactly like a CSS class but vegan (?).
32
+
33
+
So, pretend you don't know what a CSS class is, and explore
34
+
this related reading about sigils, and how to store data in
35
+
elements marked with a sigil:
36
+
37
+
@{article:Concepts: Sigils and Metadata}.
38
+
39
+
The source code of the DOM utilities of Javelin is here:
40
+
41
+
https://we.phorge.it/source/phorge/browse/master/webroot/rsrc/externals/javelin/lib/DOM.js
42
+
43
+
== Find Element by ID with `$` ==
44
+
45
+
The `$` Javelin method finds exactly one HTML element by its id. Definition:
46
+
47
+
```javascript
48
+
function X.$(id: string): Element
49
+
```
50
+
51
+
Example usage:
52
+
53
+
```javascript
54
+
var elementById = JX.$('my-id');
55
+
```
56
+
57
+
As you can imagine, this method is just a shorter version for the native
58
+
[[ https://developer.mozilla.org/en-US/docs/Web/API/Document/getElementById | document.getElementById() ]].
59
+
60
+
Please remember to write `'id'` and not `'#id'`.
61
+
62
+
Comparison table from other frameworks:
63
+
64
+
| | From Code | To Javelin |
65
+
|-----------------|---------------|-----------------|
66
+
| **From jQuery** | `$('#my-id')` | `JX.$('my-id')` |
67
+
68
+
== Look Down for Multiple Elements with `scry` ==
69
+
70
+
The `scry` Javelin method looks down for multiple HTML elements by sigil.
71
+
Definition:
72
+
73
+
```javascript
74
+
function JX.DOM.scry(parent: Element, tagName: string, sigil: string): Element[]
75
+
```
76
+
77
+
Example usage:
78
+
79
+
```javascript
80
+
var elementsWithSigil = JX.DOM.scry(document.body, '*', 'my-sigil');
81
+
```
82
+
83
+
The method requires a starting element to descend from and
84
+
it returns an array of elements at any child depth, that have
85
+
the specified sigil __and__ the specified tag name. Few tips:
86
+
87
+
- if you don't want to specify a tag name, set "`*`" as tag name
88
+
- if you specify a tagname like "`a`", it may be faster
89
+
90
+
Comparison table from other frameworks:
91
+
92
+
| | From Code | To Javelin |
93
+
|-----------------|---------------------------------|------------------------------------------|
94
+
| **From jQuery** | `$(parent).find('.class-name')` | `JX.DOM.scry(parent, '*', 'sigil-name')` |
95
+
96
+
== Look Down for One Element with `find` ==
97
+
98
+
The `find` Javelin method looks down for exactly one element by sigil.
99
+
Definition:
100
+
101
+
```javascript
102
+
function JX.DOM.find(root: Element, tagName: string, sigil: string): Element
103
+
```
104
+
105
+
Example usage:
106
+
107
+
```javascript
108
+
var child = JX.DOM.find(document.body, '*', 'my-sigil');
109
+
```
110
+
111
+
As you can imagine, the method `find` is just a particular case of the method `scry`,
112
+
to be sure that you return exactly one element.
113
+
114
+
Comparison table from other frameworks:
115
+
116
+
| | From Code | To Javelin |
117
+
|-----------------|------------------------------------|------------------------------------------|
118
+
| **From jQuery** | `$(parent).find('.class-name')[0]` | `JX.DOM.find(parent, '*', 'sigil-name')` |
119
+
120
+
== Look Up for One Element with `findAbove` ==
121
+
122
+
The `findAbove` Javelin method looks up for exactly one HMTL element by sigil.
123
+
Definition:
124
+
125
+
```javascript
126
+
function JX.DOM.findAbove(anchor: Element, tagName: string, sigil: string): Element
127
+
```
128
+
129
+
Example usage:
130
+
131
+
```javascript
132
+
var parent = JX.DOM.findAbove(child, '*', 'my-sigil');
133
+
```
134
+
135
+
Comparison table from other frameworks:
136
+
137
+
| | From Code | To Javelin |
138
+
|-----------------|---------------------------------------|-----------------------------------------------|
139
+
| **From jQuery** | `$(anchor).closest('.class-name')[0]` | `JX.DOM.findAbove(anchor, '*', 'sigil-name')` |