Customization - rejetto/hfs GitHub Wiki

HFS 3 customization is very different and not compatible with things made for HFS 2. In principle, you can do fewer things because the old system was very easy to break at each update. Too much power = too much responsibility.

Customization capabilities are work in progress. Feel free to suggest ideas.

The basic idea is that if you need to make a change, you should use style rules (CSS), or sometimes the translation of text. If you need to remove things, still do it with CSS. In some cases even additions can be obtained with CSS, but in most cases you'll want to type the HTML.

Adding HTML

Go to Admin-panel > Custom HTML and find the correct section. For example, select the "before login" section and your HTML will be added inside the login dialog, on top. There's a "script" section dedicated to JavaScript.

There's no documentation yet on where the sections apply, but hopefully, the names are clear enough.

All sections are saved to a file custom.html that you can edit with any text editor. The syntax (borrowed from HFS2) consists of each section starting with a line like this

[sectionName]

so that the whole file is divided in different sections.

Adding CSS

Go to Admin-panel > Custom HTML and select the "style" section. Example:

#root { background: red }

We have currently no documentation on classes and IDs, so please inspect the DOM with your browser to figure out the rules you need (right click > inspect).

Please note we are using some CSS variables like --bg, --text, and --button-bg that can make your work much easier. Have a look at the blue background example.

Dev-tools

There's a way to generate the style code by using a tool that most browsers have, often called developer tools.

The following example is based on Chrome, and it shows how I can make the backdrop of the login-dialog red.

This is not the only possible way to operate, but one of the easier ones.

https://github.com/rejetto/hfs/assets/1367199/a9c15d72-a840-423b-ade2-59afa596a464

Images

To include images you have a few options:

  • with a hidden folder:
    • put your image files in a folder, like "images"
    • share it in the VFS
    • remove visibility (Who can see: none)
    • now you can refer to these files in your HTML/style because they are accessible like /images/logo.png
  • embed small files in style
  • use emoji

Icons

All icons used in the interface (starting with HFS 0.56) can be customized by creating a folder "icons" inside the current working directory (cwd), and putting image files whose name match one in this list. For example, put a file "login.png" into "icons" to customize the login icon.

If you want to customize icons for the files, you may want to take a look at the file-icons plugin.

Changing text

This works only starting with version 3.0.0-beta1 Let's say you want to change the "Invalid credentials" message; we'll change it to "Bad username or password". You should

  1. look for the original text inside the translation file. Since the message we are looking for is english, we'll search for it in the english file: https://github.com/rejetto/hfs/blob/main/src/langs/hfs-lang-en.json We find the row
        "login_bad_credentials": "Invalid credentials",

We need the part before the colon, also know as the key, that is login_bad_credentials.

  1. Open the Admin-panel > Custom HTML, section Script, and add this
HFS.customizeText({
  login_bad_credentials: "Bad username or password",
})

If your users were already on the page, they need to reload.

In the example above, the customization applies to ALL languages. In case you wanted to restrict it to english only, do it like this

HFS.customizeText({
  login_bad_credentials: "Bad username or password",
}, 'en')

we just added the 'en' as second parameter.

Examples

Set a wider list

Add this CSS to the "style" section

.list-wrapper { max-width: 100em; }

Adding text or image to login dialog

You can add any text ("My test" in the example) and get something like this (screenshot taken with dark theme)

Add the text in custom HTML, section "before login". But since it's HTML, you can create almost anything, like an image, with some basic code

<img src='http://rejetto.com/pics/rejetto.com.gif'>

In the example we are using a file hosted on another server.

You probably want to host your image in HFS itself by adding it to the Virtual File System, possibly hidden (removing the "can see" permission), so the address becomes something like url(/my-hidden-folder/my-logo.png)

Blue background

In "style" add this

:root { --bg: #258; --text: #fff; }
a { color: #fff; text-decoration: underline; }

We are using underline to distinguish links that are in this example same color as normal text. The result will look like this

Add a "Copy link" to file menu

Add this to section "script"

    HFS.onEvent('fileMenu', ({ entry }) => ({
      label: "Copy link",
      async onClick() { 
        copy(location.origin + entry.uri)
        HFS.dialogLib.alertDialog("Link copied")
      }
    }))

function copy(x) { const d = document; const ta = d.createElement("textarea"); ta.textContent = x; d.body.appendChild(ta); ta.select();  d.execCommand("copy"); d.body.removeChild(ta) }

Consider click on the whole row as if the file/folder entry was clicked

Add this to section "script"

document.addEventListener('click', ({ target: t }) => {
  if (t.tagName === 'LI' && t.closest('ul.dir'))
      t.querySelector('a')?.click()
})

Hide paging bar at the bottom

Add this to section "Style"

#paging { display: none }

Make "Get list" recursive

Add this to section "script"

HFS.onEvent('fileMenu', ({ menu }) => {
  for (let x of menu)
    if (x?.id === 'list')
      x.href += '&depth=*'
})

Clicking the icon/thumbnail will 'show' instead of menu/open

HFS.onEvent('entryIcon', ({ def, entry }, { output }) => {
    const otherPlugin = output.find(Boolean)
    if (otherPlugin)
        output.length = 0 // remove other
    return HFS.h('span', { 
        onClick(e) {
            if (!HFS.fileShow(entry)) return
            e.stopPropagation()
            e.preventDefault()
        } 
    }, otherPlugin || def)
})

Execute another program at a regular interval

Consider a file myscript.bat that I want to run once a week; enter this in the "Server code", in admin-panel/options:

exports.init = api => {
  const { exec } = api.require('child_process')
  const { repeat } = api.require('./misc')
  const DAY = 86400*1000
  const cancel = repeat(7 * DAY, () =>
    exec('myscript.bat', err => console.log('myscript error:', err || 'none 👍')) )
  return { unload: cancel }
}