1. Installation and Configuration
This section describes how to install WebTerminal to your Caché system and
perform a basic (optional) configuration to make it ready for any use case.
1.1. Installing Web Terminal for InterSystems
The latest WebTerminal versions are supported for any Caché (Ensemble,
HealthShare, etc) platform version higher than 2014.1. The older versions
of WebTerminal (versions 1-2) will work on 2013.1.
The installation begins from the simple import of classes to Caché. Before doing
that, you need to download the latest available version
on this website. To do this, go to the downloads page
and select the most up-to-date (the most top one) version from the list.
The download will save the XML file to your computer, which you will need to
import then. See the section below to import the classes to your Caché
installation.
1.1.1. Importing Classes
Once you have the XML file of the latest WebTerminal version downloaded from the
downloads page, you need to import it to your Caché
system. To do this, you need to have system privileges. On a clean Caché
installation the user _SYSTEM can perform this operation. The default
password of this user is SYS. Once you notice the window prompting you
to enter a username and a password, try the default ones (_SYSTEM /
SYS).
There are three common ways of how to install WebTerminal:
-
Import using Caché Studio (Windows OS only)
If you have access to Caché Studio, then this is the simplest method.
Open up the Studio window, choose the namespace you want to import
WebTerminal to (for example, select USER namespace), and just
drag & drop the XML file onto the Studio window. Caché Studio will
prompt you to compile the classes, check "yes" and then press OK.
At the bottom of the studio (by default) you will see the message
saying that compilation is successful. However, there may appear some
errors. Check the Resolving Import Errors
(1.1.2) section for more information on this.
-
Import Using Management Portal (any OS)
If you have access to the Management Portal, then you can go to
"System Explorer" -> "Classes" page and click on the "Import" button
there. Select the "File" option in the dialog, and then choose the
full path to the XML file you want to import (WebTerminal-?.?.?.xml).
Check "Compile imported items" checkbox and then press OK. Check the
output of the compilation process and refer to
Resolving Import Errors (1.1.2) section
for more information on errors if there are any.
-
Import Using Terminal (any OS)
If you have access to Caché Terminal, you can import WebTerminal
by using this command:
do $system.OBJ.Load("/path/to/xml/file/WebTerminal-?.?.?.xml","ck")
Replace the
/path/to/xml/file/WebTerminal-?.?.?.xml to
the path to WebTerminal's XML file in your filesystem. Then, check the
output of the compilation process and refer to
Resolving Import Errors (1.1.2) section
for more information on errors if there are any.
1.1.2. Resolving Import Errors
During the installation, there may happen some errors. You will receive the
alert message with the error description, as well as the Studio (terminal)
output describing the error. There are the most common errors and their
descriptions listed:
-
<PROTECT> error.
If you have this error, double check if the user within you are
currently logged in has sufficient privileges to access the %SYS
namespace. During the installation, WebTerminal tries to change the
namespace to %SYS and then tries to set up the
/terminal web application.
-
ERROR #921: Operation requires %Admin_Secure:USE privilege
This means that the current user (the one you are trying to import
WebTerminal under) is missing %Admin_Secure
resource access. The access to this resource is provided with the
%All (superuser) by default, so make sure
you are logged in as a superuser (_SYSTEM user by default).
1.1.3. Launching WebTerminal
WebTerminal is a web application. To open WebTerminal, use the next URL
address: http://[host]:[port]/terminal/
There are a few things you need to take into account:
- The slash symbol (/) at the end of the URL is required.
-
[host] and [port]
URL parts must be replaced with the hostname and port number of the server
you installed WebTerminal to. You can easily check this data by opening
the Management Portal — the URL beginning will be the same for WebTerminal
as well as for Management Portal. Here is the default URL of Caché
WebTerminal installed on the clean system:
http://localhost:57772/terminal/
-
If the web application still showing "404 not found" error, double check
if the installation process resulted with no errors.
1.1.4. Installing Old WebTerminal Versions (1-2)
It is always recommended to install the newest versions. However, if you exited
so much about WebTerminal project and want to try it, for example, on Caché
2013.1, the only option you have is to install version 2. Do this by performing
the following steps:
- Go to WebTerminal Downloads and download the version 2.0.0-beta.8, which is
the XML file. This page also has some additional instructions.
- Using Studio or whatever you like (see above), import this XML file into the
%SYS namespace and compile all imported classes and CSP pages. If you
have the "access error" while importing classes, then you need to
temporarily enable write access to CACHELIB database, see here how.
- Open {host}:{port}/csp/sys/webterminal/index.CSP page in the browser.
Note that the newer versions have several fixes and enhancements introduced, so
please do not submit any issues affecting versions 1-2. These versions are not
supported "officially".
1.2. Configuring WebTerminal Web Application
Once you install WebTerminal, there are two Caché web applications appear.
The first one, /terminal, is a user interface
of the terminal application. The second one,
/terminalsocket, is the "empty" web application
for incoming WebSocket connections. The
/terminalsocket web application has to be opened
to any user and the password protection must be disabled on it, as Caché CSP
gateway will block any WebSocket connections. The token accepted by opened
WebSocket connection is generated by the /terminal
application, and this is exactly the web application you need to apply
restrictions to.
1.2.1. Password Protection
Password protection is enabled by default for the
/terminal web application. This means that
any Caché user would be able to log in with their username and a password
to WebTerminal, if they have the access to the database WebTerminal were
installed to.
1.2.2. Setting Web Application Up
The /terminal web application is set up
automatically the first time you install WebTerminal. You can find it by going
to the Management Portal ->
System Administration ->
Security ->
Applications ->
Web Applications and then selecting
/terminal web application from the list.
You should not change the name of this application, as this will prevent
WebTerminal from updating normally. Also, do not change the dispatch class this
application refers to.
However, the things you can change are listed on the web application definition
edit page: description, namespace, security and session settings and roles
added to the web application user. You can find more information about setting
up web applications in the InterSystems documentation.
1.2.3. Restricting Access To A Particular Users Group
You may want to restrict the access to WebTerminal web application only to
specific users. To do this, open up the WebTerminal web application
configuration by going to the Management Portal ->
System Administration ->
Security ->
Applications ->
Web Applications page and then selecting
/terminal web application from the list.
Now, select the %WebTerminal as a required resource
(Resource Required drop-down menu in Security Settings).
If you don't have this resource in the list, check if you have the latest
WebTerminal version installed. Or, alternatively, you can create your own
resource and role to access this resource, and then assign created resource to
the web application (see the documentation).
Once you choose %WebTerminal resource, click
Save on the top of the page. Then go to the
System Administration ->
Security ->
Users page and select the user you need to
allow the access to WebTerminal. Then, go to the
Roles tab and assign the
WebTerminal role by selecting the role from the
left list, pressing the right arrow button and then pressing
Assign button.
Note that superuser (_SYSTEM by default) does not require
WebTerminal role to be assigned, as superuser has
%All role, which grants the full access to all
resources in the system.
2. Usage Basics
This section describes the basic usage of WebTerminal and all of its features.
2.1. Using Autocomplete
When you type commands you may notice the autocompletion variants appearing.
To complete the input with proposed suggestion, use
TAB key.
If there is a list of autocomplete variants available, use left and right
CTRL key to switch to the next or the previous
variant in the list respectively.
2.2. Using WebTerminal's Special Commands
All special commands in WebTerminal start from /
symbol. Enter this symbol to get the list of available commands as a suggestion.
2.2.1. Getting Help
To get the help information printed, enter /help
special command. This command, as well as any other special command can be
entered in both default and SQL terminal modes.
2.2.2. Clearing All The History
WebTerminal does not have the history limit like standard terminal. This is
useful to see all the output and search through it, but sometimes, when you
execute a lot of commands in one session terminal may slow down because of this.
In this case, you can trigger /clear special
command to clear all the history.
2.2.3. Configuring WebTerminal
To customize the WebTerminal's behavior, use /config
command. Refer to 2.3 section to find out more about
local and global configuration.
2.2.4. Remembering Particular Commands
If you execute some command frequently, you can define a shortcut for it. To do
this, enter
/favorite {name} write "I am always right!"
where {name} can be any symbolic name of the
command you want to save. Then you can restore this command by entering
/favorite {name}
To delete previously saved commands, use
/favorite delete {name}
To delete all saved commands, use
/favorite delete
2.2.5. Showing Project Information
To display information about the project, use /info
command.
2.2.6. Logging Out From WebTerminal
WebTerminal, as any other web application remembers the username and password
you enter. You will still be logged in after the page refresh or even browser
restart. To log out from the current user use
/logout command.
2.2.7. Toggling SQL Mode
WebTerminal features the convenient SQL mode build in. To enter the SQL mode,
use /sql command. To exit this mode, enter
/sql command again.
In SQL mode you can execute any SQL queries and get the syntax highlight and
suggestions for SQL. Also, when getting SQL results you will see simple
SQL table, which is easy to read comparing to the simple terminal output.
2.2.8. Tracing Globals And Files
You can start tracking changes in globals or files. For globals, tracking is
available only for multi-dimensional ones. WebTerminal will notify you about
the changes in global dimension. To start tracking, use the following commands:
/trace /path/to/file (to track files)
/trace ^globalName (to track globals)
You will start receiving notifications as a printed output to the current
session. Use
/trace stop
To stop tracking all files and globals.
2.2.9. Updating WebTerminal Manually
When you disable the auto-update, or if the initial output is omitted, you can
still check for the updates manually by entering
/update command.
2.3. Configuring WebTerminal
WebTerminal configuration is divided into to client and server configuration.
The client configuration persists in the browser's local storage (so it resets
when browser changes), and the server configuration is global for the whole
Caché instance. All the settings can be changed with
/config special command.
2.3.1. Changing Default Namespace
Affects client only. To change the default namespace use the next command:
/config defaultNamespace = "USER"
The user logged will enter this namespace at start if they have access to it.
2.3.2. Hiding Initial Messages
Affects client only. If you want to stop showing the initial messages upon the
start, enter
/config initMessage = false
command.
2.3.3. Changing The Language
Affects client only. The closest interface language you need is detected
automatically during the WebTerminal start. But you can change it by entering
/config language = ru
Affects client only. You can try entering any language and WebTerminal will show
the list of available languages if the one you entered cannot be set up.
2.3.4. Increasing Stored History Size
Affects client only. WebTerminal stores 200 last commands in history. To change
this limit, enter
/config maxHistorySize = 777
2.3.5. Changing The Rows Limit In SQL Mode
Affects client only. If you need to change the maximum number of rows displayed
in SQL mode, enter
/config sqlMaxResults = 999
2.3.6. Toggling Autocomplete
Affects client only. If for some reason you don't want autocomplete to help you,
turn it off by using
/config suggestions = false
2.3.7. Toggling Syntax Highlight
Affects client only. If for some reason you don't want the input to be
highlighted, turn it off by using
/config syntaxHighlight = false
2.3.8. Toggling Updates Check
Affects client only. There may be some cases when you won't need to notify
client about available WebTerminal updates. The most common case is embedding
WebTerminal to other applications for non-privileged users. If you are using
clean URL parameter, than you don't need to turn
this option off. In case of you don't want to update terminal regularly, it's
sad, but you can turn the updates off by using
/config updateCheck = false
2.3.9. Changing The Server Name
Affects server. Changes the name of the server displayed in initial message and
in the browser's tab. This becomes extremely useful if you have WebTerminal
installed on multiple servers and you open many browser tabs at once. Use this
to change the server name:
/config serverName = "Pentagon"
2.4. Interrupting Commands Execution
Sometimes the line of code you execute in WebTerminal may freeze for a while or
even never get completed. In this case you may want to interrupt the command
execution. To do this, press Ctrl + C keys
combination. If no text were selected, the interrupt signal will be sent to the
server and you will get <EXTERNAL INTERRUPT> error.
3. Output Options
WebTerminal supports
VT100
escape sequences and some others to format and control the output. This section
describes the supported escape sequences and their usage.
The <ESC> designation in this section stands for
the non-printable character with ASCII code 27 (equivalent of ObjectScript
$Char(27) result), which is commonly used escape
character. This character begins the control sequence, and it is usually
followed by other characters which apply the different conditions and control
the terminal output.
For example, <ESC>[31m stands for printing
these characters using the next ObjectScript code:
write $Char(27), "[31m".
3.1. Changing Output Color And Font
There is an option to change the output font weight and color. The table below
demonstrates the basic escape sequences that can be used in output.
| Sequence |
Description |
<ESC>[0m |
Reset all output options mentioned in 3.1
to default
|
<ESC>[1m |
Switch font to bold
|
<ESC>[2m |
Make font dim
|
<ESC>[3m |
Make font italic
|
<ESC>[4m |
Underline the text
|
<ESC>[5m |
Print blinking text
|
<ESC>[7m |
Print Invert the printed text colors
|
<ESC>[8m |
Print invisible text (but still selectable)
|
For example, to print "Impossible is nothing!"
on the screen, you can type the following write statement in terminal
(Caché ObjectScript):
write "Impossible is ", $Char(27), "[4mnothing", $Char(27), "[0m!"
Alternatively, if you are using JavaScript API, then the next will do the same:
term.print("Impossible is \x1b[4mnothing\x1b[0m!");
As well as font, the color of the text and its background can be changed by
using these sequences:
| Sequence |
Description |
<ESC>[3Xm |
Changes the font color. The X here is a
number which can be one of the following:
0 for Black,
1 for Red,
2 for Green,
3 for Yellow,
4 for Blue,
5 for Magenta,
6 for Cyan and
7 for White.
|
<ESC>[4Xm |
Changes the background color. The same digits described for
<ESC>[3Xm
sequence can be used here instead of X.
|
<ESC>[38;5;Ym |
Changes the font color according to 8-bit color table. The
Y here can take integers from 0 to 255,
which corresponds to pre-defined 8-bit color table.
|
3.2. Formatting Output
To format output and set up tab stops the next escape sequences are used:
| Sequence |
Description |
<ESC>[XG |
Moves cursor to column X. In Caché
ObjectScript you can just use a "?" symbol to shorten this escape
sequence, for example: w ?25, "duck"
|
<ESC>H |
Set the tab stop at the current position. By default tab stops are
set at each 8th column.
|
<ESC>[g |
Clears the tab stop at the current position if present.
|
<ESC>[3g |
Clears all tab stops.
|
3.3. Cursor control
The next escape sequences are used to control the cursor:
| Sequence |
Description |
<ESC>[Y;XH |
Moves cursor to (X, Y)
position (the upper left corner is (1, 1)).
Both X and Y
can be omitted, e.g. <ESC>[H will
set the cursor to position (1, 1).
|
<ESC>[XA |
Moves the cursor up by X rows; the default count is 1.
|
<ESC>[XB |
Moves the cursor down by X rows; the default count is 1.
|
<ESC>[XC |
Moves the cursor forward by X rows; the default count is 1.
|
<ESC>[XD |
Moves the cursor backward by X rows; the default count is 1.
|
<ESC>[s |
Saves the current cursor position.
|
<ESC>[u |
Loads the last saved cursor position.
|
<ESC>7 |
Save the current cursor positions and its attributes (font and color).
|
<ESC>8 |
Restore the last saved cursor positions and its attributes (font and color).
|
3.4. Printing Hyperlinks (WebTerminal Only)
WebTerminal provides a special escape sequence to print hyperlinks. Note that
this will work only for WebTerminal.
| Sequence |
Description |
<ESC>!URL=<link> (<text>) |
Prints the <text> highlighted as
a link. Pressing on the printed <text>
will open a new tab with the URL address <link>.
Make sure that the <link> does
not contain spaces (they must be encoded with %20 character combination)
and other non-URL symbols. Note that there is a space between
<link> and ( symbol.
|
Example:
USER > write "Visit ", $Char(27), "!URL=https://github.com (GitHub)!"
Visit GitHub!
3.5. Printing HTML (WebTerminal Only)
WebTerminal can print HTML! This opens almost infinite possibilities of
extending WebTerminal applications with modern web technologies. See the table
below for the HTML printing options.
| Sequence |
Description |
<ESC>(<classname>)m |
Prints the text wrapped into HTML <span class="<classname>">
element. To clear the assigned class use <ESC>[0m
escape sequence as well. Check the available WebTerminal classes here.
|
<ESC>!<HTML>{html}</HTML> |
Converts the current line in output to the HTML line. This line will
include any {html} given to the
sequence. Once the given {html} will be
rendered on the screen, the height of the rendered part will be
calculated instantly and assigned to the containing line (the height of
the line may be slightly higher than the content height). This height
will not be changed when content height changes.
NOTE that this sequence will block
output until the closing </HTML> comes.
|
Example:
USER > write $Char(27), "!<HTML><h1>I am a very big title!</h1></HTML>end."
I am a very big title!
end.
3.6. Other Supported Output Options
There are more escape sequences not mentioned above but is supported by VT100
terminal standard. You can check the other escape sequences
here.
If you find the escape sequence missing in WebTerminal, you can request for this
sequence to be impemented. Go to describe
an issue, or, you can even implement it by yourself starting from
this
file.
4. Embedding WebTerminal To Other Applications
WebTerminal can be easily used inside any other web application. See the
description below to find out more about embedding.
4.1. Embedding With IFrame
To embed WebTerminal to any other web application, you can use <iframe>
HTML tag. Example:
<iframe id="terminal" src="http://127.0.0.1:57772/terminal/?ns=SAMPLES&clean=1"></iframe>
The id="terminal" attribute will be used in examples
below to refer the iFrame element on the page. You are free to use any other
JavaScript references in your application.
4.1.1. IFrame Attributes
-
The
src attribute specifies the URL of the WebTerminal web application.
-
Any styles can be applied to iFrame element with HTML
style or class
attributes.
4.1.2. URL Parameters
URL parameters are specified after the ? symbol in
the URL. They are used to configure WebTerminal behavior when embedding.
WebTerminal supports the following URL parameters:
4.2. JavaScript API
WebTerminal has its own JavaScript API. Please refer to the section below.
4.2.1. Handling Terminal Initialization
To use WebTerminal's API, you need to get WebTerminal instance first. Use
iFrame's onTerminalInit function for this:
document.querySelector("#terminal").contentWindow.onTerminalInit(function (term) {
// now you can access the term object here
});
The callback is triggered only after WebTerminal establish an authorized
connection. But we need to handle the iFrame load event before you can start
using the onTerminalInit function. To do this, add
the load listener to iFrame element:
var iFrame = document.querySelector("#terminal");
// This function will be shown in the examples below without iFrame binding code.
function myInitHandler (term) {
// now you can access the term object here
}
// At first, handle iFrame load event. Note that the load handler won't work
// if this code is executed at the moment when iFrame is already initialized.
iFrame.addEventListener("load", function () {
iFrame.contentWindow.onTerminalInit(myInitHandler);
});
4.2.2. Executing Commands
To execute a line of Caché ObjectScript code in runtime, use
term.execute(command, [options], [callback])
function. It accepts three arguments:
-
String
command, specifying the command to be
executed.
-
Optional object
options, which may have two
boolean properties echo (default is
false) and
prompt (default is
false). When echo
is true, the command being executed will be
output to the screen like it was entered by user. When
prompt is true, the
user will be prompted to enter a command after execution
(NAMESPACE > will be printed as well).
-
If
callback is passed, the output buffer will
come as a first argument of the callback
function in a form of an array of strings.
Example of executing the line of ObjectScript code at the startup:
function myInitHandler (term) {
term.execute("set hiddenVariable = 7", {
echo: true,
prompt: false // the default is false, this is shown just for the demo
});
}
4.2.3. Handling User Input
To handle the commands user enters, use the
term.onUserInput(cb) function.
callback(text, mode) is fired right after user
presses enter. Argument text is a
String of user input, and
mode is a Number, which
can be compared with one of the terminal mode constants, such as
MODE_PROMPT. The list of these constants is shown
below:
-
term.MODE_PROMPT handles regular input
(ObjectScript command).
-
term.MODE_SQL handles input in SQL mode
(SQL command)
-
term.MODE_READ handles prompt issued by ObjectScript
read x command
-
term.MODE_READ_CHAR handles prompt issued by ObjectScript
read *x command
-
term.MODE_SPECIAL handles special WebTerminal's
commands like /help, /config etc.
Here is example of user input handling:
function myInitHandler (term) {
term.onUserInput(function (text, mode) {
if (mode !== term.MODE_PROMPT)
return; // expect only the ObjectScript input
if (text.indexOf("set secret = ") === 0)
alert("Do not set secret variables!!!");
});
}
4.2.4. Printing
To print something to terminal output, use
term.print(text) function, where
text is a simple string. This string can include any
special characters and escape sequences. This function is input-safe, which
means that you can print event when terminal is waiting for user input. In this
case the input will reappear right after the printed text.
Example:
function myInitHandler (term) {
term.print("\r\nWe're ready!\r\n\n");
}
4.2.5. Handling Output
You can handle terminal output by using
term.onOutput([ options ], callback). By default,
callback(strings) will be called before the user is prompted for
input, and strings array will always contain an array of chunks
of all the text printed between the prompts. For example, if user writes
write 123 and presses "Enter", the strings will
contain this array: ["\r\n", "123", "\r\n"]. However, when user
enters write 1, 2, 3, strings will result with
["\r\n", "1", "2", "3", "\r\n"]. You can join this array with
join("") array method to get the full output.
Optional options object may include stream property,
which is false by default. When set to true,
callback will be fired every time something is printed to the terminal
simultaneously.
Example:
function myInitHandler (term) {
term.onOutput((chunks) => {
// If you "write 12", chunks are ["\r\n", "12", "\r\n"].
// If you "write 1, 2", chunks are ["\r\n", "1", "2", "\r\n"].
if (chunks.slice(1, -1).join("") === "duck") { // if the user enters: write "duck"
alert(`You've found a secret phrase!`);
}
});
}
4.2.6. Removing Callbacks
Every function that accepts callback also returns the same callback, which can
be passed to term.removeCallback(callback). After
callback is passed to this function, it will not longer execute.
5. Contributing To WebTerminal Project
The Caché WebTerminal is an open-source project anyone can contribute to. Anyone
are welcome to join and contribute to this project on InterSystems official
GitHub.
This section describes the basic guidelines and principles of contributing.
5.1. Development Workflow
The development workflow of Caché WebTerminal lies completely outside Caché
(without using Caché Studio / Atelier) and is possible for any platform. It
uses a Gulp building tool to gather and build the Caché-ready project from bare
sources, JavaScript ECMAScript 6 standard and SCSS (SASS) for styling.
To set up the project, you have to have latest
Git and
NodeJS installed
(tested on NodeJS v4-6). Then, use command line to download and setup the
project:
git clone https://github.com/intersystems-community/webterminal
cd webterminal # enter repository directory
npm install # install all project's dependencies
npm run build # build the project
After this, you will get the build directory
containing Caché classes in UDL format. To import these classes to Caché,
and to perform the build with one single command, go to edit the
import.cmd or import.sh
file (depending on your OS). There you need to change only constants like
CACHE_DIR, which may be different for your system.
Just do not commit this file after changing, and use the next command
import
to build and import new classes to Caché. Once you have imported classes, you
should receive IMPORT STATUS: OK and
EXPORT STATUS: OK messages.
The workflow to release a new version of WebTerminal is presented below.
Please, be very careful when releasing new versions, as all the WebTerminal
users will start receiving updates. To release a new WebTerminal version, do the following:
-
Build and carefully test the project as described above.
-
Copy
build/WebTerminal-vX.Y.Z.xml file to the
docs/files directory.
-
Append a record describing changes to
docs/terminal.json file.
You can accurately copy-paste-edit record from the previous records. Make sure you changed
the /versions/X/v and /versions/X/url properties
to the latest version and the location of the file respectively. Note that the latest version
bust be greater than the previous version. Make sure that the JSON structure is still
valid.
-
If the change is pretty important, add it to visible releases (this website) by editing
docs/index.html file.
-
After you push these changes to repository, test whether terminal receives the new version and
properly updates.
A special care must be taken while altering WebTerminal updating mechanism
(WebTerminal.Updater class). If you push a broken change, WebTerminal
will update itself normally for the first time. During the next updates WebTerminal
will use the new update code which can possibly make it never update again, and user
will need to reinstall WebTerminal manually).
You can put the /motd (message of the day) message to
docs/terminal.json: all WebTerminal users will start to see this
message in console. Do it only when absolute necessary: do not distract users. This functionality
is kept for the critical WebTerminal faults, when users will need to reinstall WebTerminal
manually (hopefully never).
One more thing for repository maintainers: **never** rename the repository or move the
docs (website) to the custom domain until you will be completely sure
that this won't break the WebTerminal auto-updating mechanism (update URLs).
5.2. Guidelines
There are several guidelines you should consider if you want to contribute to
WebTerminal project by yourself:
-
Create a new issue
or open a pull request for every new contribution.
-
Use spaces instead of tabs (4 spaces), comment and format well any
contribution if needed.
-
When introducing new features or extending WebTerminal API, open a new
issue
to discuss the way how to implement it as best as possible.
5.3. Entry Points
This section describes the main files of the project.
| File name / Directory |
Description |
/import.* |
Script used to build and import the project to local Caché with one
command. This script assumes editing before usage (changing constants).
|
/src/client/ |
Directory containing the client files (HTML, SCSS, JavaScript).
|
/src/cls/ |
Directory containing the server files (HTML, SCSS, JavaScript). Both
client and server files are pre-processed. For example, you may notice
that server files include comments with special syntax (f.e.
<!-- @echo package.title -->). These
lines are pre-processed during the build and are replaced with
corresponding values.
|
/src/client/js/
output/esc.js |
File that describes all supported escape sequences. The exported
object's keys contain the character pattern of escape sequence,
and the regular expression patterns enclosed by
{} characters. The function as a key is
triggered once the sequence is printed. However, no characters will
appear in the output if the sequence is recognized.
|
/src/client/js/
parser/grammar.js |
You can easily make pull requests on this file if you need to enhance
Caché ObjectScript grammar recognition.
This file describes the grammar for Caché ObjectScript and SQL
languages. See the comments in this file to understand its structure
and feel free to enhance the grammar file to improve highlighting and
autocomplete.
|
/src/client/js/
localization/dictionary.js |
You can easily make pull requests on this file if you need to
support any UI language for WebTerminal.
This file includes all available translations for WebTerminal user
interface. Using the same file structure, new languages can be easily
introduced just by adding text only to this file.
|
| others |
There are many other project files, please consider exploring their
comments if you need more information.
|
6. Licensing (MIT)
The Caché WebTerminal is an open-source project developed and supported
primarily by Nikita
Savchenko for the InterSystems community. Anyone are welcome to join and
contribute to this project on InterSystems official
GitHub.
The project is distributed under the MIT license, which provides absolutely free
non-commercial and commercial use of the software. The license text is shown
below.
The MIT License (MIT)
Copyright (c) 2013-2018 Nikita Savchenko
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
