interface/README.md

   1 # OpenEMR-interface
   2
   3 The OpenEMR-interface uses [Storybook](https://storybook.js.org) to document and standardize the creation of user interface elements. The project is using bootstrap as base and is built with [SASS](https://sass-lang.com/) (compiled with [gulp](https://gulpjs.com/)).
   4
   5 The live version of this guide can be found at [openemr-interface.surge.sh](http://openemr-interface.surge.sh).
   6
   7 ### Themes
   8
   9 Different `themes` share a common `core` and have their own overrides to customize the appearance of OpenEMR. You can view how these themes differ using the "Knobs" tool at the bottom of the storybook interface.
  10
  11 There are three different types of themes:
  12 * The `light` theme is the default modern theme
  13 * The `manila` theme is a combination of OpenEMR's legacy themes (which have all been removed) with some modern elements.
  14 * The other themes (called `colors`) are the same `color_base` theme with different color palettes.
  15
  16 `rtl_` prefixed themes are built by appending the `rtl.css` file to every theme automatically. These overrides provide right to left adjustments for all `style*.css` files
  17
  18 Files specific to different themes are named with the following conventions:
  19 * `themes/core` contain shared styles that all themes import toward the top of their files
  20 * `themes/colors` contain all changes specific to the color theme work (led by [zbig01](https://github.com/zbig01))
  21 * `themes/[component_name]` (e.g. `buttons` or `navigation-slide`) contain files named after each theme variant.
  22     * See TODOs on how we might be able to manage component-level styles in the future
  23
  24 ## Getting Started
  25
  26 Combiling SASS files locally requires [node.js](http://nodejs.org) and [npm](https://www.npmjs.com/).
  27
  28 **Setup local development environment:**
  29
  30 ```
  31 $ cd interface
  32 $ npm install
  33 ```
  34
  35 From here you can either:
  36 * `npm run dev-docs` - runs Storybook (proxied port 9001) and watches changes to local `.scss` files.
  37     * `http://localhost:3000` will refresh css automatically with [BrowserSync](http://www.browsersync.io/) after every change.
  38 * `npm run dev` - just compiles the local `.scss` files and recompiles them whenever they are changed.
  39 * `npm run dev 8081` (EXPERIMENTAL) - loads your local OpenEMR instance using BrowserSync (port 3000) in front of 8081 (you can use any port in this command)
  40
  41 **If you're using docker** or other locally-hosted development environment, it is recommended that you automatically copy files to a mounted volume instead of mounting your working directory. See ["Option 2" in this doc](/contrib/util/docker/README.md) for more info.
  42
  43 ### Development Environment Features
  44
  45 - Live preview sever
  46 - CSS Autoprefixing
  47 - Sass compilation (not yet using in our current themes)
  48 - Browserify bundling
  49 - Image optimization
  50
  51 ## Build
  52
  53 **Build before you make your final css commit:**
  54
  55 ```
  56 $ npm run build
  57 ```
  58
  59 ## TODOs
  60 - [ ] Add built css (and other dependencies) to storybook .out directory
  61 - [ ] Add a lot of documentation on current component usage (starting with theme-only components)
  62 - [ ] Migrate style dependencies in the php code to use the components from the `interface` directory
  63 - [ ] Migrate component css still left in the `/themes` directory into scss