Page Menu
Home
Phorge
Search
Configure Global Search
Log In
Files
F2503904
D25822.1726849440.diff
No One
Temporary
Actions
View File
Edit File
Delete File
View Transforms
Subscribe
Award Token
Flag For Later
Advanced/Developer...
View Handle
View Hovercard
Size
6 KB
Referenced Files
None
Subscribers
None
D25822.1726849440.diff
View Options
diff --git a/webroot/rsrc/externals/javelin/docs/concepts/behaviors.diviner b/webroot/rsrc/externals/javelin/docs/concepts/behaviors.diviner
--- a/webroot/rsrc/externals/javelin/docs/concepts/behaviors.diviner
+++ b/webroot/rsrc/externals/javelin/docs/concepts/behaviors.diviner
@@ -84,7 +84,7 @@
Another way to think about them is that you are defining methods which represent
the entirety of the API exposed by the document. The recommended approach to
-glue code is that the server interact with Javascript on the client //only// by
+glue code is that the server interact with JavaScript on the client //only// by
invoking behaviors, so the set of available behaviors represent the complete set
of legal interactions available to the server.
@@ -152,7 +152,7 @@
Javelin behaviors provide a more structured solution to some of these problems:
- - All your Javascript code is in Javascript files, not embedded in strings in
+ - All your JavaScript code is in JavaScript files, not embedded in strings in
in some host language on the server side.
- You can use static analysis and minification tools normally.
- Provided you use a reasonable server-side library, you can't get escaping
diff --git a/webroot/rsrc/externals/javelin/docs/javelin.book b/webroot/rsrc/externals/javelin/docs/javelin.book
--- a/webroot/rsrc/externals/javelin/docs/javelin.book
+++ b/webroot/rsrc/externals/javelin/docs/javelin.book
@@ -2,13 +2,16 @@
"name" : "javelin",
"title" : "Javelin Documentation",
"short" : "Javelin Docs",
- "preface" : "Documentation for developers using Javelin.",
+ "preface" : "Documentation for JavaScript developers using Javelin.",
"uri.source":
"https://we.phorge.it/diffusion/P/browse/master/%f$%l",
"rules": {
"(\\.diviner$)": "DivinerArticleAtomizer"
},
"groups": {
+ "introduction": {
+ "name": "Introduction"
+ },
"concepts": {
"name": "Concepts"
}
diff --git a/webroot/rsrc/externals/javelin/docs/javelin_intro.diviner b/webroot/rsrc/externals/javelin/docs/javelin_intro.diviner
new file mode 100644
--- /dev/null
+++ b/webroot/rsrc/externals/javelin/docs/javelin_intro.diviner
@@ -0,0 +1,139 @@
+@title Javelin Introduction
+@group introduction
+
+Explore the Javelin framework to make your frontend "go brrrrr".
+
+= Preamble =
+
+As you know, Phorge is the fork of Phabricator. But, you may not know
+that Phabricator was designed with a particular Open Source JavaScript
+library called **Javelin**.
+
+So, why I should master Javelin?
+
+The Javelin APIs are un-documented, un-intuitive, and esoteric,
+and you may prefer X / Y / Z framework instead.
+But hey: Javelin will //not// be abandoned anytime soon.
+Give Javelin a try, so you can make Phorge even better.
+
+Some advantages of Javelin:
+
+- Javelin encourages strong separation between CSS selectors and
+ business logic selectors
+- Javelin un-minified is more lightweight than jQuery minified
+- it starts with "Jav" like "JavaScript" so it's easy
+
+= Concepts: DOM Traversing with Sigils =
+
+Traversing the DOM using Javelin is simple... as long as
+you know what a "sigil" is. In fact, Javelin is designed to avoid
+finding something by CSS classes. Instead, Javelin introduced
+"sigils" - that is, exactly like a CSS class but vegan (?).
+
+So, pretend you don't know what a CSS class is, and explore
+this related reading about sigils, and how to store data in
+elements marked with a sigil:
+
+@{article:Concepts: Sigils and Metadata}.
+
+The source code of the DOM utilities of Javelin is here:
+
+https://we.phorge.it/source/phorge/browse/master/webroot/rsrc/externals/javelin/lib/DOM.js
+
+== Find Element by ID with `$` ==
+
+The `$` Javelin method finds exactly one HTML element by its id. Definition:
+
+```javascript
+function X.$(id: string): Element
+```
+
+Example usage:
+
+```javascript
+var elementById = JX.$('my-id');
+```
+
+As you can imagine, this method is just a shorter version for the native
+[[ https://developer.mozilla.org/en-US/docs/Web/API/Document/getElementById | document.getElementById() ]].
+
+Please remember to write `'id'` and not `'#id'`.
+
+Comparison table from other frameworks:
+
+| | From Code | To Javelin |
+|-----------------|---------------|-----------------|
+| **From jQuery** | `$('#my-id')` | `JX.$('my-id')` |
+
+== Look Down for Multiple Elements with `scry` ==
+
+The `scry` Javelin method looks down for multiple HTML elements by sigil.
+Definition:
+
+```javascript
+function JX.DOM.scry(parent: Element, tagName: string, sigil: string): Element[]
+```
+
+Example usage:
+
+```javascript
+var elementsWithSigil = JX.DOM.scry(document.body, '*', 'my-sigil');
+```
+
+The method requires a starting element to descend from and
+it returns an array of elements at any child depth, that have
+the specified sigil __and__ the specified tag name. Few tips:
+
+- if you don't want to specify a tag name, set "`*`" as tag name
+- if you specify a tagname like "`a`", it may be faster
+
+Comparison table from other frameworks:
+
+| | From Code | To Javelin |
+|-----------------|---------------------------------|------------------------------------------|
+| **From jQuery** | `$(parent).find('.class-name')` | `JX.DOM.scry(parent, '*', 'sigil-name')` |
+
+== Look Down for One Element with `find` ==
+
+The `find` Javelin method looks down for exactly one element by sigil.
+Definition:
+
+```javascript
+function JX.DOM.find(root: Element, tagName: string, sigil: string): Element
+```
+
+Example usage:
+
+```javascript
+var child = JX.DOM.find(document.body, '*', 'my-sigil');
+```
+
+As you can imagine, the method `find` is just a particular case of the method `scry`,
+to be sure that you return exactly one element.
+
+Comparison table from other frameworks:
+
+| | From Code | To Javelin |
+|-----------------|------------------------------------|------------------------------------------|
+| **From jQuery** | `$(parent).find('.class-name')[0]` | `JX.DOM.find(parent, '*', 'sigil-name')` |
+
+== Look Up for One Element with `findAbove` ==
+
+The `findAbove` Javelin method looks up for exactly one HMTL element by sigil.
+Definition:
+
+```javascript
+function JX.DOM.findAbove(anchor: Element, tagName: string, sigil: string): Element
+```
+
+Example usage:
+
+```javascript
+var parent = JX.DOM.findAbove(child, '*', 'my-sigil');
+```
+
+Comparison table from other frameworks:
+
+| | From Code | To Javelin |
+|-----------------|---------------------------------------|-----------------------------------------------|
+| **From jQuery** | `$(anchor).closest('.class-name')[0]` | `JX.DOM.findAbove(anchor, '*', 'sigil-name')` |
File Metadata
Details
Attached
Mime Type
text/plain
Expires
Fri, Sep 20, 16:24 (18 h, 44 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
889727
Default Alt Text
D25822.1726849440.diff (6 KB)
Attached To
Mode
D25822: Documentation: add article about Javelin DOM stuff
Attached
Detach File
Event Timeline
Log In to Comment