# Infusion
[](https://codecov.io/github/fluid-project/infusion?branch=main)
## What Is Infusion?
Infusion is a different kind of JavaScript framework. Our approach is to leave you in control—it's your interface,
using your markup, your way. Infusion is accessible and very, very configurable.
Infusion includes:
* an application framework for developing flexible stuff with JavaScript and jQuery
* a collection of accessible UI components
## Where Can I See Infusion Components?
<https://fluidproject.org/infusion.html>
## How Do I Get Infusion?
* [Download a Release](https://github.com/fluid-project/infusion/releases)
* [Install from NPM](https://www.npmjs.com/package/infusion)
* [Fork on GitHub](https://github.com/fluid-project/infusion)
* [Use from a Content Distribution Network(CDN)](https://unpkg.com/browse/infusion)
* To try out Infusion quickly you can use the following `script` tag to include the full framework from the CDN:
`<script src='https://unpkg.com/browse/infusion@2.0.0/dist/infusion-all.js'></script>`
See [How Do I Create an Infusion Package?](#how-do-i-create-an-infusion-package), for details on creating complete or
custom packages of Infusion.
## Where is the Infusion Documentation?
Infusion has comprehensive documentation at <https://docs.fluidproject.org/infusion>.
## Who Makes Infusion, and How Can I Help?
The Fluid community is an international group of designers, developers, and testers who focus on a common mission:
improving the user experience and accessibility of the open web.
The best way to join the Fluid Community is to jump into any of our community activities. Visit our
[website](https://fluidproject.org/) for links to our mailing lists, chat room, wiki, etc.
## Inclusion
The Fluid community is dedicated to inclusive design—design that considers the full range of human diversity with
respect to ability, language, culture, gender, age and other forms of human difference. To help ensure that our
community is a safe space for all contributors, we have adopted a
[code of conduct](https://wiki.fluidproject.org/display/fluid/Inclusion+in+the+Fluid+Community) based on the
[Contributor Covenant](https://contributor-covenant.org/). All participants and contributors have the responsibility to
uphold this code. Please contact the [Advocacy working group](mailto:fluid-advocacy@fluidproject.org) if you encounter
unacceptable behaviour.
## Where is Infusion Used?
Infusion is the cornerstone of a number of Fluid's own projects dedicated to supporting inclusive design on the Web. You
can see some of them featured on our [Projects page](https://fluidproject.org/projects.html). Infusion is also used in a
variety of third-party applications, which are listed on the
[Infusion Integrations](https://wiki.fluidproject.org/display/fluid/Infusion+Integrations) wiki page.
## How Do I Create an Infusion Package?
For simplicity and performance reasons, Infusion distributions are minified. However, such a file is often difficult to
read. To address this, source maps for the minified files are automatically generated to make debugging easier.
### Source Maps
Source maps are supported in all of the major browsers:
[Chrome](https://developers.google.com/web/tools/chrome-devtools/javascript/source-maps),
[Firefox](https://developer.mozilla.org/en-US/docs/Tools/Debugger/How_to/Use_a_source_map),
[Edge](https://docs.microsoft.com/en-us/microsoft-edge/devtools-guide/debugger#source-maps), and Safari. To make use of
them, enable source maps in your debugging environment, and ensure that the source maps are hosted adjacent to the file
they are associated with.
#### Source Map Example
* From the command line, run `npm run build` to generate Infustion distributions
* All Infusion distributions come with a source map for the concatenated JavaScript file
* CSS files compiled from SASS also include source maps.
* In the Infusion package, modify one of the demos to replace the individual javascript includes with a reference to
"infusion-all.js"
* The "infusion-all.js" includes a reference to the "infusion-all.js.map" file, which is assumed to be hosted as its
sibling
* Open the demo in a browser
* In the browser's debugger ensure that source maps are enabled
* In Firefox open the debugger
* In the debugger options, ensure that "Show Original Sources" is enabled
* see [MDN: Use a source map](https://developer.mozilla.org/en-US/docs/Tools/Debugger/How_to/Use_a_source_map)
* In the debugger you should now be able to view and debug the individual JavaScript files as though they were included
separately
### Dependencies
* [node.js](https://nodejs.org/)
All other development dependencies will be installed by running the following from the project root:
```bash
npm install
```
### Build Types
#### Distribution Builds
Will build a set of predefined distribution bundles of Infusion, some of which include third-party dependencies and some
of which do not, for distribution on [NPM](https://www.npmjs.com/package/infusion). Each distribution file will be
placed in the `dist` directory and will be accompanied by a [source map](#source-maps).
```bash
npm run build
```
Distribution bundles can be [viewed on unpkg](https://unpkg.com/browse/infusion/dist/).
#### Infusion All Build
Will include all of Infusion, including third-party dependencies. The source files packaged along with the single
concatenated JavaScript file will include all of the demos, examples and unit tests. This is a good choice if you are
trying to learn Infusion.
```bash
npm run build:pkg
```
#### Custom Build
Will only include the modules you request, and all of their dependencies, minus any that are explicitly excluded. Unlike
the [Infusion All](#infusion-all-build) build, none of the demos, examples or tests are included with a custom package.
```bash
npm run build:pkg:custom
```
#### Custom Build Options
Any of the following options can be passed to a custom build by specifying the option after `--`. Examples are shown
below.
##### -i, --include
**value**: "module(s)" (String)
_only available to custom builds_
The `--include` option takes a comma-separated string of the [Modules](#modules) to be included in a custom package.
Only these modules and their dependencies will be included. By default, all modules are included; however, demos,
examples and tests are never included with custom builds.
```bash
npm run build:pkg:custom -- --include="fluid-inline-edit, fluid-ui-options"
# shorthand
npm run build:pkg:custom -- -i "fluid-inline-edit, fluid-ui-options"
```
##### -e, --exclude
**value**: "module(s)" (String)
_only available to custom builds_
The `--exclude` option takes a comma-separated string of the [Modules](#modules) to be excluded from a custom package.
By default, no modules are excluded. Excludes take priority over includes.
```bash
npm run build:pkg:custom -- --exclude=jquery
# shorthand
npm run build:pkg:custom -- -e jquery
```
##### -n, --name
**value**: "custom suffix" (String)
_only available to custom packages which have specified an include and/or exclude option_
By default, custom packages are given a name in the form _infusion-custom-{version}.zip_ and the concatenated JavaScript
file is called _infusion-custom.js_. By supplying the `--name` option, you can replace "custom" with any valid string.
If neither the `--include` nor `--exclude` options are specified, `--name` will be ignored and "custom" will be replaced
with "all".
_**NOTE**_: If built from a tag, the version will correspond to the tag name. (e.g. _infusion-custom-myTag.zip_)
```bash
# this produces infusion-myPackage.js
npm run build:pkg:custom -- --name=myPackage
# shorthand
npm run build:pkg:custom -- -n myPackage
```
#### Producing builds for a GitHub release
The build commands producing the zip files which accompany a GitHub release (infusion-all-vx.y.z.zip and
infusion-uio-vx.y.z.zip) can be produced by the following commands:
```bash
npm run build:pkg
npm run build:pkg:custom -- -i "fluid-ui-options" -n uio
```
The zip files will obliterate the contents of the `products` directory and must be copied out after each command.
### Modules
#### Framework Modules
* fluid-enhancement
* fluid-framework
* fluid-preferences
* fluid-renderer
#### Component Modules
* fluid-inline-edit
* fluid-orator
* fluid-overview-panel
* fluid-pager
* fluid-progress
* fluid-reorderer
* fluid-sliding-panel
* fluid-switch
* fluid-table-of-contents
* fluid-textfield-controls
* fluid-text-to-speech
* fluid-tooltip
* fluid-ui-options
* fluid-undo
* fluid-uploader
#### External Libraries
* atkinson-hyperlegible
* fast-xml-pull
* hypher
* jquery
* jquery-ui
* jquery-scrollto
* jquery-ui-touch-punch
* opendyslexic
* opensans
* roboto-slab
## How Do I Run Tests?
### Run Tests On Your Computer
To run both the browser and node tests for this package:
```bash
npm test
```
To run only the node tests:
```bash
npm run test:node
```
To run only the browser tests:
```bash
npm run test:browser
```
Testem will attempt to launch Chrome and Firefox sequentially with each browser running the full Infusion test suite.
The results will be returned in your terminal in the [TAP](https://testanything.org/) format.
If you would like to debug individual tests or view the test summary in a browser, you can:
1. Host the working directory:
```bash
npm start
```
Your terminal will show you the local address for the working directory, which will normally be <http://localhost:5000>.
2. Open the "rollup" file `tests/all-tests.html` that runs all tests in a browser. Continuing the above example, you
would load the URL <http://localhost:5000/tests/all-tests.html>.
To run tests of Infusion's distribution bundles:
```bash
npm run test:bundles
```
#### Coverage Reporting
When you run the tests using `npm test`, the full test suite will run and a coverage report will be saved to the
`reports` directory.
The `npm test` command has [two additional associated scripts](https://docs.npmjs.com/cli/v6/using-npm/scripts#pre--post-scripts).
The `pretest` script runs before the command defined for the `test` script. The `posttest` script runs after. In our
case we use a `pretest` script to clean up previous coverage data before we run the tests, and a `posttest` script to
compile the actual report (this can also be accomplished by running `npm run test:report` after running tests). You do
not need to run the `pretest` script manually before running either the node or browser tests, or to run the `posttest`
script afterwards.
### Run Tests In a Docker Container
You can also run the tests from a [Docker](https://docs.docker.com/get-docker) container.
Once you have Docker installed, run the following commands to build a Docker image and start a container:
* Build the image: `docker build -t infusion .`
* Run the container: `docker run --name infusion -p 8000:80 infusion`
Infusion will be available at [http://localhost:8000](http://localhost:8000)
* To stop and remove the container: `docker rm -f infusion`
If you make changes to Infusion, repeat the steps to build the image and start a new container.
## Other Scripts
Host the working directory (this will make it available at <http://localhost:5000> and let you access demos, examples,
and tests in your browser):
```bash
npm start
```
Copy Infusion's dependencies from "node_modules" into the "src/lib" directory:
```bash
npm run deps
```
Lint JavaScript, JSON, Markdown and other files using [fluid-lint-all](https://github.com/fluid-project/fluid-lint-all):
```bash
npm run lint
```
Remove all of the copied or built directories and files:
```bash
npm run clean
```
## Developing with the Preferences Framework
The Preferences Framework uses [Sass](http://sass-lang.com/) for CSS pre-processing. Only Sass files are included in the
GitHub repository.
For developing the Preferences Framework, run the following from the project root to compile Sass files to CSS:
```bash
# unminified
npm run build:sass
# minified
npm run build:sass:min
```
A `watch` task is also supplied to ease Sass development. This task launches a process that watches all Sass files in
the `src` directory and recompiles them when they are changed. This task can be started using the following command:
```bash
# unminified
npm run watch:sass
# minified
npm run watch:sass:min
```
For more information on styling the Preferences Framework, please review the documentation on
[using Sass with the Preferences Framework](./src/framework/preferences/css/sass/README.md).