How to add Semantic-UI to Phoenix

Question

How do I add Semantic-UI to Phoenix?

Semantic-UI is installed in a folder and updated using NPM, and the actual CSS and Javascript files are built using GULP. Where should the full install folder be placed?

Can it be automatically updated through Mix like the rest of the dependencies?

Should the generated css and javascript be placed in project/web/static/css (or /js) or /vendor?

How do set up Gulp/Sematic-UI configuration to automatically put the files in the right places?

Again, can Mix run Gulp/Semantic-UI build automatically?

Answer 1

Where should the full install folder be placed?

Actually, you just need 2 files: semantic.js & semantic.css. if you did npm install --save semantic-ui you should find them in ./semantic/dist/

So, where should these 2 files be placed? It depends on ... are you brunch or webpack? What is relevant to a phoenix app is to find the static files (css, js, font, img, ...) in the ./priv/static folder as you can see in the endpoint.ex Plug.Static. Phoenix is not aware of the directory where you did put these files before running brunch, webpack or/and gulp.

Can it be automatically updated through Mix ...

Yes, add a script in package.json, modify the watchers in config/dev.exs

Should the generated css and javascript be placed in project/web/static/css (or /js) or /vendor?

Same answer, are you brunch or webpack? What is relevant to a phoenix app is to find the static files (css, js, font, img, ...) in the ./priv/static folder as you can see in the endpoint.ex Plug.Static. Phoenix is not aware of the directory where you did put these files before running brunch, webpack or/and gulp.

How do set up Gulp/Sematic-UI configuration to automatically put the files in the right places?

Check out the file ./semantic.json to set up the output of the gulp build command.

can Mix run Gulp/Semantic-UI build automatically?

Yes, add a script in package.json, modify the watchers in config/dev.exs

This is not easy, and I recommend you to first start using npm semantic-ui-css and when your build works well to switch to npm semantic-ui

Answer 2

It is quite easy to integrate Semantic UI LESS only Distribution with Phoenix application with a bit of a trick. I would suggest you to use Webpack instead of brunch/gulp as it is relatively popular with lot of plugins and easy to configure.

Before starting with the procedure, it is expected that the Phoenix App is installed with default Brunch build tool and it's working.

Integrating Webpack

Please follow my Semantic UI and Webpack integration detailed guide with in-depth step by step procedure. This answer is in reference to this article. Link: How to Integrate Your Phoenix Application with Semantic UI and Webpack

Integrating Semantic UI

Before we install Semantic UI, we need to put some configurations in place. We will create a new semantic-fix file.

vim web/static/lib/semantic-fix.js

Paste the following contents in the semantic-fix.js file which we just created. This file will take care of putting all Semantic UI assets in place for using it with our application

// ----------------------------------------------------
// File: web/static/lib/semantic-fix.js
// ----------------------------------------------------

var fs = require('fs');

// relocate default config
fs.writeFileSync(
  'node_modules/semantic-ui-less/theme.config',
  "@import '../../src/semantic/theme.config';\n",
  'utf8'
);

// fix well known bug with default distribution
fixFontPath('node_modules/semantic-ui-less/themes/default/globals/site.variables');
fixFontPath('node_modules/semantic-ui-less/themes/flat/globals/site.variables');
fixFontPath('node_modules/semantic-ui-less/themes/material/globals/site.variables');

function fixFontPath(filename) {
  var content = fs.readFileSync(filename, 'utf8');
  var newContent = content.replace(
    "@fontPath  : '../../themes/",
    "@fontPath  : '../../../themes/"
  );
  fs.writeFileSync(filename, newContent, 'utf8');
}

We are going to make a custom theme.config file for Semantic UI. Hence change the path location in semantic-fix.js file as follows:

// ----------------------------------------------------
// File: web/static/lib/semantic-fix.js
// ----------------------------------------------------

// Old default code
fs.writeFileSync(
  'node_modules/semantic-ui-less/theme.config',
  "@import '../../src/semantic/theme.config';\n",
  'utf8'
);

