diff --git a/docs/development/jump-menu.md b/docs/development/jump-menu.md index d65ab966c..8a66f2a31 100644 --- a/docs/development/jump-menu.md +++ b/docs/development/jump-menu.md @@ -15,35 +15,71 @@ lang: ee Add-ons can easily add custom items for the Jump Menu. -NOTE: Sample File: https://gist.github.com/obfuscode/77d0135970c9ce8bc84139c127507bb1 +TIP: If you are working with an existing add-on, we recommend you start with [Modernizing add-ons](development/modernizing-existing-add-ons.md) -1. Create a `jump.[addon_name].php` file in your add-on folder +## Creating your add-on jump file. +Jumps are created via the CLI by using the `make:jump` command. -2. Your jump file MUST have the following: +``` +php eecli.php make:jump +Let's create an add-on Jump File! +What add-on is the Jumps file being added to? (amazing_add_on, cron): [amazing_add_on] +Building Add-on Jumps file now. +Jumps file successfully created! Please note: You may need to clear your browser cache before you can see the new jump menu items + +``` + +Follow the prompts to add a jump file to your add-on. +This will create a `jump.amazing_add_on.php` file in your add-on. + +``` +amazing_add_on + ┣ jump.amazing_add_on.php + ┗ ... + ``` + +Please note, your jump file will contain of the following: use ExpressionEngine\Service\JumpMenu\AbstractJumpMenu; class [AddonName]_jump extends AbstractJumpMenu { - protected static $items = []; + protected static $items = array( + 'commandArrayTitle' => array( + 'icon' => 'fa-file', + 'command' => 'few lowercase words to be fuzzy-matched in jump menu', + 'command_title' => 'Displayed command title upon match from above', + 'dynamic' => false, + 'requires_keyword' => false, + 'target' => 'See Below. Behavior changes based on dynamic element above' + )); -3. Add commands for your custom items. -Item commands are comprised of the following: +To Add Jump Menu commands to your add-on, you simply add array elements to the `$items` array in the example generated -- `[commandTitle]` _(string)_ Unique command title used as key in global jumps array. Will be prefixed with `[addonName]:` so a command title in Assets of `editS3Source` will be `Assets:editS3Source` +The array of a Jump Menu command is comprised of the following keys: + +- `commandArrayTitle` _(string)_ Unique command title used as key in global jumps array. Will be prefixed with the add-ons name so a command title in the add-on AmazingAddOn of `processData` will be `AmazingAddon:processData` - `icon` _(string)_ FontAwesome format: `fa-file` -- `command` )(string)_ lowercase fuzzy-matched search text: `edit external source` -- `command_title` _(string)_ Human-readable command title, shows up in results +- `command` _(string)_ lowercase string to be fuzzy-matched when user is typing in jump menu: “edit external source” +- `command_title` _(string)_ Language file array key for Human-readable command title, shows up in results if fuzzy-matched. *Please note, this should be in your Lang file. NOTE: Style Note: We use bold, italics, and brackets to denote keywords and actions to the user and urge you to use keep your commands in line with this style: “Edit <b>Your Object</b> titled <i>[secondary keywords]</i>” “Edit Author titled [name]” -- `dynamic` _(bool)_ default: false, whether your command has secondary results + + +- `dynamic` _(bool)_ default: false, sets whether your command has secondary options in the jump menu - `requires_keyword` _(bool)_ default: false, Used in conjunction with `dynamic`. Whether your command requires additional keywords to return results or not. An example of a `false` would be returning a list of channels. An example of `true` would be returning entries where you don’t want to prematurely return them before the user enters something to filter by. -- `target` (string) +- `target` (string) Can NOT be to an external link - If `dynamic` == true: method name in your add-on’s jump file that will be called. Will be passed an array of search keywords. - If `dynamic` == false: method name to redirect the user to in your add-on (ex: settings/license) NOTE: This is currently hard-coded to `addons/settings/[addon_name]/X` but will most likely be changed to allow any CP URL path. +In addition to the required array elements above. There are also the following array element that is optional. +``` +'permission' => 'ban_users' + +``` +- `permission` _(string)_ ExpressionEngine Role permissions that has to be matched for a user to see this jump menu command. diff --git a/docs/toc_sections/_advanced_usage_toc.yml b/docs/toc_sections/_advanced_usage_toc.yml index 70d00b6d6..3b7bf38f7 100644 --- a/docs/toc_sections/_advanced_usage_toc.yml +++ b/docs/toc_sections/_advanced_usage_toc.yml @@ -158,6 +158,8 @@ href: cli/displaying-output.md - name: Adding Template Tags href: development/custom-template-tags.md + - name: Adding Jump Menu Items + href: development/jump-menu.md - name: Using Language Files href: development/add-on-language-files.md - name: Adding Publish Form Tabs @@ -166,6 +168,7 @@ href: development/prolets.md - name: Adding Dashboard Widgets href: development/widgets.md + #- name: REMOVE - Adding Text Formatting Options # href: development/text-formatting.md - name: Modernizing add-ons @@ -308,8 +311,6 @@ - name: Wiki Module href: development/extension-hooks/module/wiki.md - - name: Jump Menu - href: development/jump-menu.md - name: Learn About the Core href: development/architecture.md - name: Services