CapeSoft.Com
Clarion Accessories
NetTalk
Doc Index
WebServer Themes
CapeSoft Logo

CapeSoft NetTalk
WebServer Themes

Download Latest Version
Installed Version Latest Version

NetTalk WebServer Themes

Introduction

One of the most striking differences between developing programs for a desktop, and developing for the web is the way that screens (pages) are designed. Taking advantage of the benefits offered by CSS, in a web application, is a critical step forward in leveraging the benefits offered by the web platform.

This document is an introduction to the way CSS is used in NetTalk web applications (and by extension in Web Services applications, and also mobile applications.) It is designed to be read by both the web application developer, and also the web application UI designer. Several of the topics in this document will be helpful to the person creating the CSS for the appliction.

A Primer for Desktop Programmers

The architecture of a typical desktop application is very screen-design focused. Procedures in the application have a screen, and code is added to the procedure to handle the user interacting with the screen, and for the screen to show information to the user. Each screen has to be crafted individually, and manually changed to meet the design standards and consistency of your application. Getting screen design exactly right in a desktop program is time-consuming, and getting each detail correct takes effort. Things like button spacing, button sizes, field locations and so on can easily differ from screen to screen creating a visual inconsistency.

By contrast, one of the first things that NetTalk programmers notice is the complete lack of a screen designer at the procedure level. Desktop programmers are so wedded to the screen designer that the concept of designing without a screen-designer can be very foreign. The most common request received (by new NetTalk programmers) is for a screen designer. Interestingly though, once the true power of the CSS layer has been exploited, this request disappears.

In order to understand why the visual aspects of the UI, and the procedures have been disconnected, it helps to understand where current desktop visual designers fall short, and also the additional problems that web applications have to cater for. In no particular order; Changing the way a programmer works can be difficult. Decades of programming screen-first have lead to habits that are hard to break. However once broken, the benefits of CSS become apparent, and desktop programing seems slow and stifled by comparison. Some of these benefits are; It is a reasonable assumption that if you are currently a desktop programmer, this will be one of the biggest changes to the way you approach programming. However with great change comes great benefit - and this will also be one of the biggest benefits you see when programming for the web.

Programming Languages

A web application, running in a browser, makes use of three separate languages to accomplish its goals. In addition to this the server makes use of a fourth language, separate from these three. It helps to see how these languages fit together;

Server Side - Clarion

In a NetTalk application, the server-side language is Clarion. This is the code that runs on the server computer, and generates the code, or supplies the static files, that will run in the browser. The NetTalk server program mostly generates HTML code, with minor amounts of CSS and JavaScript code.The server also supplies the static CSS and JavaScript files to the browser.

While somewhat simplistic, it's fair to say that the server supplies the browser with the HTML, CSS and JavaScript that it needs to present the application to the user. The HTML is mostly dynamically generated on the fly - the CSS and JavaScript are in external static text files, and are served to the browser (where they are cached). So the server is mostly just sending HTML to the browser as the user navigates through the program.

Client Side - HTML / CSS / JavaScript

The browser supports three different languages, each with a different goal. Some web sites can be built using just 1, or possibly 2 of these languages, but NetTalk applications make use of all three.

HTML

