diff --git a/.meta-files/images/Hero-Screenshot.png b/.meta-files/images/Hero-Screenshot.png new file mode 100644 index 0000000..7297eb4 Binary files /dev/null and b/.meta-files/images/Hero-Screenshot.png differ diff --git a/changelog.md b/changelog.md index f769baa..b339183 100644 --- a/changelog.md +++ b/changelog.md @@ -1,3 +1,7 @@ +## 0.15.1 + +- Fixed the + ## 0.15.0 - POTENTIALLY BREAKING CHANGE: Modified the way the GUI elements are constructed internally. If you're modifying the internals in your CSS, make sure everything looks right! diff --git a/package.json b/package.json index c0cebcf..4194239 100755 --- a/package.json +++ b/package.json @@ -2,16 +2,19 @@ "//": "--------------- Script Info --------------- ", "name": "guify", "author": "Jonathan Cole ", - "version": "0.15.0", + "version": "0.15.1", "description": "A simple GUI for inspecting and changing JS variables", "keywords": [ "gui", + "ui", "inspect", "inspector", "bind", - "ui", + "binding", "project", - "creative coding" + "creative coding", + "p5", + "three" ], "repository": { "type": "git", @@ -26,11 +29,11 @@ "scripts": { "build:prod": "webpack --mode=production", "build:dev": "webpack --mode=development --progress", + "buildall": "npm-run-all build:prod build:dev", "build:dev:watch": "webpack --mode=development --progress --watch", "serve": "webpack serve --mode=development", "develop": "npm-run-all --parallel build:dev:watch serve", "test": "mocha --require @babel/register --colors ./test/*.spec.js", - "buildall": "npm-run-all build:prod build:dev", "prepublish": "npm run-script buildall", "ci": "npm run-script buildall", "lint": "eslint ." diff --git a/readme.md b/readme.md index 0255a7e..36b9480 100644 --- a/readme.md +++ b/readme.md @@ -1,7 +1,7 @@ # guify

- +

npm version @@ -9,31 +9,62 @@

Demo + | + Docs

-Guify provides you a simple GUI for your JS code. I made this because there wasn't anything really good for quick GUI creation for things like [three.js](https://threejs.org/) or [p5.js](https://p5js.org/) projects. +Guify is a runtime JS library that gives you a simple way to build a GUI for your JS projects. It pairs very well with [three.js](https://threejs.org/) and [p5.js](https://p5js.org/). Consider it an opinionated take on [dat.GUI](https://github.com/dataarts/dat.gui). -Guify gives you toast notifications, as well as an optional header bar to give your project a "web app" look. Each component of the GUI can be bound to a variable so you don't have to manually poll its state. +Here are the big features: -Guify is designed to be accessibility-friendly, but I don't have a good way to test it. If something doesn't work for you, please file an issue and I'll do my best to help! - -[Check out the React version!](https://github.com/dbismut/react-guify) +* Bind any UI component to any variable. Guify supports arbitrary text inputs, colors, ranges, file inputs, booleans, and more. +* Guify is easy to graft onto any page and integrate with your existing JS code. Just point your components at the variables you already have: + ```js + var someVariable = 0; + guify.Register([{ + { + type: 'range', + object: this, property: 'someProperty', + label: 'Some Property', + min: 0, max: 20, step: 1 + }, + }]) + ``` +* Give it that "web app" look with an optional header bar and easy toast notifications. +* Style it however you'd like. You can use one of three built-in themes, or build your own to get exactly the look you want. +--- ## Installation -`npm install --save guify`, or copy `guify.js` from [`/lib`](/lib). +Below are some common ways to integrate Guify with your setup. -## Usage -For browser projects, you can use the transpiled version in [`/lib`](/lib). -If you're working with ES6 (for example, in a Node project), you can -use the files at [`/src`](/src) directly. +### Quick Start (Browser) + +To integrate on an existing page, you can use the transpiled version in [`/lib`](/lib), either by including it with your files or using a CDN: + +```html + +``` + +This adds a `guify` function at the global level, which you can use to construct the GUI. For example: + +```html + + + +``` + +See the Usage guide below for more details. [example.html](/example/index.html) also demonstrates this pattern. -The API can be found at [/docs/api.md](/docs/api.md). +### Quick Start (NPM) +First, install with NPM: `npm install --save guify` -### Quick Start -First import using either `require` or ES6 imports: +Then you can import using either `require` or `import` depending on your preference: ```js // ES6 import guify from 'guify' @@ -43,32 +74,72 @@ let guify = require('guify'); ``` Then you can make a quick GUI this way: +```js +var gui = new guify({ ... }); +gui.Register([ ... ]); +``` + +See the Usage guide below for more details. + +### Quick Start (React) + +Check out the unofficial [React port](https://github.com/dbismut/react-guify). + +--- + +## Usage + +Once you have Guify available to construct in your project, make a `guify` instance: + ```js var gui = new guify({ title: "Some Title", - align: 'right', - theme: 'light' }); +``` + +The various controls in Guify are called "components". You can feed component definitions to Guify as follows: +```js gui.Register([ - { + { // A slider representing a value between 0 and 20 type: 'range', label: 'Range', - min: 0, max: 20, step: 1 + min: 0, max: 20, step: 1, + onChange: (value) => { + console.log(value); + } }, { - type: 'button', label: 'Button' + type: 'button', label: 'Button', + action: () => { + console.log('Button clicked!'); + } }, { - type: 'checkbox', label: 'Checkbox' + type: 'checkbox', label: 'Checkbox', + onChange: (value) => { + console.log(value); + } } ]); ``` -See [example.html](/example/index.html) for a more complete example. +You can also bind components representing a value to your JS variables instead of using an `onChange()` handler. For example: + +```js +var someNumber = 10; +gui.Register([ + { // A slider representing `someNumber`, constrained between 0 and 20. + type: 'range', label: 'Range', + min: 0, max: 20, step: 1, + object: this, property: 'someNumber' + }, +``` + +There are many points of customization here. See the docs at [/docs/api.md](/docs/api.md). A much more robust example can also be found at [example.html](/example/index.html). ### Building This Package -If you want to build this package, you can run `npm install` and then `npm run build`, which will create `/lib/guify.min.js`. +If you want to build this package, you can run `npm install` and then `npm run build:prod`, which will create `/lib/guify.min.js`. NPM commands: @@ -76,6 +147,8 @@ NPM commands: - `build:dev`: Creates `/lib/guify.js`. - `develop`: Runs `build:dev` and serves the `/example` directory as a static web page. +--- + ## Changelog See [changelog.md](/changelog.md). @@ -89,5 +162,6 @@ This package is largely based on [control-panel](https://github.com/freeman-lab/ For setting this up, I used [webpack-library-starter](https://github.com/krasimir/webpack-library-starter). ## Alternatives -- [Dat.GUI](https://github.com/dataarts/dat.gui) +- [dat.GUI](https://github.com/dataarts/dat.gui) - [Control-Panel](https://github.com/freeman-lab/control-panel) +- [Oui](https://github.com/wearekuva/oui)