1.1.0 • Published 6 years ago

plaza-ui v1.1.0

Weekly downloads
-
License
ISC
Repository
-
Last release
6 years ago

Plaza UI

Plaza UI is a CSS framework built on Bootstrap 4 and adds custom components.

The framework is used to power Plaza (main deployment: <www.zwangerenportaal.nl>), its mobile app, and any sub-sites (support, signup, etc).

Getting started

git clone git@github.com:linkorb/plaza-ui.git
cd plaza-ui
npm install
npm run storybook

You can now browse the storybook using your browser on https://localhost:6006

Libraries and technologies used:

  • npm for dependency management
  • webpack 4 for bundling all .scss files into dist/plaza.css
  • storybook for UI development, previewing, testing
  • SASS for super-powered CSS
  • handlebars for HTML snippets, previews and page layouts

Directory layout:

  • .storybook/: Storybook configuration and story loading code. Contains custom webpack.config.js (for handlebars, scss, etc loading) and preview-head.html to include custom header code in your preview iframes (restart required)
  • dist/: The build artifacts from npm build. Not checked into git, it's contents are generated
  • src/bootstrap/: Bootstrap templates (.handlebars) for previewing and bootstrap theme overrides (.scss)
  • src/elements/: Custom element templates and scss (elements are smaller than components)
  • src/components/: Custom element templates and scss. Components are complete reusable blocks (like cards, navigation menus, footers, etc). Optionally contains .json files to inject data into the templates while previewing with Storybook
  • src/pages/: Complete pages (i.e. frontpage, contact, etc). Composed using components (by including them through handlebars "partials"). Optionally contains .json files with data for this page preview in Storybook.
  • src/data/: .json files that can be imported/reused from .json files in other directories.

Coding conventions

  • Use Bootstrap classes where provided. I.e. use btn btn-primary for primary buttons - Don't create custom button classes.
  • The templates/pages templates should simply include complete components, without any custom HTML/CSS
  • Feed data into handlebars templates by creating a file next to the handlebars file with the same name, but a .json extension. Storybook will pick up the data in the .json file and feed it into the template.
  • Ensure that every component has a working preview in Storybook. Add a .json file if the component needs data.
  • Component-specific CSS should be added in templates/components by creating a file named the same as the handlebars file, with a .scss extension. This .scss file should only target classes in the component, not introducing any side effects
  • Global CSS (i.e. font names, page background color, etc) should be added in core/core.scss including clear code comments about the effect of the CSS declaration.
  • Add storybook knobs for any components or elements that could be worth checking with different data (i.e. headers, button labels, etc)
  • Generated components, pages, etc should work equally well on both desktop, tablets and mobile phone
  • Include partials by using their filename relative to the src/ directory. Don't use relative paths like ../components/example
  • All filenames are lower-case. Use dashes for spacing.

Theming bootstrap

See Bootstrap theming:

  • Overide any bootstrap variables in src/main.scss
  • Add a .handlebars and a .scss file in bootstrap/ for the elements you are styling. This way you can preview your edits in Storybook
  • Try to minimize the amount of custom CSS in bootstrap/*.scss files. Often you can use Bootstrap variables to achieve what you want.
  • In general, use the predefined bootstrap variables where possible.
  • Don't use any hard-coded colors. Use bootstrap variables like theme-color('primary'), $gray-400 etc
  • Use the $border-radius variable for anything that could use rounded corners (i.e. cards, widgets, etc). This way the radius behaviour can be centrally configured

Phases

Phase 1:

  • Create a fully functional templates/pages/frontpage.html.hbs that looks identical to the current http://www.zwangerenportaal.nl/ frontpage
    • Top bar with logo, search, language and user boxes
    • Navigation bar (dynamic, based on JSON data)
    • Main feed with "Content Card" components.
    • First sidebar feed (Populair today) with "Content Card" components.
    • Right sidebar components (MyWeekWidget, ProviderWidget, AppointmentWidget, Social media links)
    • Footer with "About us", "Recent content" (based on JSON data), "Languages" and Social Media links
    • Final Footer with copyright, faq, terms+conditions, privacy statement and cookie declaration links

Phase 2

Phase 3

Note: you can actually use the "Betalen met iDeal" (pay with iDeal) button to pay for a subscription, it's in a "sandbox" mode, so you won't need to enter any real payment information.

Questions

How is this repository used?

Using npm build the file dist/plaza.css will be generated. This CSS file will be used in all of our plaza related projects.

We'll be transitioning our main application (plaza) in three fases:

  1. Replace all CSS in Plaza with dist/plaza.css while still using PHP+Twig
  2. Replace all Twig templates with the handlebars templates in this repository
  3. Build a React-based frontend+mobile app, also importing dist/plaza.css.

This allows us to smoothly transition from our current legacy frontend code (CSS+Twig)

Why build on Bootstrap 4?

Bootstrap 4 gives us a solid foundation for common ui classes for buttons, input widgets, etc. It offers extensive theming options, which we're using in plaza-ui to customize fonts, colors, etc.

Additionally our current templates are built on bootstrap too (v3). This means we can simply replace the CSS without too many manual changes to the templates.

Why handlebars?

Handlebars templating is available in most programming languages. We're using a mix of PHP and JS at the moment. Handlebars allows us to reuse our templates in all of our projects.

Why not React

We are using React in combination with the CSS generated by Plaza-UI for mobile applications. The React apps can simply use classnames defined by plaza-ui, and won't be needing any other CSS solutions (styled components, css-modules, etc)

Why not CSS-in-JS?

Styled components, Glamour, Emotion etc are all really cool libraries for managing styles.

In this project we've chosen not to use it, as we wanted 1 CSS file as a final deliverable. Most CSS-in-JS solutions generate their CSS per request, meaning you'll never have 1 full CSS file of all classes you're using in a project. This is both a pro and a con. In our case it's a con, as we will be using this CSS in more traditional applications that generate their templates serverside using twig, handlebars, etc. For this we really need a single dist/plaza.css to work.

Publishing to github pages

Use the following command to build a static storybook deployment and publish it to github pages:

npm run publish

It will be published to https://linkorb.github.io/plaza-ui

Building for distribution

To generate the dist/ directory:

npm run dist
@infinitebrahmanuniverse/nolb-plaz@everything-registry/sub-chunk-2446@zalastax/nolb-plaz
1.1.0

6 years ago

1.0.0

6 years ago