User:ATomasevich (WMF)/Code splitting usage

Using Codex Vue 3 components

Note that this section also includes using Codex composables.

Getting started

See the official docs to learn more about the available Vue 3 components, including demos and usage information (for example, see the Button component demo). Make sure to use the MediaWiki-specific code samples, since usage differs slightly in and outside of MediaWiki.

Requiring Codex components in MediaWiki and extensions

Codex is included in MediaWiki. There are two ways you can access Codex Vue components in your ResourceLoader module: by including only the components you need, or by requiring the entire library of components.

Subset of components

It is recommended only to require the components you need to improve performance. To see a working example of this system, reference the CodexExample extension.

First, make the following changes to your ResourceLoader module definition in extension.json or skin.json:

Set the class to MediaWiki\\ResourceLoader\\CodexModule
Add a list of codexComponents, including all components and composables that you will be using

"ext.myExtension.blockform": {
    "class": "MediaWiki\\ResourceLoader\\CodexModule",
    "codexComponents": [
        "CdxButton",
        "CdxCard",
        "CdxDialog",
        "CdxIcon",
        "CdxRadio",
        "CdxTextInput",
        "useModelWrapper"
    ],
    "packageFiles": [
        "init.js",
        "BlockForm.vue"
    ],
    "messages": [
		"block-target",
		"ipb-submit"
	]
}

This will generate a virtual file, codex.js, in your resources directory with the exports you need. You can then require the components and composables you requested from that virtual file:

// In resources/ext.myExtension/BlockForm.vue
const { CdxButton, CdxTextInput } = require( '../codex.js' );

Entire library

You can access all Codex components by adding the @wikimedia/codex ResourceLoader module to your module's dependencies.

Example of the module definition (in extension.json format):

"ext.myExtension.blockform": {
	"dependencies": [
		"@wikimedia/codex"
	]
	"packageFiles": [
		"init.js",
		"BlockForm.vue"
	],
	"messages": [
		"block-target",
		"ipb-submit"
	]
}

Then you can import components and composables as follows:

// In resources/ext.myExtension/BlockForm.vue
const { CdxButton, CdxTextInput } = require( '@wikimedia/codex' );

Using Codex components in MediaWiki and extensions

Once you have included Codex components as a dependency of your ResourceLoader module and required them in your Vue file, you can then pass these components to the components option of your component, and use them in your component's template. Remember that kebab-case is required in templates , so you have to use <cdx-button> for CdxButton, <cdx-text-input> for CdxTextInput, etc.

Example

Example of a simple block form using the CdxButton and CdxTextInput components from Codex:

<template>
    <div class="mw-block-form">
        {{ $i18n( 'block-target' ) }}
        <cdx-text-input v-model="username"></cdx-text-input>
        <cdx-button
            type="primary"
            action="destructive"
            :disabled="!isUsernameSet"
            @click="blockUser"
        >
            {{ $i18n( 'ipb-submit' ) }}
        </cdx-button>
    </div>
</template>

<script>
// This assumes you're using a subset of Codex components as described above.
const { CdxButton, CdxTextInput } = require( '../codex.js' );

// @vue/component
module.exports = exports = {
    components: {
        CdxButton,
        CdxTextInput
    },
    data: {
        username: ''
    },
    computed: {
        isUsernameSet() {
            return this.username !== '';
        }
    },
    methods: {
        blockUser() {
            // ...
        }
    }
};
</script>