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 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.
XJS and SSJS
This web UI makes extensive use of XJS Files and, to a lesser extent, SSJS files.
<?xjs ?> tags; apart from the
<?xjs ?> blocks, they are the same as any HTML document.
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.
Header and Footer
<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/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/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
<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.
<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
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/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
- 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.
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
- Available options at the moment are
HIDDENpages will not appear in the menus or in the activity fields of the who's online list
NO_SIDEBARdirective 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:
with these contents:
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
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.