OUGC Custom Promotion Field

---

Allow administrators to select custom table fields to consider for group promotions.

📜 Table of Contents

• About
• Getting Started
  • Dependencies
  • File Structure
  • Install
  • Update
• Usage
• Built Using
• Authors
• Acknowledgments
• Support & Feedback

🚀 About

Custom Promotion Field is the plugin that takes MyBB Group Promotions to the next level! This powerful tool empowers administrators by allowing them to select custom tables and columns for seamless validation during group promotions. For a quick setup, a simple form simplifies the creation of a custom field, while an advanced form with JSON scripting caters to more complex verification needs. Tailor validations to specific criteria, ensuring precision in user group promotions, making MyBB's core group promotions more flexible to your forum's unique needs.

Go up to Table of Contents

📍 Getting Started

The following information will assist you into getting a copy of this plugin up and running on your forum.

Dependencies

A setup that meets the following requirements is necessary to use this plugin.

• MyBB >= 1.8
• PHP >= 7.0
• PluginLibrary for MyBB >= 13

File structure

 .
 ├── inc
 │ ├── languages
 │ │ ├── english
 │ │ │ ├── admin
 │ │ │ │ ├── users_ougc_custompromotionfield.lang.php
 │ │ │ ├── users_ougc_custompromotionfield.lang.php
 │ ├── plugins
 │ │ ├── ougc_custompromotionfield.php

Installing

Follow the next steps in order to install a copy of this plugin on your forum.

1. Download the latest package from the MyBB Extend site or from the repository releases.
2. Upload the contents of the Upload folder to your MyBB root directory.
3. Browse to Configuration » Plugins and install this plugin by clicking Install & Activate.

Updating

Follow the next steps in order to update your copy of this plugin.

1. Browse to Configuration » Plugins and deactivate this plugin by clicking Deactivate.
2. Follow step 1 and 2 from the Install section.
3. Browse to Configuration » Plugins and activate this plugin by clicking Activate.

If you are updating to 1.8.36 from any previous version:

1. After following the above steps, make sure to review your settings and templates as they were updated for this version.

Go up to Table of Contents

📖 Usage

Group Promotions

Read the following description to understand and design your custom promotions fields when managing your group promotions.

1. Go to the Administrator Control Panel, add or update a group promotion from Home » Users & Groups » Group Promotions.

• Custom Field: Table text
  • Select a custom table to consider for this promotion. This table has to exist within the forum table.
• Custom Field: Column text
  • Select a custom column to consider for this promotion. This column has to exist within the selected table above.
• Custom Field: Value text
  • Select the value to compare against for the selected column above.
• Custom Field: JSON Script text
  • JSON compatible script to set complex promotion verifications. If set, the above single custom field will be added to the end of the following objects automatically. Read the documentation for more on this.

Example Basic Custom Field

To promote users based on their last post date use the following configuration:

• Custom Field: Table users
• Custom Field: Column lastpost
• Custom Field: Value 3 - Months

Find more presets in the official forum.

JSON Complex Custom Fields

The plugin accepts a JSON compatible script to process complex custom verifications. Below is a description of the expected format.

• whereClauses array
  • tableName alphaNumeric
  • columnName alphaNumeric
  • columnValue mixed
    • Accepts single or multiple values (array)
  • columnOperator comparisonOperator
    • Allowed values: >, >=, =, !=, <=, <, <=>, IN, NOT IN, LIKE, NOT LIKE, LOWER, or UPPER
  • aggregateFunction aggregateFunction
    • Sanitized to float, integer, or string
    • Allowed values: COUNT, MAX, MIN, or SUM
  • aggregateAlias alphaNumeric
  • relationMainField mixed
    • Alphanumeric and dot . allowed.
  • relationSecondaryField mixed
    • Alphanumeric and dot . allowed.
• logicalOperator logicalOperator
  • Allowed values: AND, OR, or XOR

Because mixing probabilities are high and no validation is done on the script, it is possible to cause SQL errors which should at most cause the specific group promotion to fail. Test carefully to make sure your script works.

Example JSON Complex Custom Verification

The following script should validate the following:

• Get users with 3 or more threads.
• Count only visible threads.
• Count only threads from forums which forum identifier (fid) is 2 OR 30.

{
  "whereClauses": [
    {
      "tableName": "threads",
      "columnName": "tid",
      "columnValue": 3,
      "columnOperator": ">=",
      "aggregateFunction": "COUNT",
      "aggregateAlias": "totalThreads"
    },
    {
      "tableName": "threads",
      "columnName": "visible",
      "columnValue": 1,
      "columnOperator": "="
    },
    {
      "tableName": "threads",
      "columnName": "fid",
      "columnValue": [
        2,
        30
      ],
      "columnOperator": "IN"
    }
  ],
  "logicalOperator": "AND"
}

Go up to Table of Contents

⛏ Built Using

• MyBB - Web Framework
• MyBB PluginLibrary - A collection of useful functions for MyBB
• PHP - Server Environment

Go up to Table of Contents

✍️ Authors

• @Omar G - Idea & Initial work

See also the list of contributors who participated in this project.

Go up to Table of Contents

🎉 Acknowledgements

• The Documentation Compendium

Go up to Table of Contents

🎈 Support & Feedback

This is free development and any contribution is welcome. Get support or leave feedback at the official MyBB Community.

Thanks for downloading and using our plugins!

Go up to Table of Contents