This is the primary building block of the procedure (page). Most of the code generated by the NetTalk templates is HTML. HTML is great for "data" - putting information on the page, and identifying items on the page (This is a button, it's this kind of button, when someone clicks it run this function and so on.) HTML can be thought of as the content of the page.

JavaScript

[Hint: JavaScript is not JAVA]

JavaScript is the language that determines the page behavior. It can interact with the items on the page, but it also "runs" as you would expect code to run. It can hide or unhide elements, deal with clicks, update the server with new data, and so on.

CSS

CSS is the UI language of the browser. It determines what things look like. It is ultimately just a list of rules that determine what things should look like, how they should adapt to small and large screens, and where things go on the screen.

While all three languages serve a different purpose, it is true to say that there is some cross-over between them. Some "layout" features are managed primarily in HTML, not CSS. For example a browse consists of a number of fields. The primary order for these fields is set in HTML, not CSS.

That said, the true power lies in the use of HTML and CSS together. For example the page at https://www.clarionlive.com/ consists of two browses - but neither of them look like a typical spreadsheet-like browse.

A Primer for the CSS Designer

If your role is primarily to create, or modify a CSS theme for a NetTalk program, then this document is for you. It will explore in some depth the way the CSS is constructed, and how best to make changes in the CSS.

While the CSS designer is focused on the CSS, the programmer will be focused on the HTML. There may well be cases where adding some HTML to the procedure (or adding a CSS class to an element) simplifies the design. Doing these things is straight-forward for the developer, and can be added to their application on request.

It's worth noting that the Theme model is constantly evolving and being improved. If you encounter areas which you feel could be improved (or make your life easier) please don't hesitate to reach out to us at support at capesoft dot com.

Hint: While in some cases it is necessary to use #id selectors in the CSS, this should be avoided if possible. Using #id selectors can lead to UI bugs in the future if the ID in the program changes. Since the programmer is unlikely to be aware of this dependence on procedure and field names, it's better to use come other selector if possible.

Hint: The server has two basic modes of operation - Development and Deployment. Make sure the server is set into Development mode while you are working on the theme. Specifically if you find you are editing Theme.CSS then stop - that is a combined file, and you should be editing the source file(s) not that file.

Hint: You can change theme at runtime using the following parameter to the website URL;

?_theme_=whatever

This will change the theme for the duration of your session. This lets you test a new theme, without interfering with the current production theme. For example

https://www.capesoft.com/clarion?_theme_=sunny

HTML Layout

HTML Layout, via CSS, options have evolved considerably over the years. Early programs used Table layout, while later programs were able to use Div layouts, using the CSS Flexbox feature set. More recently CSS Grids have become available. Each approach has strengths and weaknesses, so it can be advantageous to use the correct approach in a specific situation.

From a programmer's point of view, layout is organized into three broad categories; Browses, Forms and Children. The default mode for each of these categories can be set globally, but they can also be overridden at the procedure level. So, for example, Browses might be set to default to Grid, forms can be set to default to Flexbox, and a specific browse procedure could be set to say Flexbox, or even Table.

From a designers point of view it is useful to liaise with the programmer to set the default approach you prefer, but also to let them know where an alternate approach may be useful.

Programmer Responsibilities

Development / Deployment mode

In the WebServer procedure, NetTalk Extension, Settings / Performance tab are items for improving site performance. All of these settings can be quick-set using two buttons at the top of the tab. The one is labelled Deployment, and the other is Development.

While working on the CSS it is best to put the server into Development mode. This means that the individual source files are sent to the browser, and any changes made by the designer (and saved to the server) take immediate effect (by just pressing Ctrl-F5 in the browser.)

When development is complete, the server can be switch back into Deployment mode. This will optimize the performance of the server. After clicking the Deployment option run the GZIPALL.BAT file in the application folder. This will combine all the CSS into a single Theme.CSS file. Copy this file to the server web\themes\whatever folder. (if it's not already there). Other support files (like icon SVG files) should also be deployed to the server.

Custom CSS, Custom Theme CSS

Editing the shipping source files will lead to problems, as these files will be overwritten by NetTalk updates. For this reason it is possible for the programmer to add custom css files to the \web\styles folder, as well as custom theme files to the \web\themes\whatever folder. Custom designs can be added to these files in the knowledge that they will be safe from future NetTalk updates.

To tell your program to use these new file(s) go to the WebServer procedure, NetTalk Extension, Settings / Styles / Files tab.

If you wish to edit the files in the \web\themes\whatever folder then it is recommended that you clone this folder to a new \web\themes\somenewname folder. You may wish to prefix this folder name so as not to run the risk of the theme being supplanted by a future-shipping nettalk theme with the same name.

For example to make a new theme, similar to the PalmTree theme, calling it xSailing copy the \web\themes\palmtree folder to \web\themes\xsailing folder. For new themes, you are free to edit any of the files in the Themes folder and they will not be overwritten by future NetTalk releases. You do not need to "register" new themes in the program - just including them in the \web\themes folder is sufficient.

Setting the Default Theme

The default theme (the theme which will be applied to the site) is set in the WebServer procedure, NetTalk Extension, Defaults / General tab. the theme name should be in quotes (if a constant value) or can be set to an expression (variable) if desired.

Assigning Classes to Elements

Assigning Icons

In any of the Icon template prompts you can put the name of an icon. You can supplement this with the space-separated list of additional css classes. the following classes, exist and can make useful additions;
CSS Class Use Case
ui-icons-light Use an icon from the "light" set
ui-icons-dark Use an icon from the "dark" set
ui-icons-16 Set the size of the icon to 16 pixels
ui-icons-20 Set the size of the icon to 20 pixels
ui-icons-24 Set the size of the icon to 24 pixels
ui-icons-32 Set the size of the icon to 32 pixels
ui-icons-48 Set the size of the icon to 48 pixels
ui-icons-64 Set the size of the icon to 64 pixels

CSS and Theme File Locations

There are two primary locations for CSS files in the \web folder. The first is \web\styles and contains CSS files that are common to all themes.
Theme specific files are located in the \web\themes\whatever folder.

When the program is put into Deployment mode, all the CSS files from the \web\styles and \web\themes\whatever folders are combine to make a single theme.css file. This is located in the \web\themes\whatever folder. Using this combined (and pre-compressed) file improves performance for the client. It should also be noted that this file is cached by the browser, so it is only sent to the browser once.

Themer (86) Example Program

NetTalk ships with a number of web application examples - one of which is called Themer (86). This example is useful to CSS designers because it allows a number of common theming attributes (like colors, corners, gradients etc) to be set directly in the browser.

The example also contains Expo pages, which contain various different controls. This makes it a good example application to test a new theme to see if it is complete and consistent.

If making a new theme, then this is a good starting point as this application allows for rapid changes to the most common theme settings. This program is safe to run with manually-edited nt-theme.css files, as it only affects the settings it is designed to change. All other settings are preserved.

To see a webinar of this example program in action see https://www.youtube.com/watch?v=Stve8cfX2kg from the 1:07:00 mark to around the 1:35:00. This webinar also acts as a good introduction to some of the CSS techniques used in the theme.

Understanding NetTalk Themes

This section will explore the low-level mechanics of the theme files. It is faster to edit these properties using the Themer program, but of course there are many more settings in the CSS files than are exposed in the Themer program, and so manual editing is often desired. You can safely use theme on these files after manually editing the files.

CSS files in \themes\whatever

Each theme is stored in it's own folder, located under the themes folder. The folder name is the theme name.

Each theme consists of (at least) 3 source files, as detailed below.

When working on the theme, make sure the server is in Development mode.

When the program is in Deployment mode then these three files, and all the styles used in the \styles folder, are combined into a single file (theme.css) which is then pre-compressed using GZIP to make theme.css.gz. If the browser supports file compression (as most do) then only this single theme.css.gz file is set to the browser.

nt-theme.css

Note: If you edit this file, make sure you make a new theme, don't edit a shipping theme as it will be overwritten with a later NetTalk build.

The primary theme file in each theme is nt-theme.css. This file contains (only) CSS Custom Properties (aka CSS Variables) which are then used by other CSS files. The vast majority of the custom theme changes will take place in this file.

The file is broken down into a number of sections;
  • Icons - determines the size, and icon files to use
  • Typography - determines the font, fontsize, and various other font related settings
  • Curvature - determines the corner radius for on-screen elements, as well as gradients
  • Colors - determines the colors used by the theme
  • Elements - applies the various settings above to the various screen element types

jquery-ui-theme.css

Note: If you edit this file, make sure you make a new theme, don't edit a shipping theme as it will be overwritten with a later NetTalk build.

This file contains the CSS related to the visual options for all the jQuery widgets.  Most of the classes in this file have the ui- prefix.

This file originated as part of the jQuery UI themes, but it has since been heavily modified to work with nt-theme.css. It is no longer compatible with themeroller, but can be manually edited. Most of the settings in this file use variables set in nt-theme.css

nettalk-ui.css

Note: If you edit this file, make sure you make a new theme, don't edit a shipping theme as it will be overwritten with a later NetTalk build.

This file contains the CSS related to the visual options for all the NetTalk widgets. Most of the classes in this file have the nt- prefix

This file can be manually edited. Many of the settings in this file use variables set in nt-theme.css

SVG Icons

NetTalk 12 themes make use of SVG icons, which display well at all screen resolutions, and which can support multiple colors per icon. SVG (Simple Vector Graphic) files are text files, and can be viewed in a text editor. Some simple changes to the header part of the Icons.SVG file can dramatically alter the icon set quickly, and easily.

Note: In this section Icons.SVG refers to the Icons file(s) used by the theme, regardless of the name of the file.

Icons are located in the \web\icons folder. A number of default files are shipped in this folder in both light and dark variants. A sample test file (using the Palmtree theme) is also included as \icons\icons.htm. You can edit this file, or clone it, to test other themes.

The colors used in the Icons.SVG file needs to be set at the top of that file. [1]

The primary change you will make to the Icons.SVG file is the color of the icons.

Note 1 : Aside:  Because Icons in jQuery are implemented as background images, and because the :root custom properties are out of scope for SVG files used in this way, the colors from the nt-theme.css file cannot be used directly in the Icons.SVG file.

Size

Because the icons are defined as vector graphics, they scale very well to many different sizes. This can be done using the css transform property.
For example;

transform: scale(0.5)

Since the icons are drawn on an arbitrarily chosen 32x32 pixel space, a scale of 0.5 leads to a icon of 16 x 16 pixels.

NetTalk has seven categories of icons - and of course you can add more if you need them. These are declared in the nt-theme-css file. In this file you can specify the scale used for each category. For example;

--icons:url("/icons/nt-icons-light.svg");
--icons-scale:0.5;

--icons-tab:var(--icons);
--icons-tab-scale:0.8;


The built-in use of each category is set in jquery-ui.theme.css.
They are generally applied as follows;

Category Use
--icons Used by the jQuery UI JavaScript code. This is basically all the dynamic icons like the open/close icons on menus, accordions and taskpanels.
--icons-entry Used on form controls - like check boxes, drop lists and so on. Typically these icons should contrast well with the --entry-background color.
--icons-button Used on all buttons
--icons-menu Used on menu items, but not for menu navigation icons. (see --icons above)
--icons-tab Used on Tab headers
--icons-highlight Used when a widget (button etc) is highlighted.
--icons-error Used for Error messages etc.

Color

The top of the icons file contains a number of colors that are declared here, and used in the icon drawings. You may wish to customize these colors to match your theme. You can create your own icon files, and just adjust the URL properties in nt-theme.css

Here is a sample set of colors as taken from the nt-icons-light.SVG file.

    <style>
        .colors{
            --icon-color:#FFFFFF;
            --icon-shade:#999999;
            --icon-contrast:#333333;
            --icon-warning:#bbac1d;
            --icon-error:#9d412a;
            --transparent:transparent;
        }
    </style>


Colored Button Icons

The ShoeStrap2 theme is an example of a theme with colored icons - in the sense that the buttons in the them are colored based on their function. So an Insert button has a green icon, a Delete button has a red icon and so on.

The specific changes to the theme to support this are annotated below;
  1. The custom icons SVG file (nt-icons-buttons.svg) is created by copying from the default icons (\icons\nt-icons-dark.svg) to the \themes\shoestrap2 folder.
  2. The nt-icons-buttons.svg file is edited to set the icon colors; --green, --blue and --red added to the <style> section
  3. The individual icons are edited to use these colors (see trash as an example)
  4. In \themes\shoestrap2\nt-theme.css the --icons-button property is set to

    --icons-button:url("nt-icons-buttons.svg");

    This is a custom icon file, unique to this theme (created in step 1 above), and located in the specific theme folder. (Note the url is relative, not pointing to the icons folder as the other settings do.)

Available Icons

The icon names follow the same pattern as for jQuery UI. However a number of new icons have been added to the set to make it a bit more useful. For a list of the available icons check out the /icons/icons.htm document on your server.

Making Your Own Icons

The icon system is easily extended to incorporate your own icons. There are a couple of approaches you can take;

a) Clone the existing icons.svg file to a new file, and add in additional icons to the file. There are a few empty spaces you can use for this. Then add entries to either jquery-ui.theme.css (or better yet, your custom.css) to define the new icon names and locations. However this approach will mean that any improvements to the shipping icons, or new shipping icons, will be difficult to merge into your application.

b) Create a new icons.svg file (say myicons.svg), and new css file (say myicons.css), and use this in conjunction with the shipping icons. The Themer (86) example includes an example of this approach.  It includes /icons/customicons.svg, and /styles/customicons.css. This example also shows the use of multi-colored icons - in this case the icons attached to the menus.
TroubleShooting
You can check the validity of the SVG file by just opening it in the browser. For example http://127.0.0.1:88/icons/customicons.svg

