Quick.JS Documentation

Transcription

1 Quick.JS Documentation Release v0.6.1-beta Michael Krause Jul 22, 2017

2 Contents 1 Installing and Setting Up Installation Setup Reference Guide Basic Installation A Guide To Quick.JS Features Data Binding With Quick.JS Getting Started + A Quick Example Some Extra Information What Does Quick.JS Use to Compile? Building Your Own Copy of This Documentation i

3 CHAPTER 1 Installing and Setting Up Installation To install Quick.JS, we have two options: getting the latest release from GitHub or fetching Quick.JS from a CDN. Using a CDN Quick.JS is proud to be hosted on JSDelivr, one of the fastest commercially available content distribution networks, or CDNs for short. This allows you, the user, to access Quick.JS easier than ever. To get started with the CDN, just use this template page: <meta charset="utf-8"> <meta http-equiv="x-ua-compatible" content="ie=edge"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>quick.js Demo Page!</title> <link rel="stylesheet" href=" Welcome to Quick.JS! <qk-page qk-pageid="page2"> This is the second page of the demo app. <a qk-linkto="page1">go back to page 1</a> <script src=" <script> 1

4 }); </script> qk.go({ home: "page1", Instead of manually downloading Quick.JS files and then hosting them on the web server of your choice, this outsources the hosting, not only increasing ease, but also increasing your page s load speed. We hope that you enjoy this feature of Quick.JS. GitHub If you would like to host your own copy of Quick.JS, use the absolute latest code, or contribute to Quick.JS, you likely want to grab Quick.JS from GitHub. The Quick Version Head over to Quick.JS releases page 1 on GitHub. Look for the latest release, and download the attached two files. One should be quick.js, which is the actual JS logic, and the other should be quick.css, which includes some styling to make Quick.JS work. Be sure to link to the quick.css file in your header and the quick.js file at the very bottom of your page, after every other JS import. The Nice and Detailed Version If that paragraph above didn t quite work for you, don t worry. We can help. The very first thing that we ll need to do is to head over to the GitHub page for Quick.JS. This is where the code for Quick.JS lives, and it s where the released are housed for you to download them. The link to access the main repository with the latest source code is here 2 and the code to access all of the prebuilt releases is here 3. We ll focus on the releases page. On the releases page, the newest stable release will be at the top of the page. There is a short changelog and under it, there are 4 links: one for quick.css (this is for helping with styling), one for quick.js (this is the logic itself), and two for the source code of the release. <meta charset="utf-8"> <meta http-equiv="x-ua-compatible" content="ie=edge"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>quick.js Demo Page!</title> <link rel="stylesheet" type="text/css" href="./quick.css"> Welcome to Quick.JS! <qk-page qk-pageid="page2"> This is the second page of the demo app Installation 2

5 <a qk-linkto="page1">go back to page 1</a> <script src="./quick.js"></script> <script> qk.go({ home: "page1", }); </script> Create a new folder to house all of your files for your Quick.JS project. Now, create a new file, paste the above starter page into it, and save it as index.html. In the same folder, download both the quick.css and the quick.js files from GitHub, and put them both in the same folder. Now, when you fire up your index.html file in your web browser of choice, it should display Welcome to Quick.JS! with no special styling. At this point, you ve successfully installed Quick.JS! If you would like to see a more complex demo page, download the source code for the release in either.zip format for Windows, or.tar.gz format for Linux/OS X. Within the source code, there is a build folder, and within that, there is a demo folder, which contains some demo files to help show off what Quick.JS can do. Setup Let s break down what s happening in that starter page. There are just a few things that distinguish it from a normal HTML document, so we ll take a look at those. First of all, there are the two links to the quick.js and the quick. css files, which are essential for making Quick.JS work. The CSS file is linked in the header, and the JS file is the last linked file in the footer of the document, like so: <link rel="stylesheet" type="text/css" href="./quick.css"> <script src="./quick.js"></script> These are essential. Without these imports, Quick.JS is not installed. If you used a CDN, those above statements were replaced with links to JSDelivr s servers. They function in the same manner. The next thing to note is the <qk-page> tags scattered around the document, as we see here: <qk-page qk-pageid="page2"> 1.2. Setup 3

6 These are how Quick.JS divides up an application into separate pages. As we know, the purpose of Quick.JS is to provide a simple way to create one-page apps, with no linking to multiple pages. As such, it needs a way to split up an HTML page into separate, virtual, page-like entities. The <qk-page> tag is the answer. You can also see that each <qk-page> has an attribute associated with it called qk-pageid. In order for a <qk-page> to be recognized as valid, it must have that attribute, which is essentially just a unique ID for the page. The final thing to note is the very last thing on the page. Take a look: <script> qk.go({ }); </script> home: "page1", As you ve probably realized by now, anytime you see qk, it represents something to do with Quick.JS (for instance, qk-page). In this case, we re calling Quick.JS starting method, by using qk.go(). You ve also probably noticed that we have a line that says home: "page1",. This is part of a list of arguments that are provided to Quick.JS in order to help it out. Currently, the only argument that can be provided in the argument list is home. Put in the ID of the qk-page that you intend to be the first page displayed. Recall that we specified the ID using the qk-pageid attribute. Note that since we provide a list of arguments, there are curly braces within the parentheses for the qk.go() method, like so: { } home: "page1", //other arguments here, //and here, //in the future, Once this qk.go({args}) method is called, the ball is rolling, and Quick.JS will format the page correctly Setup 4

7 CHAPTER 2 Reference Guide Basic Installation If you haven t already, be sure to check out the Installing and Setting Up section. A Guide To Quick.JS Features Pages Quick.JS aims to provide an easy way to create simple single page applications, or SPAs. In order to provide this experience, Quick.JS divides the base HTML file up into individual pages by using a custom delimiter. If you ve read the Installion and Setting Up page linked at the top of this page, you ll know that this is accomplished using the <qk-page> HTML tag. Please note: From here on out in this section of the documentation, consider a page to be the content displayed on the page at one time. As we ll find out in a moment, this is happened by dividing up the HTML page into different sections. Thus, each section is a page. Example: your content here <qk-page qk-pageid="page2"> more content here <qk-page qk-pageid="page3"> even more content here In a nutshell, Quick.JS will identify every <qk-page> tag, and group all of that content together into a single unit to display. 5

8 IMPORTANT: Do NOT nest <qk-page> tags. Only one page can be shown at a time, and nesting the pages may have unexpected consequences, such as not working. When you declare your <qk-page> tags, you must also include the attribute qk-pageid in the tag. This tells Quick.JS what you want the page to be identified by. As we covered in the Setup page, when we initialize Quick.JS, we provide an argument to the argument list which specifies what the homepage is. This homepage is specified by the qk-pageid. In another example, when we link between pages, we need to use the qk-pageid to specify the target page to display. Constant Elements This is a feature that allows an element to be constantly displayed across pages. This is applicable to elements such as navbars or social media icons. Please note that this feature will be expanded upon quite a bit in the future, so look forward to that! 2-way Data Binding Quick.JS can do simple 2-way data binding, meaning that it can easily exchange data between the HTML page and an associated Javascript script. Check out the documentation on data binding here. The Advantages of Quick.JS Lots and lots of stuff! :) Don t worry, this page of documentation is still under development. We ll be finishing it up soon! 2.2. A Guide To Quick.JS Features 6

9 CHAPTER 3 Data Binding With Quick.JS Getting Started + A Quick Example Let s take a look back at the starter template provided to us in the Installing and Setting Up section. It looked like this: <meta charset="utf-8"> <meta http-equiv="x-ua-compatible" content="ie=edge"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>quick.js Demo Page!</title> <link rel="stylesheet" type="text/css" href="./quick.css"> <!-- or JSDelivr CDN Link--> Welcome to Quick.JS! <qk-page qk-pageid="page2"> This is the second page of the demo app. <a qk-linkto="page1">go back to page 1</a> <script src="./quick.js"></script> <!-- or JSDelivr CDN Link--> <script> qk.go({ home: "page1", }); </script> Let s now assume that in the same directory we have a Javascript file called data.js. Here s the contents of that file: 7

10 var somerandomdata = new function(){ this.sampledata = {"helloworld" : "Welcome to Quick.JS!"}; }; As you can tell, it s a fairly small file, but it has some critical characteristics. First, it has a namespace. This is denoted by: var somerandomdata = new function(){ your data here}; This helps in keeping your code clean. If you need some more convincing as to why you should include a namespace in your code, you should read the Wikipedia article 4 about it. Trust me, it will make your life easier. Inside of our namespace, we have a single line of JSON-formatted data. In a nutshell, JSON, short for Javascript Object Notation, is a way to organize data via a series of key-value pairs. In the example above, our key-value pair has the key "helloworld" and the value "Hello World!". This was set to the variable this.sampledata. If you want to learn more about JSON, check out W3Schools nice guide 5. After that brief tangent on JSON and namespacing, let s bring it back to the topic at hand, data binding. In our HTML document, let s replace the line Welcome to Quick.JS! with a div tag. We ll also link to that data.js file in the footer. Here s an example: <meta charset="utf-8"> <meta http-equiv="x-ua-compatible" content="ie=edge"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>quick.js Demo Page!</title> <link rel="stylesheet" type="text/css" href="./quick.css"> <!-- or JSDelivr CDN Link--> <div> <!-- nothing here yet --> </div> <qk-page qk-pageid="page2"> This is the second page of the demo app. <a qk-linkto="page1">go back to page 1</a> <script src="./data.js"></script> <!-- our data source --> <script src="./quick.js"></script> <!-- or JSDelivr CDN Link--> <script> qk.go({ home: "page1", }); </script> Very good. If you ve been paying attention, you ll have noticed that in our data file, we declared the value of our keyvalue pair to be "Welcome to Quick.JS!", which is what the page used to day before we replaced its contents Getting Started + A Quick Example 8

11 with a div. Coincidence? Nope. We re going to make that div we just added say "Welcome to Quick.JS!" also, just with the magic of data binding. Let s do that now. The first thing to change is to add a special attribute to that div, like so: <div qk-datafrom="somerandomdata.sampledata"> <!-- nothing here yet --> </div> As you know, anything that s prefaced by qk is related to Quick.JS. Thus, it s not hard to figure out that qk-datafrom is an attribute critical to Quick.JS data binding. It essentially serves to point Quick.JS to a starting point to fetch it s data from. When we imported data.js using the <script src="./data.js"></script> line in our HTML page, all of the variables in data.js became accessible to our HTML and all of the rest of our Javascript. By saying somerandomdata.sampledata, we reference the somerandomdata namespace that we had defined previously, and then with sampledata we can reference the specific variable within that namespace. Even if we opened up this page in a web browser right now, nothing would appear. Why? We have our variable linked up to our div, so what s the catch? Well, remember how the variable itself is in JSON format? We need to define which value from that JSON that we want to appear. In order to do that, we need to supply the key for the value that we want. This is done using double square brackets. Take a look: <div qk-datafrom="somerandomdata.sampledata"> [[data.helloworld]] </div> Okay. The helloworld part makes sense: it s just the key for the value that we d like to display. But what about the data part? Quick.JS uses a pseudo-parent object to reference all of the data within the variable specified by qk-datafrom. Essentially, this means that if our data.js actually looked like this: var somerandomdata = new function(){ this.sampledata = {"data_array": [ "helloworld" : "Welcome to Quick.JS!", "helloworld2" : "not what we want"], "evenmoredata": "more data"}; 3.1. Getting Started + A Quick Example 9

12 }; where we see that this.sampledata is not one JSON key-value pair, but rather an array of key-value pairs and another random pair, we can still navigate through our data. Say that we still wanted to access the "helloworld" keyvalue pair. Instead of using [[data.helloworld]] like we did previously, we can say [[data.data_array. helloworld]]. Okay. Let s uncomplicate things. Now that we ve established what the double square bracket notation is and what the data. prefix is, let s just assume that our data.js file looks like this: var somerandomdata = new function(){ this.sampledata = {"name" : "Quick.JS!"}; }; Well. The Welcome to part of "Welcome to Quick.JS!" is gone! Don t worry, it s a perfect opportunity to demonstrate how we can mix standard text and Quick.JS double bracket notation in the same div. Take a look: <div qk-datafrom="somerandomdata.sampledata"> Welcome to [[data.name]] </div> Now, we can change the value for the key "name" to be anything we want. If we change it from "Quick.JS!" to, say, "Google", it would merely display "Welcome to Google". Simple as that Getting Started + A Quick Example 10

13 CHAPTER 4 Some Extra Information You may or may not find some of this useful. We certainly hope that you make some use of it. What Does Quick.JS Use to Compile? Quick.JS uses Google s Closure Compiler 6 to compile and minify. After compiling, Closure keeps some newline tags in the JS code, which takes up ~10 bytes of space. Since we believe that every byte really does matter, we run it through the minifier here 7 to remove those newlines. As for our CSS, we use a standard CSS minifier here 8. Since our CSS code is tiny, we don t use Sass or LESS. It would be massively overkill. Building Your Own Copy of This Documentation Fun fact: This documentation is directly linked to Quick.JS repository. Whenever changes are commited, these docs are rebuilt. Due to this, they should always be the most up-to-date and reliable docs out there for Quick.JS. However, if you, for whatever reason, want to build your own copy of the documentation to host locally, please feel free to. The only prerequisite is that you have Sphinx 9 installed. If you have Python installed, it s as easy as running pip install Sphinx in a terminal or command prompt. Open the docs/ folder of the GitHub repository on your local machine in a terminal or command prompt (OSX, Windows, or Linux all work fine in this case). From there, just run make html to generate HTML versions of the documentation, or run make latex to make a LaTeX version