Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs update #242

Draft
wants to merge 4 commits into
base: v2
Choose a base branch
from
Draft

Docs update #242

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
33fe6af
[docs update] Replace var with let
DmitrySharabin Jun 25, 2021
be83a1e
[docs update] Remove deprecated $.clone()
DmitrySharabin Jun 25, 2021
8918907
[docs update] $()
DmitrySharabin Jun 25, 2021
660a43b
[docs update] $$()
DmitrySharabin Jun 25, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
125 changes: 45 additions & 80 deletions docs.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ <h1>Overview</h1>

<p>Bliss includes several static methods (on the <code>Bliss</code> or <code>$</code> object). For example, to copy all properties of an object onto another object, you would call <a href="$.extend"><code>$.extend()</code></a>:</p>

<pre><code>var yolo = $.extend({foo: 1}, {bar: 2}); // or Bliss.extend(…)
<pre><code>let yolo = $.extend({foo: 1}, {bar: 2}); // or Bliss.extend(…)
// yolo is {foo: 1, bar: 2}</code></pre>

<p>Many of Bliss’ methods take an element or an array of elements as their first argument. For example, to set both the <code>width</code> and <code>padding</code> of an element to 0, you could use the <a href="#$.style"><code>$.style()</code></a> method:</p>
Expand Down Expand Up @@ -206,7 +206,7 @@ <h1 class="transform-ignore">$()</h1>

<p class="description">Select an element by selector. Mainly a shortcut for <code>element.querySelector()</code>.</p>

<pre><code>var element = $(selector [, context])</code></pre>
<pre><code>let element = $(selector [, context])</code></pre>

<dl class="args">
<dt class="string">selector</dt>
Expand All @@ -219,32 +219,30 @@ <h1 class="transform-ignore">$()</h1>
<dd>The matched element or <code>null</code> if none found.</dd>
</dl>

<pre class="examples"><code>// return the first element with a class of .foo
<pre class="examples"><code>// Return the first element with a class of .foo
// that is inside the first element with a class of .bar
var ret = $(".foo", $(".bar"));</code></pre>
let ret = $(".foo", $(".bar"));</code></pre>

<pre><code>// Return the first element with a class of .foo
// that is inside any element with a class of .bar
var ret = $(".bar .foo");</code></pre>
let ret = $(".bar .foo");</code></pre>

<pre><code>// Get the first element with a class of .foo
// and set its title attribute to "yolo"
// and set its title attribute to "yolo".
// If there is no such element, this will throw an exception!
$(".foo").setAttribute("title", "yolo");</code></pre>

<ul class="notes">
<li>If the element is not found, it will return <code>null</code>. This could cause an exception if methods are called on the result.
You might previously check if the element exists by caching the node in a variable
into an <code>if</code> statement:</li>
into an <code>if</code> statement or use the optional chaining operator <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining"><code>?.</code></a>
(for supporting browsers):</li>
</ul>

<pre><code>// Check if the .foo element exists
// and set an attribute by using a variable "foo"
// as a reference of the element
var foo = $(".foo");
if (foo) {
foo.setAttribute("title", "yolo");
}</code></pre>
<pre><code>// Get the first element with a class of .foo
// and, if it exists, set its title attribute to "yolo".
// If there is no such element, this will return "undefined"
$(".foo")?.setAttribute("title", "yolo");</code></pre>

<a href="http://api.jquery.com/jQuery/#jQuery1" class="jq">$</a>
</article>
Expand All @@ -254,7 +252,7 @@ <h1 class="transform-ignore">$$()</h1>

<p class="description">Get all elements that match a given selector as an array. Similar to <code>element.querySelectorAll()</code> but returns an Array instead of a NodeList, so it has all of the convenience methods we’ve come to love on arrays.</p>

<pre><code>var array = $$(selector [, context])</code></pre>
<pre><code>let array = $$(selector [, context])</code></pre>

<dl class="args">
<dt class="string">selector</dt>
Expand All @@ -267,7 +265,7 @@ <h1 class="transform-ignore">$$()</h1>
<dd>The matched elements as an array.</dd>
</dl>

<pre class="def"><code>var array = $$(collection)</code></pre>
<pre class="def"><code>let array = $$(collection)</code></pre>

<dl class="args">
<dt>collection</dt>
Expand All @@ -279,27 +277,23 @@ <h1 class="transform-ignore">$$()</h1>
</dl>

