Readme — fulcrologic/semantic-ui-react-wrappers 2.0.4

Liking cljdoc? Tell your friends :D

NOTICE: If you use shadow-cljs for your compiler, you can use the NPM modules directly. The online documentation for Semantic and the compiler are quite good. This library is primarily useful in that it provides IDE docstrings.

If you’re using Fulcro with shadow-cljs, then instead of this library you can simply do these steps:

lein new fulcro app shadow-cljs nodemo
npm install semantic-ui-react --save
npm install

Then in some namespace:

(ns your-app
  (:require
    [fulcro.client.dom :as dom]
    ["semantic-ui-react" :refer [Dropdown DropdownItem DropdownMenu]]))

(defn ui-dropdown [& args] (dom/macro-create-element Dropdown args))
(defn ui-dropdown-menu [& args] (dom/macro-create-element DropdownMenu args))
(defn ui-dropdown-item [& args] (dom/macro-create-element DropdownItem args))

(defsc SomeComponent [this props]
  (ui-dropdown {:text "Filter"}
    (ui-dropdown-menu {}
      (ui-dropdown-item {} "A")
      (ui-dropdown-item {} "B"))))

You can also require individual modules with this approach by doing require on the module files instead of the top-level semantic-ui-react name, which can result in a much smaller production build.

It is possible to do this optimization in this library by splitting things into namespaces that do those requires, if a contributor is interested in helping make that change.

Semantic UI Wrapper

A library to interface with Semantic UI React. The NPM support in Clojurescript is not yet advanced enough to support using Semantic UI directly, and the cljsjs support leaves a few things to be desired:

You have to extract each component into a local symbol
You have to make a React factory for each element
There are no doc strings

This library is a simple set of cljs wrappers around the cljsjs/semantic-ui-react package that makes it a bit easier to use:

It includes symbols in icons.cljs for all of the icon names (800+)
It includes factory functions in factories.cljs for all of the elements, modules, etc.
The names are prefixed with ui- and converted from camel-case to hyphenated names.
The factory functions have doc strings that summarize the props available

Usage

Add the dependency to you project. Be sure to include your desired version of semantic-ui-react as well. The latest version of both are:
Make sure you’ve include the semantic UI CSS (via CDN or by pulling them from that project)

Use the provided factories and icons!

(ns app.ui
  (:require [fulcrologic.semantic-ui.factories :as f]
            [fulcrologic.semantic-ui.icons :as i])

...
(f/ui-button {:content       "Like"
                  :icon          i/heart-icon
                  :label         {:as "a" :basic true :pointing "right" :content "2,000"}
                  :labelPosition "left"})
...

Porting from Semantic UI React Documentation Examples

Props are required. The factories will convert them to js for you, but if you want every ounce of possible speed you can pre-tag your props with #js. Note that the "nested" elements with dot notation become just hyphenated names (e.g. Button.Group → ui-button-group, and List.List → ui-list-list):

React Version:

<Button
  content='Like'
  icon='heart'
  label={{ as: 'a', basic: true, content: '2,048' }}
  labelPosition='right'/>

<Button.Group>
   <Button icon>
     <Icon name='align left' />
   </Button>
   <Button icon>
     <Icon name='align center' />
   </Button>
   <Button icon>
     <Icon name='align right' />
   </Button>
   <Button icon>
     <Icon name='align justify' />
   </Button>
</Button.Group>

This library:

(f/ui-button {:content       "Like"
              :icon          i/heart-icon ; or just "heart"
              :label         {:as "a" :basic true :content "2,048"}
              :labelPosition "right"}))

(f/ui-button-group nil
  (f/ui-button {:icon true}
    (f/ui-icon {:name i/align-left-icon}))
  (f/ui-button {:icon true}
    (f/ui-icon {:name i/align-center-icon}))
  (f/ui-button {:icon true}
    (f/ui-icon {:name i/align-right-icon}))
  (f/ui-button {:icon true}
    (f/ui-icon {:name i/align-justify-icon})))

Elements, Modules, etc.

The wrappers in the factories namespace create low-level React elements, which use Javascript objects for their props. The docstrings on these symbols are derived from the JSON docstrings extracted from the real semantic-ui-react library.

Icons

The icons namespace simply has symbol definitions for each legal string icon name. This allows you to use your IDE’s code completion to find icon names as long as you can remember something about that name. You may, of course, simply use a known icon name as a string instead.

Using with CLJSJS React

Make sure you have a consistent version of React by analyzing your dependencies. Libraries like Om have direct dependencies on React, as does the cljsjs semantic ui package.

Using with NPM React

Make sure to exclude react from all cljs deps
Add react and react-dom to your npm-deps
Add a foreign lib config to cause the npm version to appear like the cljsjs version

...
        :dependencies [...
                       ;; STEP 1: Make sure React isn't pulled in by dependencies
                       [org.omcljs/om "1.0.0-beta1" :exclusions [cljsjs/react cljsjs/react-dom]]
                       ...]
...
       :cljsbuild    {:builds
                      [{:id           "blah"
                        :source-paths ["src/main"]
                        :compiler     {:asset-path           "js/cards"
                                       :main                 blah.core
                                       :optimizations        :none
                                       :output-dir           "resources/public/js/blah"
                                       :output-to            "resources/public/js/blah.js"
                                       ;; STEP 2: Make the NPM react also acts AS IF it were the cljsjs version
                                       :foreign-libs         [{:provides       ["cljsjs.react"]
                                                               :file           "node_modules/react/dist/react.js"
                                                               :global-exports {cljsjs.react React}}
                                                              {:provides       ["cljsjs.react.dom"]
                                                               :file           "node_modules/react-dom/dist/react-dom.js"
                                                               :global-exports {cljsjs.react.dom ReactDOM}}]
                                       ;; STEP 3: Add in the correct NPM dependencies
                                       :install-deps         true
                                       :npm-deps             {:react                             "15.5.4"
                                                              :react-dom                         "15.5.4"}}}]}
...

Using With shadow-cljs

Shadow-cljs is highly recommended. It has much better integration with the NPM ecosystem, which allows you to easily upgrade your semantic-ui-react dependency without worrying about cljsjs at all. Simply add semantic-ui-react to your package.json:

$ npm install --save-dev semantic-ui-react

Contributing

Ping the Fulcro slack channel with your idea, or create a github issue. It is a good idea to do that before trying to help.

Regenerating Factories

The factories.cljs file is generated (to automatically get the docstrings). The user namespace can be run in a normal Clojure REPL, and contains a comment block at the bottom that has the necessary command. The input files (componentInfo/*.info.json) come from the real Semantic UI React project from github (clone it, install npm deps, and run yarn build:docs to generate it).

LICENSE

MIT Public License

Can you improve this documentation? These fine people already did:
Tony Kay, LiesbethW & flipmokidEdit on GitHub

cljdoc is a website building & hosting documentation for Clojure/Script libraries

Keyboard shortcuts Report a problem cljdoc on GitHub

× close