Welcome to the getting start guide for the White Label website template. This guide and repo is meant to serve as a simple and easy way for you to get a website up and running connected to the White Label and Soundcloud APIs.
This template is currently in Alpha and under active development. Feel free to contribute with any optimizations/features/bug fixes via pull request.
This open source template is a Middleman web app which uses the AngularJS framework. It comes configured with a live reloading development environment and a way to build a static website for production. This guide will show you how to quickly connect the website to the White Label API using your client id and play your mixtape tracks through Soundcloud.
Before we start, you need to have a few things already installed, Ruby and NodeJS. If you already have these, feel free to skip to step 3.
- Ruby is a programming language which runs Middleman, the static site generator we use. Download and install the latest version of Ruby for your platform by following the instructions here. Once you have Ruby set up, install the Ruby dependency manager bundler with
gem install bundler. - NodeJS is a way to run JavaScript code locally. We use Node and its package manager, npm, to install some frontend dependencies. Download and install the latest stable release of NodeJS here.
- Clone this repo by running the following command in a terminal.
git clone https://github.com/NoonPacific/White-Label-Web-Template.git.
This template requires you to have 2 API keys, White Label and Soundcloud.
The White Label API key is needed to connect to the White Label server to fetch your collections, mixtapes, and tracks. If you do not already have a WL client id, please sign up.
A Soundcloud API key is needed to play your mixtape tracks in the browser. You can get a Soundcloud API key by registering a new application. You will need the Client ID.
Now that you have Ruby, Node, API keys, and the template downloaded, you are ready to start running the website locally.
- Open a terminal and navigate to the cloned repo.
cd White-Label-Web-Template - Install all Node dependencies.
npm install - Install all Ruby dependencies.
bundle install - Open
source/js/app/config.jsin your favorite editor and replaceYOUR_WHITE_LABEL_CLIENT_ID_HEREandYOUR_SOUNDCLOUD_CLIENT_ID_HEREwith your White Label and Soundcloud client id's respectively. - Replace
YOUR_DEFAULT_COLLECTION_HEREwith the White Label collection you want to load when you visit the root of the website.http://YOUR_DOMAIN_NAME/ - Run the website locally with the command
npm run dev. - Open localhost:4567 in a browser. You should see the default collection mixtapes and be able to play tracks right in the browser.
This template is only meant to serve as a starting point for your website. We encourage you to dig around and customize anything you want. Create something rad, then email us and we'll help promote it.
Before we start to customize your website, let's first go over how the project is structured.
White-Label-Web-Template/
node_modules/
source/
css/
img/
js/
app/
controllers/
lib/
services/
vendor/
layouts/
partials/
views/
Gemfile
package.json
All of the source files for the website are located in source/.
source/js/app/- Main Angular app and configuration
source/js/controllers/- Angular controllers and logic to manage playback of audio, grid of mixtapes, and the currently playing mixtape and tracks
source/js/services/- Angular collections and services to communicate with the network and pull in data.
The most important file is arguably mix-service.js. This service uses your CLIENT_ID to communicate with the White Label API to fetch your collections, mixtapes, and tracks.
To change the logo that appears at the top of the website, simply replace source/img/logo.svg with another svg file. We recommend using an svg file to ensure the logo looks sharp on all screen sizes.
Google fonts are open source and really easy to setup in this template. To change the font, open source/css/_variables.sass and edit these lines to your desired font.
@import 'https://fonts.googleapis.com/css?family=Open+Sans'
$font: 'Open Sans', serifAll main colours can be found in source/css/_variables.sass and edited to match your brand.
$black: #333
$grey: #adadad
$white: #fff
$selected: #3863FF
$facebook: #3b5998
$twitter: #55acee
$soundcloud: #ff8800
$instagram: #3f729b
$amazon: #FF9900
$spotify: #24CF5F
$text: $black
$footer: $white
$player: $whiteThe css for the main page layout is in source/css/main.css.sass
- Layout of the current mixtape and tracks
source/views/playlist.html
- Layout of the mixtape grid
source/index.html.haml
You may have noticed that in source/js/app/config.js there is a field called HTML_5_MODE, which is set to false by default. Setting this to true will remove the # in the url path. One thing to note though, is that if this is true and your website is deployed, the server must be able to handle serving the same file for all paths.
To build the website for production, run npm run build. This will minify all JavaScript files into a build/ directory. This directory can be uploaded to a server or service which can serve static websites, such as Amazon S3 or Heroku.
If you do not already have a server setup and ready to use, an easy way to get your website online so the world can listen to your mixtapes, is by using a service called surge.sh. The free tier of Surge allows you serve static websites with a custom domain and free SSL. If that doesn't already sound amazing, it is also ridiculously easy to setup.
Now if you have HTML_5_MODE set to true, you will need to copy the index.html file to 200.html. This ensures the Angular router picks up on all url paths.
cp build/index.html build/200.html
- Install surge globally.
npm i -g surge - Run
surge -p buildand follow the steps to register/login and choose a domain name.
An example of the template running on surge
If you do not want to use the Angular template, or want to incorporate White Label into your already existing website, there is a JavaScript library you can use to easily communicate with the White Label API. This way you do not have to worry about network requests or pagination.
The library can be downloaded here and added to your website through a <script> tag.
<script src="whitelabel.min.js"></script>This will expose the global class WhiteLabel. After the page has been loaded, initialize an instance providing your White Label client id.
var wl = new WhiteLabel(CLIENT_ID);Getting array of all Mixtape objects in the collection with slug "collection-slug"
wl.getCollectionMixtapes("collection-slug", {
all: true,
results: true
}).then(function(mixtapes) {
// Do something with array of mixtapes
});Get array of Track objects for mixtape with slug "mixtape-slug"
wl.getMixtapeTracks("mixtape-slug", {
results: true
}).then(function(tracks) {
// Do something with array of tracks
});Get all mixtapes for a collection with slug "collection-slug" ordered by mixtape title descending.
wl.getCollectionMixtapes("collection-slug", {
all: true,
results: true,
filters: {
ordering: "-title"
}
}).then(function(mixtapes) {
// Do something with array of mixtapes
});Get array of all tracks from artist "Cool Artist"
wl.getAllTracks({
results: true,
all: true,
filters: {
search: "Cool Artist"
}
});For the full documentation on the White Label JavaScript library please go here.
This template is supposed to be easy to setup and customize. If you feel like you can improve this process with a pull request, please do so.
The White Label platform was created and is maintained by Clark Dinnison and Alex Givens.
The development and usage of the JavaScript library was done by Jake Runzer.