Font Based Icons

Note that the use of the Webdings or Wingdings fonts are not recommended in web applications since they are not universal to all platforms. If a font is to be used to draw icons, then use a Unicode font, and make sure the application is set to use the utf-8 charset.

There are a number of free and commercial icon-based fonts available on the web (see links below). While each may have specific installation instructions, they will all follow a similar pattern, and one (Font Awesome) is documented below.

Colored Button Icons

  1. If necessary, add the colors you want to use to the nt-theme.css file. For example;

    --icons-red:#c43c35;   
    --icons-green:#57a957;
    --icons-blue:#0064cd;

  2. Add a section to the nettalk-ui.css file, based on the button that needs coloring. For example, for the insert button;

    .nt-insert-button>.nt-font-icon-button{
        color:var(--icons-green);
    }


    Repeat for all the buttons that need coloring.

Font Awesome Icons

One of the most popular icons to use on webapps are a set of icons created by Font Awesome. These are available in both a free, and commercial version. The commercial version is notable for having a wider selection of icons. The icons are extremely well drawn, and are provided as a Font file rather than as a sprite file.

This section assumes some familiarity with the Font Awesome methodology in naming, and identifying icons. Specifically the icon name consists of a style (fas, far, fal, fab) followed by an icon name with the fa- prefix. So 'fas fa-umbrella' .