<pre class="examples"><code>// Add an id to all &lt;h1> headings that don’t already have one
$$("h1:not([id])").forEach(function(h1){
h1.id = h1.textContent.replace(/\W/g, "");
});</code></pre>
$$("h1:not([id])").forEach(h1 =>
h1.id = h1.textContent.replace(/\W/g, "")
);</code></pre>
<pre><code>// Get an array with all ids on the page
var ids = $$("[id]").map(function(element){
return element.id;
});</code></pre>
let ids = $$("[id]").map(element => element.id);</code></pre>
<pre><code>// Get all of an element’s attributes starting with data-bliss-
$$(element.attributes).filter(function(attribute){
return attribute.name.indexOf("data-bliss-") === 0;
}).map(function(attribute){
return attribute.name;
});</code></pre>
$$(element.attributes)
.filter(attribute => attribute.name.startsWith("data-bliss-"))
.map(attribute => attribute.name);</code></pre>
</article>

<article>
<h1>create</h1>

<p class="description">Create an element.</p>

<pre><code>var element = $.create([tag,] [options]);</code></pre>
<pre><code>let element = $.create([tag,] [options]);</code></pre>

<dl class="args">
<dt class="string">tag</dt>
Expand Down Expand Up @@ -331,9 +325,9 @@ <h1>create</h1>
]
});</code></pre>

<pre><code>var paragraph = $.create("p");</code></pre>
<pre><code>let paragraph = $.create("p");</code></pre>

<pre><code>var div = $.create();</code></pre>
<pre><code>let div = $.create();</code></pre>

<ul class="notes">
<li>If you’re only creating an element without setting any options on it, just use the native <code>document.createElement(tag)</code></li>
Expand Down Expand Up @@ -445,35 +439,6 @@ <h1 class="element array set">contents</h1>
<a class="jq">jQuery.fn.html</a>
</article>

<article class="full">
<h1 class="element full">clone</h1>

<p class="description">Clone an element including its descendants, with events and data. <strong>This function is deprecated and will be removed in the next version of Bliss</strong></p>

<pre><code>var clone = $.clone(subject)</code></pre>
<pre><code>var clone = subject._.clone()</code></pre>

<dl class="args">
<dt class="element">subject</dt>
<dd>The element to be cloned.</dd>

<dt class="element">clone</dt>
<dd>The cloned element.</dd>
</dl>

<pre><code>var button = $("button");
button.addEventListener("click", function() { console.log("Click from listener!"); });
button.onclick = function() { console.log("Click from inline event!"); };
var button2 = button._.clone();
// If clicked, button2 will print both messages</code></pre>

<ul class="notes">
<li>If you don’t care about copying events and data, just use the native <a href="https://developer.mozilla.org/en-US/docs/Web/API/Node/cloneNode"><code>element.cloneNode()</code></a></li>
</ul>

<a class="jq">jQuery.fn.clone</a>
</article>

<article>
<h1 class="element array set">after</h1>

Expand Down Expand Up @@ -687,8 +652,8 @@ <h1 class="element">transition</h1>

<p class="description">Set multiple CSS properties with a transition and execute code after the transition is finished.</p>

<pre><code>var promise = $.transition(subject, properties [, duration])</code></pre>
<pre><code>var promise = subject._.transition(properties [, duration])</code></pre>
<pre><code>let promise = $.transition(subject, properties [, duration])</code></pre>
<pre><code>let promise = subject._.transition(properties [, duration])</code></pre>

<dl class="args">
<dt class="element array">subject</dt>
Expand Down Expand Up @@ -985,7 +950,7 @@ <h1>ready</h1>

<p class="description">Execute code after the DOM is ready.</p>

<pre><code>var promise = $.ready([context], [callback])</code></pre>
<pre><code>let promise = $.ready([context], [callback])</code></pre>

<dl class="args">
<dt class="document">context</dt>
Expand All @@ -1011,8 +976,8 @@ <h1 class="element">when</h1>

<p class="description">Defer code until an event fires.</p>

<pre><code>var promise = $.when(subject, type [, test])</code></pre>
<pre><code>var promise = subject._.when(type [, test])</code></pre>
<pre><code>let promise = $.when(subject, type [, test])</code></pre>
<pre><code>let promise = subject._.when(type [, test])</code></pre>

<dl class="args">
<dt class="element">subject</dt>
Expand Down Expand Up @@ -1046,8 +1011,8 @@ <h1 class="array">all</h1>

<p class="description">Run a method on all elements of an array, get the results as an array.</p>

<pre><code>var ret = $.all(array, method [, args...])</code></pre>
<pre><code>var ret = array._.all(method [, args...])</code></pre>
<pre><code>let ret = $.all(array, method [, args...])</code></pre>
<pre><code>let ret = array._.all(method [, args...])</code></pre>

<dl class="args">
<dt class="array">array</dt>
Expand Down Expand Up @@ -1078,7 +1043,7 @@ <h1>Class</h1>

<p class="description">Helper for defining OOP-like “classes”, for those who have been irreparably damaged by Java-like languages.</p>

<pre><code>var myClass = $.Class(options);</code></pre>
<pre><code>let myClass = $.Class(options);</code></pre>

<dl class="args">
<dt class="object">options</dt>
Expand Down Expand Up @@ -1118,7 +1083,7 @@ <h1>each</h1>

