App Development Turn your JS/CSS project into an atomic package

What is an "App"?

In Kickstrap, an app is nothing more than a folder with css and js files. But what really makes it tick is the config.ks file. This is a script for Kickstrap's resource loader to instruct how to load the css and js in your app.

As simple as this is, packaging it this way has profound implications for User Experience:

• Users can install apps throughout their website just by copying in the folder and turning it on in kickstrap.less.
• App resources are automatically non-blocking. That is, the resources load via organized AJAX calls after DOM load.
• Because apps are simple by design--not compiled or generated--they're also optional. Users can always link in the resources the normal way.

Create an App

The bulk of the work involved in creating an app is simply the creation of a JavaScript project. This guide assumes you have already created such a project. Otherwise, documentation for creating such a project is outside the scope of this guide. Check out CodeAcademy to learn how to program in JavaScript

Unlike "apps" for other devices and platforms, making an app for Kickstrap doesn't mean making it exclusively for Kickstrap. You can turn your existing JavaScript projects into Kickstrap apps in seconds.

Packaging

To begin creating your app, drag and drop all your resources--images, media, JS, CSS, etc--into a folder with the name of your app. This folder name is what users will write in their kickstrap.less file to refer to your app.

A Simple Example

Follow along with our example creation of a "Hello World" app. In a folder called "helloworld," we have a config.ks file and a helloworld.js file.

Structure

            helloworld/
              config.ks
              helloworld.js
            

Let's assume helloworld.js has the code alert('hello world!');.

Now we'll open the config.ks file and tell add helloworld.js as a resource. To do that, just write helloworld.js, no quotes, in that file.

config.ks

helloworld.js

That's it! We now have an app. All the user needs to do is include the helloworld folder in her Kickstrap/apps/ directory and write "helloworld" in their @apps in kickstrap.less.

TIP: The disadvantage to running your app as non-blocking javascript is that regular blocking Javascript will run whether your app is ready or not. Alternatively, you or your users can use the kickstrap.ready() function to ensure code loads after all apps have loaded. See the API.

kickstrap.less

            ...
            @apps: "jgrowl, bootstrap, helloworld";
            ...
            

More Interesting Examples

Of course, for the helloworld app, making this into an app is a bit overkill. It's easier to see the utility of an app with a slightly more complicated example. Let's see how this works with an image slider plugin.

First, we'll need to create the folder and put in a blank config.ks file...

Structure

            imageslider/
              config.ks
            

Now, let's add the images themselves and put them in a folder called "img"

Structure

            imageslider/
              config.ks
              img/
                boy.jpg
                girl.jpg
                man.jpg
                woman.jpg
            

We'll also need some css files for css3 transitions and special bordering and effects for the images. We'll put those in a folder called "css."

Structure

            imageslider/
              config.ks
              img/
                boy.jpg
                girl.jpg
                man.jpg
                woman.jpg
              css/
                transitions.css
                imgstyles.css
            

Finally, we need the JS file to run this.

Structure

            imageslider/
              config.ks
              img/
                boy.jpg
                girl.jpg
                man.jpg
                woman.jpg
              css/
                transitions.css
                imgstyles.css
              js/
                imageslider.js
            

Now that we have all our resources, the last thing we need to do to make this into an app is tell config.ks how to load our resources. Let's assume our image slider is loading the images via the js file using the global rootDir variable to ensure the app doesn't break for sites with subdomains.

That means, we really just need to tell the app to load the JS and CSS files.

config.ks

imageslider.js, transitions.css, imgstyles.css

Remember, if your app requires a certain HTML structure, as is surely the case with this image slider, include this in your docs. Users may otherwise expect to see an image slider pop up on their page when turning on the app.

As long as the project files work on their own, they should now work as a Kickstrap app. Just don't forget to place this folder in Kickstrap/apps and link it in the @apps in kickstrap.less

What if our image slider app was actually an extension of another, simpler jQuery plugin called "Basic Image Slider" (bis)? By default, all files in the app are loaded in asynchronous AJAX calls. Our imageslider.js file uses functions from bis.js so we need to make sure bis.js loads first while imageslider.js loads only when bis.js is ready. To do this, just place your required resources (bis.js) on the first line, and the dependent resources (imageslider.js) on the second line.

config.ks

bis.js
            imageslider.js, transitions.css, imgstyles.css

Structure

            imageslider/
              config.ks
              img/
                boy.jpg
                girl.jpg
                man.jpg
                woman.jpg
              css/
                transitions.css
                imgstyles.css
              js/
                imageslider.js
                bis.js
            

Note it doesn't matter to the js files where the css files go in terms of the top line or the bottom line. Kickstrap only waits for js files to load before moving to the next line.

To verify your resources have loaded the way they are intended, make sure the console is turned on in kickstrap.less and inspect the loaded apps. See Debugging to see how this works.

