Forem: Ben Sharman

Customise a new Phoenix app (Part 2 - Style)

Ben Sharman — Thu, 27 Jun 2019 00:42:15 +0000

TL;DR try CustomPhx - GitHub in a new Phoenix project to automate Tailwindcss installation and HTML generation.

In Part 1 of this series we updated both mix and NPM dependencies in a new Phoenix project. Let's continue our customisations with some style!

You generate a new Phoenix project. Do you continue building on top of the default styles? or choose your own adventure?

Phoenix Default

Since Phoenix 1.4, all new projects include the minimal CSS framework Milligram in assets/phoenix.css. This provides classless markup for any HTML generated with mix phx.gen.html.

Style with Milligram

You chose Milligram!

You have sensible defaults and can use the generators to get up and running quickly.

To theme your project write custom classes and add them to your markup. Check out Awesome Milligram for additional resources.

Style with something else

You chose to replace Milligram!

You have options. Lots of options. Start with this categorised list Awesome CSS Frameworks.

Installation instructions are specific to each framework but if it comes with a pre-processor (LESS, SCSS, SASS, PostCSS) you'll need to install a loader to package.json and configure it in webpack.config.js. See Webpack Loaders - Styling.

Unfortunately, the Phoenix HTML generated files will look unstyled and may require significant markup changes and additional classes to look good in a new framework. Alternatively you can Customise your Phoenix HTML Generator.

Style with Tailwindcss

I chose Tailwindcss!

This utility-first framework recently matured into a 1.0 release and has quite a buzz around it (fully justified IMO).

For a basic install see the excellent Using Tailwind with Phoenix guide.

For a more comprehensive approach i've created a mix archive to automate installation with a custom HTML generator CustomPhx - GitHub. Give it a try!

Generated form field markup

<%= label class: "block mb-6" do %>
  <span class="form-label block">name</span>
  <%= text_input f, :name, class: "form-input w-full mt-1" %>
<% end %>
<%= error_tag f, :name %>

Generated form

Customise a new Phoenix app (Part 1 - Outdated Packages)

Ben Sharman — Sat, 15 Jun 2019 08:37:29 +0000

At the end of the Phoenix Up and Running Guide it logically suggests
The next step is customising our application just a bit… and whisks you away to learn about Adding Pages. I'd like to recommend a few extra steps of customisation to get familiar with before building out a new application.

Outdated packages

Even with a shiny new Phoenix project generated from the latest archive your hex and npm dependencies are likely to contain old or insecure versions. Perform these checks immediately after install and make them part of your maintenance routine.

Find and update outdated Hex dependencies

Run mix hex.outdated to output a table.

Dependency	Current	Latest	Update possible
ecto_sql	3.1.5	3.1.5

If your Update possible column is clear or contains only Yes then run mix deps.update --all to update all dependencies and compile them.
If any dependencies have a No in the Update possible column then an automated update is not possible. This package has likely broken its API contract with a major version bump. You'll need to check package release notes for the upgrade process.

NOTES:

From the docs: Upgrading a dependency often requires the projects it depends on to upgrade too. In this situation you can update a single dependency and not touch its children.
As an extra precaution run mix hex.audit to show all Hex dependencies that have been marked as retired.

Find and update outdated NPM packages

Run npm outdated from your assets directory to output a table.

Package	Current	Wanted	Latest	Location
css-loader	2.1.1	2.1.1	3.0.0

For consistency, and after being bitten a few times over the years, I recommend directly editing the version numbers in your package.json file to the Latest. For major version bumps check the release notes before upgrading.
Run npm install to add the new packages in /node_modules, generate an updated package.lock.json and output a security report summary from npm audit.

audited 14403 packages in 6.166s
found 4 vulnerabilities (2 low, 1 moderate, 1 high)
  run `npm audit fix` to fix them, or `npm audit` for details

If you have any vulnerabilities then run npm audit to get more details on each one. I'm cautious to automate this process and prefer to upgrade the packages manually in package.json. In your case and especially if this is a new project try npm audit fix to update packages without breaking changes or npm audit fix --force to install breaking changes.

NOTES: The output from npm outdated may not list all potential updates. A workaround for VSCode users is to hover over each package in package.json to get a tooltip about that package with the latest version (other editors may require extensions).

Look out for Customise a new Phoenix app (Part 2 - Style) coming soon. I'm bringing some style to your new app by replacing the default CSS framework Milligram with Tailwindcss and sharing some tips on avoiding spaghetti CSS.

Do you have any customisations you like to perform after a new Phoenix install?

Customise your Phoenix HTML Generator

Ben Sharman — Fri, 10 Mar 2017 19:26:20 +0000

Generator Hostel Dublin by Rosa G

NOTE: 2019 update in progress... Phoenix 1.4 and Tailwindcss ftw

What’s it all about?

Scaffolding with Phoenix generators, especially with mix phx.gen.html, is a great way start out a project. Not only do you get a resource all wired up for CRUD it also provides unit tests and demonstrates best practices.

All this sounds great so why did I stop using such a powerful ally after that initial burst of enthusiasm? I think the main reason was the desire to take off the proverbial training wheels provided by the generator and get writing some sweet Elixir code. My confidence was up and going it alone was aided by a helpful feedback loop of error messages and stack traces.

The fundamental point i’d completely missed of using a generator with templates is achieving consistency through automation. Consistency is one of the keys to a maintainable codebase and also happens to be the basis of a great UX. By customising the Phoenix HTML generator maybe I can achieve both of these goals.

The scenario

Being an opinionated software engineer I’ve decided my new CRUD project will use Milligram, a minimalist css framework, instead of the standard bootstrap css used by Phoenix and most of the web. Making that one simple decision renders the standard Phoenix HTML generator pretty useless.

One of many solutions

Replace the standard mix phx.gen.html with a project specific generator and templates. The templates can then be updated and re-used to generate each new resource I add with the latest styles and layout.

Let’s do it!

Create a new Phoenix 1.3 project

mix phx.new boiler && cd boiler

Replace assets/css/phoenix.css with milligram.css
Make the templates and mix task project directories

mkdir -p priv/templates/boiler.gen.html && mkdir -p lib/boiler/mix/tasks

Copy all current HTML generator templates to the new project templates directory

cp -a deps/phoenix/priv/templates/phx.gen.html/. priv/templates/boiler.gen.html

Copy the current generator task to the new project tasks directory

cp deps/phoenix/lib/mix/tasks/phx.gen.html.ex lib/boiler/mix/tasks/boiler.gen.html.ex

Open lib/boiler/mix/tasks/boiler.gen.html.ex in your favourite editor and update the module name to Mix.Tasks.Boiler.Gen.Html
In the same file search / replace all instances of lowercase phx with boiler
Check that your code compiles and you have a boiler project mix task

mix compile && mix help | grep boiler

If all went well you should see our new mix task listed as mix boiler.gen.html

Its time to edit the eex templates in priv/templates/boiler.gen.html using Milligram classes and any markup changes before using our new generator command.

Milligram uses a different grid system to bootstrap so we also need to update lib/boiler/web/templates/layout/app.html.eex

Its generate time!

Use our new mix task as you would with the Phoenix generator.

mix boiler.gen.html Accounts User users name:string email:string phone:string

Follow the instructions to add the resource to the router and run the migrations.

Start the server with mix phx.server and visit http://localhost:4000/users to see your custom generated HTML templates in action.

Don’t stop now

This is a small example of generating custom markup for a CRUD app but its only a taster of what’s possible.

Are you using Phoenix custom generators in creative ways?

Thanks for reading!

The repo can be found at https://github.com/mutablestate/boiler