<p class="description">Loop over properties of an object and map them onto another object.</p>

<pre><code>var ret = $.each(obj, callback [, ret]);</code></pre>
<pre><code>let ret = $.each(obj, callback [, ret]);</code></pre>

<dl class="args">
<dt class="object">obj</dt>
Expand Down Expand Up @@ -1154,11 +1119,11 @@ <h1>extend</h1>
<dd>If array or string, a whitelist of property names. If function, it is called on each property and only the properties it returns a truthy value on will be copied. If it’s a regular expression, only matching property names will be copied.</dd>
</dl>

<pre><code>var o1 = {foo: 1, bar:2}
<pre><code>let o1 = {foo: 1, bar:2}
o2 = $.extend(o1, {foo: 3, baz: 4});
// o2 is {foo: 3, bar: 2, baz: 4}</code></pre>
<pre><code>// Get typography-related computed style on &lt;body>
var type = $.extend({},
let type = $.extend({},
getComputedStyle(document.body),
/^font|^lineHeight$/);</code></pre>

Expand Down Expand Up @@ -1235,7 +1200,7 @@ <h1>type</h1>

<p class="description">Determine the internal JavaScript [[Class]] of an object.</p>

<pre><code>var type = $.type(object)</code></pre>
<pre><code>let type = $.type(object)</code></pre>

<dl class="args">
<dt class="object">object</dt>
Expand All @@ -1256,7 +1221,7 @@ <h1>type</h1>
<article>
<h1>value</h1>
<p class="description">Get the value of a nested property reference if it exists, and <code>undefined</code> without any errors if not.</p>
<pre><code>var val = $.value([obj, ] property1, [property2 [,...[, propertyN]]])</code></pre>
<pre><code>let val = $.value([obj, ] property1, [property2 [,...[, propertyN]]])</code></pre>

<dl class="args">
<dt class="object">obj</dt>
Expand All @@ -1280,7 +1245,7 @@ <h1>fetch</h1>

<p class="description">Helper for AJAX calls, inspired by the new <a href="https://fetch.spec.whatwg.org" target="_blank">Fetch API</a>.</p>

<pre><code>var promise = $.fetch(url, options)</code></pre>
<pre><code>let promise = $.fetch(url, options)</code></pre>

<dl class="args">
<dt class="string">url</dt>
Expand Down Expand Up @@ -1331,7 +1296,7 @@ <h1>load</h1>

<p class="description">Include a CSS or JS resource dynamically, only once, and run code after it has loaded.</p>

<pre><code>var promise = $.load(url [, base])</code></pre>
<pre><code>let promise = $.load(url [, base])</code></pre>

<dl class="args">
<dt>url</dt>
Expand All @@ -1352,7 +1317,7 @@ <h1>include</h1>

<p class="description">Include a script file conditionally and run code after it has loaded.</p>

<pre><code>var promise = $.include([condition,] url)</code></pre>
<pre><code>let promise = $.include([condition,] url)</code></pre>

<dl class="args">
<dt>condition</dt>
Expand All @@ -1366,16 +1331,16 @@ <h1>include</h1>
</dl>

<pre><code>// Load ES5-shim if needed
var url = "https://cdnjs.cloudflare.com/ajax/libs/es5-shim/4.3.1/es5-sham.min.js";
let url = "https://cdnjs.cloudflare.com/ajax/libs/es5-shim/4.3.1/es5-sham.min.js";
$.include(Array.prototype.forEach, url).then(function(){
$$("div").forEach(function(){
// some code here
});
});</code></pre>
<pre><code>// Load dropbox.js from a CDN if it’s not already loaded and run some code that uses it
var url = "https://cdnjs.cloudflare.com/ajax/libs/dropbox.js/0.10.2/dropbox.min.js";
let url = "https://cdnjs.cloudflare.com/ajax/libs/dropbox.js/0.10.2/dropbox.min.js";
$.include(self.Dropbox, url).then(function(){
var client = new Dropbox.Client({ key: key });
let client = new Dropbox.Client({ key: key });
// ...
});</code></pre>

Expand Down Expand Up @@ -1439,7 +1404,7 @@ <h1>overload</h1>
</dd>
</dl>

<pre><code>var method = Bliss.overload(function (key, val) {
<pre><code>let method = Bliss.overload(function (key, val) {
console.log(key + " " + val);
}, 0);
method('name', 'Lea');
Expand All @@ -1449,7 +1414,7 @@ <h1>overload</h1>
// lang javascript
</code></pre>

<pre><code>var method = Bliss.overload(function (param1, param2, key, val) {
<pre><code>let method = Bliss.overload(function (param1, param2, key, val) {
console.log(key + " " + val);
}, 2);
method(param, param, 'name', 'Lea');
Expand Down
Loading