interface/README.md

   1 # OpenEMR-interface
   2
   3 OpenEMR 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 ### Special Classes
  25
  26 * `position-override` gives a hook for style to change placement of buttons. In light/manila style this is ignored and buttons go to left positioned under data entry field. Whereas in the other styles this is used to center the buttons.
  27 * `oe-opt-btn-group-pinch` gives a hook for style to pinch the buttons (i think make them more rounded). Not used in light/manila, but used in other styles.
  28 * `oe-opt-btn-separate-left` gives a hook to place a space between the buttons. Not used in light/manila, but used in other styles.
  29 * `oe-text-to-right` does as it says (and then does the opposite for RTL languages).
  30 * `oe-text-to-left` does as it says (and then does the opposite for RTL languages).
  31
  32 ## Getting Started
  33
  34 Compiling SASS files locally requires [node.js](http://nodejs.org) and [npm](https://www.npmjs.com/).
  35
  36 1. **Setup your local development environment** as described in [CONTRIBUTING.md](../CONTRIBUTING.md)
  37
  38 - If running on a local machine, run `npm install` from the root directory.
  39 - If running in docker: `docker exec -it [your_container_id] /bin/sh` then cd into `openemr`
  40
  41 From here you can either:
  42 * `npm run dev-docs` - runs Storybook (proxied port 9001) and watches changes to local `.scss` files.
  43     * `http://localhost:3000` will refresh css automatically with [BrowserSync](http://www.browsersync.io/) after every change.
  44 * `npm run dev` - just compiles the local `.scss` files and recompiles them whenever they are changed.
  45 * `npm run dev-sync` (EXPERIMENTAL*) - loads your local OpenEMR instance using BrowserSync (port 3000) in front of 80 (feel free to edit the package.json to change the port)
  46     * [See video of `dev-sync` in action](https://imgur.com/a/C0dVnfq)
  47
  48 ## TODOs
  49 - [ ] Incorporate tabs_style_compact.css and tabs_style_full.css (and associated RTL) into scss
  50 - [x] Don't require 2 build runs to build the rtl themes
  51 - [x] Add built css (and other dependencies) to storybook .out directory
  52 - [ ] Add a lot of documentation on current component usage (starting with theme-only components)
  53 - [ ] Migrate style dependencies in the php code to use the components from the `interface` directory
  54 - [ ] Migrate component css still left in the `/themes` directory into scss