mirror of
https://gerrit.wikimedia.org/r/mediawiki/extensions/Popups
synced 2024-11-30 18:34:40 +00:00
83a28d177f
Storybook.js provides a framework for viewing and working with UI components. https://storybook.js.org/ This patch adds the Storybook.js UI library to Popups for the purposes of viewing multiple previews at once. This enables viewing page previews in the following states: - with thumbnails - without thumbnails - with SVG thumbnails - with narrow thumbnails - with white background thumbnails - in RTL languages - in non-latin languages - disambiguation popups Storybook also allows users to change the image or text of a popup through a GUI. This patch sets up Storybook as a "mini" repo inside the.storybook folder with a seperate package.json file to avoid incompatibilities with the current webpack/babel (or even Node) versions used in the Popups repo. Storybook requires at least Node v8.3 to run. (an .nvmrc file with 11.3.0 has been added to the .stories dir). To start: `cd .storybook && npm install && npm run start`. Bug: T205989 Change-Id: I041e46c4f0cf173950015067e2dce81c023d3fdd
90 lines
4 KiB
Markdown
90 lines
4 KiB
Markdown
|
|
|
|
# mediawiki/extensions/Popups
|
|
|
|
See https://www.mediawiki.org/wiki/Extension:Popups for more information about
|
|
what it does.
|
|
|
|
## Development
|
|
|
|
Popups uses an asset bundler so when developing for the extension you'll need
|
|
to run a script to assemble the frontend assets.
|
|
|
|
You can find the frontend source files in `src/`, the compiled sources in
|
|
`resources/dist/`, and other frontend assets managed by resource loader in
|
|
`resources/*`.
|
|
|
|
After an `npm install`:
|
|
|
|
* On one terminal, kickstart the bundler process:
|
|
* `npm start` Will run the bundler in watch mode, re-assembling the files on
|
|
file change. Additionally, this builds debug-friendly assets and enables
|
|
[Redux DevTools] debugging.
|
|
* `npm run build` Will compile the assets just once, ready for deployment. You
|
|
*must* run this step before sending the patch or CI will fail (so that
|
|
sources and built assets are in sync).
|
|
* On another terminal, run tests and linting tools:
|
|
* `npm test` To run the linting tools and the tests.
|
|
* You can find the QUnit tests that depend on running MediaWiki under
|
|
`tests/qunit/`
|
|
* You can find the isolated QUnit tests under `tests/node-qunit/`, which you
|
|
can run with `npm run test:node`
|
|
* We recommend you install a file watcher like `nodemon` to watch sources and
|
|
auto run linting and tests.
|
|
* `npm install -g nodemon`
|
|
* Example running linting and node unit tests:
|
|
* `nodemon -w src/ --exec "grunt lint:all && npm run test:node"`
|
|
* Get code coverage report with `npm run coverage`
|
|
* Reports printed in the `coverage/` folder
|
|
|
|
Developers are likely to work with local MediaWiki instances that do not have
|
|
content to test with. To reduce this pain, you can create a single page with
|
|
a list of links that point to an existing and external wiki by using the
|
|
following config flag:
|
|
|
|
$wgPopupsGateway = 'restbaseHTML';
|
|
$wgPopupsRestGatewayEndpoint = 'https://en.wikipedia.org/api/rest_v1/page/summary/';
|
|
|
|
Popups works with a local copy of the [Mobile Content Service] too:
|
|
|
|
$wgPopupsGateway = 'restbaseHTML';
|
|
$wgPopupsRestGatewayEndpoint = 'http://localhost:6927/en.wikipedia.org/v1/page/summary/';
|
|
|
|
[Redux DevTools]: https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd
|
|
[Mobile Content Service]: https://gerrit.wikimedia.org/r/plugins/gitiles/mediawiki/services/mobileapps/+/master
|
|
|
|
## Debugging
|
|
|
|
* Popups are dismissed ("abandoned") when the cursor leaves the popup
|
|
container. As such, it can be difficult to debug a popup of interest
|
|
without it popping in and out of the DOM. A useful workaround in
|
|
DevTools is to context click a link, select inspect, move the cursor
|
|
some place comfortable, and then from the console enter
|
|
`$($0).trigger('mouseenter')`.
|
|
* As described in [[#Development]], `npm start` enables Redux DevTools
|
|
functionality. In production builds, this same functionality can be
|
|
enabled by setting a `debug=true` query. E.g.,
|
|
`https://en.wikipedia.org/wiki/Popup?debug=true`.
|
|
|
|
## Storybook.js Component Library
|
|
|
|
The root of the repository contains a .storybook directory. This folder contains
|
|
a separate NPM project using the [Storybook.js](https://storybook.js.org/) UI framework.
|
|
This framework provides an environment that showcases all possible permutations of popups,
|
|
without the state-management constraints of having only one popup per page.
|
|
|
|
This framework requires Node v8 (because of the spread `...` operator) and is therefore
|
|
separated from the main package.json until CI upgrades from Node v6. NVM can be used to
|
|
manage multiple Node versions to run the Storybook app (`cd .storybook && nvm use`).
|
|
See the .storybook/README.md for details.
|
|
|
|
## Terminology
|
|
|
|
* Hovercard - Deprecated term for popup.
|
|
* Link preview - A similar user feature in the Android native app.
|
|
* Navpop / nav pop - A popup-like UI from the NavigationPopups gadget.
|
|
* Popup - Generic term for a dialog that appears to float above a link that is
|
|
being hovered over by a cursor.
|
|
* Page preview - A specific type of popup that shows a page summary.
|
|
* Preview - A synonym for popup.
|