From 201636b175a8160de12b46f053f1cf7ddb545167 Mon Sep 17 00:00:00 2001 From: Tom Jaeger Date: Fri, 6 Jan 2023 12:49:58 -0500 Subject: [PATCH 1/5] updating docs on how to make jump menu command for clarity --- docs/development/jump-menu.md | 37 +++++++++++++++++++++++++---------- 1 file changed, 27 insertions(+), 10 deletions(-) diff --git a/docs/development/jump-menu.md b/docs/development/jump-menu.md index d65ab966c..08dc05fce 100644 --- a/docs/development/jump-menu.md +++ b/docs/development/jump-menu.md @@ -17,33 +17,50 @@ Add-ons can easily add custom items for the Jump Menu. NOTE: Sample File: https://gist.github.com/obfuscode/77d0135970c9ce8bc84139c127507bb1 -1. Create a `jump.[addon_name].php` file in your add-on folder +Create a `jump.[addon_name].php` file in your add-on folder -2. Your jump file MUST have the following: +Your jump file MUST have 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 elemnts to the $items array in the example above -- `[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 Assets of `editS3Source` will be `Assets:editS3Source` - `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. From b1c5e864a4fe302ee8c82ff5df475acd7a3dd0b6 Mon Sep 17 00:00:00 2001 From: Tom Jaeger Date: Fri, 6 Jan 2023 13:04:24 -0500 Subject: [PATCH 2/5] spelling fix --- docs/development/jump-menu.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development/jump-menu.md b/docs/development/jump-menu.md index 08dc05fce..add236683 100644 --- a/docs/development/jump-menu.md +++ b/docs/development/jump-menu.md @@ -36,7 +36,7 @@ Your jump file MUST have the following: 'target' => 'See Below. Behavior changes based on dynamic element above' )); -To Add Jump Menu commands to your add-on, you simply add array elemnts to the $items array in the example above +To Add Jump Menu commands to your add-on, you simply add array elements to the $items array in the example above The array of a Jump Menu command is comprised of the following keys: From c92493aca3912d93841338329add7d0ee62071af Mon Sep 17 00:00:00 2001 From: Matt Johnson Date: Tue, 31 Jan 2023 11:14:52 -0600 Subject: [PATCH 3/5] Remove extra character --- docs/development/jump-menu.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development/jump-menu.md b/docs/development/jump-menu.md index add236683..a830c63f4 100644 --- a/docs/development/jump-menu.md +++ b/docs/development/jump-menu.md @@ -42,7 +42,7 @@ 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 Assets of `editS3Source` will be `Assets:editS3Source` - `icon` _(string)_ FontAwesome format: `fa-file` -- `command` )_(string)_ lowercase string to be fuzzy-matched when user is typing in jump menu: “edit external source” +- `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: From 083b15e99a671dff5c21d40ed869e2506c51d718 Mon Sep 17 00:00:00 2001 From: Tom Jaeger Date: Tue, 14 Feb 2023 12:14:41 -0500 Subject: [PATCH 4/5] updated jump menu docs to instruct people to use the CLI.. moved in navigation --- docs/development/jump-menu.md | 27 +++++++++++++++++++---- docs/toc_sections/_advanced_usage_toc.yml | 5 +++-- 2 files changed, 26 insertions(+), 6 deletions(-) diff --git a/docs/development/jump-menu.md b/docs/development/jump-menu.md index a830c63f4..1dc4731b0 100644 --- a/docs/development/jump-menu.md +++ b/docs/development/jump-menu.md @@ -15,11 +15,30 @@ 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) -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. -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 have the following: use ExpressionEngine\Service\JumpMenu\AbstractJumpMenu; @@ -36,7 +55,7 @@ Your jump file MUST have the following: 'target' => 'See Below. Behavior changes based on dynamic element above' )); -To Add Jump Menu commands to your add-on, you simply add array elements to the $items array in the example above +To Add Jump Menu commands to your add-on, you simply add array elements to the $items array in the example generated The array of a Jump Menu command is comprised of the following keys: diff --git a/docs/toc_sections/_advanced_usage_toc.yml b/docs/toc_sections/_advanced_usage_toc.yml index 67530e8bd..2737b3eb0 100644 --- a/docs/toc_sections/_advanced_usage_toc.yml +++ b/docs/toc_sections/_advanced_usage_toc.yml @@ -154,6 +154,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 @@ -162,6 +164,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: Accessing the Database @@ -302,8 +305,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 From a29af9ff20624fb6e30783b1743226af4a5c1a6f Mon Sep 17 00:00:00 2001 From: Matt Johnson Date: Tue, 14 Feb 2023 12:45:31 -0600 Subject: [PATCH 5/5] Update to not use Assets as an example --- docs/development/jump-menu.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/development/jump-menu.md b/docs/development/jump-menu.md index 1dc4731b0..8a66f2a31 100644 --- a/docs/development/jump-menu.md +++ b/docs/development/jump-menu.md @@ -23,7 +23,7 @@ Jumps are created via the CLI by using the `make:jump` command. ``` 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] +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 @@ -38,28 +38,28 @@ amazing_add_on ┗ ... ``` -Please note, your jump file will have the following: +Please note, your jump file will contain of the following: use ExpressionEngine\Service\JumpMenu\AbstractJumpMenu; class [AddonName]_jump extends AbstractJumpMenu { - 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' - )); + 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' + )); -To Add Jump Menu commands to your add-on, you simply add array elements to the $items array in the example generated +To Add Jump Menu commands to your add-on, you simply add array elements to the `$items` array in the example generated 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 Assets of `editS3Source` will be `Assets:editS3Source` +- `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 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.