Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Add partner docs directory; Add module management doc #8801

Merged
merged 1 commit into from
Feb 9, 2018
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 67 additions & 0 deletions docs/partners/managing-modules.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
# Customizing Jetpack's Modules

Occasionally, hosts have asked how they could customize Jetpack's modules. The documentation below will provide use cases and instructions on how to manage modules.

### How to get a list of modules

Before we can disable or force a module on or off, we need to know the slug of the module we want to modify. To get the slugs, we have a couple of options:modules

1) You can run `wp jetpack module list` to get list of module slugs as well as the status for each module.
2) You can view the PHP files directly in the `modules` directory in Jetpack. Each PHP file that is in the top-level `modules` direcory is loaded as a module. The module slug is the file name minus the extension.

### Disabling modules

In cases where Jetpack has a competing feature with a host, it may be preferable to disable the module in Jetpack. This is easily done via a filter in Jetpack, however, we would caution hosts to consider user experience when making this decision. If a user expects a commonly used module to be available, and it's not, that could cause confusion and a support request for the host and/or Jetpack support.

Now that we've got that warning out of the way, let's get to it!

The filter that we'll use to disable a module is `jetpack_get_available_modules`. You can find documentation as well as an example for that filter here:PHP

[https://developer.jetpack.com/hooks/jetpack_get_available_modules](https://developer.jetpack.com/hooks/jetpack_get_available_modules/)

Here are a couple more alternative examples:

#### Disabling the Photon module

```php
add_filter( 'jetpack_get_available_modules', 'jetpack_docs_filter_module_example' );
function jetpack_docs_filter_module_example( $modules ) {
if( isset( $modules['photon'] ) ) {
unset( $modules['photon'] );
}

return $modules;
}
```

#### Disabling the Lazy Images module

```php
add_filter( 'jetpack_get_available_modules', 'jetpack_docs_filter_module_example' );
function jetpack_docs_filter_module_example( $modules ) {
return array_diff_key( $modules, array( 'photon' => 'Does not matter' ) );
}
```

Note: As of Jetpack 5.8.0, there is a regression in filtering out the Photon module. While the module can be filtered out with the code above, the Jetpack admin UI shows an `undefined` string instead of hiding the setting. This behavior also applies to the Lazy Images module which was introduced in 5.8.0. This issue has been fixed in Automattic/jetpack#8780 which should go out in Jetpack 5.9.0.

### Forcing modules to be active

In some cases, a host may decide that forcing a module to be active may be preferable. For example, to minimize bandwidth on the host's server, a host could force the Photon module to be active. In these cases, it is possible to force a module on with the `jetpack_active_modules` filter.

Documentation for that filter can be found at the following URL:preferable

[https://developer.jetpack.com/hooks/jetpack_active_modules](https://developer.jetpack.com/hooks/jetpack_active_modules/)

Here's an example of how to force the Photon module to be activated:preferable

```php
add_filter( 'option_jetpack_active_modules', 'jetpack_docs_filter_active_modules' );
function jetpack_docs_filter_active_modules( $modules ) {
return array_values( array_merge( $modules, array( 'photon' ) ) );
}
```

Note: The Jetpack admin UI isn't yet aware of this filter. So, if you force a filter to be active, the UI to enable/disable that module still displays. This issue is being tracked at this URL:

[https://github.com/Automattic/jetpack/issues/8800](https://github.com/Automattic/jetpack/issues/8800)