Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/valerauko/checkbox-tree-example

React / reagent / re-frame example using the CheckboxTree component
https://github.com/valerauko/checkbox-tree-example
clojurescript example hacktoberfest re-frame react reagent
Last synced: 13 days ago
JSON representation
React / reagent / re-frame example using the CheckboxTree component
Host: GitHub
URL: https://github.com/valerauko/checkbox-tree-example
Owner: valerauko
Created: 2020-06-11T13:37:22.000Z (over 4 years ago)
Default Branch: master
Last Pushed: 2024-06-19T03:12:16.000Z (5 months ago)
Last Synced: 2024-06-19T10:36:50.628Z (5 months ago)
Topics: clojurescript, example, hacktoberfest, re-frame, react, reagent
Language: Clojure
Homepage:
Size: 104 KB
Stars: 1
Watchers: 1
Forks: 0
Open Issues: 1
Metadata Files:
- Readme: README.md
Awesome Lists containing this project

README

        # CheckboxTree example

A [re-frame](https://github.com/day8/re-frame) application example of using the [CheckboxTree](https://github.com/jakezatecky/react-checkbox-tree) React component.

![image](https://user-images.githubusercontent.com/6322484/84403165-5ad4c780-ac40-11ea-9f57-177b686cdbf1.png)

## Getting Started

### Project Overview

* Architecture:

[Single Page Application (SPA)](https://en.wikipedia.org/wiki/Single-page_application)

* Languages

  - Front end ([re-frame](https://github.com/day8/re-frame)): [ClojureScript](https://clojurescript.org/) (CLJS)

* Dependencies

  - UI framework: [re-frame](https://github.com/day8/re-frame)

  ([docs](https://github.com/day8/re-frame/blob/master/docs/README.md),

  [FAQs](https://github.com/day8/re-frame/blob/master/docs/FAQs/README.md)) ->

  [Reagent](https://github.com/reagent-project/reagent) ->

  [React](https://github.com/facebook/react)

* Build tools

  - Project task & dependency management: [Leiningen](https://github.com/technomancy/leiningen)

  - CLJS compilation, REPL, & hot reload: [`shadow-cljs`](https://github.com/thheller/shadow-cljs)

* Development tools

  - Debugging: [CLJS DevTools](https://github.com/binaryage/cljs-devtools)

#### Directory structure

* [`/`](/../../): project config files

* [`dev/`](dev/): source files compiled only with the [dev](#running-the-app) profile

  - [`cljs/user.cljs`](dev/cljs/user.cljs): symbols for use during development in the

[ClojureScript REPL](#connecting-to-the-browser-repl-from-a-terminal)

* [`resources/public/`](resources/public/): SPA root directory;

[dev](#running-the-app) / [prod](#production) profile depends on the most recent build

  - [`index.html`](resources/public/index.html): SPA home page

    - Dynamic SPA content rendered in the following `div`:

        ```html

        


        ```

    - Customizable; add headers, footers, links to other scripts and styles, etc.

  - Generated directories and files

    - Created on build with either the [dev](#running-the-app) or [prod](#production) profile

    - Deleted on `lein clean` (run by all `lein` aliases before building)

    - `js/compiled/`: compiled CLJS (`shadow-cljs`)

      - Not tracked in source control; see [`.gitignore`](.gitignore)

* [`src/cljs/checkbox_tree/`](src/cljs/checkbox_tree/): SPA source files (ClojureScript,

[re-frame](https://github.com/Day8/re-frame))

  - [`core.cljs`](src/cljs/checkbox_tree/core.cljs): contains the SPA entry point, `init`

### Editor/IDE

Use your preferred editor or IDE that supports Clojure/ClojureScript development. See

[Clojure tools](https://clojure.org/community/resources#_clojure_tools) for some popular options.

### Environment Setup

1. Install [JDK 8 or later](https://openjdk.java.net/install/) (Java Development Kit)

2. Install [Leiningen](https://leiningen.org/#install) (Clojure/ClojureScript project task &

dependency management)

3. Install [Node.js](https://nodejs.org/) (JavaScript runtime environment) which should include

   [NPM](https://docs.npmjs.com/cli/npm) or if your Node.js installation does not include NPM also install it.

7. Clone this repo and open a terminal in the `checkbox-tree` project root directory

8. (Optional) Download project dependencies:

    ```sh

    lein deps

    ```

### Browser Setup

Browser caching should be disabled when developer tools are open to prevent interference with

[`shadow-cljs`](https://github.com/thheller/shadow-cljs) hot reloading.

Custom formatters must be enabled in the browser before

[CLJS DevTools](https://github.com/binaryage/cljs-devtools) can display ClojureScript data in the

console in a more readable way.

#### Chrome/Chromium

1. Open [DevTools](https://developers.google.com/web/tools/chrome-devtools/) (Linux/Windows: `F12`

or `Ctrl-Shift-I`; macOS: `⌘-Option-I`)

2. Open DevTools Settings (Linux/Windows: `?` or `F1`; macOS: `?` or `Fn+F1`)

3. Select `Preferences` in the navigation menu on the left, if it is not already selected

4. Under the `Network` heading, enable the `Disable cache (while DevTools is open)` option

5. Under the `Console` heading, enable the `Enable custom formatters` option

#### Firefox

1. Open [Developer Tools](https://developer.mozilla.org/en-US/docs/Tools) (Linux/Windows: `F12` or

`Ctrl-Shift-I`; macOS: `⌘-Option-I`)

2. Open [Developer Tools Settings](https://developer.mozilla.org/en-US/docs/Tools/Settings)

(Linux/macOS/Windows: `F1`)

3. Under the `Advanced settings` heading, enable the `Disable HTTP Cache (when toolbox is open)`

option

Unfortunately, Firefox does not yet support custom formatters in their devtools. For updates, follow

the enhancement request in their bug tracker:

[1262914 - Add support for Custom Formatters in devtools](https://bugzilla.mozilla.org/show_bug.cgi?id=1262914).

## Development

### Running the App

Start a temporary local web server, build the app with the `dev` profile, and serve the app with

hot reload:

```sh

lein dev

```

Please be patient; it may take over 20 seconds to see any output, and over 40 seconds to complete.

When `[:app] Build completed` appears in the output, browse to

[http://localhost:8280/](http://localhost:8280/).

[`shadow-cljs`](https://github.com/thheller/shadow-cljs) will automatically push ClojureScript code

changes to your browser on save. To prevent a few common issues, see

[Hot Reload in ClojureScript: Things to avoid](https://code.thheller.com/blog/shadow-cljs/2019/08/25/hot-reload-in-clojurescript.html#things-to-avoid).

Opening the app in your browser starts a

[ClojureScript browser REPL](https://clojurescript.org/reference/repl#using-the-browser-as-an-evaluation-environment),

to which you may now connect.

#### Connecting to the browser REPL from your editor

See

[Shadow CLJS User's Guide: Editor Integration](https://shadow-cljs.github.io/docs/UsersGuide.html#_editor_integration).

Note that `lein dev` runs `shadow-cljs watch` for you, and that this project's running build id is

`app`, or the keyword `:app` in a Clojure context.

Alternatively, search the web for info on connecting to a `shadow-cljs` ClojureScript browser REPL

from your editor and configuration.

For example, in Vim / Neovim with `fireplace.vim`

1. Open a `.cljs` file in the project to activate `fireplace.vim`

2. In normal mode, execute the `Piggieback` command with this project's running build id, `:app`:

    ```vim

    :Piggieback :app

    ```

#### Connecting to the browser REPL from a terminal

1. Connect to the `shadow-cljs` nREPL:

    ```sh

    lein repl :connect localhost:8777

    ```

    The REPL prompt, `shadow.user=>`, indicates that is a Clojure REPL, not ClojureScript.

2. In the REPL, switch the session to this project's running build id, `:app`:

    ```clj

    (shadow.cljs.devtools.api/nrepl-select :app)

    ```

    The REPL prompt changes to `cljs.user=>`, indicating that this is now a ClojureScript REPL.

3. See [`user.cljs`](dev/cljs/user.cljs) for symbols that are immediately accessible in the REPL

without needing to `require`.

### Running `shadow-cljs` Actions

See a list of [`shadow-cljs CLI`](https://shadow-cljs.github.io/docs/UsersGuide.html#_command_line)

actions:

```sh

lein run -m shadow.cljs.devtools.cli --help

```

Please be patient; it may take over 10 seconds to see any output. Also note that some actions shown

may not actually be supported, outputting "Unknown action." when run.

Run a shadow-cljs action on this project's build id (without the colon, just `app`):

```sh

lein run -m shadow.cljs.devtools.cli  app

```

### Debug Logging

The `debug?` variable in [`config.cljs`](src/cljs/checkbox_tree/config.cljs) defaults to `true` in

[`dev`](#running-the-app) builds, and `false` in [`prod`](#production) builds.

Use `debug?` for logging or other tasks that should run only on `dev` builds:

```clj

(ns checkbox-tree.example

  (:require [checkbox-tree.config :as config])

(when config/debug?

  (println "This message will appear in the browser console only on dev builds."))

```

## Production

Build the app with the `prod` profile:

```sh

lein prod

```

Please be patient; it may take over 15 seconds to see any output, and over 30 seconds to complete.

The `resources/public/js/compiled` directory is created, containing the compiled `app.js` and

`manifest.edn` files.

The [`resources/public`](resources/public/) directory contains the complete, production web front

end of your app.

Always inspect the `resources/public/js/compiled` directory prior to deploying the app. Running any

`lein` alias in this project after `lein dev` will, at the very least, run `lein clean`, which

deletes this generated directory. Further, running `lein dev` will generate many, much larger

development versions of the files in this directory.