| 1 |
# WDEV Free Notices Module # |
| 2 |
|
| 3 |
WPMU DEV Free Notices module (short wpmu-free-notices) is used in our free plugins hosted on wordpress.org |
| 4 |
It will display, |
| 5 |
|
| 6 |
* A welcome message upon plugin activation that offers the user a 5-day introduction email course for the plugin. |
| 7 |
|
| 8 |
* After 7 days a message asking the user to rate the plugin on wordpress.org. |
| 9 |
|
| 10 |
* After 2 days a giveaway notice asking for email subscription. |
| 11 |
|
| 12 |
# How to use it # |
| 13 |
|
| 14 |
1. Insert this repository as **sub-module** into the existing project |
| 15 |
|
| 16 |
2. Include the file `module.php` in your main plugin file. |
| 17 |
|
| 18 |
3. Call the action `wpmudev_register_notices` with the params mentioned below. |
| 19 |
|
| 20 |
4. Done! |
| 21 |
|
| 22 |
|
| 23 |
# Upgrading to v2.0 |
| 24 |
|
| 25 |
The 2.0 release is backward incompatible with the 1.x versions. To accommodate new functionality and fix WordPress coding standards violations, a lot of the hooks/filters have been refactored. |
| 26 |
Make sure to change the following: |
| 27 |
|
| 28 |
1. Update the `do_action` hook name from `wdev-register-plugin` to `wpmudev_register_notices`. |
| 29 |
2. Update the params to new format (See example below). |
| 30 |
3. Both `wdev-email-message-` and `wdev-rating-message-` filters have been changed to `wdev_email_title_`/`wdev_email_message_` and `wdev_rating_title_`/`wdev_rating_message_` |
| 31 |
|
| 32 |
## IMPORTANT: |
| 33 |
|
| 34 |
DO NOT include this submodule in Pro plugins. These notices are only for wp.org versions. |
| 35 |
|
| 36 |
|
| 37 |
## Code Example : Registering a plugin (from Smush) ## |
| 38 |
|
| 39 |
``` |
| 40 |
#!php |
| 41 |
|
| 42 |
<?php |
| 43 |
add_action( 'admin_init', 'mycustom_free_notices_init' ); |
| 44 |
|
| 45 |
function mycustom_free_notices_init() { |
| 46 |
// Load the notices module. |
| 47 |
include_once 'external/free-notices/module.php'; |
| 48 |
|
| 49 |
// Register the current plugin for notices. |
| 50 |
do_action( |
| 51 |
'wpmudev_register_notices', |
| 52 |
'smush', // Required: plugin id. Get from the below list. |
| 53 |
array( |
| 54 |
'basename' => WP_SMUSH_BASENAME, // Required: Plugin basename (for backward compat). |
| 55 |
'title' => 'Smush', // Plugin title. |
| 56 |
'wp_slug' => 'wp-smushit', // Plugin slug on wp.org |
| 57 |
'cta_email' => __( 'Get Fast!', 'ga_trans' ), // Email button CTA. |
| 58 |
'installed_on' => time(), // Plugin installed time (timestamp). Default to current time. |
| 59 |
'screens' => array( // Screen IDs of plugin pages. |
| 60 |
'toplevel_page_smush', |
| 61 |
'smush_page_smush-bulk', |
| 62 |
'smush_page_smush-directory', |
| 63 |
), |
| 64 |
) |
| 65 |
); |
| 66 |
} |
| 67 |
``` |
| 68 |
|
| 69 |
> IMPORTANT: Make sure to initialize this on a hook which is executed in admin-ajax requests too. The recommended hook is `admin_init` |
| 70 |
|
| 71 |
## Plugins and IDs |
| 72 |
Only wp.org plugins are listed below. |
| 73 |
|
| 74 |
| Plugin | ID | |
| 75 |
|-------------|-------------| |
| 76 |
| Smush | smush | |
| 77 |
| Hummingbird | hummingbird | |
| 78 |
| Defender | defender | |
| 79 |
| SmartCrawl | smartcrawl | |
| 80 |
| Forminator | forminator | |
| 81 |
| Hustle | hustle | |
| 82 |
| Snapshot | snapshot | |
| 83 |
| Branda | branda | |
| 84 |
| Beehive | beehive | |
| 85 |
|
| 86 |
|
| 87 |
## Testing Notices |
| 88 |
|
| 89 |
To see the notices before the due time, you can fake the current time by appending `&wpmudev_notice_time=CUSTOMTIMESTAMP` to the url on a page where the notice should be visible. Please make sure you are using a timestamp after the due time. |
| 90 |
|
| 91 |
## Optional: Customize the notices via filters ## |
| 92 |
|
| 93 |
``` |
| 94 |
<?php |
| 95 |
// The email message contains 1 variable: plugin-name |
| 96 |
add_filter( |
| 97 |
'wdev_email_message_smush', // change plugin id. |
| 98 |
'custom_email_message' |
| 99 |
); |
| 100 |
function custom_email_message( $message ) { |
| 101 |
$message = 'You installed %s! This is a custom <u>email message</u>'; |
| 102 |
return $message; |
| 103 |
} |
| 104 |
``` |
| 105 |
|
| 106 |
``` |
| 107 |
<?php |
| 108 |
// The rating message contains 2 variables: user-name, plugin-name |
| 109 |
add_filter( |
| 110 |
'wdev_rating_message_smush', // Change plugin id. |
| 111 |
'custom_rating_message' |
| 112 |
); |
| 113 |
function custom_rating_message( $message ) { |
| 114 |
$message = 'Hi %s, you used %s for a while now! This is a custom <u>rating message</u>'; |
| 115 |
return $message; |
| 116 |
} |
| 117 |
``` |
| 118 |
|
| 119 |
``` |
| 120 |
<?php |
| 121 |
// To disable or enable a notice type. |
| 122 |
add_filter( |
| 123 |
'wpmudev_notices_is_disabled', |
| 124 |
'custom_rating_message', |
| 125 |
10, |
| 126 |
2 |
| 127 |
); |
| 128 |
function disable_rating_message( $disabled, $type, $plugin ) { |
| 129 |
if ( 'rate' === $type && 'beehive' === $plugin ) { |
| 130 |
return true; |
| 131 |
} |
| 132 |
|
| 133 |
return $disabled; |
| 134 |
} |
| 135 |
``` |
| 136 |
|
| 137 |
# Development |
| 138 |
|
| 139 |
Do not commit anything directly to `master` branch. The `master` branch should always be production ready. All plugins will be using it as a submodule. |
| 140 |
|
| 141 |
## Build Tasks (npm) |
| 142 |
|
| 143 |
Everything should be handled by npm. Note that you don't need to interact with Gulp in a direct way. |
| 144 |
|
| 145 |
| Command | Action | |
| 146 |
|----------------------|--------------------------------------------------------| |
| 147 |
| `npm run watch` | Compiles and watch for changes. | |
| 148 |
| `npm run compile` | Compile production ready assets. | |
| 149 |
| `npm run build` | Build production ready submodule inside `/build/` folder | |
| 150 |
|
| 151 |
## Git Workflow |
| 152 |
|
| 153 |
- Create a new branch from `dev` branch: `git checkout -b branch-name`. Try to give it a descriptive name. For example: |
| 154 |
- `release/X.X.X` for next releases |
| 155 |
- `new/some-feature` for new features |
| 156 |
- `enhance/some-enhancement` for enhancements |
| 157 |
- `fix/some-bug` for bug fixing |
| 158 |
- Make your commits and push the new branch: `git push -u origin branch-name` |
| 159 |
- File the new Pull Request against `dev` branch |
| 160 |
- Assign somebody to review your code. |
| 161 |
- Once the PR is approved and finished, merge it in `dev` branch. |
| 162 |
- Checkout `dev` branch. |
| 163 |
- Run `npm run build` and copy all files and folders from the `build` folder. |
| 164 |
- Checkout `master` branch and replace all files and folders with copied content from the build folder. |
| 165 |
- Commit and push the `master` branch changes. |
| 166 |
- Inform all devs to update the submodule. |