CDN Resources Optimize apps with CDN-sourced dependencies

Content Delivery Networks, or CDNs, distribute your content to servers all over the world, matching your users with the server closest to them. This means users will get the fastest download possible relative to their location.

Using a CDN resource in your app is tremendously simple. Say you have this as your config.ks file:

config.ks

app.js, app.css

Now we want to load app.js from http://cdnjs.com/app.js. Just put this address in the file instead of app.js. Kickstrap will automatically detect either an "http:" or "https:" prefix and load it remotely instead.

config.ks

http://cdnjs.com/app.js, app.css

While using a CDN resource in your app has many benefits, be aware the app will only work with an internet connection, which may be undesirable for developers working on their local host, potentially without internet access. For example, I like to do some programming on long subway rides home.

A good practice is to include the resource locally as well, and simply comment it out in config.ks.

config.ks

http://cdnjs.com/app.js, //app.js, app.css

If the user wants to use the local version instead, she can simply comment out the public link and uncomment the local one.

config.ks

//http://cdnjs.com/app.js, app.js, app.css

Debugging Troubleshoot your app right from the console.

Kickstrap.js will closely monitor your app's resource-loading and report in the console. We recommend using Google Chrome's console for its minimalist reporting and its ability to report when the console is closed. However, Kickstrap will write to the default console object, so any browser with a console should work.

Once an app has been called, you'll see the name of the app loaded with an array of its properties.

The properties will tell you how many resources were found and how many were loaded successfully.

In case your app does not load, check the "countRequired" and "countDependent" values. Also verify the configPath is set up correctly. This is where kickstrap.js is looking for config.ks

The first number tells you how many were loaded, the second tells you how many should have loaded. In the above example, the app successfully loaded 0 of 0 dependent resources (The second line of config.ks) and 1 of 1 required resources.

You can see what these resources are, successfully loaded or not, in the "resourcesRequired" and "resourcesDependent" values.

Note that "successfully loading" a css file only means Kickstrap has successfully linked in the css file into the DOM. It does not validate the css file itself. It is possible that the path name could be incorrect yet still count this as a successful load in the app.

However, JS resources are counted as successful when the AJAX call to the resource returns with success.

API Speak Kickstrap's language from your app

Kickstrap 1.x has a small, humble API for apps to use

[app]

Before loading the apps, Kickstrap looks through config.ks and creates a JavaScript object which can be reused later. The name of the object is just the name of the app. To pull in properties from the app, you may need to use the syntax window[[app]] where [app] is the app's name without brackets. (e.g. window[qunit].) From there, you may use JavaScript dot notation to pull in properties from that app object.

consoleLog(msg)

Using consoleLog() instead of console.log() in your app allows any such command to be toggled off when the user turns off the console in settings. This also future-proofs your app for any additional features which may be built into this function or other apps which read from it.

@footerHeight

This is a LESS variable used in the sticky footer, which is coded in the standard Kickstrap footer and header. Unlike directly styling the footer element, this value is brought into a calculation to make the footer stick to the bottom.

loadApp(appName) Experimental

Load app is a manual way to load an app at any time, even if it's not included in kickstrap.less. Simply write in the name of the app in quotes.

rootDir

This is defined in settings with a trailing slash. Use this JS variable in the front of any paths to ensure your app does not break in Kickstrap sites working from a subdirectory.

.hello

Say "hi" to Kickstrap and get version number.

.edit()

Edit anything on the page. (Go ahead, try it on this page.)

.ready()

This is modeled to work just like the jQuery $(document).ready() function. The only difference is this will run after all your apps have successfully loaded. Feel free to use this as many times as you want throughout your application. It will store each instance in an array and fire them off in order. Like the jQuery document ready, this should only appear after kickstrap.js has loaded. (And yes, you can use them in apps).

Themes Create a personalized look for your Kickstrap site

Theme Functions

Your theme may require some accompanying js, but you wouldn't want to force your user to manually add it as an app or write it into their HTML.

Instead, you can include a functions.js file in your theme folder. This is done with the mytheme theme if you'd like to see a working example.

This is achieved by including the following lines in mytheme.less

mytheme.less

            #themeFunctions {
               content: '<script>themeFunction(\'mytheme\');<\/script>';
               ie: '<script>themeFunction(\'mytheme\');<\/script>';
            }

Structure

            Kickstrap/
              themes/
                mytheme.less
                mytheme/
                  functions.js
            

It's a mouthful, but all you'll need to change is the word "mytheme" appearing twice. Change this to the name of the folder in Kickstrap/themes/ where you'll store your function file. In this case, it's also called "mytheme."

Now you can write any JavaScript/jQuery in your functions.js file and it will automatically load with your theme. mytheme's functions.js file replaces the low resolution background image (which loads quickly) with a high definition version only after it has loaded.