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

Jump to bottom

V3 #34

Merged
merged 30 commits into from
Jan 26, 2024
Merged

V3 #34

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
30 commits
Select commit Hold shift + click to select a range
8f7afd8
replace document with context option
tomhazledine Jan 10, 2024
9fc575f
adding watch to dev mode
tomhazledine Jan 10, 2024
66e8712
moving legacy files into dir
tomhazledine Jan 10, 2024
bd1c540
adding wrapper element to fake-ranges to attach focus class
tomhazledine Jan 10, 2024
275d41d
add focus outlines to default theme
tomhazledine Jan 10, 2024
04298e9
updating tests to reflect context and range-focus changes
tomhazledine Jan 10, 2024
47d2552
composable components
tomhazledine Jan 10, 2024
eb24f47
updating default theme to new composable markup
tomhazledine Jan 10, 2024
3db22a3
aligning tests with new markup format
tomhazledine Jan 10, 2024
47b5e83
updating skeleton theme to new markup
tomhazledine Jan 10, 2024
826a14d
renaming css files and root class name
tomhazledine Jan 11, 2024
92bb090
classnames refactor in JS
tomhazledine Jan 11, 2024
fcf3b0c
refactoring skeleton theme classnames
tomhazledine Jan 12, 2024
02016bd
expanding demo sandbox
tomhazledine Jan 12, 2024
0623ea6
adding picobel.main.css output
tomhazledine Jan 12, 2024
00ebb84
refactoring default theme classnames
tomhazledine Jan 12, 2024
d6c44d2
demo page navigation
tomhazledine Jan 12, 2024
3fffd70
conditionals to check for existence of nodes before applying actions etc
tomhazledine Jan 12, 2024
02de708
fixing index hooks
tomhazledine Jan 16, 2024
614b96c
adding type examples to demo
tomhazledine Jan 16, 2024
c4a9796
handle empty data-artist display
tomhazledine Jan 16, 2024
64a3a5d
get meta from all sources
tomhazledine Jan 16, 2024
bb25c81
adding manual build output
tomhazledine Jan 16, 2024
6455045
only set user components if user has explicitly set components
tomhazledine Jan 23, 2024
e4122c8
updating legacy tests to match new markup
tomhazledine Jan 24, 2024
fd4d620
handling string labels for sliders
tomhazledine Jan 24, 2024
c4a16af
support nested wrapped components
tomhazledine Jan 24, 2024
589569c
adding composable component options to demo page
tomhazledine Jan 24, 2024
b46494a
refactor bbc-theme classnames
tomhazledine Jan 26, 2024
4efa9fa
update readme and contributing docs
tomhazledine Jan 26, 2024
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
66 changes: 27 additions & 39 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,45 +1,27 @@
# Contribute

This started out as a "scratch your own itch" tool for a specific project. I'm open-sourcing it in the hope it might prove useful to others too. There are _a few_ audio player tools/plugins out there, but most have too many features for my needs. I like simplicity, and I like any JS I add to my sites to be as lean as possible.
Picobel started out in 2015 as a "scratch your own itch" tool for a specific project which I then open-sourced in the hope it might prove useful to others.

