What wikimedia-page-library is for
- Transform-specific CSS.
- Minimal CSS overrides that complement service output but for one reason or another is impractical to change elsewhere.
What wikimedia-page-library is not for
- Style-only changes wanted by all clients. These should probably live in Common.css.
- Template or extension-specific style or HTML changes wanted by all clients.
- Style or HTML changes wanted by all apps. In the long term these should probably live in Parsoid or a Parsoid-based service such as the Mobile Content Service or Page Content Service.
What wikimedia-page-library delivers
- wikimedia-page-library-pcs.css bundle of CSS required by the DOM transformations and potential overrides of the base CSS
- wikimedia-page-library-transform.js bundle of all transform JS (implementation details - previously bundled with the native apps)
- wikimedia-page-library-transform.css bundle of all CSS required by the bundled transform JS
- wikimedia-page-library-override.js an unwanted extraneous build product that may safely be ignored
- wikimedia-page-library-override.css optional CSS overrides for improved appearance that are independent of transforms
File locations and naming
Example file names and locations for an image widening transform:
- src/transform/WidenImage.js - the transform. required
- src/transform/WidenImage.css - CSS used by the transform. optional
- src/override/Empty.css - CSS overrides that are independent of transforms and that couldn't be upstreamed
- test/WidenImage.test.js - tests of the transform. required
- test/fixtures/WidenImage.html - fixtures used by transform tests. optional
todo: rename Empty.css to a real override.
Directory names should be lowercase. Filenames should be singular.
- Prefer to read and modify the CSS class list rather than style attributes or computed styles and prefer to avoid usage of
- Prefer Minerva and Parsoid style defaults. Any deviations should be deliberate and tightly scoped.
- Wide screen selectors should apply to devices in landscape orientation or portrait orientation and >= 768px wide.
- JS function names use camelCase
- JS module names use PascalCase
- CSS class names use snake_case;
pagelib_class_name_element_state(note: class name omits the word "Transform").
- Colors adhere to the Wikimedia UI Style Guide.
- Theme-specific CSS rules should appear in one of the following files:
- If a related transform exists, directly below any default / non-themed rule or at least in the transform's CSS file.
- Otherwise, if a default override rule exists, directly below it.
- Otherwise in ThemeTransform.css.
- Legacy-specific CSS fallback rules should appear in one of the following files:
- If a related transform exists, directly above any default / non-compatibility rule or at least in the transform's CSS file.
- Otherwise, if a default override rule exists, directly above it.
- Otherwise in CompatibilityTransform.css.
Development setup and workflow
Debugging production code while running tests
To be able to get breakpoints to work in your production code you'll want to use the (in memory) webpack-dev-server instead of the regular build output. To run it:
npm run -s build:watch
The /page/mobile-html endpoint, plus the Android and iOS Wikipedia apps make use of the
wikimedia-page-library. At some point their respective build phases invoke
npm install which causes a published version of this library to be retrieved and used in their respective builds.
But sometimes we want to test unpublished
wikimedia-page-library branches. This could be to review bug fixes or new feature branches or to develop fixes and features ourselves. We'd like to be able to checkout a local branch of
wikimedia-page-library and run the app's build process and have the app use whatever we had checked out of our local copy of
To do this:
Step 1 (only need to do this once)
Create a local clone of
git clone https://github.com/wikimedia/wikimedia-page-library.git
Step 2 (do this as needed)
Checkout the branch to be tested:
cd wikimedia-page-library git checkout somebranch
and run the debug build:
npm run -s build:debug
Step 3 (only need to do this once)
Now we need to temporarily tell NPM to use our local copy of
wikimedia-page-library so when we run the app's build process and it runs
npm install, our local copy of
wikimedia-page-library will be used instead of the published one.
We can use the
npm link command to do this.
cd wikimedia-page-library npm link
npm link command above configures NPM with a global
wikimedia-page-library symlink. Note that it infers the name of the package from the package folder we
cd'ed into. We will use this symlink in the next step. You only have to create this symlink once as long as you don't change the file system location of your local clone of
Step 4 (do this when you begin testing against a local copy)
Now we have to configure the app to point to the symlink we just created.
cd $NATIVE_APP_REPO/www # Replace $NATIVE_APP_REPO with the path to the Android or iOS repo. npm link wikimedia-page-library
After running the
link command above, your file system browser should show a symlink folder for
www/node_modules/wikimedia-page-library instead of a normal folder.
Now NPM is "pointing" to our local copy of
wikimedia-page-library and when the app's build process invokes
npm install NPM will try to get
wikimedia-page-library build products from our local copy.
Step 5 (do this each time you make a change to the local copy)
Don't forget to rebuild the local copy of
wikimedia-page-library any time you make a change to it (before you run the app's build process), otherwise the app's build process won't "see" the change!
cd wikimedia-page-library npm run -s build
You may find it helpful to combine this step's command with a command kicking of the respective app's build process into a shortcut of some kind. Most of the development workflow involves make a change to your local copy of
wikimedia-page-library, telling that local copy to re-build, then telling the app to rebuild.
Step 6 (do this when you are done testing against the local copy)
When you have finished testing against your local copy of
wikimedia-page-library, you can simply
unlink so the app's build process will again pull from the published version of
cd $NATIVE_APP_REPO/www # Replace $NATIVE_APP_REPO with the path to the Android or iOS repo. npm unlink wikimedia-page-library
un in the command above.
After running the
unlink command above, your file system browser should again show a normal folder for
www/node_modules/wikimedia-page-library instead of a symlink folder.
Supported ES6 syntax
Babel transpiles ES6 syntax to ES5 except for...of, spread, array destructuring, spread, generators, and async functions. Additionally, ES6 built-ins such as
Array.from() are not transpiled. babel-polyfill is not a requirement of this library so do not use these features.
Automatic incremental builds
Demos are viewable by running
npm -s start which also updates the browser instantly for changes.
Adding new demo article
Note: These are only used by the theme transform demo.
- Add new article in
articles.jsonand the two new article fetches (ignore the changes to the existing files - sometimes changes to existing data files happens when structural html or timestamp changes occur upstream)
Tests are executed prior to commits but may also be executed manually:
- Run all tests:
npm -s t
- Run all tests for a module:
npm -s t -- -g ElementUtilities
- Run all tests for a method:
npm -s t -- -g 'isNestedInTable()'
ESLint is executed prior to commits and publishing to identify cataloged style and functionality concerns. Linting may also be performed by running
npm run -s lint:all. When a violation is detected, it may be fixed manually or suppressed by selectively disabling the rule. Some rules support automated fixes via
npm run -s lint -- --fix ..
When linting fails with a mysterious error message like, the following removing the
.eslintcache file should help.
TypeError: Cannot convert undefined or null to object at Function.keys (<anonymous>) at Object.keys (node_modules/flat-cache/cache.js:52:19)
Please see our Phabricator workboard for contribution ideas. We're currently consolidating existing code in the Android and iOS clients. Pull requests are welcome but please signal on Phabricator tasks before starting work to avoid unnecessary churn.
Copyright 2017 Wikimedia Foundation
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.