Skip to content

Customization

echicken edited this page Mar 13, 2019 · 5 revisions

CSS

This web interface uses Bootstrap 3.3.5. It should be possible to use any compatible stylesheet.

  • You can place your own CSS overrides in webv4/root/css/custom.css. Create this file and use it if you want to use fonts, colours, etc. other than the defaults. It is not recommended that you modify any of the existing stylesheets.

Sidebar Modules

Sidebar modules are the widgets displayed in the narrow column running down the right (or left) side of the page. A sidebar module can be an SSJS, XJS, HTML, or TXT file.

  • Sidebar modules are loaded in alphanumeric order from the webv4/sidebar/ directory; see the included files for examples and for a file-naming convention that enforces order of appearance
  • HTML, XJS, and SSJS sidebar modules should not be complete HTML documents. They should not have <html>, <head>, or <body> tags. Instead, they should contain (or produce) an HTML snippet suitable for inclusion in the overall page.
  • TXT sidebar modules are displayed inside of <pre> tags to preserve fixed-width formatting.
  • Support for additional file formats can be added if necessary, but by using HTML and Javascript you should be able to display whatever you like. (If you want to put an image in the sidebar, a simple HTML file containing an <img> tag will do the job, for example.)

Pages

Several default Pages (Home, Forum, User List, etc.) are included with this web interface, but you can also create your own. Like sidebar modules, Pages can be HTML, XJS, SSJS, or TXT files. A special file type, .link can be used to add a menu entry that links to an external site.

  • Pages are loaded into the menu bar from the webv4/pages/ directory, in alphanumeric order. See the included files for examples and for a file-naming convention that enforces order of appearance.
  • As with sidebar modules, HTML, XJS, and SSJS pages should not be complete HTML documents. They should contain (or generate) snippets of text or HTML suitable for inclusion in the overall page.
  • Your webv4/pages/ directory can contain a webctrl.ini file.
    • You can use this file to restrict access to certain pages so that guests or unprivileged users can't see them
  • In an HTML, XJS, or SSJS file, the first line containing a comment is treated as the control line for the page.
    • The format of the control line is OPTION|OPTION:Title
    • Available options at the moment are HIDDEN and NO_SIDEBAR
    • HIDDEN pages will not appear in the menus or in the activity fields of the who's online list
    • The NO_SIDEBAR directive tells the layout script not to include a sidebar on this page
      • The main content will expand to fill the space normally used by the sidebar
    • The part of the control line following the first colon is treated as the title of the page. This is the text that appears in the menu, browser title bar, and who's online list.
      • If you don't need to specify any options, (and as long as your page title doesn't contain a colon) you can omit the colon, and the entire string will be treated as the title of the page, or you can start the control line with a colon.

Here's an example control line for a hidden HTML file:

<!--HIDDEN:My Awesome Web Page-->

Here's an example control line for a hidden XJS page with no sidebar:

<!--HIDDEN|NO_SIDEBAR:My Awesome Web Page-->

Here's an example control line for an SSJS script with no settings:

//My Awesome Web Page

If your page title contains a colon, it's necessary to prepend a dummy one like so:

//:Awesome Web Pages: This is one

Of course, that's not an issue if you're providing some settings:

<!--NO_SIDEBAR:Awesome Web Pages: This is one-->

You can add drop-down menus to the navigation bar by adding subdirectories to the webv4/pages/ directory. The files within these subdirectories follow the same format described above.

  • The name of the subdirectory is used as the text of the menu item.
  • You can nest additional subdirectories to create sub-menus.
  • Subdirectories with names beginning with . will be ignored.
  • Each subdirectory can contain a webctrl.ini file for access control.

External Links

Your navigation bar and submenus can include links to external sites, or internal pages that are not part of this web interface. To add a link to an external site, create a .link file in your web/pages/ directory or a subdirectory thereof. The format of a .link file is url,title on a single line, for example creating this file:

web/pages/999-synchronet.link

with these contents:

http://synchro.net/,Synchronet BBS

would add a Synchronet BBS link to your menu bar, pointing to http://synchro.net/.

Including images/other content in Pages and Sidebar Modules

If you want to include an image or link to some other kind of asset in a Page or Sidebar Module, place the file to be included somewhere under your webv4/root/ directory (eg. in web/root/images/) and then reference it accordingly:

<!--My Image Gallery-->
<img src="/images/some-picture.png">
<img src="/images/some-other-picture.png">
<a href="/files/album.zip">Download this photo album</a>

You can create subdirectories under webv4/root/ to organize content as you see fit.

Appearance & Layout

Page layout is mainly controlled by three files:

  • web/root/index.xjs
  • web/root/css/style.css
  • web/root/css/custom.css

By default, that last file (web/root/css/custom.css) does not exist. You can create it and add any CSS rules that you like, overriding any rules set by web/root/css/style.css in the process. Many changes to the appearance (colours, background graphics, etc.) can be made via CSS.

Modification of web/root/index.xjs is discouraged, and I'm not interested in supporting your broken hack of this script should you choose to interfere with it. With that having been said, it's your website and you can do what you like with it. Just be sure to back up your copy of index.xjs prior to running the install/update script, as any changes you've made will be lost.

You can’t perform that action at this time.