Skip to content

Commit

Permalink
Replace 3 scripts with installation explanation and link to them
Browse files Browse the repository at this point in the history
  • Loading branch information
@TechnicJelle
TechnicJelle authored Apr 3, 2024
1 parent 2287223 commit 87c17a3
Showing 1 changed file with 11 additions and 200 deletions.
211 changes: 11 additions & 200 deletions community/Customisation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,17 @@ styles: [
This should make all BlueMap's buttons fully red.
From here on, you can customise any BlueMap class you want.

## WebApp Script Addons
Aside from custom CSS snippets, BlueMap also supports custom JavaScript snippets to customise the behaviour of the webapp.
You can find those in the [3rd Party Addons section of this wiki]({{site.baseurl}}3rdPartySupport.html), under the "script" platform filter.

The installation process for these is basically the same as for a CSS snippet:
Download, copy, or create a `.js` file in your webroot (usually `/bluemap/web/`).
Then you need to register that script with BlueMap, so it'll actually load it.
You do this in `webapp.conf`, by putting the file name in the `scripts: [ ]` list.
After adding it to the list, you'll probably want to reload BlueMap, so BlueMap applies the changes you've made to the configs.
You can do so with the `/bluemap reload light` command.

## Embed
In some places, when you share a link to your map, it'll embed a bit of extra info. In Discord it looks like this:

Expand Down Expand Up @@ -97,203 +108,3 @@ To fix that, you need an external webserver. Here is a guide on how to do that w

> It is not possible to do remove the port with an SRV Record, like you probably did for your Minecraft Server. Browsers do not support SRV Records.
{: .info .important }

## Watermark/Overlay Image
To add a "watermark" overlay image to your map, we'll need to write a little bit of JavaScript and CSS.

To get started, you should create two files: `watermark.js` and `watermark.css` in your webroot (usually `/bluemap/web/`).
Copy this into both of those files:

`/bluemap/web/watermark.js`:
```js
// JavaScript function to show the watermark
function showWatermark() {
const anchor = document.createElement("a"); //create HTML <a>
document.body.appendChild(anchor); //place it on the page
anchor.href = "https://bluemap.bluecolored.de/"; //set the link

const watermarkImage = document.createElement("img"); //create HTML <img>
anchor.appendChild(watermarkImage); //place it inside the just created <a>
watermarkImage.src = "https://avatars.githubusercontent.com/u/42522657"; //set the image URL
watermarkImage.id = 'watermarkImage'; //set the tag's ID, so the CSS style will apply to it
}

// Call the function to show the watermark
showWatermark();
```
> Feel free to change the `anchor.href` link and the `watermarkImage.src` link.
{: .info }

`/bluemap/web/watermark.css`:
```css
/* Apply to the HTML tag with the ID 'watermarkImage' */
#watermarkImage {
/* Place the image in the bottom left, 20 pixels from each side. */
bottom: 20px;
left: 20px;

/* Adjust this size as needed */
max-width: 150px;
max-height: 150px;

display: block;
position: fixed;
z-index: 9999;
}
```
> Feel free to change the placement and the size of the watermark.
{: .info }

Now you need to register these files with BlueMap, so it'll actually load them.
You do this in `webapp.conf`, by putting the file name of the script in the `scripts: [ ]` list,
and the file name of the style in the `styles: [ ]` list, like this:
```hocon
scripts: [
"watermark.js"
]
styles: [
"watermark.css"
]
```
After adding these to the lists, you need to reload BlueMap, so BlueMap applies the changes you've made to the configs.
You can do so with the `/bluemap reload light` command.

## Extra side-bar button
There is currently no simple way to do this, sadly. The best way would be to clone the BlueMap webapp source code, modify that, and recompile it.
That is very complicated, though, and also a lot of effort.

Luckily a community member has devised a workaround to do this anyway! (Even if it's not ideal...)
For this, we will make use of the BlueMap feature that allows us to inject any custom JavaScript snippets that we want.

To get started, you should create a `.js` file in your webroot (usually `/bluemap/web/`).
Then you need to register that script with BlueMap, so it'll actually load it.
You do this in `webapp.conf`, by putting the file name in the `scripts: [ ]` list.
After adding it to the list, you need to reload BlueMap, so BlueMap applies the changes you've made to the configs.
You can do so with the `/bluemap reload light` command.

Ththe following codeblock is the content of the script file. You can customise the text of the button by changing what's inside the label div,
and you can change what it links to by replacing the link in the `a`'s `href` attribute.

`/bluemap/web/my-custom-button.js`:
```js
const buttonTemplate = document.createElement("template");
buttonTemplate.innerHTML = `
<a style="text-decoration: none" href="https://bluemap.bluecolored.de/">
<div class="simple-button">
<div class="label">Visit BlueMap Website</div>
</div>
</a>
`.trim();
const button = buttonTemplate.content.firstChild;

setInterval(() => {
const buttonList = document.querySelector(".side-menu .content")?.children.item(0);
if (buttonList && Array.from(buttonList.children).every(el => el.tagName === "HR" || el.className === "simple-button")) {
buttonList.appendChild(button);
}
}, 10);
```
`plugins/BlueMap/webapp.conf`:
```hocon
scripts: [
"my-custom-button.js"
]
```
The example above will open your new button within the same window.
To force it to open within a new/separate tab within your browser, immediately after `href="https://bluemap.bluecolored.de/"`, include the following: `target="_blank"`.
Example:
```js
buttonTemplate.innerHTML = `
<a style="text-decoration: none" href="https://bluemap.bluecolored.de/" target="_blank">
<div class="simple-button">
<div class="label">Visit BlueMap Website</div>
</div>
</a>
`.trim();
```
## Map icons
Similar to adding a custom button to the side-bar, it's possible to include your own custom world icons. This would replace the existing tiny `"•"` to the left of the world name, represented by the sky colors.
To get started, you need to upload the world icon images that you'd like to use, into your assets webroot (usually `/bluemap/web/assets/`). Ideally, have the images be no larger than 32x32 pixels, and to use the code below, you should rename them to match the respective `.conf` file name found within `/BlueMap/maps/`, and the file type used in this example is a `.png`.
Examples:
- `/bluemap/web/assets/world.png`
- `/bluemap/web/assets/world_nether.png`
- `/bluemap/web/assets/world_the_end.png`
Next, you should create a `.js` file in your webroot (usually `/bluemap/web/`).
Then you need to register that script with BlueMap, so it'll actually load it.
You do this in `webapp.conf`, by putting the file name in the `scripts: [ ]` list.
After adding it to the list, you'll probably want to reload BlueMap, so BlueMap applies the changes you've made to the configs.
You can do so with the `/bluemap reload light` command.
`/bluemap/web/map-icons.js`:
```js
// trigger an update to map icons
document.body.addEventListener("click", function() {
setTimeout(updateMapBtns, 50); // needs slight delay to work properly
});

// updating the map buttons
function updateMapBtns() {
// find map-buttons (if available)
const mapBtns = document.querySelectorAll(".map-button");
mapBtns?.forEach(btn => {
// grab the "title" for the btn
let btnTitle = btn.getAttribute("title");

// grab the "display-name" to update the image alt-text
let btnName = btn.querySelector("span.name").innerText;

// replace sky "•" with block image
let btnSkySpan = btn.querySelector("span.sky");
let btnImg = `assets/${btnTitle}.png`;
let newImg = new Image();
newImg.src = btnImg;
newImg.alt = btnName;
btnSkySpan.innerText = ""; // remove the "•"
btnSkySpan.appendChild(newImg);
});
}
```
If you're using another image type that isn't `.png`, make sure to update this line to the appropriate file type (and location) you're using:
```js
let btnImg = `assets/${btnTitle}.png`;
```
Finally, you'll want to consider adding some custom CSS to have the images fit within the menu appropriately.
Repeat the process for creating a custom JavaScript file above, but for CSS.
Create a `.css` file in your webroot where the `.js` file is stored.
Then you need to register the styles.
In `webapp.conf`, put the CSS file name in the `styles: [ ]` list.
After adding it to the list, you'll probably want to reload BlueMap, so BlueMap applies the changes you've made to the configs.
You can do so with the `/bluemap reload light` command.
`/bluemap/web/map-icons.css`:
```css
/* map [world] icons */
.side-menu .map-button {
overflow: hidden;
}

.side-menu .map-button .sky {
font-size: 2em;
margin: 0 1em 0 0.5em;
}

.side-menu .map-button .sky img {
max-width: 32px;
max-height: 32px;
}
```

0 comments on commit 87c17a3

Please sign in to comment.