====== webv4 Customization ======

==== CSS ====

[[https://www.w3schools.com/css/default.asp|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 [[http://getbootstrap.com/|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 [[http://wiki.synchro.net/server:web#xjs_files|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 [[http://wiki.synchro.net/server:web#javascript_objects|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.

==== Components ====

=== Header and Footer ===
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 [[http://wiki.synchro.net/server:web#xjs_files|XJS Files]].

== Header ==
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.

== Fооter ==
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).

=== Modal ===
''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.

=== Navbar ===
''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 ===

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, [[http://wiki.synchro.net/server:web#xjs_files|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/''.

=== 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, [[http://wiki.synchro.net/server:web#xjs_files|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, [[http://wiki.synchro.net/server:web#xjs_files|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 [[http://wiki.synchro.net/server:web#webctrlini_per-directory_configuration_file|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, [[http://wiki.synchro.net/server:web#xjs_files|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:

<code html>
<!--HIDDEN:My Awesome Web Page-->
</code>

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

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

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

<code js>
//My Awesome Web Page
</code>

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

<code js>
//:Awesome Web Pages: This is one
</code>

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

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

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.

== 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 ''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:

<code>
web/pages/999-synchronet.link
</code>

with these contents:

<code>
http://synchro.net/,Synchronet BBS
</code>

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:

<code html>
<!--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>
</code>

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

===== See Also =====
  * [[:custom:|custom index]]

{{tag>}}