How to create an extension

An extension is simply a Git repository that a user clones into their project. The repository should contain code that builds on core code to expose new functionality.

Because the user's project will already be a git repository. They'll install your git repo as a Git submodule. A Git submodule is simply a repo in a repo.

As Kickstart is maintained primarily as a Gulp project, this guide will show you how to make extensions by cloning Kickstart itself.

Because of there is some overlap, this guide documents how to create both a component and a theme.

# Here's how the user will install your extension
$ git submodule add git://github.com/yournamehere/myextension.git

Create a project to contain your extensions

For your first extension, you're going to create two repositories. The first will be a project to contain all the extensions you build from now on. this is what we'll mean when we say "project" from here on.

The second will be the extension itself. This is a highly recommended workflow for extension development.

First, clone the Kickstart repo.

# Create a "My Extensions" directory and cd into it.
$(~) git clone git@github.com:adamjgrant/kickstart.git myextensions && cd myextensions

Now you'll need to install all the necessary Kickstart dependencies with the following commands.

$(myextensions) sudo npm install -g gulp && sudo npm install . && bundle && make

If everything worked correctly, you should be able to launch the project with the gulp command. This will automatically launch a browser with a basic sample webpage.

If you'd like to save your project environment on github, you can remove the existing origin remote from .git/config and add your own (Using the instructions provided on Github after creating a new repo is a great way to do this.)

$(myextensions) gulp

Create your first extension

You can now use the following steps for your first and every new extension you wish to create.

Components

For components, take a look in the lib/sass/vendor directory. This is where you'll create your first extension. You should see there is already an extension there called "switch."

You may want to refer to the structure of this sample component in creating your own.

$(myextensions) cd lib/sass/vendor && ls -l
total 8
-rw-r--r--  _index.sass
drwxr-xr-x  switch

Let's create an extension with the name "status-text"

Because submodules are inherently remote repositories, we need to actually create a repository in GitHub first.

Create a new repo in GitHub and initiate with a README.md file. In this example, we'll say we created a repo called "status-text"

Beware of extensionless files Please avoid using files that do not have extensions. For example, LICENSE should be renamed to LICENSE.md. Extensionless files create issues in your Rails end users

Now that you have your status-text repo, you'll need to add it as a submodule in your project.

Don't clone! It's tempting to just git clone your repo, here, but you won't be able to maintain it as easily from within your project.

You should then see this directory created alongside the switch extension.

$(vendor) git submodule add git@github.com:mygithubaccount/status-text.git

$(vendor) ls
switch status-text _index.sass

Before we cd into your new extension, let's add your extension as a vendor asset for your project.

Edit lib/sass/vendor/_index.sass as such:

// Vendor libraries
// ================
// 3rd party additions to the Kickstart UI library should
// be indexed here.

// e.g. @import datepicker
@import switch/switch
@import status-text/index.sass

body
  display: inherit

Now we just need to add that "index.sass" in status-text.

cd into status-text and create it. For now, it doesn't need to create anything. It just needs to exist.

$(vendor) cd status-text && touch index.sass

Start coding

You're now fully setup to write the code for your extension. Anything you write to status-text/index.sass will be availble to your end user.

Let's write some code in index.sass to get started.

In this example, status-text will be a sass mixin that uses the colors defined in the user's Kickstart theme and applies them to text.

We'll let them use the keywords "good," "okay," and "bad" to denote the status.

Let's create the mixin that does that.

// In status-text/index.sass

=status-text($type: 'good')
  @if $type == 'good'
    color: map-get($colors, green)

  @if $type == 'okay'
    color: map-get($colors, yellow)

  @if $type == 'bad'
    color: map-get($colors, red)

At this point, the end user can easily just use your extension in their project as such:

Of course, this is too simple an extension to be useful, but with the entire core of Kickstart at your disposal, you can build it out to do much more.

// In lib/sass/style.sass

@import themes/default/theme

// Write your styles here.

p.stable
  +status-text('good')

p.error
  +status-text('bad')

p.warning
  +status-text('okay')

Themes

For themes, look in lib/sass/themes/. There you'll see a directory called "default" and a sass file called theme.sass.

We'll need to create a structure similar to default. First, we'll need to create an empty repository on GitHub so we can create a submodule from it.

Create a repository with the name of your theme, including a README.md file, and add it as a submodule to your lib/sass/themes directory.

Then copy in the default theme from the core directory. This will be the sass file that will become your theme.

# Add the repo as a submodule.
$(themes) git submodule add git@github.com:mygithubaccount/mytheme.git

# Copy the core theme into "dark"
$(themes) cd ../../../
$(myextensions) cp lib-core/sass/themes/default/theme.sass lib/sass/themes/mytheme/

At this point, it may be helpful to read about the anatomy of a theme to understand how a theme works in Kickstart.

If you understand that, getting started writing your own theme should be straightforward.

Before you start, however, you should probably change your project theme to the new one you're now creating. Open lib/style.sass and change the @import to point to your new theme.

// lib/sass/style.sass

@import themes/dark/theme

// Write your styles here.

Test your theme with the docs

Better, just use the docs! This will allow you to test your theme with all the core components.

Instead of gulp, run gulp watch:docs. This will compile all the files in lib-docs instead of lib.

Because there are several places you'd need to change the theme (The docs use a long list of css files.) the chosen theme can be changed in all files from lib-docs/sass/chosen-theme.sass.

If you want to run both the lib and lib-docs directories, no problem. Gulp will automatically use different ports for each.

// In lib-docs/sass/chosen-themes.sass
// We need to reach up a couple directories to get to our theme in lib.
@import ../../lib/sass/themes/mytheme/theme.sass