NetTalk 12 allows FontAwesome icons to be used in a number of places where icons are supported. Support includes icons on buttons, icons on menu and menu items, and tab headings. In some places (notably where icons are live-changed in JavaScript such as on a checkbox) only SVG based icons can be used.
Installing
After downloading the Font Awesome files, you will need to
  1. Add their webfonts folder to your web folder (as \web\webfonts) [2]
  2. Copy their \css\all.css file to the \styles folder. Rename this file to something more descriptive (like FontAwesomeAll.Css).
  3. Go to the Application, WebServer procedure, NetTalk Extension, Settings, Styles, Files and add the css file there. (Use the same name as used in step 2, so in this example 'FontAwesomeAll.Css')
[Note 2] You can place the fonts in a different folder - like the \fonts folder, if you prefer. If you do this wold will need to change all the URL references in FontAwesomeAll.Css
Using
the places where Font Awesome fonts are supported you can simply use the Font Awesome style name, and font name. For example to use the Font Awesome trash icon (which is part of the solid style - hence fas - you would set the icon to be 'fas fa-trash'.

Font Awesome icons can be used in places where the icons are "non functional" - including buttons, menu items, and tab headings. They cannot be used on functional items (checkboxes, accordions and so on.)

Hint: It is a common misconception that Font Awesome requires an <i> block. This is not the case, and in NetTalk a <span> is used as this is semantically more correct.

Useful Links

In no particular order;
Link
Description
https://fontawesome.com Home of Font Awesome icons
https://css-tricks.com/snippets/css/a-guide-to-flexbox/ Visual CSS reference to Flexbox properties
https://css-tricks.com/snippets/css/complete-guide-grid/ Visual CSS reference to Grid properties
http://xahlee.info/js/svg_circle_arc.html Interactive Arc drawing in SVG
https://1stwebdesigner.com/best-free-icon-fonts-web-design/
List of good, free, Icon font sets




Backward Compatibility

Considerable effort has gone into making the new theme system backward compatible with themes from NetTalk 11 and earlier. Nevertheless some small modifications to the old themes are likely desirable to keep using them. These changes have been made to those shipping themes that have not yet been updated to the new framework. If you have your own custom theme, then these changes may well be desirable in your own theme.

File Class Suggested Change Comments
nettalk-ui.css .nt-small-button
.nt-small-button span
Move these 2 lines down to below the nt-button declaration.
(only 1 line lower)
The nt-button class has been added to the HTML to small buttons, so this class is now in play, and needs to be overridden by the n-small-button class.

.nt-button remove font-size property.
.nt-button{min-width: 7em;}
No longer desirable - causes buttons to appear with a smaller font.

.nt-small-button remove width and height properties, set min-width to Auto
.nt-small-button{margin: 0!important; margin-right:0.5em!important;min-width: auto;}





Random CSS Tips

This section contains some tips to do some common adjustments in custom.css files.

#1. Remove Close button from top right of Dialog Headers;

.ui-dialog .ui-dialog-titlebar-close {display: none;}

#2. Left-Justify Dialog titles

.ui-dialog .ui-dialog-title {justify-content:start}

#3. Size main panels

@media screen and (min-width: 1025px){
    .nt-leftpanel-l {
        width: 12em;
    }
}


If you have both a left and right panel then use

@media screen and (min-width: 1025px){
    .nt-leftpanel-lr {
        width: 12em;
    }
}


If you have a right-side-menu set the width to accommodate your longest menu item, without getting too small.

@media screen and (min-width: 1025px){
    .nt-rightpanel-r {
        width: 12em;
    }
}


If you have both a left and right panel then use

@media screen and (min-width: 1025px){
    .nt-rightpanel-lr {
        width: 12em;
    }
}

Adjust the size of the middle panel to match

@media screen and (min-width: 1025px){
    .nt-contentpanel-lr {
        min-width: calc(100% - 25em);
    }   
}



#5. To make the header text in browses not wrap

.nt-browse-header-all{
    flex-wrap:nowrap;
}


#6 To make the content part of a browse scrollable, with fixed hearers and footers (Flex mode only)
Add .nt-browse-flex-body-scroll to the Browse Body Div. Adjust height as desired;

.nt-browse-flex-body-scroll{
    height: 50vh;
}


#7 Change the "line height" of browses

A browse row (ie a row in the data table) can consist of one or more lines in an HTML table, flex, or grid.
The following classes are applied to cells in the browse;
Class Use case
nt-browse-first-line Applied to the first HTML row of a multi-line browse.
nt-browse-middle-line Applied to the middle HTML row of a multi-line browse.
nt-browse-last-line Applied to the last HTML row of a multi-line browse.
nt-browse-only-line Appears in the HTML row if the browse is set as one line per row.

The primary theme settings (in nt-theme.css) which are used are;
Setting Use case Example value
--browse-line-padding-top The padding between one browse row and the next 0.3em;
--browse-line-padding-bottom The padding between one browse row and the next 0.3em;
--browse-line-border-top The border line between this line and the one above it 1px solid var(--light-grey);
--browse-line-border-bottom The border line between this line and the one below it 1px solid var(--light-grey);

#8 change the size of small buttons;

.nt-small-button {
    height:1.5em;
    width:1.6em;
}


#9 Change the size of Icons in in-row small buttons

in nt-theme.css, set the --icons-button-scale. This is as a fraction of 32pixels. For example, for 16 pixel icons use.

--icons-button-scale: 0.50;

[End of this document]
Return to NetTalk Documentation Index