README.md
166 lines
| 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. |