Extension:GrowthExperiments/Technical documentation/Frontend
Client modules map
[edit]| ResourceLoader Module | Usage | Server side rendering | Base UI components | Custom UI components | Notes |
| ext.growthExperiments.Account | Set up ULS for WelcomeSurvey; show confirm email in Special:CreateAccount | MessageBox
TagMultiselectWidget |
|||
| ext.growthExperiments.Account.styles | Style elements in ext.growthExperiments.Account, custom landing pages, Special:Contributions | ✓ | |||
| ext.growthExperiments.DataStore | Manage states for filters and newcomer tasks | ||||
| ext.growthExperiments.Help | Ask help dialog; contents of the help panel | Layouts (PanelLayout, IndexLayout, StackLayout)
ProcessDialog SearchInputWidget |
|||
| ext.growthExperiments.HelpPanel | Help panel CTA, help panel popup; suggested edits guidance | HelpPanelButton
SuggestedEditsPeek |
|||
| ext.growthExperiments.Homepage.ConfirmEmailNotice | Show a notification after the user confirms their email | ||||
| ext.growthExperiments.Homepage.Impact | Homepage module; Show page views for edited articles (activated) or open suggested edits (unactivated) | ✓ | PopupButtonWidget | ||
| ext.growthExperiments.Homepage.Logger | Logger class for homepagemodule schema | ||||
| ext.growthExperiments.Homepage.Logging | Set up logging for homepage modules | ||||
| ext.growthExperiments.Homepage.Mentorship | Homepage module; Show questions posted to mentor; opt in/out of mentorship | ✓ | ButtonMenuSelectWidget
MessageDialog |
||
| ext.growthExperiments.Homepage.mobile | Set up mobile overlays for homepage modules | ✓ | MobileOverlay (MobileFrontend)
Drawer (MobileFrontend) |
Maybe it's worth considering splitting out the overlays from the server-side rendered view | |
| ext.growthExperiments.Homepage.styles | Style server-side rendered elements of the homepage | ✓ | |||
| ext.growthExperiments.Homepage.SuggestedEdits | Homepage module; suggested edits feed and filters | ✓ | ProcessDialog
PanelLayout PopupButtonWidget MessageWidget SwipePane |
SuggestedEditsPeek | |
| ext.growthExperiments.HomepageDiscovery | Show banner w/instructions on how to back to Special:Homepage; Remove mobile discovery banner after it's been closed | ✓ | |||
| ext.growthExperiments.MentorDashboard | Allow mentors to manage their mentees, their mentorship status | mw.widgets.UserInputWidget
ProcessDialog |
There's room for improvement in the UI in terms of mobile/responsive layouts and loading/progress feedback to users | ||
| ext.growthExperiments.MentorDashboard/MenteeOverview | Browse mentees, see mentee stats | Inputs (NumberInput, ButtonSelect, CheckboxInput) | FilterDropdown | ||
| ext.growthExperiments.MentorDashboard/MentorTools | Claim mentees, set mentor availability | Select (Browser native), Dialog | |||
| ext.growthExperiments.MentorDashboard/Resources | Lists useful links for mentors | ✓ | Could be a candidate for experimentings with custom SSR on PHP. That means building a mustache template in the server that matches the generated HTML of a Vue component. | ||
| ext.growthExperiments.PostEdit | Show dialog upon task completion | MessageWidget | CollapsibleDrawer | ||
| ext.growthExperiments.StructuredTask | Base classes for structured tasks | VE classes | |||
| ext.growthExperiments.StructuredTask.desktop | Desktop-specific classes for structured tasks | VE classes | |||
| ext.growthExperiments.StructuredTask.mobile | Mobile-specific classes for structured tasks | VE classes | |||
| ext.growthExperiments.StructuredTask.PreEdit | Check for structured task eligiblity; show onboarding dialog (mobile) | ProcessDialog | MultiPaneDialog
SwipePane |
Might be a good candidate if we have the dialog component but since the onboarding is bundled w/StructuredTask module, we may need to research bundling Vue-based modules with VE | |
| ext.growthExperiments.SuggestedEditSession | Manage states for suggested edits |
Disclaimer: the table is not updated since May 2022
Unit testing
[edit]The GrowthExperiments extension client code can and should be tested with one of MediaWiki's preferred runners: jest or qunit. Specifically Jest is used for running Vue components unit tests and QUnit for running other Javascript scripts. QUnit tests live under the folder tests/qunit whereas Jest tests are normally placed in source directories by the side of the script they are testing. The current CI setup (tbd: add reference to doc/sources) will execute both kinds of tests whenever a change is pushed to gerrit. Sadly there's not a single command (yet) to run them all from a developer environment.
QUnit
[edit]For running QUnit tests use ./node_modules/.bin/grunt qunit --qunit-component=GrowthExperiments from the root mediawiki directory.
Jest
[edit]For running Jest tests use the NPM script npm run test:jest from the GrowthExperiments extension directory.
Snapshot testing
[edit]Jest supports snapshot testing which is a useful feature to make sure UIs do not change unexpectedly. To create a snapshot file from a component for the first time use npm run test:jest. To update an existing snapshot based on source component changes use npm run test:jest:update
Testing a Codex patch in the frontend documentation
[edit]Pull the relevant Codex patch
/projects/codex$ git review -d 1234
Build all Codex packages since the build of packages/codex may depend
on the build of packages/codex-design-tokens
/projects/codex$ npm run build-all
Link the local package into your package
$ cd /projects/codex/packages/codex # go to the codex package directory
/projects/codex/packages/codex$ npm link # create a global link
$ cd /projects/my-node-package # go to your package directory
/projects/my-node-$ npm link @wikimedia/codex # link-install the codex package
All import '@wikimedia/codex' or require( '@wikimedia/codex' ) statements should work as expected. Relative imports
in .{vue,js,ts} files should also continue to work, eg: import '../../node_modules/@wikimedia/codex/dist/codex.style.css';
VitePress projects
[edit]On VitePress projects only files within the root directory are allowed to be served by default. Assuming the codex repository folder is a sibling of the target project to test, the vite config can be modified to temporary allow serving files from outside its root.
// vite.config.js
const { defineConfig } = require( 'vite' );
module.exports = defineConfig( {
server: {
fs: {
/**
* Allow serving files from the codex local package.
* Only files from the dist/ directory should be used
*/
allow: [ '../codex/packages/codex/dist' ]
}
}
} );
This change should not be pushed to the remote repository.
Unlinking
[edit]To revert your project to use the original Codex version:
/projects/my-node-package$ npm unlink --no-save @wikimedia/codex # remove the package without removing its original entry in package.json
/projects/my-node-package$ npm install # install the package again from the npm registry
See npm-link
Trouble shooting
[edit]VitePress creates a cache dependency directory which isn't updated on unlinking operations. You can just flush its content and the cache will be populated again with the current packages from node_modules.
/projects/my-node-package$ rm -rf docs/.vitepress/cache/deps/
Integrating a Vue prototype into a MW extension
[edit]Pre-steps ( developed in the VitePress sandbox in the prototyping phase )
[edit]This is a backlog of issues found while trying to integrate a Vue component developed with VitePress and Codex into GrowthExperiments. TODO: add links to phab tasks.
- Integrate with a MW-compatible i18n system T335277
- Meet, at least, the UX excellence level of OOUI version of the implemented component
Steps ( developed in MW in the integration phase )
[edit]- Compile the Vue code
- Load it through RL
- Testing? Regression?
- ...