Mod Creation/Sidebar API Reference: Difference between revisions
(Use SyntaxHighlight) |
(Fix incorrect IDs for sidebar skills) |
||
(3 intermediate revisions by the same user not shown) | |||
Line 186: | Line 186: | ||
<syntaxhighlight lang="js" line>// Move Astrology above Firemaking | <syntaxhighlight lang="js" line>// Move Astrology above Firemaking | ||
sidebar.category('Non-Combat').item('Astrology', { before: 'Firemaking' }); | sidebar.category('Non-Combat').item('melvorD:Astrology', { before: 'melvorD:Firemaking' }); | ||
// Create a new item and add a subitem beneath it | // Create a new item and add a subitem beneath it | ||
Line 203: | Line 203: | ||
'''Example''' | '''Example''' | ||
<syntaxhighlight lang="js" line>sidebar.category('Combat').removeItem('Attack');</syntaxhighlight> | <syntaxhighlight lang="js" line>sidebar.category('Combat').removeItem('melvorD:Attack');</syntaxhighlight> | ||
=== removeAllItems(): void === | === removeAllItems(): void === | ||
Line 290: | Line 290: | ||
<syntaxhighlight lang="js" line>// Navigate to the Woodcutting page | <syntaxhighlight lang="js" line>// Navigate to the Woodcutting page | ||
sidebar.category('Non-Combat').item('Woodcutting').click();</syntaxhighlight> | sidebar.category('Non-Combat').item('melvorD:Woodcutting').click();</syntaxhighlight> | ||
=== toggle(force?: boolean): void === | === toggle(force?: boolean): void === | ||
Line 316: | Line 316: | ||
<syntaxhighlight lang="js" line>// Removes the Summoning skill from the sidebar | <syntaxhighlight lang="js" line>// Removes the Summoning skill from the sidebar | ||
sidebar.category('Non-Combat').item('Summoning').remove();</syntaxhighlight> | sidebar.category('Non-Combat').item('melvorD:Summoning').remove();</syntaxhighlight> | ||
=== subitem(id: string, config?: SubitemConfig, builder?: (subitem: Subitem) => void): Subitem === | === subitem(id: string, config?: SubitemConfig, builder?: (subitem: Subitem) => void): Subitem === | ||
Line 342: | Line 342: | ||
// Add a shortcut to Alt. Magic beneath Magic | // Add a shortcut to Alt. Magic beneath Magic | ||
sidebar.category('Combat').item('Magic').subitem('Alt. Magic', { | sidebar.category('Combat').item('melvorD:Magic').subitem('Alt. Magic', { | ||
onClick() { | onClick() { | ||
sidebar.category('Non-Combat').item(' | sidebar.category('Non-Combat').item('melvorD:Magic').click(); | ||
} | } | ||
});</syntaxhighlight> | });</syntaxhighlight> |
Latest revision as of 01:07, 15 June 2023
The sidebar
object is a global variable and is used to customize the side (left-hand) navigation menu.
The sidebar is organized into four levels:
- Sidebar
- Category
- e.g. "Combat"
- Item
- e.g. "Attack" under "Combat"
- Subitem
- e.g. "Skills" under "Completion Log"
- Category
Sidebar
The global sidebar
object.
category(id: string, config?: CategoryConfig, builder?: (category: Category) => void): Category
Alternatively category(id: string, builder?: (category: Category) => void): Category
Gets or creates then gets a category by its id
.
Parameters
id: string
The id of the category to get or create
config?: CategoryConfig
An optional configuration object that may be used to configure either a new or existing category. See CategoryConfig within the Category section below.
builder?: (category: Category) => void
An optional callback that receives the category as a parameter. Useful for adding items to the category without needing to store it as a variable.
Returns
Category
The category object.
Example
// Move COMBAT skills to be below NON-COMBAT
sidebar.category('Combat', { after: 'Non-Combat' });
// Create a new category "GREETINGS" and add an item beneath it
sidebar.category('Greetings', { toggleable: true }, (greetings) => {
greetings.item('Hello');
});
categories(): Category[]
Returns
Category[]
An ordered array of all categories.
Example
const allCategories = sidebar.categories();
removeCategory(id: string): void
Remove a category by its id
.
Parameters
id: string
The id of the category to remove.
Example
sidebar.removeCategory('Combat');
removeAllCategories(): void
Remove all categories from the sidebar. Not completely sure why you'd want to do that, though.
Example
sidebar.removeAllCategories();
Category
See sidebar's category
method for category creation.
CategoryConfig
All properties are optional.
interface CategoryConfig {
rootClass?: string | null; // String separated classes to add to the rootEl
categoryClass?: string | null; // String separated classes to add to the categoryEl
name?: string | HTMLElement | null; // Override the displayed name (defaults to category id)
nameClass?: string | null; // String separated classes to add to the nameEl
toggleable?: boolean | null; // Determines if the category can be hidden (example: Combat & Non-Combat)
before?: string; // Places the category before another category by id. Cannot be present if after is defined.
after?: string; // Places the category after another category by id. Cannot be present if before is defined.
onClick?: (() => void) | null; // Code to execute if the category title is clicked
onRender?: (elements: CategoryElements) => void; // See notes below
}
If creating a new category and neither a before
nor after
is defined, the category is added to the bottom of the sidebar.
You can pass null to any property to remove previously configured options. For example, setting name
to null
sets the display of the category back to its id.
The onRender
property can be set to a callback that will receive an object containing the category's HTML element properties once the sidebar is rendered. This is because the sidebar can be configured before it is rendered so a category's rootEl
property will be undefined
until it has been rendered. The elements parameter contains the following:
interface CategoryElements {
rootEl: HTMLLIElement;
categoryEl: HTMLDivElement;
nameEl: HTMLSpanElement;
toggleEl?: HTMLElement;
}
id: string
(Property) The category's id.
rootEl: HTMLLIElement
(Property) The category's root HTML element. This contains the categoryEl
and all item's rootEl's
.
categoryEl: HTMLDivElement
(Property) The category's primary HTML element. This contains the nameEl
and toggleEl
, if defined.
nameEl: HTMLSpanElement
(Property) The category's name HTML element. This contains the defined name
property.
toggleEl: HTMLElement
(Property) The category's toggle HTML element (the visibility eyecon). This is undefined
if the category's toggleable
property is set to false
or null
.
click(): void
Trigger's the category's configured onClick
property, if present.
Example
const clickMe = sidebar.category('Click Me', {
onClick() {
console.log('I have been clicked!');
}
});
clickMe.click(); // I have been clicked!
toggle(force?: boolean): void
Toggles the category's visibility.
Parameters
force?: boolean
Optionally set to true
to force display the category, false
to hide.
Example
// Show Combat items if currently hidden, or hide if currently being shown
sidebar.category('Combat').toggle();
// Hide Non-Combat items
sidebar.category('Non-Combat').toggle(false);
remove(): void
Removes this category from the sidebar.
Example
// Remove Non-Combat skills
sidebar.category('Non-Combat').remove();
item(id: string, config?: ItemConfig, builder?: (item: Item) => void): Item
Alternatively item(id: string, builder?: (item: Item) => void): Item
Gets or creates then gets an item by its id
.
Parameters
id: string
The id of the item to get or create
config?: ItemConfig
An optional configuration object that may be used to configure either a new or existing item. See ItemConfig within the Item section below.
builder?: (item: Item) => void
An optional callback that receives the item as a parameter. Useful for adding subitems to the item without needing to store it as a variable.
Returns
Item
The item object.
Example
// Move Astrology above Firemaking
sidebar.category('Non-Combat').item('melvorD:Astrology', { before: 'melvorD:Firemaking' });
// Create a new item and add a subitem beneath it
sidebar.category('General').item('Greetings', { nameClass: 'text-warning' }, (greetings) => {
greetings.subitem('Hello');
});
removeItem(id: string): void
Remove an item from the category by its id
.
Parameters
id: string
The id of the item to remove
Example
sidebar.category('Combat').removeItem('melvorD:Attack');
removeAllItems(): void
Remove all items from the category.
Example
sidebar.category('Combat').removeAllItems();
Item
ItemConfig
All properties are optional.
interface ItemConfig {
rootClass?: string | null; // String separated classes to add to the rootEl
itemClass?: string | null; // String separated classes to add to the itemEl
icon?: string | HTMLElement | null; // Either a URL (string) or an HTMLElement to appear in the item's icon slot.
iconClass?: string | null; // String separated classes to add to the iconEl
name?: string | HTMLElement | null; // Override the displayed name (defaults to item id)
nameClass?: string | null; // String separated classes to add to the nameEl
aside?: string | HTMLElement | null; // Text or HTMLElement to be displayed in the aside slot. Example: level (1/99) text on skills.
asideClass?: string | null; // String separated classes to add to the asideEl
link?: string | null; // URL to open if this item is clicked
ignoreToggle?: boolean | null; // Set to true if this item should be visible even if its parent category is hidden. Example: Combat Level under the Combat category.
before?: string; // Places the item before another item by id. Cannot be present if after is defined.
after?: string; // Places the item after another item by id. Cannot be present if before is defined.
onClick?: (() => void) | null; // Code to be executed if the item is clicked
onRender?: (elements: ItemElements) => void; // See notes below
}
If creating a new item and neither a before
nor after
is defined, the item is added to the bottom of the category.
You can pass null to any property to remove previously configured options. For example, setting name
to null
sets the display of the item back to its id.
The onRender
property can be set to a callback that will receive an object containing the item's HTML element properties once the sidebar is rendered. This is because the sidebar can be configured before it is rendered so an item's HTML element properties will be undefined
until it has been rendered. The elements
parameter contains the following:
interface ItemElements {
rootEl: HTMLLIElement;
itemEl: HTMLAnchorElement;
iconEl: HTMLSpanElement;
nameEl: HTMLSpanElement;
asideEl?: HTMLElement;
subMenuEl?: HTMLUListElement;
}
id: string
(Property) The item's id.
rootEl: HTMLLIElement
(Property) The item's root HTML element. This contains the itemEl
and subMenuEl
.
itemEl: HTMLAnchorElement
(Property) The item's primary HTML element. This contains the iconEl
, nameEl
, and asideEl
.
iconEl: HTMLSpanElement
(Property) The item's icon HTML element. This contains the defined icon
property.
nameEl: HTMLSpanElement
(Property) The item's name HTML element. This contains the defined name
property.
asideEl: HTMLElement
(Property) The item's aside HTML element. This contains the defined aside
property. This is undefined
if no aside
property is set.
subMenuEl: HTMLUListElement
(Property) The item's sub-menu HTML element. Contains any subitems defined. This is undefined
if no subitems exist.
category: Category
(Property) The parent category of the item.
click(): void
Triggers the item's configured onClick
property, if present.
Example
// Navigate to the Woodcutting page
sidebar.category('Non-Combat').item('melvorD:Woodcutting').click();
toggle(force?: boolean): void
Toggles the visibility of the item's subitem menu, if any subitems exist.
Parameters
force?: boolean
Optionally set to true
to force display the category, false
to hide.
Example
// Collapse (hide) the Completion Log's submenu if currently expanded (shown)
// Or expand (show) the submenu if currently collapsed (hidden)
sidebar.category('General').item('Completion Log').toggle();
// Collapse (hide) the Completion Log's submenu
sidebar.category('General').item('Completion Log').toggle(false);
remove(): void
Removes this item from the parent category.
Example
// Removes the Summoning skill from the sidebar
sidebar.category('Non-Combat').item('melvorD:Summoning').remove();
subitem(id: string, config?: SubitemConfig, builder?: (subitem: Subitem) => void): Subitem
Alternatively subitem(id: string, builder: (subitem: Subitem) => void): Subitem
Gets or creates then gets a subitem by its id.
Parameters
id: string
The id of the subitem to get or create
config?: SubitemConfig
An optional configuration object that may be used to configure either a new or existing subitem. See SubitemConfig within the Subitem section below.
builder?: (subitem: Subitem) => void
An optional callback that receives the subitem as a parameter
Returns
Subitem
The subitem object
Example
// Move Pets above Skills in the Completion Log
sidebar.category('General').item('Completion Log').subitem('Pets', { before: 'Skills' });
// Add a shortcut to Alt. Magic beneath Magic
sidebar.category('Combat').item('melvorD:Magic').subitem('Alt. Magic', {
onClick() {
sidebar.category('Non-Combat').item('melvorD:Magic').click();
}
});
removeSubitem(id: string): void
Remove a subitem from the item by its id
.
Parameters
id: string
The id of the subitem to remove
Example
sidebar.category('General').item('Completion Log').removeSubitem('Skills');
removeAllSubitems(): void
Removes all subitems from the item.
Example
sidebar.category('General').item('Completion Log').removeAllSubitems();
Subitem
SubitemConfig
interface SubitemConfig {
rootClass?: string | null; // String separated classes to add to the rootEl
subitemClass?: string | null; // String separated classes to add to the subitemEl
name?: string | HTMLElement | null; // Override the displayed name (defaults to subitem id)
nameClass?: string | null; // String separated classes to add to the nameEl
aside?: string | HTMLElement | null; // Text or HTMLElement to be displayed in the aside slot. Example: completion percentages in the Completion Log.
asideClass?: string | null; // String separated classes to add to the asideEl
link?: string | null; // URL to open if this item is clicked
before?: string; // Places the subitem before another subitem by id. Cannot be present if after is defined.
after?: string; // Places the item after another item by id. Cannot be present if before is defined.
onClick?: (() => void) | null; // Code to be executed if the subitem is clicked
onRender?: (elements: SubitemElements) => void; // See notes below
}
If creating a new subitem and neither a before
nor after
is defined, the subitem is added to the bottom of the parent item's sub-menu.
You can pass null
to any property to remove previously configured options. For example, setting name
to null
sets the display of the subitem back to its id.
The onRender property can be set to a callback that will receive an object containing the subitem's HTML element properties once the sidebar is rendered. This is because the sidebar can be configured before it is rendered so a subitem's HTML element properties will be undefined
until it has been rendered. The elements
parameter contains the following:
interface SubitemElements {
rootEl: HTMLLIElement;
subitemEl: HTMLAnchorElement;
nameEl: HTMLSpanElement;
asideEl?: HTMLElement;
}
id: string
(Property) The subitem's id.
rootEl: HTMLLIElement
(Property) The subitem's root HTML element. This contains the ubitemEl
.
subitemEl: HTMLAnchorElement
(Property) The subitem's primary HTML element. This contains the nameEl
and asideEl
.
nameEl: HTMLSpanElement
(Property) The subitem's name HTML element. This contains the defined name
property.
asideEl: HTMLElement
(Property) The subitem's aside HTML element. This contains the defined aside
property. This is undefined
if no aside
property is set.
item: Item
(Property) The parent item of the subitem.
click(): void
Triggers the subitem's configured onClick
property, if present.
Example
// Navigate to the Completion Log's Items page
sidebar.category('General').item('Completion Log').subitem('Items').click();
remove(): void
Removes this subitem from the parent item.
Example
// Remove Items from the Completion Log sidebar
sidebar.category('General').item('Completion Log').subitem('Items').remove();
Melvor Idle version v1.3 (Released: 13th June 2024) | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||
Skills:
| ||||||||||||||||||||
Other:
| ||||||||||||||||||||
Reference Tables: Items, Equipment, Experience Table, Upgrading Items, Combat Areas, Slayer Areas, Dungeons, Strongholds, The Abyss, Monsters |