I'm hoping Picobel can be of use to as many people as possible. If you have an improvement or bug-fix or new feature, get in touch! Make a pull request on the [Picobel.js Github repo](https://github.com/tomhazledine/picobel). I'm just getting started with "open source", so I'd be very glad of any help or suggestions or advice.
If you have an improvement or bug-fix or new feature, get in touch! Make a pull request on the [Picobel.js Github repo](https://github.com/tomhazledine/picobel). Contributions are encouraged and any feedback (positive or negative) is very welcome.

## Dev dependencies
## Making changes

Once you've forked the repo, run `npm install` to install the development dependencies. I'm trying to keep the build chain as short as possible, so there's not too much to be installed:
To make changes to Picobel, you'll need to follow these steps:

* `babel-cli` and `babel-preset-env` are there to transpile the raw ES6 from [`/esm/picobel.js`](https://github.com/tomhazledine/picobel/blob/master/esm/picobel.js) into the ES5-compatible versions.
* `node-sass` is there to compile the SCSS in [`/scss/`](https://github.com/tomhazledine/picobel/blob/master/scss) into vanilla CSS.
* Once the regular SCSS has been compiled, it gets run through `autoprefixer` (using `postcss-cli`) to make sure the necessary browser prefixes are added to the raw CSS.
* To compile the ES6/UMD modules, I've added `webpack` (and `webpack-cli` and `babel-loader`).
* The test suite is run using `jest`.
1. fork the repo and clone it to your local machine.
2. install the dev dependencies with `yarn` (or `npm install`).
3. make changes to the code in the `/src` directory.
4. run `yarn build` (or `npm run build`) to compile the code. There is also `yarn build:dev` (or `npm run build:dev`) which will watch for changes and recompile automatically as well as generating source maps for the compiled files. Once built, the final code will appear in the `/build` directory.
5. run `yarn test` (or `npm run test`) to run the test suite.
6. commit your changes and make a pull request.

## Editing the JS
## Project structure

The canonical source code lives with the [`/src`](https://github.com/tomhazledine/picobel/blob/master/src) directory. This is where you should make any changes to the JavaScript code.
### JavaScript

Wherever possible I've tried to keep all functions as ["pure"](https://medium.com/javascript-scene/master-the-javascript-interview-what-is-a-pure-function-d1c076bec976) as possible: given the same arguments, they should always return the same result, without any side effects. I'm a recent convert to the world of "functional" programming, so accept that I might not always get it right - if you can suggest any improvements, I'll be more than happy to hear them 👍.
Picobel is first-and-foremost a JavaScript project, and all the JS code lives in [`/src/js`](https://github.com/tomhazledine/picobel/blob/master/src/js) with the main file being [`/src/js/Picobel.js`](https://github.com/tomhazledine/picobel/blob/master/src/js/Picobel.js). The function `picobel()` is the default export from this file, and is the function that gets called when you use Picobel in your own code.

### Modules

The code is written using ES6 (UMD) module syntax (e.g. `import VARIABLE from 'PACKAGE_NAME';`).

As far as code organization goes, I've batched functions into roughly-similar groups, and put those groups into their own modules. The groups take the form of objects, that can then be imported into the main app. For example:

// Module file:
const groupedFunctions = {
aCoolFunction: () => {/* the function code */},
somethingUsefull: () => {/* the function code */}
};
export default groupedFunctions;

// App file:
import groupedFunctions from './path-to-module-file';
function TheMainAPP() {
// Use one of the grouped functions:
groupedFunctions.aCoolFunction();
}
export default TheMainAPP;
JS is written using ESM module syntax (e.g. `import { foo } from './bar.js';`), and helper-functions and utilities are imported from partials that also live in `/src/js`.

There are several modules in this project:

Expand All @@ -49,16 +31,22 @@ There are several modules in this project:
* `PicobelMarkup.js`: these functions handle creating the markup that Picobel replaces native `<audio>` elements with.
* `PicobelSetup.js`: these functions initialize Picobel (parsing options, generating initial `state`, etc.).

Once you've finished making changes, run `npm run build` to generate the UMD and CommonJS versions (which will appear in `/esm/picobel.js` and `/cjs/picobel.js` respectively).
The JS is compiled into a production-ready build using [esbuild](https://esbuild.github.io/), which is setup and configured in [`/build.js`](https://github.com/tomhazledine/picobel/blob/master/build.js) and run with `yarn build` (or `npm run build`).

### Tests
### CSS

There are tests for most Picobel functions. Picobel uses Jest for running tests. Test files live in the `/tests` directory, and match the main module files: for example, the `/src/helpers.js` file has a corresponding test file called `/tests/helpers.tests.js`
Picobel supports several pre-build "themes". A Picobel theme is a set of namespaced CSS rules that apply specific styles based on the theme name. For example, the default theme is called `default` and all the CSS rules for this theme are namespaced with `.picobel.default`.

## Editing the CSS
The themes are all written in vanilla CSS and can be found in [`/src/css`](https://github.com/tomhazledine/picobel/blob/master/src/css). Running the build step (with `yarn build` etc.) will create minified versions of the themes in the `/build` directory.

The CSS themes are written in [SCSS](https://sass-lang.com/guide) and compiled to vanilla CSS using the `npm run styles` command. `npm run styles` compiles the SCSS and then runs it through [Autoprefixer](https://github.com/postcss/autoprefixer) to add all the required vendor prefixes.
There are several stylesheets available:

New themes should be named with the following pattern: `/scss/player.NEW_THEME_NAME.scss`. They must also be included in the "all themes" stylesheet: [`/scss/all.scss`](https://github.com/tomhazledine/picobel/blob/master/scss/all.scss)
* `picobel.all.css`: a single stylesheet that contains all the themes. (useful for experimentation, but not recommended for production).
* `picobel.default.css`: the default theme.
* `picobel.skeleton.css`: a "bare bones" theme with minimal styling intended as a jumping-off point for folks to write their own themes. Includes basic layout, loading state, custom-styled volume and progress range sliders, etc.

@import "player.NEW_THEME_NAME";
* `picobel.bbc.css`: a theme that resembles the BBC iPlayer interface circa 2015.
* `picobel.eatenbymonsters.css`: the theme built for [eatenbymonsters.com](https://eatenbymonsters.com) that was the initial inspiration for Picobel.
* `picobel.itunes.css`: a theme that resembles the iTunes app mini-player interface circa 2015.
* `picobel.pitchfork.css`: a theme that resembles the [Pitchfork](https://pitchfork.com/) web audio player interface circa 2015.
* `picobel.soundcloud.css`: a theme that resembles the Soundcloud embedded web audio player interface circa 2015.
162 changes: 30 additions & 132 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,16 @@

<h1 align="center">Picobel.js</h1>

[![Node.js CI](https://github.com/tomhazledine/picobel/actions/workflows/node.js.yml/badge.svg)](https://github.com/tomhazledine/picobel/actions/workflows/node.js.yml)
<p align="center">v3.0.0</p>

<p align="center"><a href="https://github.com/tomhazledine/picobel/actions/workflows/node.js.yml"><img src="https://github.com/tomhazledine/picobel/actions/workflows/node.js.yml/badge.svg" alt="Node.js CI" style="max-width: 100%;"></a></p>

Picobel.js (pronounced _peek-o-bell_, as in _decibel_) is a lightweight dependency-free Javascript tool that converts html audio tags into styleable markup.

* [Overview](#why-would-i-need-this)
* [Installation](#installation)
* [Usage](#usage)
* [Quick start](#quick-start)
* [Setting "artist" and "track name" values](#setting-artist-and-track-name-values)
* [Pre-made themes](#pre-made-themes)
* [Contribute](#contribute)

## Why would I need this?

Expand All @@ -35,144 +35,63 @@ _Picobel-styled audio players_

**Picobel** allows you to create custom styles for your audio players: providing cross-browser consistency and a seamless integration with your existing brand styles.

## Installation

### Install with NPM
## Quick start

`npm install picobel` (or `yarn add picobel`) will install Picobel in your `node_modules` directory. Then you can include Picobel in your javascript like this:

```js
// Include Picobel in your project:
import picobel from 'picobel';
Add Picobel to your project:

// Initialise picobel:
picobel()

// ...or initialise picobel with your chosen options:
picobel({ theme: 'default' })
```bash
yarn add picobel
```

If you are using WebPack (or similar) to bundle your scripts, you can include the stylesheet for your chosen Picobel theme here too:
In your JS, initialise Picobel with your chosen class name:

```js
// Include the styles for *all* the themes:
import 'picobel/css/all.css';
import picobel from "picobel";

// ...or include only the styles for a specific theme:
import 'picobel/css/player.default.css';
picobel({theme: "my-awesome-audio-player"});
```

Alternatively you could include the stylesheets manually with a `<link>` tag in your `index.html`:
Picobel will then find any `<audio>` elements on the page and replace them with markup you can style with CSS.

```html
<!-- Load the Picobel CSS -->
<link rel='stylesheet' href='node_modules/picobel/css/player.default.css' type='text/css'/>
```

When your page loads, Picobel will replace any default `<audio>` elements with a block of custom-markup, complete with classes that you can use to apply your custom CSS.

### Manually install

To use **Picobel.js** you'll need to include the `picobel.js` file (found here: [picobel.legacy.min.js](https://github.com/tomhazledine/picobel/blob/master/picobel.legacy.min.js)) in your project. This needs to be called before your custom scripts, and ideally in the `<footer>` of your page.

```html
<!-- Load Picobel -->
<script type='text/javascript' src='picobel.min.js'></script>
```

You will also need the CSS styles. Choose which "theme" you'd like to use, and load that stylesheet. All current themes can be previewed in the [Picobel.js CodePen Collection](http://codepen.io/collection/XpZEor/), and all the css files can be found in the repo, [here](https://github.com/tomhazledine/picobel/tree/master/css).

```html
<!-- Load the Picobel CSS -->
<link rel='stylesheet' href='player.default.css' type='text/css'/>
```
## Setting "artist" and "track name" values

Then initialize the function. For simplicity, the example below does this in an in-line `<script>` tag, but you can add this to your master JS file. Just make sure you initialise Picobel _after_ the picobel.min.js file has been called.
Applying metadata to your audio file requires adding data-attributes to your `<audio>` markup. Picobel gets the track name from the regular `title` attribute, and looks for artist information in the `data-artist` attribute. For the demo at the top of this page, the markup looks like this:

```html
<!-- Initialise Picobel -->
<script>
Picobel();
</script>
<audio src="http://audio.eatenbymonsters.com/reviews/coldWarKids/lostThatEasy.mp3" title="Lost that easy" data-artist="Cold War Kids" controls>
Your browser does not support the <code>audio</code> element.
</audio>
```

When your page loads, Picobel will replace any default `<audio>` elements with a block of custom-markup, complete with classes that you can use to apply your custom CSS.

## Usage
## Using premade themes

If you're using a theme other than "basic", you'll need to specify the theme name in the options object when you intialise Picobel.
Picobel comes with several pre-made themes that you can use out-of-the-box. To use a theme, simply pass the theme name to the `picobel()` function:

```js
Picobel( { theme: 'themename' } );
picobel({theme: "default"});
```

This adds a class to the container of each audio element, so if you've made your own styles you can use this to make sure your CSS is nicely namespaced.

### This:

```html
<audio src="http://path/to/audio/file.mp3"></audio>
```

### Gets turned into this:

```html
<div class="customAudioPlayer player_0" data-song-index="0">
<div class="loader"></div>
<button class="playerTrigger">
<span class="buttonText">play</span>
</button>
<div class="metaWrapper">
<span class="titleDisplay">file.mp3</span>
<span class="artistDisplay"></span>
</div>
<div class="timingsWrapper">
<span class="songPlayTimer">0:00</span>
<div class="songProgressSliderWrapper">
<div class="pseudoProgressBackground"></div>
<div class="pseudoProgressIndicator"></div>
<div class="pseudoProgressPlayhead"></div>
<input type="range" min="0" max="100" class="songProgressSlider">
</div>
<span class="songDuration">3:51</span>
</div>
<div class="songVolume">
<div class="songVolumeLabelWrapper">
<span class="songVolumeLabel">Volume</span>
<span class="songVolumeValue">10</span>
</div>
<div class="songVolumeSliderWrapper">
<div class="pseudoVolumeBackground"></div>
<div class="pseudoVolumeIndicator"></div>
<div class="pseudoVolumePlayhead"></div>
<input type="range" min="0" max="1" step="0.1" class="songVolumeSlider">
</div>
</div>
</div>
```

## Setting "artist" and "track name" values

Applying metadata to your audio file requires adding data-attributes to your `<audio>` markup. Picobel gets the track name from the regular `title` attribute, and looks for artist information in the `data-artist` attribute. For the demo at the top of this page, the markup looks like this:
Then include the theme's CSS in your project:

```html
<audio src="http://audio.eatenbymonsters.com/reviews/coldWarKids/lostThatEasy.mp3" title="Lost that easy" data-artist="Cold War Kids" controls>
Your browser does not support the <code>audio</code> element.
</audio>
<link rel="stylesheet" href="path/to/picobel.default.css">
```

## Pre-made themes

Picobel comes with many pre-made themes. To use a theme, make sure you've downloaded the correct stylesheet from the [Picobel CSS library](https://github.com/tomhazledine/picobel/tree/master/css) and then reference the chosen theme name as an option when you initialize Picobel in your JS.
Picobel comes with a few pre-made themes (for times when you don't want to style an entire audio player from scratch). To use a theme, make sure you've downloaded the correct stylesheet from the [Picobel CSS library](https://github.com/tomhazledine/picobel/tree/master/src/css) and then reference the chosen theme name as an option when you initialize Picobel in your JS.

```html
<!-- Initialise Picobel with a theme-->
<!-- Load the theme's stylesheet -->
<link rel="stylesheet" href="path/to/picobel.default.css">

<!-- Initialise Picobel with a theme -->
<script>
Picobel( { theme: "chosenThemeName" } );
Picobel( { theme: "default" } );
</script>
```

So if you wanted to use the "iTunes" theme, your Picobel call would look like this: `Picobel({theme:"itunes"});`. If you don't explicitly choose a theme, then the Default theme will be used. The current options are: `skeleton`, `itunes`, `bbc`, `soundcloud`, `pitchfork`, & `eatenbymonsters`.
So if you wanted to use the "iTunes" theme, your Picobel call would look like this: `Picobel({theme:"itunes"});`. If you don't explicitly choose a theme, then the Default theme will be used. The current options supported by Picobel v3 are: `skeleton` & `default`.

You can see them all in action in the [Picobel.js CodePen Collection](http://codepen.io/collection/XpZEor/), and see screenshots of each featured theme on this page:

Expand All @@ -182,25 +101,4 @@ _Default theme. [View the this theme on CodePen](http://codepen.io/tomhazledine/
![Skeleton theme](images/theme_skeleton.png)
_Skeleton theme (use this as a jumping-off point for your own styles). [View the this theme on CodePen](http://codepen.io/tomhazledine/pen/zZXyGa)_

![BBC iPlayer theme](images/theme_bbc.png)
_BBC iPlayer-esque theme. [View the this theme on CodePen](http://codepen.io/tomhazledine/pen/kXZaKL)_

![iTunes theme](images/theme_itunes.png)
_iTunes-esque theme. [View the this theme on CodePen](http://codepen.io/tomhazledine/pen/NAyWQW)_

![Soundcloud theme](images/theme_soundcloud.png)
_Soundcloud-esque theme. [View the this theme on CodePen](http://codepen.io/tomhazledine/pen/VpNqjJ)_

![Pitchfork theme](images/theme_pitchfork.png)
_Pitchfork-esque theme. [View the this theme on CodePen](http://codepen.io/tomhazledine/pen/OpGrXN)_

![Eaten by Monsters theme](images/theme_ebm.png)
_Eaten by Monsters theme. [View the this theme on CodePen](http://codepen.io/tomhazledine/pen/gmyZLP)_

## Contribute

This started out as a "scratch your own itch" tool for a specific project. I'm open-sourcing it in the hope it might prove useful to others too. There are _a few_ audio player tools/plugins out there, but most have too many features for my needs. I like simplicity, and I like any JS I add to my sites to be as lean as possible.

I'm hoping Picobel can be of use to as many people as possible. If you have an improvement or bug-fix or new feature, get in touch! Make a pull request on the [Picobel.js Github repo](https://github.com/tomhazledine/picobel). I'm just getting started with "open source", so I'd be very glad of any help or suggestions or advice.

Read more about contribute in this project's [Contribution Guide](https://github.com/tomhazledine/picobel/blob/master/CONTRIBUTING.md)
**Note:** several other themes were available with <=v2 of Picobel, but have been removed in v3. If you need access to these themes, you can still use Picobel v2.1.0. They will return to v3 soon along with a detailed migration guide for upgrading to v3.
Loading
Loading