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 ### 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 Combiling SASS files locally requires [node.js](http://nodejs.org) and [npm](https://www.npmjs.com/).
  35
  36 **Setup local development environment:**
  37
  38 ```
  39 $ cd interface
  40 $ npm install
  41 ```
  42
  43 From here you can either:
  44 * `npm run dev-docs` - runs Storybook (proxied port 9001) and watches changes to local `.scss` files.
  45     * `http://localhost:3000` will refresh css automatically with [BrowserSync](http://www.browsersync.io/) after every change.
  46 * `npm run dev` - just compiles the local `.scss` files and recompiles them whenever they are changed.
  47 * `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)
  48
  49 **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.
  50
  51 ### Development Environment Features
  52
  53 - Live preview sever
  54 - CSS Autoprefixing
  55 - Sass compilation (not yet using in our current themes)
  56 - Browserify bundling
  57 - Image optimization
  58
  59 ## Build
  60
  61 **Build before you make your final css commit:**
  62
  63 ```
  64 $ npm run build
  65 ```
  66
  67 ## TODOs
  68 - [ ] Incorporate tabs_style_compact.css and tabs_style_full.css (and associated RTL) into scss
  69 - [ ] Don't require 2 build runs to build the rtl themes
  70 - [ ] Add built css (and other dependencies) to storybook .out directory
  71 - [ ] Add a lot of documentation on current component usage (starting with theme-only components)
  72 - [ ] Migrate style dependencies in the php code to use the components from the `interface` directory
  73 - [ ] Migrate component css still left in the `/themes` directory into scss