webv4 Customization

Cascading Style Sheets can customize the look and layout of your site. In particular, webv4/root/css/custom.css can hold locally-defined rules. If it exists, this file is loaded into the page *after* the stock style sheets, and can override previously declared rules or add new ones. You can use this file to alter the background colour of your site, include a background image, change the appearance of links, change the layout, etc.

You should *not* modify any of the stock .css files unless you have a good reason for doing so. Put your changes in webv4/root/css/custom.css instead.

Note that webv4/root/css/custom.css does not exist by default. If you want to use it, you must create it.

This web interface uses Bootstrap 3.3.5. It should be possible to use any compatible style sheet. Some work probably needs to be done to make these easier to swap out.

This web UI makes extensive use of XJS Files and, to a lesser extent, SSJS files.

XJS files are HTML documents with snippets of Server-Side JavaScript embedded within them, inside <?xjs ?> tags; apart from the <?xjs ?> blocks, they are the same as any HTML document.

SSJS files are Server-Side JavaScript modules. They must contain only valid javascript, which will be executed on the server. They can send strings to the client using the write() or writeln() methods. If they don't send anything, the client will receive an empty page.

If you're sending a lot of output to the client with only a few dynamic components, it's best to use XJS. If you're mostly performing scripted tasks and sending little static output to the client, SSJS may be more appropriate.

See the the webserver documentation for information about special values and methods available to scripts running on the web server. (Note: The web server generally handles creating and sending HTTP headers. Use the http_reply object sparingly and with caution.)

You may notice several .xjs.ssjs files in various locations. These are compiled XJS files, and are generated as needed when somebody requests an XJS file from the server. You can ignore these files, and you should not waste time editing them as they are frequently overwritten.

Modifying the main layout script, webv4/root/index.xjs is strongly discouraged. In general modifying any of the *included* files within the webv4/root/ directory structure is not recommended. You can of course add as many files and subdirectories within that structure as you want.

The header and footer “components” can be used to insert custom content into every (managed) page on your site. If present, these components are loaded by the main layout script every time a page is viewed. You can use these components to execute server-side javascript, client-side javascript (in a <script/> block), or insert some HTML into the page (such as an <img> tag for loading a banner graphic).

If you want to run some server-side JS within these components, you should be familiar with XJS Files.

You can add a custom “header” to your page by copying webv4/components/header.xjs to webv4/mods/components/header.xjs and altering the copy as desired. Output from this script will appear between the navigation bar (at the top of the page) and the rest of the page content.

You can add a custom footer to your page by copying webv4/components/footer.xjs to webv4/mods/components/footer.xjs and altering the copy as desired. Output from this script will appear inside the <footer/> block at the bottom of each page (where the copyright statement is by default).

webv4/components/modal.xjs contains the pop-up dialog which is raised when a notification (telegrams, etc.) arrives for a logged-in user. You can customize this file if you want to, by copying it to webv4/mods/components/modal.xjs and editing as needed, but you probably shouldn't. In particular, you should *not* alter the id attribute of any HTML element in this file.

webv4/components/navbar.xjs contains the navigation bar, being the menu strip that appears at the top of every page. If you wish to alter this file, copy it to webv4/mods/components/navbar.xjs and make your changes there.

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](http://wiki.synchro.net/server:web#xjs_files), 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 (or produce) complete HTML documents. They should not contain <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.)

If you wish to customize an existing sidebar module, copy it into webv4/mods/sidebar/ and make your changes there. Likewise if you wish to create your own custom sidebar modules, create them in webv4/mods/sidebar/.

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/ and webv4/mods/pages/ directories, in alphanumeric order. See the included files for examples and for a file-naming convention that enforces order of appearance.
• If a file in exists webv4/mods/pages/ with the same name (and relative path) as a file in webv4/pages/, the copy from webv4/mods/pages/ will be used. If you wish to alter one of the stock pages, copy it to webv4/mods/pages/ and make your changes to the copy. If you want to add your own custom pages, it is recommended that you create them in webv4/mods/pages/.
• 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](http://wiki.synchro.net/server:web#webctrlini_per-directory_configuration_file) file for access control.

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 webv4/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/`.

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 webv4/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.

• custom index