Replace it with following code:

// ----------------------------------------------------
// File: web/static/lib/semantic-fix.js
// ----------------------------------------------------

// Relocate default config
fs.writeFileSync(
  'node_modules/semantic-ui-less/theme.config',
  "@import '../../web/static/css/theme.config';\n",
  'utf8'
);

I recently wrote an in-depth step-by-step tutorial to integrate Semantic UI framework with Elixir based Phoenix application and Webpack.

Add semantic-fix.js needs to run on every postinstall callback while installing npm packages. Hence we will place it as follows under package.json scripts section.

// ----------------------------------------------------
// File: package.json
// ----------------------------------------------------

{
  ...
  "scripts": {
    ...
    "postinstall": "node semantic-fix.js",
    ...
  }
  ...
}

Now it's time to install Semantic UI LESS package. After the installation, the semantic-fix.js file will be called from the postinstall script.

npm install --save semantic-ui-less && node semantic-fix.js

After Semantic UI finishes installation, we need to copy the node_modules/semantic-ui-less/theme.config.example to web/static/css/theme.config.

cp node_modules/semantic-ui-less/theme.config.example web/static/css/theme.config

Override the existing paths to our paths

/* Path to site override folder */
@siteFolder  : '../../web/static/css/site';

&

// @import "theme.less";
@import "~semantic-ui-less/theme.less";

Copy semantic LESS initialising file node_modules/semantic-ui-less/semantic.less to web/static/css. This file imports different component styles.

Change the locations for this file's import statements from @import "definitions/...."' to @import "~semantic-ui-less/definitions/...."

Similarly we need to add semantic.js file to web/static/js folder to import all JavaScript components as follows:

//---------------------------------------------
// File: web/statis/js/semantic.js
//---------------------------------------------

import 'semantic-ui-less/definitions/globals/site';
import 'semantic-ui-less/definitions/behaviors/api';
import 'semantic-ui-less/definitions/behaviors/colorize';
import 'semantic-ui-less/definitions/behaviors/form';
import 'semantic-ui-less/definitions/behaviors/state';
import 'semantic-ui-less/definitions/behaviors/visibility';
import 'semantic-ui-less/definitions/behaviors/visit';

import 'semantic-ui-less/definitions/modules/accordion';
import 'semantic-ui-less/definitions/modules/checkbox';
import 'semantic-ui-less/definitions/modules/dimmer';
import 'semantic-ui-less/definitions/modules/dropdown';
import 'semantic-ui-less/definitions/modules/embed';
import 'semantic-ui-less/definitions/modules/modal';
import 'semantic-ui-leKaabilss/definitions/modules/nag';
import 'semantic-ui-less/definitions/modules/popup';
import 'semantic-ui-less/definitions/modules/progress';
import 'semantic-ui-less/definitions/modules/rating';
import 'semantic-ui-less/definitions/modules/search';
import 'semantic-ui-less/definitions/modules/shape';
import 'semantic-ui-less/definitions/modules/sidebar';
import 'semantic-ui-less/definitions/modules/sticky';
import 'semantic-ui-less/definitions/modules/tab';
import 'semantic-ui-less/definitions/modules/transition';
import 'semantic-ui-less/definitions/modules/video';

web/static/js/app.js is the entry file in our webpack config. Hence we need to import all the files including Semantic UI files to app.js. Add the following lines at the end of app.js file

//---------------------------------------------
// File: web/statis/js/app.js
//---------------------------------------------

...
...

import "./semantic.js";
import '../css/semantic.less';

The integration is now complete and ready to run. Semantic UI is now completely intergrated with webpack and it's time to give it a try. Run the Phoenix server mix phoenix.server from project root. It should trigger webpack to compile all the files including semantic-ui - mix phoenix.server

This procedure is documented in more detail in my article (Linked on the top) which can be referred if there is any confusion.

Hope that helps.