OOUI is a component-based JavaScript UI library. Key features:
- Common widgets, layouts, and dialogs
- Classes, elements, and mixins to create custom interfaces
- Internationalization and localization, like right-to-left (RTL) languages support
- Theme-ability
- Built-in icons
- Accessibility features
It is the standard library for Web products at the Wikimedia Foundation, having been originally created for use by VisualEditor.
The library is available on npm. To install:
$ npm install oojs-uiOnce installed, include the following scripts and styles to get started:
<script src="node_modules/jquery/dist/jquery.min.js"></script>
<script src="node_modules/oojs/dist/oojs.min.js"></script>
<script src="node_modules/oojs-ui/dist/oojs-ui.min.js"></script>
<script src="node_modules/oojs-ui/dist/oojs-ui-wikimediaui.min.js"></script>
<link rel="stylesheet" href="node_modules/oojs-ui/dist/oojs-ui-wikimediaui.min.css">While the distribution directory is chock-full of files, you will normally load only the following three:
oojs-ui.js, containing the full library;- One of
oojs-ui-wikimediaui.cssoroojs-ui-apex.css, containing theme-specific styles; and - One of
oojs-ui-wikimediaui.jsoroojs-ui-apex.js, containing theme-specific code
You can load additional icon packs from files named oojs-ui-wikimediaui-icons-*.css or oojs-ui-apex-icons-*.css.
The remaining files make it possible to load only parts of the whole library.
Furthermore, every CSS file has a right-to-left (RTL) version available, to be used on pages using right-to-left languages if your environment doesn't automatically flip them as needed.
Found a bug or missing feature? Please report it in our issue tracker Phabricator!
We are always delighted when people contribute patches. To setup your development environment:
-
Clone the repo:
$ git clone https://gerrit.wikimedia.org/r/oojs/ui oojs-ui -
Move into the library directory:
$ cd oojs-ui -
Install composer and make sure running
composerwill execute it (e.g. add it to$PATHin POSIX environments). -
Install dev dependencies:
$ npm install -
Build the library (you can alternatively use
grunt quick-buildif you don't need to rebuild the PNGs):$ grunt build -
You can see a suite of demos in
/demosby executing:$ npm run-script demos -
You can also copy the distribution files from the dist directory into your project.
-
You can start a local web server by running
php -S localhost:80in your root dir. -
You can navigate to http://localhost/tests/ to run the tests locally in your browser.
We use Gerrit for code review, and Phabricator to track issues. To contribute patches or join discussions all you need is a developer account.
- If you've found a bug, or wish to request a feature raise a ticket on Phabricator.
- To submit your patch, follow the "getting started" quick-guide. We try to review patches within a week.
- We automatically lint and style-check changes to JavaScript, PHP, LESS/CSS, Ruby and JSON files. You can test these yourself with
npm testandcomposer testlocally before pushing changes. SVG files should be squashed in advance of committing with SVGO usingsvgo --pretty --disable=removeXMLProcInst --disable=cleanupIDs <filename>.
A new version of the library is released most weeks on Tuesdays.
Get updates, ask questions and join the discussion with maintainers and contributors:
- Join the Wikimedia Developers mailing list, wikitech-l.
- Chat with the maintainers on
#wikimedia-devonirc.libera.chat. - Ask questions on StackOverflow.
- Watchlist the documentation on MediaWiki to stay updated.
We use the Semantic Versioning guidelines.
Releases will be numbered in the following format:
<major>.<minor>.<patch>
- Create an NPM account, if you don't have one already
- Verify that you can log into your NPM account
- Verify that you are listed as a maintainer of the oojs-ui package. If not, ask an existing maintainer to add you.
- Make sure that you have two-factor authentication (2FA) set up.
- Run
npm loginand follow the steps. You should only need to do this once on each computer. If you're not sure if you've already done this, you can runnpm whoami; if it prints your NPM username, you're already logged in. - Clone the mediawiki/vendor repository: https://gerrit.wikimedia.org/r/admin/repos/mediawiki/vendor,general
From the root of this repository, update master and check out a new release branch:
$ git remote update
$ git checkout -B release -t origin/masterClean-install npm dependencies, update Composer dependencies, and ensure tests pass:
$ npm ci && composer update && npm test && composer testGenerate a list of commits that are part of this release:
$ git log --format='* %s (%aN)' --no-merges v$(node -e 'console.log(require("./package").version);')...HEAD | grep -v "Localisation updates from" | sortIn History.md, add a new heading for this version and date. Copy the list of commits into the new section and sort into five sub-sections, in order, omitting any sub-section that has no commits:
### Breaking changes
### Deprecations
### Features
### Styles
### CodeGenerate the list of Phabricator tasks for this release. Copy the resulting list and save it for later. In a later step, you will add it to the commit message of the MediaWiki core commit.
$ git log --pretty=format:%b v$(node -e 'console.log(require("./package").version);')...HEAD | grep Bug: | sort | uniqUpdate the version number (in the following command, change 'patch' to 'minor' if you've made breaking changes):
$ npm version patch --git-tag-version=falseCommit the release and submit to Gerrit. Note that if there is a Phabricator task associated with
the release, you should edit the commit to add the bug number before running git review.
$ git add -u
$ git commit -m "Tag v$(node -e 'console.log(require("./package").version);')"
$ git reviewAfter the tag commit is merged in this repo, push the tag and publish to NPM:
$ git remote update
$ git checkout origin/master
$ git tag "v$(node -e 'console.log(require("./package").version);')"
$ npm run publish-build && git push --tags && npm publishIn your local mediawiki/vendor repo, point composer to the new version and pull in the updated vendor files:
# Replace 1.2.34 with the version number of the new release
$ composer require oojs/oojs-ui 1.2.34 --no-update
$ composer update --no-devThen commit the changes with the following commit message, replacing 1.2.34 with the new OOUI version number (example: https://gerrit.wikimedia.org/r/c/mediawiki/vendor/+/813629).
$ git add -u
$ git commitCommit message format:
Update OOUI to v1.2.34
Release notes: https://gerrit.wikimedia.org/g/oojs/ui/+/v1.2.34/History.mdPush this to gerrit. Take note of the Change-Id in the commit message. Copy it and save it for later. You will need it for the Depends-On: line in the commit message when updating MediaWiki.
$ git review
# Show the last commit
$ git show --statIn your local MediaWiki core repo, open composer.json and update the version number of
oojs/oojs-ui to the new version number.
Open RELEASE-NOTES-1.NN. If there is already a list item about OOUI, update the latest version
number. For example, if there is a list item that says "Updated OOUI from v1.2.0 to v1.2.33",
update the latter version number fo v1.2.34. If there isn't a list item about OOUI yet, add one
in the Changed external libraries section.
Open resources/lib/foreign-resources.yaml. For the OOUI listing, change the version, the purl,
and the src URL to use the new version number. Compute the new integrity hash:
$ php maintenance/run.php manageForeignResources make-sri ooui
# Or if you're running Docker...
$ docker compose exec mediawiki php maintenance/run.php manageForeignResources make-sri oouiThen update the OOUI library files:
$ php maintenance/run.php manageForeignResources update ooui
# Or if you're running Docker...
$ docker compose exec mediawiki php maintenance/run.php manageForeignResources update oouiThen run the following command to update foreign-resources.cdx.json:
$ php maintenance/run.php manageForeignResources make-cdx
# Or if you're running Docker...
$ docker compose exec mediawiki php maintenance/run.php manageForeignResources make-cdxThen commit the changes with the following commit message, replacing 1.2.34 with the new OOUI version number:
$ git add -u
$ git commitCommit message format, where the list of bugs is the list you generated during the OOUI tag step, and Depends-On is set to the Change-Id of the mediawiki/vendor commit:
Update OOUI to v1.2.34
Release notes: https://gerrit.wikimedia.org/g/oojs/ui/+/v1.2.34/History.md
Bug: T123456
Bug: T234567
Depends-On: I12345678901234567890Then push that commit to gerrit:
git reviewIn your local VisualEditor/VisualEditor repo, run the script to create a commit updating the local copy of OOUI, and push the commit to Gerrit:
$ ./bin/update-ooui.sh
$ git review