Github mirror of "mediawiki/extensions/MediaSearch" - our actual code is hosted with Gerrit (please see https://www.mediawiki.org/wiki/Developer_access for contributing)
Go to file
libraryupgrader e1756c00e2 build: Updating grunt-banana-checker to 0.12.0
Change-Id: Ieebd14bc3559bd5a6550d78d404f5b469b9e7c33
2024-05-10 15:53:24 +00:00
.phan Apply diff up to 25b8791bcadac46d4bc3da0189fe225cbc5d4fcd 2021-03-11 09:16:22 +01:00
i18n Localisation updates from https://translatewiki.net. 2024-04-30 09:21:00 +02:00
maintenance Use IResultWrapper::numRows to check for empty IResultWrapper 2024-04-18 22:13:36 +02:00
resources build: Updating npm dependencies 2024-05-08 13:44:58 +01:00
src build: Upgrade mediawiki/mediawiki-codesniffer to v43.0.0 2024-03-11 20:12:31 +01:00
templates Update no-JS UI to match new CSS-only Tabs implementation 2023-08-03 14:11:37 -07:00
tests build: Updating npm dependencies 2024-05-08 13:44:58 +01:00
.eslintignore Initial test setup with Jest 2021-04-14 15:11:11 -07:00
.eslintrc.json build: Updating npm dependencies 2024-05-08 13:44:58 +01:00
.gitignore Move MediaSearch code into its own extension 2021-02-10 09:19:09 -05:00
.gitreview Add .gitreview 2020-10-19 22:39:08 +02:00
.phpcs.xml build: Updating npm dependencies 2024-05-08 13:44:58 +01:00
.stylelintrc.json build: Updating npm dependencies 2024-05-08 13:44:58 +01:00
CODE_OF_CONDUCT.md Move MediaSearch code into its own extension 2021-02-10 09:19:09 -05:00
COPYING Move MediaSearch code into its own extension 2021-02-10 09:19:09 -05:00
Gruntfile.js build: Run stylelint for vue files 2022-11-22 22:47:00 +01:00
MediaSearch.i18n.alias.php Rename Special:NewMediaSearch to Special:MediaSearch 2021-05-12 13:25:33 -04:00
README.md Fix casing of MediaWiki 2024-03-12 15:26:35 +00:00
composer.json build: Updating dependencies 2024-05-09 07:35:34 +00:00
extension.json extension.json: Drop 'es6' flag, always true since MediaWiki 1.41 2024-01-12 19:03:26 -05:00
jest.config.js Port MediaSearch to Codex 2023-06-26 14:22:13 -07:00
jest.setup.js Merge "IP masking - do not show preferences notice to temp users" 2023-07-07 11:35:43 +00:00
package-lock.json build: Updating grunt-banana-checker to 0.12.0 2024-05-10 15:53:24 +00:00
package.json build: Updating grunt-banana-checker to 0.12.0 2024-05-10 15:53:24 +00:00
phpunit.xml.dist Move MediaSearch code into its own extension 2021-02-10 09:19:09 -05:00

README.md

MediaSearch is an alternative, media-focused way to display search results.

Requirements

While not strictly required, we suggest installing these dependencies to enhance the media search experience.

System-level dependencies

  • ElasticSearch (see here for more information on how to install)

MW Extensions

The following MediaWiki extensions are recommended:

  • CirrusSearch and dependencies, for improved search results & per-mediatype tab support

If you have a Wikibase repository, we strongly recommend also installing these extensions to allow more data to be used to enhance the search results:

Installation

After the extensions listed above are set up properly, enable the extension by adding wfLoadExtension( 'MediaSearch' ); along with the required config variables to LocalSettings.php.

You might need to run composer install in the extension directory, or in the root directory of your MediaWiki installation if you are using a setup that merges all extension's dependencies into MediaWiki's vendor directory.

Configuration

Extension configuration variables are sets of key-value pairs. They are documented in more detail in extension.json. Config variables should be added to LocalSettings.php. The following config options are available for this extension:

// External entity search base URI (for autocomplete suggestions, optional)
// Leave blank/default (empty string) to use local API.
// To disable autocomplete suggestions completely, set to null.
$wgMediaSearchExternalEntitySearchBaseUri = 'https://www.wikidata.org/w/api.php';

// URI for getting search results from production during local development.
// If this is set, search API calls will be made to this URI. Left blank,
// search results will be retrieved from the local API by default.
$wgMediaSearchExternalSearchUri = 'https://commons.wikimedia.org/w/api.php';

Coding conventions

JavaScript/Vue

As much as possible, we default to the Vue Style Guide.

For now, we are not using full single-file components because we need to be able to compile Less separately so it can be included immediately before the app loads to style the PHP UI.

CSS/Less

Since Wikimedia UI base variables aren't in core, we require them as a package dependency, then use a shell script to copy them to the lib directory. To update the base variables, require the new version in package.json and install it, then run npm run build-lib to copy the updated file into lib. Commit the updated files.

We're including the base variables in our custom variables file, resources/mediasearch-variables.less. To use them in other files, include mediasearch-variables.less rather than directly including the base file itself.

The CSS class name prefix sdms should be used for extension-level components. sd should be used for base components to keep them extension-agnostic, in case we decide to pull them out into a separate library.

Testing

Front-end test suite

This extension includes a front-end test suite powered by the Jest framework. The tests also make extensive use of the official Vue.js testing library.

For more information about testing Vue code in MediaWiki, please consult the guide here.

At runtime, our JS code relies on a number of objects in the global MediaWiki JS environment. Some of these features need to be mocked during testing. The jest.setup.js file is the best place for mocks that are needed in lots of places. Individual test files can provide additional mocks or override what already exists if more specific mocks are needed.

To run unit tests locally, use the following commands:

# install all required dependencies
npm install

# run all linters and front-end tests
npm run test

# run only the front-end unit tests by themselves
npm run test:unit

See also