Telstar Wiki - User contributions [en]

1970s Home Computing in the UK

2025-10-04T10:00:17Z

John: Created page with "Just a starting point, many of these could not realistically be classified as home or personal computers, despite many of them being used in a single user mode. === 1970 === *Datapoint (CTC) 2200 - TTL Computer *ICL 1900 series — British mainframes, widely deployed. *Data General Nova — imported 16-bit minicomputer. *DEC PDP-11/20 — first PDP-11 systems reached UK universities/labs. === 1971 === *HP 2100A minicomputer — available via HP UK offices...."

Just a starting point, many of these could not realistically be classified as home or personal computers, despite many of them being used in a single user mode.

=== 1970 ===

*Datapoint (CTC) 2200 - TTL Computer
*ICL 1900 series — British mainframes, widely deployed.
*Data General Nova — imported 16-bit minicomputer.
*DEC PDP-11/20 — first PDP-11 systems reached UK universities/labs.

=== 1971 ===

*HP 2100A minicomputer — available via HP UK offices.
*Interdata 7/16 — 16-bit minicomputer, sold in UK.
*Kenbak 1 - First Personal Computer ?
*Intel SIM4-01
*Intel SIM4-02

=== 1972 ===

*DEC PDP-11/40 — expanded PDP-11 family in UK use.
*IBM System/3 — midrange systems shipped to UK businesses.
*QI Corporation Q1
*IBM SCAMP (1972/1973)
*Intel SIM8-01

=== 1973 ===

*Wang 2200 — BASIC desktop computer, imported to UK.
*ICL 2900 series — launched as successor to 1900 series.
*R2E MicralN - French computer
*Intel Intellec
*Xerox Alto
*Xerox Star

=== 1974 ===

*Mark-8 (kit, Intel 8008) — hobbyist kit plans; some built in UK by enthusiasts.
*DEC PDP-11/34 — later PDP-11s became standard in UK universities.
*RCA Fred/Cosmac
*Mark 8 - Radio and Electronics
*QI Corporation Q1/Lite
*QI Corporation Q1/MicroLite

=== 1975 ===

*MITS Altair 8800 (kit) — available via import/mail order in UK.
*IMSAI 8080 (kit) — Altair-compatible S-100 system, imported.
*Sphere 1 — limited UK import.
*SWTPC 6800 (kit) — Motorola-based system available through UK distributors.
*IBM 5100

=== 1976 ===

*Processor Technology SOL-20 — first pre-assembled micro, imported to UK.
*MOS Technology KIM-1 (single board) — popular among UK hobbyists.
*Polymorphic Systems Poly-88 — some UK availability via specialist dealers.
*Digital Group machines — imported modular kits.
*Bywood Scrumpy - The first single-board computer kit made in the UK.
*Apple 1
*Cosmac Elf - Magazine/Kit
*Motorola MEK6800D2 - Development board.
*MPT 8080 Microtutor

=== 1977 ===

*Apple II — began UK distribution.
*Commodore PET 2001 — available in UK education/business.
*TRS-80 Model I — sold by Tandy in UK stores.
*Heathkit H8 (kit) — obtainable in UK.
*Science of Cambridge MK14 (kit) — UK-only.
*Nascom-1 (kit) — British single-board kit, launched late 1977.
*System 68 - ETI Magazine

=== 1978 ===

*Nascom-2 (kit) — enhanced British micro.
*Ohio Scientific Superboard II — imported; inspired the UK101.
*Exidy Sorcerer — some units imported to UK.
*Cromemco Z-2 — S-100 business micro, UK dealer support.
*NorthStar Horizon — floppy-based micro, sold in UK.
*Vector Graphic 1 — CP/M micro, available through importers.
*MZ-80K — An all-in-one unit with keyboard.
*Transam Triton - ETI
*Rockwell Aim-65
*Synertek Sym-1
*Intel SDK-85
*IBM 5110

=== 1979 ===

*Acorn System 1 (kit/assembled) — first Acorn computer, UK.
*Tangerine Microtan-65 (kit) — 6502 kit, UK release.
*Compukit UK101 (kit) — UK clone of OSI Superboard II.
*Atari 400 / 800 — home micros, UK launch late 1979.
*Texas Instruments TI-99/4 — imported to UK in 1979.
*Intertec Superbrain — business-oriented CP/M micro, available in UK.
*Compucolor II — colour micro, limited UK availability.
*MZ-80C- Featured an improved keyboard and 48KB of memory.
*Powertran PSI Comp 80 - Wireless World Z80

=== Considerations ===

*VAX
*DEC
*Prime Computers
*Cromemco systems (late 1970s) — S-100 family machines, imported to the UK.
*Zenith assembled systems (via dealers).
*Sord
*Toshiba — available in UK through niche distributors.
*Data General — popular 16-bit minicomputer, sold in UK.
*Honeywell
*Burroughs
*Univac

Main Page

2025-10-04T09:57:40Z

John: Changed redirect target from Pre-1980 Personal and Home Computers to 1970s Home Computing in the UK

#REDIRECT [[1970s Home Computing in the UK]]

Pre-1980 Personal and Home Computers

2025-10-02T15:51:45Z

John: /* 1961 */

==Introduction==

What follows is a list of personal computers available to the public in one form or another to members of the public. The term Personal Computer in this context refers to a general purpose computer that was designed to be used by a single person typically in their home or place of work or study.

=== 1958 ===

*Elliot 801

=== 1959 ===

==== DEC PDP 1 ====

The company’s first Programmed Data Processor, the PDP-1 computer used DIGITAL’s own system modules, which came from the existing range of 1OMC logic released in late 1959. The first PDP-1, delivered in December 1959, was a high speed, 18.bit, small computer capable of addressing 32K of core memoy. An average configuration cost $120,000 in an era when most computer systems were sold for a million dollars or more. [1]

Standard peripherals included a paper tape reader and punch, and a terminal. Optional peripherals included graphics displays, a light pen, line printer, punched card reader and punch, and magnetic tape controller and drives. [2]

A PDP-1 at MIT's RLE served as the nucleus for early hacker culture at MIT, including for the first video game, Spacewar!. The PDP-1/D at BBN was much used in the early ARPANET work; both for software development, and as the Network Control Center's first machine. [2]

[1] "DEC 1957 to the Present" p.3
[2] https://gunkies.org/wiki/PDP-1

=== 1960 ===

*Elliott 803A

=== 1961 ===

*Elliot 803B

=== 1962 ===

*Linc - Personal Minicomputer

=== 1967 ===

*Wireless World Computer = Transistor based Computer from Wireless World Magazine (August 1967)

=== 1970 ===

*Datapoint (CTC) 2200 - TTL Computer
*ICL 1900 series — British mainframes, widely deployed.
*Data General Nova — imported 16-bit minicomputer.
*DEC PDP-11/20 — first PDP-11 systems reached UK universities/labs.

=== 1971 ===

*HP 2100A minicomputer — available via HP UK offices.
*Interdata 7/16 — 16-bit minicomputer, sold in UK.
*Kenbak 1 - First Personal Computer ?
*Intel SIM4-01
*Intel SIM4-02

=== 1972 ===

*DEC PDP-11/40 — expanded PDP-11 family in UK use.
*IBM System/3 — midrange systems shipped to UK businesses.
*QI Corporation Q1
*IBM SCAMP (1972/1973)
*Intel SIM8-01

=== 1973 ===

*Wang 2200 — BASIC desktop computer, imported to UK.
*ICL 2900 series — launched as successor to 1900 series.
*R2E MicralN - French computer
*Intel Intellec
*Xerox Alto
*Xerox Star

=== 1974 ===

*Mark-8 (kit, Intel 8008) — hobbyist kit plans; some built in UK by enthusiasts.
*DEC PDP-11/34 — later PDP-11s became standard in UK universities.
*RCA Fred/Cosmac
*Mark 8 - Radio and Electronics
*QI Corporation Q1/Lite
*QI Corporation Q1/MicroLite

=== 1975 ===

*MITS Altair 8800 (kit) — available via import/mail order in UK.
*IMSAI 8080 (kit) — Altair-compatible S-100 system, imported.
*Sphere 1 — limited UK import.
*SWTPC 6800 (kit) — Motorola-based system available through UK distributors.
*IBM 5100

=== 1976 ===

*Processor Technology SOL-20 — first pre-assembled micro, imported to UK.
*MOS Technology KIM-1 (single board) — popular among UK hobbyists.
*Polymorphic Systems Poly-88 — some UK availability via specialist dealers.
*Digital Group machines — imported modular kits.
*Bywood Scrumpy - The first single-board computer kit made in the UK.
*Apple 1
*Cosmac Elf - Magazine/Kit
*Motorola MEK6800D2 - Development board.
*MPT 8080 Microtutor

=== 1977 ===

*Apple II — began UK distribution.
*Commodore PET 2001 — available in UK education/business.
*TRS-80 Model I — sold by Tandy in UK stores.
*Heathkit H8 (kit) — obtainable in UK.
*Science of Cambridge MK14 (kit) — UK-only.
*Nascom-1 (kit) — British single-board kit, launched late 1977.
*System 68 - ETI Magazine

=== 1978 ===

*Nascom-2 (kit) — enhanced British micro.
*Ohio Scientific Superboard II — imported; inspired the UK101.
*Exidy Sorcerer — some units imported to UK.
*Cromemco Z-2 — S-100 business micro, UK dealer support.
*NorthStar Horizon — floppy-based micro, sold in UK.
*Vector Graphic 1 — CP/M micro, available through importers.
*MZ-80K — An all-in-one unit with keyboard.
*Transam Triton - ETI
*Rockwell Aim-65
*Synertek Sym-1
*Intel SDK-85
*IBM 5110

=== 1979 ===

*Acorn System 1 (kit/assembled) — first Acorn computer, UK.
*Tangerine Microtan-65 (kit) — 6502 kit, UK release.
*Compukit UK101 (kit) — UK clone of OSI Superboard II.
*Atari 400 / 800 — home micros, UK launch late 1979.
*Texas Instruments TI-99/4 — imported to UK in 1979.
*Intertec Superbrain — business-oriented CP/M micro, available in UK.
*Compucolor II — colour micro, limited UK availability.
*MZ-80C- Featured an improved keyboard and 48KB of memory.
*Powertran PSI Comp 80 - Wireless World Z80

=== Considerations ===

*VAX
*DEC
*Prime Computers
*Cromemco systems (late 1970s) — S-100 family machines, imported to the UK.
*Zenith assembled systems (via dealers).
*Sord
*Toshiba — available in UK through niche distributors.
*Data General — popular 16-bit minicomputer, sold in UK.
*Honeywell
*Burroughs
*Univac

== Sources ==

* Centre for Computing History (UK)
* Science Museum Group (UK) — Nascom and other UK machines
* Contemporary records: MK14, Acorn System 1, Nascom, Microtan-65, Compukit UK101
* DEC PDP-11 and other minicomputers in UK use
* ICL in UK

Pre-1980 Personal and Home Computers

2025-10-02T15:51:38Z

John: /* 1960 */

==Introduction==

What follows is a list of personal computers available to the public in one form or another to members of the public. The term Personal Computer in this context refers to a general purpose computer that was designed to be used by a single person typically in their home or place of work or study.

=== 1958 ===

*Elliot 801

=== 1959 ===

==== DEC PDP 1 ====

The company’s first Programmed Data Processor, the PDP-1 computer used DIGITAL’s own system modules, which came from the existing range of 1OMC logic released in late 1959. The first PDP-1, delivered in December 1959, was a high speed, 18.bit, small computer capable of addressing 32K of core memoy. An average configuration cost $120,000 in an era when most computer systems were sold for a million dollars or more. [1]

Standard peripherals included a paper tape reader and punch, and a terminal. Optional peripherals included graphics displays, a light pen, line printer, punched card reader and punch, and magnetic tape controller and drives. [2]

A PDP-1 at MIT's RLE served as the nucleus for early hacker culture at MIT, including for the first video game, Spacewar!. The PDP-1/D at BBN was much used in the early ARPANET work; both for software development, and as the Network Control Center's first machine. [2]

[1] "DEC 1957 to the Present" p.3
[2] https://gunkies.org/wiki/PDP-1

=== 1960 ===

*Elliott 803A

=== 1961 ===

Elliot 803B

=== 1962 ===

*Linc - Personal Minicomputer

=== 1967 ===

*Wireless World Computer = Transistor based Computer from Wireless World Magazine (August 1967)

=== 1970 ===

*Datapoint (CTC) 2200 - TTL Computer
*ICL 1900 series — British mainframes, widely deployed.
*Data General Nova — imported 16-bit minicomputer.
*DEC PDP-11/20 — first PDP-11 systems reached UK universities/labs.

=== 1971 ===

*HP 2100A minicomputer — available via HP UK offices.
*Interdata 7/16 — 16-bit minicomputer, sold in UK.
*Kenbak 1 - First Personal Computer ?
*Intel SIM4-01
*Intel SIM4-02

=== 1972 ===

*DEC PDP-11/40 — expanded PDP-11 family in UK use.
*IBM System/3 — midrange systems shipped to UK businesses.
*QI Corporation Q1
*IBM SCAMP (1972/1973)
*Intel SIM8-01

=== 1973 ===

*Wang 2200 — BASIC desktop computer, imported to UK.
*ICL 2900 series — launched as successor to 1900 series.
*R2E MicralN - French computer
*Intel Intellec
*Xerox Alto
*Xerox Star

=== 1974 ===

*Mark-8 (kit, Intel 8008) — hobbyist kit plans; some built in UK by enthusiasts.
*DEC PDP-11/34 — later PDP-11s became standard in UK universities.
*RCA Fred/Cosmac
*Mark 8 - Radio and Electronics
*QI Corporation Q1/Lite
*QI Corporation Q1/MicroLite

=== 1975 ===

*MITS Altair 8800 (kit) — available via import/mail order in UK.
*IMSAI 8080 (kit) — Altair-compatible S-100 system, imported.
*Sphere 1 — limited UK import.
*SWTPC 6800 (kit) — Motorola-based system available through UK distributors.
*IBM 5100

=== 1976 ===

*Processor Technology SOL-20 — first pre-assembled micro, imported to UK.
*MOS Technology KIM-1 (single board) — popular among UK hobbyists.
*Polymorphic Systems Poly-88 — some UK availability via specialist dealers.
*Digital Group machines — imported modular kits.
*Bywood Scrumpy - The first single-board computer kit made in the UK.
*Apple 1
*Cosmac Elf - Magazine/Kit
*Motorola MEK6800D2 - Development board.
*MPT 8080 Microtutor

=== 1977 ===

*Apple II — began UK distribution.
*Commodore PET 2001 — available in UK education/business.
*TRS-80 Model I — sold by Tandy in UK stores.
*Heathkit H8 (kit) — obtainable in UK.
*Science of Cambridge MK14 (kit) — UK-only.
*Nascom-1 (kit) — British single-board kit, launched late 1977.
*System 68 - ETI Magazine

=== 1978 ===

*Nascom-2 (kit) — enhanced British micro.
*Ohio Scientific Superboard II — imported; inspired the UK101.
*Exidy Sorcerer — some units imported to UK.
*Cromemco Z-2 — S-100 business micro, UK dealer support.
*NorthStar Horizon — floppy-based micro, sold in UK.
*Vector Graphic 1 — CP/M micro, available through importers.
*MZ-80K — An all-in-one unit with keyboard.
*Transam Triton - ETI
*Rockwell Aim-65
*Synertek Sym-1
*Intel SDK-85
*IBM 5110

=== 1979 ===

*Acorn System 1 (kit/assembled) — first Acorn computer, UK.
*Tangerine Microtan-65 (kit) — 6502 kit, UK release.
*Compukit UK101 (kit) — UK clone of OSI Superboard II.
*Atari 400 / 800 — home micros, UK launch late 1979.
*Texas Instruments TI-99/4 — imported to UK in 1979.
*Intertec Superbrain — business-oriented CP/M micro, available in UK.
*Compucolor II — colour micro, limited UK availability.
*MZ-80C- Featured an improved keyboard and 48KB of memory.
*Powertran PSI Comp 80 - Wireless World Z80

=== Considerations ===

*VAX
*DEC
*Prime Computers
*Cromemco systems (late 1970s) — S-100 family machines, imported to the UK.
*Zenith assembled systems (via dealers).
*Sord
*Toshiba — available in UK through niche distributors.
*Data General — popular 16-bit minicomputer, sold in UK.
*Honeywell
*Burroughs
*Univac

== Sources ==

* Centre for Computing History (UK)
* Science Museum Group (UK) — Nascom and other UK machines
* Contemporary records: MK14, Acorn System 1, Nascom, Microtan-65, Compukit UK101
* DEC PDP-11 and other minicomputers in UK use
* ICL in UK

Pre-1980 Personal and Home Computers

2025-10-02T15:51:25Z

John: /* 1960 */

==Introduction==

What follows is a list of personal computers available to the public in one form or another to members of the public. The term Personal Computer in this context refers to a general purpose computer that was designed to be used by a single person typically in their home or place of work or study.

=== 1958 ===

*Elliot 801

=== 1959 ===

==== DEC PDP 1 ====

The company’s first Programmed Data Processor, the PDP-1 computer used DIGITAL’s own system modules, which came from the existing range of 1OMC logic released in late 1959. The first PDP-1, delivered in December 1959, was a high speed, 18.bit, small computer capable of addressing 32K of core memoy. An average configuration cost $120,000 in an era when most computer systems were sold for a million dollars or more. [1]

Standard peripherals included a paper tape reader and punch, and a terminal. Optional peripherals included graphics displays, a light pen, line printer, punched card reader and punch, and magnetic tape controller and drives. [2]

A PDP-1 at MIT's RLE served as the nucleus for early hacker culture at MIT, including for the first video game, Spacewar!. The PDP-1/D at BBN was much used in the early ARPANET work; both for software development, and as the Network Control Center's first machine. [2]

[1] "DEC 1957 to the Present" p.3
[2] https://gunkies.org/wiki/PDP-1

=== 1960 ===

Elliott 803A

=== 1961 ===

Elliot 803B

=== 1962 ===

*Linc - Personal Minicomputer

=== 1967 ===

*Wireless World Computer = Transistor based Computer from Wireless World Magazine (August 1967)

=== 1970 ===

*Datapoint (CTC) 2200 - TTL Computer
*ICL 1900 series — British mainframes, widely deployed.
*Data General Nova — imported 16-bit minicomputer.
*DEC PDP-11/20 — first PDP-11 systems reached UK universities/labs.

=== 1971 ===

*HP 2100A minicomputer — available via HP UK offices.
*Interdata 7/16 — 16-bit minicomputer, sold in UK.
*Kenbak 1 - First Personal Computer ?
*Intel SIM4-01
*Intel SIM4-02

=== 1972 ===

*DEC PDP-11/40 — expanded PDP-11 family in UK use.
*IBM System/3 — midrange systems shipped to UK businesses.
*QI Corporation Q1
*IBM SCAMP (1972/1973)
*Intel SIM8-01

=== 1973 ===

*Wang 2200 — BASIC desktop computer, imported to UK.
*ICL 2900 series — launched as successor to 1900 series.
*R2E MicralN - French computer
*Intel Intellec
*Xerox Alto
*Xerox Star

=== 1974 ===

*Mark-8 (kit, Intel 8008) — hobbyist kit plans; some built in UK by enthusiasts.
*DEC PDP-11/34 — later PDP-11s became standard in UK universities.
*RCA Fred/Cosmac
*Mark 8 - Radio and Electronics
*QI Corporation Q1/Lite
*QI Corporation Q1/MicroLite

=== 1975 ===

*MITS Altair 8800 (kit) — available via import/mail order in UK.
*IMSAI 8080 (kit) — Altair-compatible S-100 system, imported.
*Sphere 1 — limited UK import.
*SWTPC 6800 (kit) — Motorola-based system available through UK distributors.
*IBM 5100

=== 1976 ===

*Processor Technology SOL-20 — first pre-assembled micro, imported to UK.
*MOS Technology KIM-1 (single board) — popular among UK hobbyists.
*Polymorphic Systems Poly-88 — some UK availability via specialist dealers.
*Digital Group machines — imported modular kits.
*Bywood Scrumpy - The first single-board computer kit made in the UK.
*Apple 1
*Cosmac Elf - Magazine/Kit
*Motorola MEK6800D2 - Development board.
*MPT 8080 Microtutor

=== 1977 ===

*Apple II — began UK distribution.
*Commodore PET 2001 — available in UK education/business.
*TRS-80 Model I — sold by Tandy in UK stores.
*Heathkit H8 (kit) — obtainable in UK.
*Science of Cambridge MK14 (kit) — UK-only.
*Nascom-1 (kit) — British single-board kit, launched late 1977.
*System 68 - ETI Magazine

=== 1978 ===

*Nascom-2 (kit) — enhanced British micro.
*Ohio Scientific Superboard II — imported; inspired the UK101.
*Exidy Sorcerer — some units imported to UK.
*Cromemco Z-2 — S-100 business micro, UK dealer support.
*NorthStar Horizon — floppy-based micro, sold in UK.
*Vector Graphic 1 — CP/M micro, available through importers.
*MZ-80K — An all-in-one unit with keyboard.
*Transam Triton - ETI
*Rockwell Aim-65
*Synertek Sym-1
*Intel SDK-85
*IBM 5110

=== 1979 ===

*Acorn System 1 (kit/assembled) — first Acorn computer, UK.
*Tangerine Microtan-65 (kit) — 6502 kit, UK release.
*Compukit UK101 (kit) — UK clone of OSI Superboard II.
*Atari 400 / 800 — home micros, UK launch late 1979.
*Texas Instruments TI-99/4 — imported to UK in 1979.
*Intertec Superbrain — business-oriented CP/M micro, available in UK.
*Compucolor II — colour micro, limited UK availability.
*MZ-80C- Featured an improved keyboard and 48KB of memory.
*Powertran PSI Comp 80 - Wireless World Z80

=== Considerations ===

*VAX
*DEC
*Prime Computers
*Cromemco systems (late 1970s) — S-100 family machines, imported to the UK.
*Zenith assembled systems (via dealers).
*Sord
*Toshiba — available in UK through niche distributors.
*Data General — popular 16-bit minicomputer, sold in UK.
*Honeywell
*Burroughs
*Univac

== Sources ==

* Centre for Computing History (UK)
* Science Museum Group (UK) — Nascom and other UK machines
* Contemporary records: MK14, Acorn System 1, Nascom, Microtan-65, Compukit UK101
* DEC PDP-11 and other minicomputers in UK use
* ICL in UK

Pre-1980 Personal and Home Computers

2025-10-02T15:50:38Z

John: /* 1961 */

==Introduction==

What follows is a list of personal computers available to the public in one form or another to members of the public. The term Personal Computer in this context refers to a general purpose computer that was designed to be used by a single person typically in their home or place of work or study.

=== 1958 ===

*Elliot 801

=== 1959 ===

==== DEC PDP 1 ====

The company’s first Programmed Data Processor, the PDP-1 computer used DIGITAL’s own system modules, which came from the existing range of 1OMC logic released in late 1959. The first PDP-1, delivered in December 1959, was a high speed, 18.bit, small computer capable of addressing 32K of core memoy. An average configuration cost $120,000 in an era when most computer systems were sold for a million dollars or more. [1]

Standard peripherals included a paper tape reader and punch, and a terminal. Optional peripherals included graphics displays, a light pen, line printer, punched card reader and punch, and magnetic tape controller and drives. [2]

A PDP-1 at MIT's RLE served as the nucleus for early hacker culture at MIT, including for the first video game, Spacewar!. The PDP-1/D at BBN was much used in the early ARPANET work; both for software development, and as the Network Control Center's first machine. [2]

[1] "DEC 1957 to the Present" p.3
[2] https://gunkies.org/wiki/PDP-1

=== 1960 ===

Elliott 803

=== 1962 ===

*Linc - Personal Minicomputer

=== 1967 ===

*Wireless World Computer = Transistor based Computer from Wireless World Magazine (August 1967)

=== 1970 ===

*Datapoint (CTC) 2200 - TTL Computer
*ICL 1900 series — British mainframes, widely deployed.
*Data General Nova — imported 16-bit minicomputer.
*DEC PDP-11/20 — first PDP-11 systems reached UK universities/labs.

=== 1971 ===

*HP 2100A minicomputer — available via HP UK offices.
*Interdata 7/16 — 16-bit minicomputer, sold in UK.
*Kenbak 1 - First Personal Computer ?
*Intel SIM4-01
*Intel SIM4-02

=== 1972 ===

*DEC PDP-11/40 — expanded PDP-11 family in UK use.
*IBM System/3 — midrange systems shipped to UK businesses.
*QI Corporation Q1
*IBM SCAMP (1972/1973)
*Intel SIM8-01

=== 1973 ===

*Wang 2200 — BASIC desktop computer, imported to UK.
*ICL 2900 series — launched as successor to 1900 series.
*R2E MicralN - French computer
*Intel Intellec
*Xerox Alto
*Xerox Star

=== 1974 ===

*Mark-8 (kit, Intel 8008) — hobbyist kit plans; some built in UK by enthusiasts.
*DEC PDP-11/34 — later PDP-11s became standard in UK universities.
*RCA Fred/Cosmac
*Mark 8 - Radio and Electronics
*QI Corporation Q1/Lite
*QI Corporation Q1/MicroLite

=== 1975 ===

*MITS Altair 8800 (kit) — available via import/mail order in UK.
*IMSAI 8080 (kit) — Altair-compatible S-100 system, imported.
*Sphere 1 — limited UK import.
*SWTPC 6800 (kit) — Motorola-based system available through UK distributors.
*IBM 5100

=== 1976 ===

*Processor Technology SOL-20 — first pre-assembled micro, imported to UK.
*MOS Technology KIM-1 (single board) — popular among UK hobbyists.
*Polymorphic Systems Poly-88 — some UK availability via specialist dealers.
*Digital Group machines — imported modular kits.
*Bywood Scrumpy - The first single-board computer kit made in the UK.
*Apple 1
*Cosmac Elf - Magazine/Kit
*Motorola MEK6800D2 - Development board.
*MPT 8080 Microtutor

=== 1977 ===

*Apple II — began UK distribution.
*Commodore PET 2001 — available in UK education/business.
*TRS-80 Model I — sold by Tandy in UK stores.
*Heathkit H8 (kit) — obtainable in UK.
*Science of Cambridge MK14 (kit) — UK-only.
*Nascom-1 (kit) — British single-board kit, launched late 1977.
*System 68 - ETI Magazine

=== 1978 ===

*Nascom-2 (kit) — enhanced British micro.
*Ohio Scientific Superboard II — imported; inspired the UK101.
*Exidy Sorcerer — some units imported to UK.
*Cromemco Z-2 — S-100 business micro, UK dealer support.
*NorthStar Horizon — floppy-based micro, sold in UK.
*Vector Graphic 1 — CP/M micro, available through importers.
*MZ-80K — An all-in-one unit with keyboard.
*Transam Triton - ETI
*Rockwell Aim-65
*Synertek Sym-1
*Intel SDK-85
*IBM 5110

=== 1979 ===

*Acorn System 1 (kit/assembled) — first Acorn computer, UK.
*Tangerine Microtan-65 (kit) — 6502 kit, UK release.
*Compukit UK101 (kit) — UK clone of OSI Superboard II.
*Atari 400 / 800 — home micros, UK launch late 1979.
*Texas Instruments TI-99/4 — imported to UK in 1979.
*Intertec Superbrain — business-oriented CP/M micro, available in UK.
*Compucolor II — colour micro, limited UK availability.
*MZ-80C- Featured an improved keyboard and 48KB of memory.
*Powertran PSI Comp 80 - Wireless World Z80

=== Considerations ===

*VAX
*DEC
*Prime Computers
*Cromemco systems (late 1970s) — S-100 family machines, imported to the UK.
*Zenith assembled systems (via dealers).
*Sord
*Toshiba — available in UK through niche distributors.
*Data General — popular 16-bit minicomputer, sold in UK.
*Honeywell
*Burroughs
*Univac

== Sources ==

* Centre for Computing History (UK)
* Science Museum Group (UK) — Nascom and other UK machines
* Contemporary records: MK14, Acorn System 1, Nascom, Microtan-65, Compukit UK101
* DEC PDP-11 and other minicomputers in UK use
* ICL in UK

Pre-1980 Personal and Home Computers

2025-10-02T15:50:15Z

John: /* Introduction */

==Introduction==

What follows is a list of personal computers available to the public in one form or another to members of the public. The term Personal Computer in this context refers to a general purpose computer that was designed to be used by a single person typically in their home or place of work or study.

=== 1958 ===

*Elliot 801

=== 1959 ===

==== DEC PDP 1 ====

The company’s first Programmed Data Processor, the PDP-1 computer used DIGITAL’s own system modules, which came from the existing range of 1OMC logic released in late 1959. The first PDP-1, delivered in December 1959, was a high speed, 18.bit, small computer capable of addressing 32K of core memoy. An average configuration cost $120,000 in an era when most computer systems were sold for a million dollars or more. [1]

Standard peripherals included a paper tape reader and punch, and a terminal. Optional peripherals included graphics displays, a light pen, line printer, punched card reader and punch, and magnetic tape controller and drives. [2]

A PDP-1 at MIT's RLE served as the nucleus for early hacker culture at MIT, including for the first video game, Spacewar!. The PDP-1/D at BBN was much used in the early ARPANET work; both for software development, and as the Network Control Center's first machine. [2]

[1] "DEC 1957 to the Present" p.3
[2] https://gunkies.org/wiki/PDP-1

=== 1961 ===

Elliott 803

=== 1962 ===

*Linc - Personal Minicomputer

=== 1967 ===

*Wireless World Computer = Transistor based Computer from Wireless World Magazine (August 1967)

=== 1970 ===

*Datapoint (CTC) 2200 - TTL Computer
*ICL 1900 series — British mainframes, widely deployed.
*Data General Nova — imported 16-bit minicomputer.
*DEC PDP-11/20 — first PDP-11 systems reached UK universities/labs.

=== 1971 ===

*HP 2100A minicomputer — available via HP UK offices.
*Interdata 7/16 — 16-bit minicomputer, sold in UK.
*Kenbak 1 - First Personal Computer ?
*Intel SIM4-01
*Intel SIM4-02

=== 1972 ===

*DEC PDP-11/40 — expanded PDP-11 family in UK use.
*IBM System/3 — midrange systems shipped to UK businesses.
*QI Corporation Q1
*IBM SCAMP (1972/1973)
*Intel SIM8-01

=== 1973 ===

*Wang 2200 — BASIC desktop computer, imported to UK.
*ICL 2900 series — launched as successor to 1900 series.
*R2E MicralN - French computer
*Intel Intellec
*Xerox Alto
*Xerox Star

=== 1974 ===

*Mark-8 (kit, Intel 8008) — hobbyist kit plans; some built in UK by enthusiasts.
*DEC PDP-11/34 — later PDP-11s became standard in UK universities.
*RCA Fred/Cosmac
*Mark 8 - Radio and Electronics
*QI Corporation Q1/Lite
*QI Corporation Q1/MicroLite

=== 1975 ===

*MITS Altair 8800 (kit) — available via import/mail order in UK.
*IMSAI 8080 (kit) — Altair-compatible S-100 system, imported.
*Sphere 1 — limited UK import.
*SWTPC 6800 (kit) — Motorola-based system available through UK distributors.
*IBM 5100

=== 1976 ===

*Processor Technology SOL-20 — first pre-assembled micro, imported to UK.
*MOS Technology KIM-1 (single board) — popular among UK hobbyists.
*Polymorphic Systems Poly-88 — some UK availability via specialist dealers.
*Digital Group machines — imported modular kits.
*Bywood Scrumpy - The first single-board computer kit made in the UK.
*Apple 1
*Cosmac Elf - Magazine/Kit
*Motorola MEK6800D2 - Development board.
*MPT 8080 Microtutor

=== 1977 ===

*Apple II — began UK distribution.
*Commodore PET 2001 — available in UK education/business.
*TRS-80 Model I — sold by Tandy in UK stores.
*Heathkit H8 (kit) — obtainable in UK.
*Science of Cambridge MK14 (kit) — UK-only.
*Nascom-1 (kit) — British single-board kit, launched late 1977.
*System 68 - ETI Magazine

=== 1978 ===

*Nascom-2 (kit) — enhanced British micro.
*Ohio Scientific Superboard II — imported; inspired the UK101.
*Exidy Sorcerer — some units imported to UK.
*Cromemco Z-2 — S-100 business micro, UK dealer support.
*NorthStar Horizon — floppy-based micro, sold in UK.
*Vector Graphic 1 — CP/M micro, available through importers.
*MZ-80K — An all-in-one unit with keyboard.
*Transam Triton - ETI
*Rockwell Aim-65
*Synertek Sym-1
*Intel SDK-85
*IBM 5110

=== 1979 ===

*Acorn System 1 (kit/assembled) — first Acorn computer, UK.
*Tangerine Microtan-65 (kit) — 6502 kit, UK release.
*Compukit UK101 (kit) — UK clone of OSI Superboard II.
*Atari 400 / 800 — home micros, UK launch late 1979.
*Texas Instruments TI-99/4 — imported to UK in 1979.
*Intertec Superbrain — business-oriented CP/M micro, available in UK.
*Compucolor II — colour micro, limited UK availability.
*MZ-80C- Featured an improved keyboard and 48KB of memory.
*Powertran PSI Comp 80 - Wireless World Z80

=== Considerations ===

*VAX
*DEC
*Prime Computers
*Cromemco systems (late 1970s) — S-100 family machines, imported to the UK.
*Zenith assembled systems (via dealers).
*Sord
*Toshiba — available in UK through niche distributors.
*Data General — popular 16-bit minicomputer, sold in UK.
*Honeywell
*Burroughs
*Univac

== Sources ==

* Centre for Computing History (UK)
* Science Museum Group (UK) — Nascom and other UK machines
* Contemporary records: MK14, Acorn System 1, Nascom, Microtan-65, Compukit UK101
* DEC PDP-11 and other minicomputers in UK use
* ICL in UK

Pre-1980 Personal and Home Computers

2025-10-02T15:49:32Z

John: /* 1962 */

==Introduction==

What follows is a list of personal computers available to the public in one form or another to members of the public. The term Personal Computer in this context refers to a general purpose computer that was designed to be used by a single person typically in their home or place of work or study.

=== 1959 ===

==== DEC PDP 1 ====

The company’s first Programmed Data Processor, the PDP-1 computer used DIGITAL’s own system modules, which came from the existing range of 1OMC logic released in late 1959. The first PDP-1, delivered in December 1959, was a high speed, 18.bit, small computer capable of addressing 32K of core memoy. An average configuration cost $120,000 in an era when most computer systems were sold for a million dollars or more. [1]

Standard peripherals included a paper tape reader and punch, and a terminal. Optional peripherals included graphics displays, a light pen, line printer, punched card reader and punch, and magnetic tape controller and drives. [2]

A PDP-1 at MIT's RLE served as the nucleus for early hacker culture at MIT, including for the first video game, Spacewar!. The PDP-1/D at BBN was much used in the early ARPANET work; both for software development, and as the Network Control Center's first machine. [2]

[1] "DEC 1957 to the Present" p.3
[2] https://gunkies.org/wiki/PDP-1

=== 1961 ===

Elliott 803

=== 1962 ===

*Linc - Personal Minicomputer

=== 1967 ===

*Wireless World Computer = Transistor based Computer from Wireless World Magazine (August 1967)

=== 1970 ===

*Datapoint (CTC) 2200 - TTL Computer
*ICL 1900 series — British mainframes, widely deployed.
*Data General Nova — imported 16-bit minicomputer.
*DEC PDP-11/20 — first PDP-11 systems reached UK universities/labs.

=== 1971 ===

*HP 2100A minicomputer — available via HP UK offices.
*Interdata 7/16 — 16-bit minicomputer, sold in UK.
*Kenbak 1 - First Personal Computer ?
*Intel SIM4-01
*Intel SIM4-02

=== 1972 ===

*DEC PDP-11/40 — expanded PDP-11 family in UK use.
*IBM System/3 — midrange systems shipped to UK businesses.
*QI Corporation Q1
*IBM SCAMP (1972/1973)
*Intel SIM8-01

=== 1973 ===

*Wang 2200 — BASIC desktop computer, imported to UK.
*ICL 2900 series — launched as successor to 1900 series.
*R2E MicralN - French computer
*Intel Intellec
*Xerox Alto
*Xerox Star

=== 1974 ===

*Mark-8 (kit, Intel 8008) — hobbyist kit plans; some built in UK by enthusiasts.
*DEC PDP-11/34 — later PDP-11s became standard in UK universities.
*RCA Fred/Cosmac
*Mark 8 - Radio and Electronics
*QI Corporation Q1/Lite
*QI Corporation Q1/MicroLite

=== 1975 ===

*MITS Altair 8800 (kit) — available via import/mail order in UK.
*IMSAI 8080 (kit) — Altair-compatible S-100 system, imported.
*Sphere 1 — limited UK import.
*SWTPC 6800 (kit) — Motorola-based system available through UK distributors.
*IBM 5100

=== 1976 ===

*Processor Technology SOL-20 — first pre-assembled micro, imported to UK.
*MOS Technology KIM-1 (single board) — popular among UK hobbyists.
*Polymorphic Systems Poly-88 — some UK availability via specialist dealers.
*Digital Group machines — imported modular kits.
*Bywood Scrumpy - The first single-board computer kit made in the UK.
*Apple 1
*Cosmac Elf - Magazine/Kit
*Motorola MEK6800D2 - Development board.
*MPT 8080 Microtutor

=== 1977 ===

*Apple II — began UK distribution.
*Commodore PET 2001 — available in UK education/business.
*TRS-80 Model I — sold by Tandy in UK stores.
*Heathkit H8 (kit) — obtainable in UK.
*Science of Cambridge MK14 (kit) — UK-only.
*Nascom-1 (kit) — British single-board kit, launched late 1977.
*System 68 - ETI Magazine

=== 1978 ===

*Nascom-2 (kit) — enhanced British micro.
*Ohio Scientific Superboard II — imported; inspired the UK101.
*Exidy Sorcerer — some units imported to UK.
*Cromemco Z-2 — S-100 business micro, UK dealer support.
*NorthStar Horizon — floppy-based micro, sold in UK.
*Vector Graphic 1 — CP/M micro, available through importers.
*MZ-80K — An all-in-one unit with keyboard.
*Transam Triton - ETI
*Rockwell Aim-65
*Synertek Sym-1
*Intel SDK-85
*IBM 5110

=== 1979 ===

*Acorn System 1 (kit/assembled) — first Acorn computer, UK.
*Tangerine Microtan-65 (kit) — 6502 kit, UK release.
*Compukit UK101 (kit) — UK clone of OSI Superboard II.
*Atari 400 / 800 — home micros, UK launch late 1979.
*Texas Instruments TI-99/4 — imported to UK in 1979.
*Intertec Superbrain — business-oriented CP/M micro, available in UK.
*Compucolor II — colour micro, limited UK availability.
*MZ-80C- Featured an improved keyboard and 48KB of memory.
*Powertran PSI Comp 80 - Wireless World Z80

=== Considerations ===

*VAX
*DEC
*Prime Computers
*Cromemco systems (late 1970s) — S-100 family machines, imported to the UK.
*Zenith assembled systems (via dealers).
*Sord
*Toshiba — available in UK through niche distributors.
*Data General — popular 16-bit minicomputer, sold in UK.
*Honeywell
*Burroughs
*Univac

== Sources ==

* Centre for Computing History (UK)
* Science Museum Group (UK) — Nascom and other UK machines
* Contemporary records: MK14, Acorn System 1, Nascom, Microtan-65, Compukit UK101
* DEC PDP-11 and other minicomputers in UK use
* ICL in UK

Pre-1980 Personal and Home Computers

2025-09-29T22:02:47Z

John: Created page with "==Introduction== What follows is a list of personal computers available to the public in one form or another to members of the public. The term Personal Computer in this context refers to a general purpose computer that was designed to be used by a single person typically in their home or place of work or study. === 1959 === ==== DEC PDP 1 ==== The company’s first Programmed Data Processor, the PDP-1 computer used DIGITAL’s own system modules, which came from the..."

==Introduction==

What follows is a list of personal computers available to the public in one form or another to members of the public. The term Personal Computer in this context refers to a general purpose computer that was designed to be used by a single person typically in their home or place of work or study.

=== 1959 ===

==== DEC PDP 1 ====

The company’s first Programmed Data Processor, the PDP-1 computer used DIGITAL’s own system modules, which came from the existing range of 1OMC logic released in late 1959. The first PDP-1, delivered in December 1959, was a high speed, 18.bit, small computer capable of addressing 32K of core memoy. An average configuration cost $120,000 in an era when most computer systems were sold for a million dollars or more. [1]

Standard peripherals included a paper tape reader and punch, and a terminal. Optional peripherals included graphics displays, a light pen, line printer, punched card reader and punch, and magnetic tape controller and drives. [2]

A PDP-1 at MIT's RLE served as the nucleus for early hacker culture at MIT, including for the first video game, Spacewar!. The PDP-1/D at BBN was much used in the early ARPANET work; both for software development, and as the Network Control Center's first machine. [2]

[1] "DEC 1957 to the Present" p.3
[2] https://gunkies.org/wiki/PDP-1

=== 1962 ===

*Linc - Personal Minicomputer

=== 1967 ===

*Wireless World Computer = Transistor based Computer from Wireless World Magazine (August 1967)

=== 1970 ===

*Datapoint (CTC) 2200 - TTL Computer
*ICL 1900 series — British mainframes, widely deployed.
*Data General Nova — imported 16-bit minicomputer.
*DEC PDP-11/20 — first PDP-11 systems reached UK universities/labs.

=== 1971 ===

*HP 2100A minicomputer — available via HP UK offices.
*Interdata 7/16 — 16-bit minicomputer, sold in UK.
*Kenbak 1 - First Personal Computer ?
*Intel SIM4-01
*Intel SIM4-02

=== 1972 ===

*DEC PDP-11/40 — expanded PDP-11 family in UK use.
*IBM System/3 — midrange systems shipped to UK businesses.
*QI Corporation Q1
*IBM SCAMP (1972/1973)
*Intel SIM8-01

=== 1973 ===

*Wang 2200 — BASIC desktop computer, imported to UK.
*ICL 2900 series — launched as successor to 1900 series.
*R2E MicralN - French computer
*Intel Intellec
*Xerox Alto
*Xerox Star

=== 1974 ===

*Mark-8 (kit, Intel 8008) — hobbyist kit plans; some built in UK by enthusiasts.
*DEC PDP-11/34 — later PDP-11s became standard in UK universities.
*RCA Fred/Cosmac
*Mark 8 - Radio and Electronics
*QI Corporation Q1/Lite
*QI Corporation Q1/MicroLite

=== 1975 ===

*MITS Altair 8800 (kit) — available via import/mail order in UK.
*IMSAI 8080 (kit) — Altair-compatible S-100 system, imported.
*Sphere 1 — limited UK import.
*SWTPC 6800 (kit) — Motorola-based system available through UK distributors.
*IBM 5100

=== 1976 ===

*Processor Technology SOL-20 — first pre-assembled micro, imported to UK.
*MOS Technology KIM-1 (single board) — popular among UK hobbyists.
*Polymorphic Systems Poly-88 — some UK availability via specialist dealers.
*Digital Group machines — imported modular kits.
*Bywood Scrumpy - The first single-board computer kit made in the UK.
*Apple 1
*Cosmac Elf - Magazine/Kit
*Motorola MEK6800D2 - Development board.
*MPT 8080 Microtutor

=== 1977 ===

*Apple II — began UK distribution.
*Commodore PET 2001 — available in UK education/business.
*TRS-80 Model I — sold by Tandy in UK stores.
*Heathkit H8 (kit) — obtainable in UK.
*Science of Cambridge MK14 (kit) — UK-only.
*Nascom-1 (kit) — British single-board kit, launched late 1977.
*System 68 - ETI Magazine

=== 1978 ===

*Nascom-2 (kit) — enhanced British micro.
*Ohio Scientific Superboard II — imported; inspired the UK101.
*Exidy Sorcerer — some units imported to UK.
*Cromemco Z-2 — S-100 business micro, UK dealer support.
*NorthStar Horizon — floppy-based micro, sold in UK.
*Vector Graphic 1 — CP/M micro, available through importers.
*MZ-80K — An all-in-one unit with keyboard.
*Transam Triton - ETI
*Rockwell Aim-65
*Synertek Sym-1
*Intel SDK-85
*IBM 5110

=== 1979 ===

*Acorn System 1 (kit/assembled) — first Acorn computer, UK.
*Tangerine Microtan-65 (kit) — 6502 kit, UK release.
*Compukit UK101 (kit) — UK clone of OSI Superboard II.
*Atari 400 / 800 — home micros, UK launch late 1979.
*Texas Instruments TI-99/4 — imported to UK in 1979.
*Intertec Superbrain — business-oriented CP/M micro, available in UK.
*Compucolor II — colour micro, limited UK availability.
*MZ-80C- Featured an improved keyboard and 48KB of memory.
*Powertran PSI Comp 80 - Wireless World Z80

=== Considerations ===

*VAX
*DEC
*Prime Computers
*Cromemco systems (late 1970s) — S-100 family machines, imported to the UK.
*Zenith assembled systems (via dealers).
*Sord
*Toshiba — available in UK through niche distributors.
*Data General — popular 16-bit minicomputer, sold in UK.
*Honeywell
*Burroughs
*Univac

== Sources ==

* Centre for Computing History (UK)
* Science Museum Group (UK) — Nascom and other UK machines
* Contemporary records: MK14, Acorn System 1, Nascom, Microtan-65, Compukit UK101
* DEC PDP-11 and other minicomputers in UK use
* ICL in UK

Main Page

2025-09-29T22:02:19Z

John: Changed redirect target from Pre-1980 Personal and home Computers to Pre-1980 Personal and Home Computers

#REDIRECT [[Pre-1980 Personal and Home Computers]]

Main Page

2025-09-29T17:39:32Z

John: Changed redirect target from Computers Available to the Public in the UK during the 1970s to Pre-1980 Personal and home Computers

#REDIRECT [[Pre-1980 Personal and home Computers]]

Main Page

2025-09-20T09:59:41Z

John: Changed redirect target from Telstar Viewdata System to Computers Available to the Public in the UK during the 1970s

#REDIRECT [[Computers Available to the Public in the UK during the 1970s]]

Routing

2022-05-19T20:24:25Z

John: /* Default Page Routing */

== Navigation ==

Routing in Telstar is handled by an asynchromous process that allows for routing to occur whilst pages are being rendered. This means that is a user of the system can navigate quickly to a desired page by simply entering the page number one character after another. Each successive key press will start the rendering of a page but as each subsequent key is pressed, the rendering is cancelled and the following page is rendered and so on until the desired page is rendered.

For example simply pressing ''2 2 2'' from the main index page (Page 0a) of the Telstar service will result in the Guardians UK News being displayed. For this to work correctly, all intermediary pages must be present. Creating routes through the system such as the one described above, should be the aim when designing a videotex system.

Users can jump directly to a known page by entering the page number using the format ''*page#'', for example, entering ''*92#'' into the current Telstar system will direct you to page 92.

== Page Numbering ==

Pages are defined by a single integer number between ''0'' and ''999999999''. Each page can have upto 26 frames denoted by the suffix ''a-z''. Therefore a frame denoted by for example ''222b'' would be the second frame of page ''222''. The maximum page number length is 9 digits plus the frame suffix.

== Zero Page Routing ==

In cases where a page needs more than 26 frames such as a large Telesoftware program or where a large number of news articles extends beyond frame ''z'', a process of ''Zero Page Routing'' takes place. For example if a Guradian news article starting on frame ''222z'' needed a continuation frame, the frame ''2220a'' should be used. If articles continued to frame ''2220z'' and needed further continuation frames, frame ''22200a'' should be used and so on to the maximum page number length (see above).

== Default Page Routing ==

When frames are created an optional routing table can be assigned to the frame, (see [[Frames]]) this routing table defines what page is selected when a user enters a digit into their videotex client software.

If a routing table is not defined within the frame, the default routing will be used, for example, pressing ''6'' whilst on page ''222'' will try and navigate to page ''2226'', if this page does not exist, this will return a ''Page Not Found'' message, similarly pressing ''7'' will try and navigate to ''2227'' and so on. In most cases the default routing will work well, however, when that isn't the case, the table can be created or updated manually as required.

For example, the default routing table for page 222 would effectively be:

[2220, 2221, 2222, 2223, 2224, 2225, 2226, 2227, 2228, 2229, 222]

Each entry represents a key press for example if the user presses a ''0'' then element zero is used and the user is routed to page 2220, entering a ''1'' would route the user to page 2221 etc. The last element, element 10, represents the routing when the *#* (Return Key) is entered.

In most cases the default routing will work quite well, however, when that isn't the case, the table can be created or updated manually as required. Note that when a # is entered, the priority is that a follow on frame will always be selected if one exists.

For example lets assume you have only 2 menu items, 1 and 2, and you want these to go to pages 1001 and 1002 instead of 2221 and 2222. The manually created routing table should look like this...

[1001, 1002, 2222, 2223, 2224, 2225, 2226, 2227, 2228, 2229, 222]

If a use presses 3 the system will try and navigate to page 2223 which presumably will not exist (otherwise there would be a menu item for it) and return ''Page Not Found'' which is the correct behaviour. In other words simply define the standard routing table with any changes that are required.

== Redirection ==

There exists a special frame type that will allow a frame to redirect to another frame, for example the following frame redirects from page ''0a'' to ''9a'.

{
"pid": {
"page-no": 0,
"frame-id": "a"
},
"redirect": {
"page-no": 9,
"frame-id": "a"
},
"visible": true
}

See [[Frames]] for more information on frame redirects.

Frames

2022-05-17T14:51:04Z

John: /* Adding Frames to the System */

As is typical with interactive videotex systems, pages are numbered from 0 to 999999999 and consist of one or more frames with the suffix a-z, for example the first frame for page 200 would be 200a, the second 200b and so on (see [[Routing]]) for more details). These frames are stored within TELSTAR's database as ''JSON'' objects (see https://www.json.org/) and uploaded to Telstar using a simple command line utility.

The Telstar utility program simply interacts with the Telstar API which is a restful API. This can be used directly by any software making it simple to programitically manage pages and routing information.

Frames are defined in JSON. The simplest frame that can be viewed on TELSTAR would be as follows. This would create a simple information frame with some flashing content. In this example [[Markup]] has been used within the content, however, other content types can be used including edi.tf urls, see below.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"content": {
"data": "[D]This is page[F]101a",
"type": "markup"
}
}

Shown below is a more complete example of a JSON defined frame. With this particular frame, the actual viewdata content has been created using the editor at http://edit.tf, this can be seen in the ''content.data'' and ''content.type'' keys. Both the edit.tf and zxnet (https://zxnet.co.uk/teletext/editor/) editors are supported. The example below is a simple information page with some simple routing (see [[Routing]]). Clicking the ''content.data'' link, or pasteing the value into a browser will show the page and allow it to be edited. It is not necessary to use the http://edit.tf editor, this is just one possible option.

{
"pid": {
"page-no": 0,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"content": {
"data": "http://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMMKAbNw6dyCTuyZfCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgKJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRAxQR4s6LSgzEEmdUi0otOogkzo0-lNg1JM-cCg8unNYgQIASBBj67OnXllWIMu7pl5dMOndty7uixBoy4dnTQsQIECBAgBIEHfLh2dNCDDuyINmnNl59POzKuQIECBAgQIECBAgQIECBAyQTotemggzoiCvFg1JEWkCnYemnfuw7EGHdkQIECBAgQIASBBp3dMvLdh6ad-7DsQbsvfmgw7siDvlw9NGXkuQIECBAgQM0EKrTkzotOmgkzo0-lNg1JM-cCh79vDDu8oMO7IgQIECAEgQYuvPTuy8-aDdl781wM6EjVKcVBMw9MvPogoctOPLzQIEDRBHn1otKdNizqiCTOjT6U2DUkz5wKlvw5OaxByw6dixAgBIEGHdkQUMPLZpw7cu7ouQIECBAgQIECBAgQIECBAgQIECBA2QR4NSLXg2UFOLSrSYcWmCnWKkWYsQVIsWNBsLEEOHMaIASBBh3ZEHTRlQQ9-zfz54diCHh7ZUGHJ2y7unXllXIECBAgQN0EifMkxINmmCqcsPbLsQYd2RBI37NOTD5QbsvfmuQIECBA4CHQc2TDpT50WogcMGCAScgoOnLTi69MqDpvQdNGnmgQIAaBBzy8u2nHlQd9PTQgqZdmXnvzdO-HllQYd2RBt38sq5AgQOQ0yfHQT40ZYgp2adSLNQSZ0aegTIKkWnUQUIMeLTQIECAokSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEFeLBqSItJBGn0osODTqIBIM6EQIEFDDnyoFTJywvoECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf"
},
"routing-table": [0,1,11,3,400,5,6,7,800,9,0],
"cursor": false,
}

== Adding Frames to the System ==

Frames can be added to the system using the [[the Telstar API]].

The Telstar API, in conjunction with the cross platform Telstar Util software, provides a simple method of creating and managing pages.

The API can be used to retrieve and update frames and configuring routing. The API is a restful API that uses the GET, PUT, POST and DELETE HTTP methods and as such can be used from any application.

Data is passed to and from the API in JSON format, making the system very simple to use in any programming language. The whole API could be used without any programming at all by using a command line utility such as CURL.

''Further details of the Telstar API can be found in the section [[The Telstar API]].''

== Adding Content with the Edit.tf editor ==

There are several ways to add content to a page. One of the easiest is to create the page in an editor such as http://edit.tf.

The JSON file would look something like the one showm below. Note that the content type is set to editf and the content data contains the edit.tf url.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"content": {
"data": "http://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICn_OmTJkSJApUqVKlSpUlcHApiTJkyZEiRIkyZMmTIkSJFmKf3JX58____RBg-fPnzog__2iBBo-fNX9qgQcOHDh8-fGiAp_zFf______2v7_____7X___oEGr__Qa0ur_________QoCn9ywK__6D__a__7dH__tf___1QIv_9AiQIkaPX_bo0aMpiKf_-Yr__oP_9r__tUH_-1____9og__yjnz5cldX9qUc-fPkp__uSv_-g__2v_-1Qf_7X__aIv____KZv_dIV__2pTN___yn__mK___z__a____5__tf_9qgVf__8o5_vWJX__alHP___Kf_7kr____6dBr_____-h__2qBBr__ymbPnSFf69CUzf__8pnz5iq9ejRoECBWvXr0KBGjQYOHBHz4cECBAgwcCily7__yqDhw4ePnzogQeP7RAg0fPiBB___9X___QYPH___-sCmb__KoP________3B__tUCDV__tUH___1f36XB-_______KOf_8qgRo__9B__v9X___QINX___Qav__B8-NNX_-jR___8pm__ymYrq______h_odX9qg1f___7q__9X_-h1f_5TBgwYM37__KOSur-_Ro0Pr_8_f_qDV_b___r__1f_6D___lFKlSpUu__8pmK_v7VAgwf______tNX9r______V__oP__-gQaPnwpm__yqDB__tUCD__QIEG___1f2qL____9X_-g____z5-__ymb__KoNX_-lQKl6VAgQav6_V__oNf___1f2qBX_____9-hKOf_8qgVJ0JRw4cOPLkqiQoESNGgVL0aFEjQoECJGjRoymDNm__ymTJkzZv3_____-3bt27du3Thw8efPnz58-fPnz58-fP___QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf"
}
}

== Adding Content using Markup ==

Content can be added directly to the JSON file using a very simple markup. For example consider the following frame definition.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"title": {
"data": "[D]Welcome\r\n\r\n",
"type": "markup"
},
"content": {
"data": "[Y]Hello[C]Telstar[M]World",
"type": "markup"
}
}

This frame uses markup in the title and the content, The title is specified as [D]ouble height and the three words used in the content are coloured yellow, cyan and magenta respectively.

Full details of markup can be found in the [[Markup]] section.

== Complete Frame Description ==

The frame below is a standard information page from the TELSTAR system shown in its JSON format. It represents the first frame of page 9. Taking this frame as an example, a description of the fields and their meaning is decribed below.

''The full json schema can be found [[Frame Schema|here]].''

{
"pid": {
"page-no": 9,
"frame-id": "a"
},
"visible": true,
"header-text": "",
"cost": 0,
"frame-type": "information",
"redirect": {
"page-no": 0,
"frame-id": ""
},
"content": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgc4UCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAxQIIs6PJnRYtKTOjoKkWnUQUIMeLTQIECBAgQIECBAgQIEDRAgp2adSLNQSZ0aegQIECBAgQIECBAgQIECBAgQIECBAgQNkCCPBqRa8GygpxaVaTDi00CBAgQIECBAgQIECBAgQIECBA4QIIc-dUgw6iCJFqQZMymgQIECBAgQIECBAgQIECBAgQIEDlAgmT46CfOQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMECCZPjoJ8aMgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgBVAMUNMQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIAVQDFDTAlMPUQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUAxQ0wJTD1A0EHSQIECBAgQIECBAgQIECBAgQIECBAgQIECANMCUw9QNBB0kCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAPUDQQdJAgQIECBAgQIECBAgQIECAosWLFixYsWLFixYsQIECAHSQIECAosWLFixYsWLFixYsWIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf'
},
"title": {
"data": "",
"type": "",
"merge-data": []
},
"routing-table": [
90,
91,
92,
93,
94,
95,
96,
97,
98,
990,
0
],
"cursor": false,
"connection": {
"address": "",
"mode": "",
"port": 0
},
"author-id": "",
"response-data": {
"responses": null,
"response-action": {
"exec": "",
"args": null,
"post-action-frame": {
"page-no": 0,
"frame-id": ''
},
"post-cancel-frame": {
"page-no": 0,
"frame-id": ""
}
}
},
"navmessage-select": "[B][n][Y]Select item or[W]*page# : [_+]",
"navmessage-notfound": "[B][n][Y]Page not Found :[W]"
}

=== pid ===

Specifies the page number and frame id for the frame.

"pid": {
"page-no": 9,
"frame-id": "a"
},

=== visible ===

When set to false, the frame will not be accessible and will return the ''not found'' system message to the user if an attempt is made to access it.

"visible": true,

=== header-text ===

Allows the default header text to be ovwerridden at frame level. If this is left blank the default header will be used, see configuration.

"header-text": "[Y]MICRONETn 800 (C)",

=== cost ===

"cost": 0,

=== frame-type ===

The API supports the following frame types ''initial'', ''mainindex'', ''information'', ''exit'', ''gateway'', ''test'' and ''response''.

"frame-type": "information",

* '''initial''': This frame type is used on the start page, see [[Configuration Options]]. Typically only one of these frames would exist within a system.
* '''mainindex''': This frame type is used on the main index page. , see [[Configuration Options]]. Only one of these frames should exist within a system.
* '''information''': This frame type is used for all normal content frames.
* '''exit''': This frame type is used for an exit page, any number of exit pages can be defined. When an exit page is rendered it will close the connection.
* '''gateway''': This page type is used to define a gateway page and is used in conjunction with the connection element (see below).
* '''test''': This page type indicates a test page and prevents navigation and system messages from being shown. this is typically used for frames that need to use the whole display such as 'test cards' etc.
* '''telesoftware''': Telesoftware frames (see [[Telesoftware]]).
* '''response''': This frame type is used for response frames. See [[Implementing Response Frames]].
* '''system''': Reserved for use internally.
* '''exception''': Reserved for use internally.

=== redirect ===

If set it simply means that the user is redirected to the specified frame. This can be a useful alternative form of navigation to the routing table.

"redirect": {
"page-no": 9,
"frame-id": "a"
},

The following is an example of a complete redirect page.

{
"PID": {
"page-no": 2,
"frame-id": "a"
},
"redirect": {
"page-no": 11,
"frame-id": "a"
},
"visible": true
}

=== content ===

These elements define the content. The example below shows the content.type to be an edit.tf url. The available types are shown below.

"content": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgc4UCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAxQIIs6PJnRYtKTOjoKkWnUQUIMeLTQIECBAgQIECBAgQIEDRAgp2adSLNQSZ0aegQIECBAgQIECBAgQIECBAgQIECBAgQNkCCPBqRa8GygpxaVaTDi00CBAgQIECBAgQIECBAgQIECBA4QIIc-dUgw6iCJFqQZMymgQIECBAgQIECBAgQIECBAgQIEDlAgmT46CfOQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMECCZPjoJ8aMgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgBVAMUNMQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIAVQDFDTAlMPUQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUAxQ0wJTD1A0EHSQIECBAgQIECBAgQIECBAgQIECBAgQIECANMCUw9QNBB0kCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAPUDQQdJAgQIECBAgQIECBAgQIECAosWLFixYsWLFixYsQIECAHSQIECAosWLFixYsWLFixYsWIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf'
},

Content types:

* '''zxnet''': If set, then the content will be treated as an zxnet editor url. This is converted to RawV before being rendered.
* '''edit.tf''': If set, then the content will be treated as an edit.tf url. This is converted to RawV before being rendered.
* '''markup''': If set, then the content will be treated as ''markup'' content. Full details of ''markup'' can be found in the section [[Markup]]
* '''rawV''': If set, then the content will be treated as raw videotex data. This is 7bit (00-7F) videotex format with control chars between 00-1F and escaped codes for alpha and graphic attributes. Ideally rows should have any trailing spaces removed and replaced with with a CR/LF combination. This will be rendered as is.
* '''rawT''': If set, then the content will be treated as raw teletex data. This is a 24 x 40 block of 7 bits chars (960 chars) in Teletext format (range 00-7F). This format is used internally when manipulating page data. It will be converted to RawV before being rendered.

=== title ===

This sets the title of the page. In many cases this may be left blank with all of the content specified in the ''content'' section (see above) however, the ''title'' section gives additional flexibility when creating frames.

Values for ''title-type'' are the same as defined for the content section, however, if the type ''edit-tf'' is used then only the first four (default) lines of the edit.tf defined page are used.

Separating title from content in this way allows logos and header sections to be created for the title whilst using markup for the main content or visa-versa.

==== Example 1 ====

In thi example the fields are blank meaning that only the data in the ''content'' section is displayed.

"title": {
"data": "",
"type": "",
"merge-data": []
},

==== Example 2 ====

In this example, the top 4 lines of the edit.tf content is displayed at the top of the page.

"title": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAvobotqBX__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIC_9AgQIEGv-gQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgL_0Cj4kQav6BAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAuq64P6Dx__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf",
"merge-data": []
},

To take the top 5 lines, the ''type'' field can be extended as follows.

"type": "edit.tf,5"

Note that this extended form of ''type'' only applies to edit.tf types.

==== Example 3 ====

The merge data field can be used to add ''layers'' of markup data to the title area. For example the example above shows the Guardian logo. To add some alphagraphics text to this, an additional layer could be used e.g.

"title": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAvobotqBX__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIC_9AgQIEGv-gQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgL_0Cj4kQav6BAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAuq64P6Dx__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf,5",
"merge-data": [
"[w[ UK News]]"
]
},

Note that any number of layers can be added, however, the merge layer must be defined as markup.

=== routing table ===

The routing table defines which pages are navigated to when a user presses a key whilst viewing the frame. The table has 11 entries with the first 10 representing the keys 0-9, the final entry refers to the ''hash'' (return) key.

The example below shows the default routing table for frame 9a. If the user is viewing this frame and presses 1 the frame 91a will be loaded, assuming it exists. Pressing the ''hash'' (return) key will take the user back to frame 0a, the main index.

"routing-table": [
90,
91,
92,
93,
94,
95,
96,
97,
98,
99,
0
],

=== cursor ===

This element determines whether a cursor is shown on the page. Typically a cursor would only be shown on response frames.

"cursor": false,

=== connection ===

This elements specifies the connection object used for gateway pages.

"connection": {
"address": "fish.ccl4.org",
"mode": "viewdata",
"port": 23
},

The values for ''address and port'' represent the endpoint of the system being accessed and the value for ''mode'' determines how the system is accessed, the options are:

viewdata
full_duplex
full_duplex_no_echo

=== author-id ===

This is an optional field that can be used to indicate the author of the page or other source.

"author-id": "john",

=== response-data ===

These fields should be used when the frame type is set to be a ''response-frame''.

There are two main sections, ''response-data'' and ''response-action''. Below is an example of a response frame used for the Telstar weather page. The frame is created in the normal way using ''markup'' or ''edit.tf''. In this example the text ''Town/Cty'' has been positioned near the centre of the page. Immediately to the right of this is a field for the user to enter either a Town or City, the ''response-data'' section defines that field. Once the user submits the frame the section ''response-action'' determines what happens. In the example here a binary file (''telstar-openweather-linux-amd64''), stored in the containers volume directory is executed with a single argument (''myopenweatherapikey''). Note that the ''post-action-frame'' is set to 290b, in this example frame 290b is dynamically generated by the binary file ''telstar-openweather-linux-amd64'' and contains the weather forecast.

Full details of how to implement response frames are detailed in the section [[Implementing Response Frames]].
"response-data": {
"response-fields": [
{
"vpos": 8,
"hpos": 4,
"required": true,
"length": 16,
"type": "alphanumeric",
"auto-submit": false,
"password": false
}
],
"response-action": {
"exec": "/opt/telstar/volume/telstar-openweather-linux-amd64",
"args": [
"myopenweatherapikey"
],
"post-action-frame": {
"page-no": 290,
"frame-id": "c"
}
}
},

=== navmessage-select ===

Allows the ''navigation'' system message to be customised at frame level. In most cases this can be left blank in order that the system default is used instead, see [[Configuration Options]].

"navmessage-select": "[B][n][Y]Select item or[W]*page# : [_+]",

=== navmessage-notfound ===

Allows the ''not found'' system message to be customised at frame level. In most cases this can be left blank in order that the system default is used instead, see [[Configuration Options]].

"navmessage-notfound": "[B][n][Y]Page not Found :[W]"

Frames

2022-05-17T14:49:37Z

John: /* Adding Frames to the System */

As is typical with interactive videotex systems, pages are numbered from 0 to 999999999 and consist of one or more frames with the suffix a-z, for example the first frame for page 200 would be 200a, the second 200b and so on (see [[Routing]]) for more details). These frames are stored within TELSTAR's database as ''JSON'' objects (see https://www.json.org/) and uploaded to Telstar using a simple command line utility.

The Telstar utility program simply interacts with the Telstar API which is a restful API. This can be used directly by any software making it simple to programitically manage pages and routing information.

Frames are defined in JSON. The simplest frame that can be viewed on TELSTAR would be as follows. This would create a simple information frame with some flashing content. In this example [[Markup]] has been used within the content, however, other content types can be used including edi.tf urls, see below.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"content": {
"data": "[D]This is page[F]101a",
"type": "markup"
}
}

Shown below is a more complete example of a JSON defined frame. With this particular frame, the actual viewdata content has been created using the editor at http://edit.tf, this can be seen in the ''content.data'' and ''content.type'' keys. Both the edit.tf and zxnet (https://zxnet.co.uk/teletext/editor/) editors are supported. The example below is a simple information page with some simple routing (see [[Routing]]). Clicking the ''content.data'' link, or pasteing the value into a browser will show the page and allow it to be edited. It is not necessary to use the http://edit.tf editor, this is just one possible option.

{
"pid": {
"page-no": 0,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"content": {
"data": "http://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMMKAbNw6dyCTuyZfCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgKJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRAxQR4s6LSgzEEmdUi0otOogkzo0-lNg1JM-cCg8unNYgQIASBBj67OnXllWIMu7pl5dMOndty7uixBoy4dnTQsQIECBAgBIEHfLh2dNCDDuyINmnNl59POzKuQIECBAgQIECBAgQIECBAyQTotemggzoiCvFg1JEWkCnYemnfuw7EGHdkQIECBAgQIASBBp3dMvLdh6ad-7DsQbsvfmgw7siDvlw9NGXkuQIECBAgQM0EKrTkzotOmgkzo0-lNg1JM-cCh79vDDu8oMO7IgQIECAEgQYuvPTuy8-aDdl781wM6EjVKcVBMw9MvPogoctOPLzQIEDRBHn1otKdNizqiCTOjT6U2DUkz5wKlvw5OaxByw6dixAgBIEGHdkQUMPLZpw7cu7ouQIECBAgQIECBAgQIECBAgQIECBA2QR4NSLXg2UFOLSrSYcWmCnWKkWYsQVIsWNBsLEEOHMaIASBBh3ZEHTRlQQ9-zfz54diCHh7ZUGHJ2y7unXllXIECBAgQN0EifMkxINmmCqcsPbLsQYd2RBI37NOTD5QbsvfmuQIECBA4CHQc2TDpT50WogcMGCAScgoOnLTi69MqDpvQdNGnmgQIAaBBzy8u2nHlQd9PTQgqZdmXnvzdO-HllQYd2RBt38sq5AgQOQ0yfHQT40ZYgp2adSLNQSZ0aegTIKkWnUQUIMeLTQIECAokSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEFeLBqSItJBGn0osODTqIBIM6EQIEFDDnyoFTJywvoECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf"
},
"routing-table": [0,1,11,3,400,5,6,7,800,9,0],
"cursor": false,
}

== Adding Frames to the System ==

Frames can be added to the system using the Telstar API.

The Telstar API, in conjunction with the cross platform Telstar Util software, provides a simple method of creating and managing pages.

The API can be used to retrieve and update frames and configuring routing. The API is a restful API that uses the GET, PUT, POST and DELETE HTTP methods and as such can be used from any application.

Data is passed to and from the API in JSON format, making the system very simple to use in any programming language. The whole API could be used without any programming at all by using a command line utility such as CURL.

''Further details of the Telstar API can be found in the section [[The Telstar API]].''

== Adding Content with the Edit.tf editor ==

There are several ways to add content to a page. One of the easiest is to create the page in an editor such as http://edit.tf.

The JSON file would look something like the one showm below. Note that the content type is set to editf and the content data contains the edit.tf url.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"content": {
"data": "http://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICn_OmTJkSJApUqVKlSpUlcHApiTJkyZEiRIkyZMmTIkSJFmKf3JX58____RBg-fPnzog__2iBBo-fNX9qgQcOHDh8-fGiAp_zFf______2v7_____7X___oEGr__Qa0ur_________QoCn9ywK__6D__a__7dH__tf___1QIv_9AiQIkaPX_bo0aMpiKf_-Yr__oP_9r__tUH_-1____9og__yjnz5cldX9qUc-fPkp__uSv_-g__2v_-1Qf_7X__aIv____KZv_dIV__2pTN___yn__mK___z__a____5__tf_9qgVf__8o5_vWJX__alHP___Kf_7kr____6dBr_____-h__2qBBr__ymbPnSFf69CUzf__8pnz5iq9ejRoECBWvXr0KBGjQYOHBHz4cECBAgwcCily7__yqDhw4ePnzogQeP7RAg0fPiBB___9X___QYPH___-sCmb__KoP________3B__tUCDV__tUH___1f36XB-_______KOf_8qgRo__9B__v9X___QINX___Qav__B8-NNX_-jR___8pm__ymYrq______h_odX9qg1f___7q__9X_-h1f_5TBgwYM37__KOSur-_Ro0Pr_8_f_qDV_b___r__1f_6D___lFKlSpUu__8pmK_v7VAgwf______tNX9r______V__oP__-gQaPnwpm__yqDB__tUCD__QIEG___1f2qL____9X_-g____z5-__ymb__KoNX_-lQKl6VAgQav6_V__oNf___1f2qBX_____9-hKOf_8qgVJ0JRw4cOPLkqiQoESNGgVL0aFEjQoECJGjRoymDNm__ymTJkzZv3_____-3bt27du3Thw8efPnz58-fPnz58-fP___QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf"
}
}

== Adding Content using Markup ==

Content can be added directly to the JSON file using a very simple markup. For example consider the following frame definition.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"title": {
"data": "[D]Welcome\r\n\r\n",
"type": "markup"
},
"content": {
"data": "[Y]Hello[C]Telstar[M]World",
"type": "markup"
}
}

This frame uses markup in the title and the content, The title is specified as [D]ouble height and the three words used in the content are coloured yellow, cyan and magenta respectively.

Full details of markup can be found in the [[Markup]] section.

== Complete Frame Description ==

The frame below is a standard information page from the TELSTAR system shown in its JSON format. It represents the first frame of page 9. Taking this frame as an example, a description of the fields and their meaning is decribed below.

''The full json schema can be found [[Frame Schema|here]].''

{
"pid": {
"page-no": 9,
"frame-id": "a"
},
"visible": true,
"header-text": "",
"cost": 0,
"frame-type": "information",
"redirect": {
"page-no": 0,
"frame-id": ""
},
"content": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgc4UCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAxQIIs6PJnRYtKTOjoKkWnUQUIMeLTQIECBAgQIECBAgQIEDRAgp2adSLNQSZ0aegQIECBAgQIECBAgQIECBAgQIECBAgQNkCCPBqRa8GygpxaVaTDi00CBAgQIECBAgQIECBAgQIECBA4QIIc-dUgw6iCJFqQZMymgQIECBAgQIECBAgQIECBAgQIEDlAgmT46CfOQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMECCZPjoJ8aMgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgBVAMUNMQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIAVQDFDTAlMPUQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUAxQ0wJTD1A0EHSQIECBAgQIECBAgQIECBAgQIECBAgQIECANMCUw9QNBB0kCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAPUDQQdJAgQIECBAgQIECBAgQIECAosWLFixYsWLFixYsQIECAHSQIECAosWLFixYsWLFixYsWIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf'
},
"title": {
"data": "",
"type": "",
"merge-data": []
},
"routing-table": [
90,
91,
92,
93,
94,
95,
96,
97,
98,
990,
0
],
"cursor": false,
"connection": {
"address": "",
"mode": "",
"port": 0
},
"author-id": "",
"response-data": {
"responses": null,
"response-action": {
"exec": "",
"args": null,
"post-action-frame": {
"page-no": 0,
"frame-id": ''
},
"post-cancel-frame": {
"page-no": 0,
"frame-id": ""
}
}
},
"navmessage-select": "[B][n][Y]Select item or[W]*page# : [_+]",
"navmessage-notfound": "[B][n][Y]Page not Found :[W]"
}

=== pid ===

Specifies the page number and frame id for the frame.

"pid": {
"page-no": 9,
"frame-id": "a"
},

=== visible ===

When set to false, the frame will not be accessible and will return the ''not found'' system message to the user if an attempt is made to access it.

"visible": true,

=== header-text ===

Allows the default header text to be ovwerridden at frame level. If this is left blank the default header will be used, see configuration.

"header-text": "[Y]MICRONETn 800 (C)",

=== cost ===

"cost": 0,

=== frame-type ===

The API supports the following frame types ''initial'', ''mainindex'', ''information'', ''exit'', ''gateway'', ''test'' and ''response''.

"frame-type": "information",

* '''initial''': This frame type is used on the start page, see [[Configuration Options]]. Typically only one of these frames would exist within a system.
* '''mainindex''': This frame type is used on the main index page. , see [[Configuration Options]]. Only one of these frames should exist within a system.
* '''information''': This frame type is used for all normal content frames.
* '''exit''': This frame type is used for an exit page, any number of exit pages can be defined. When an exit page is rendered it will close the connection.
* '''gateway''': This page type is used to define a gateway page and is used in conjunction with the connection element (see below).
* '''test''': This page type indicates a test page and prevents navigation and system messages from being shown. this is typically used for frames that need to use the whole display such as 'test cards' etc.
* '''telesoftware''': Telesoftware frames (see [[Telesoftware]]).
* '''response''': This frame type is used for response frames. See [[Implementing Response Frames]].
* '''system''': Reserved for use internally.
* '''exception''': Reserved for use internally.

=== redirect ===

If set it simply means that the user is redirected to the specified frame. This can be a useful alternative form of navigation to the routing table.

"redirect": {
"page-no": 9,
"frame-id": "a"
},

The following is an example of a complete redirect page.

{
"PID": {
"page-no": 2,
"frame-id": "a"
},
"redirect": {
"page-no": 11,
"frame-id": "a"
},
"visible": true
}

=== content ===

These elements define the content. The example below shows the content.type to be an edit.tf url. The available types are shown below.

"content": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgc4UCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAxQIIs6PJnRYtKTOjoKkWnUQUIMeLTQIECBAgQIECBAgQIEDRAgp2adSLNQSZ0aegQIECBAgQIECBAgQIECBAgQIECBAgQNkCCPBqRa8GygpxaVaTDi00CBAgQIECBAgQIECBAgQIECBA4QIIc-dUgw6iCJFqQZMymgQIECBAgQIECBAgQIECBAgQIEDlAgmT46CfOQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMECCZPjoJ8aMgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgBVAMUNMQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIAVQDFDTAlMPUQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUAxQ0wJTD1A0EHSQIECBAgQIECBAgQIECBAgQIECBAgQIECANMCUw9QNBB0kCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAPUDQQdJAgQIECBAgQIECBAgQIECAosWLFixYsWLFixYsQIECAHSQIECAosWLFixYsWLFixYsWIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf'
},

Content types:

* '''zxnet''': If set, then the content will be treated as an zxnet editor url. This is converted to RawV before being rendered.
* '''edit.tf''': If set, then the content will be treated as an edit.tf url. This is converted to RawV before being rendered.
* '''markup''': If set, then the content will be treated as ''markup'' content. Full details of ''markup'' can be found in the section [[Markup]]
* '''rawV''': If set, then the content will be treated as raw videotex data. This is 7bit (00-7F) videotex format with control chars between 00-1F and escaped codes for alpha and graphic attributes. Ideally rows should have any trailing spaces removed and replaced with with a CR/LF combination. This will be rendered as is.
* '''rawT''': If set, then the content will be treated as raw teletex data. This is a 24 x 40 block of 7 bits chars (960 chars) in Teletext format (range 00-7F). This format is used internally when manipulating page data. It will be converted to RawV before being rendered.

=== title ===

This sets the title of the page. In many cases this may be left blank with all of the content specified in the ''content'' section (see above) however, the ''title'' section gives additional flexibility when creating frames.

Values for ''title-type'' are the same as defined for the content section, however, if the type ''edit-tf'' is used then only the first four (default) lines of the edit.tf defined page are used.

Separating title from content in this way allows logos and header sections to be created for the title whilst using markup for the main content or visa-versa.

==== Example 1 ====

In thi example the fields are blank meaning that only the data in the ''content'' section is displayed.

"title": {
"data": "",
"type": "",
"merge-data": []
},

==== Example 2 ====

In this example, the top 4 lines of the edit.tf content is displayed at the top of the page.

"title": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAvobotqBX__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIC_9AgQIEGv-gQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgL_0Cj4kQav6BAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAuq64P6Dx__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf",
"merge-data": []
},

To take the top 5 lines, the ''type'' field can be extended as follows.

"type": "edit.tf,5"

Note that this extended form of ''type'' only applies to edit.tf types.

==== Example 3 ====

The merge data field can be used to add ''layers'' of markup data to the title area. For example the example above shows the Guardian logo. To add some alphagraphics text to this, an additional layer could be used e.g.

"title": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAvobotqBX__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIC_9AgQIEGv-gQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgL_0Cj4kQav6BAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAuq64P6Dx__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf,5",
"merge-data": [
"[w[ UK News]]"
]
},

Note that any number of layers can be added, however, the merge layer must be defined as markup.

=== routing table ===

The routing table defines which pages are navigated to when a user presses a key whilst viewing the frame. The table has 11 entries with the first 10 representing the keys 0-9, the final entry refers to the ''hash'' (return) key.

The example below shows the default routing table for frame 9a. If the user is viewing this frame and presses 1 the frame 91a will be loaded, assuming it exists. Pressing the ''hash'' (return) key will take the user back to frame 0a, the main index.

"routing-table": [
90,
91,
92,
93,
94,
95,
96,
97,
98,
99,
0
],

=== cursor ===

This element determines whether a cursor is shown on the page. Typically a cursor would only be shown on response frames.

"cursor": false,

=== connection ===

This elements specifies the connection object used for gateway pages.

"connection": {
"address": "fish.ccl4.org",
"mode": "viewdata",
"port": 23
},

The values for ''address and port'' represent the endpoint of the system being accessed and the value for ''mode'' determines how the system is accessed, the options are:

viewdata
full_duplex
full_duplex_no_echo

=== author-id ===

This is an optional field that can be used to indicate the author of the page or other source.

"author-id": "john",

=== response-data ===

These fields should be used when the frame type is set to be a ''response-frame''.

There are two main sections, ''response-data'' and ''response-action''. Below is an example of a response frame used for the Telstar weather page. The frame is created in the normal way using ''markup'' or ''edit.tf''. In this example the text ''Town/Cty'' has been positioned near the centre of the page. Immediately to the right of this is a field for the user to enter either a Town or City, the ''response-data'' section defines that field. Once the user submits the frame the section ''response-action'' determines what happens. In the example here a binary file (''telstar-openweather-linux-amd64''), stored in the containers volume directory is executed with a single argument (''myopenweatherapikey''). Note that the ''post-action-frame'' is set to 290b, in this example frame 290b is dynamically generated by the binary file ''telstar-openweather-linux-amd64'' and contains the weather forecast.

Full details of how to implement response frames are detailed in the section [[Implementing Response Frames]].
"response-data": {
"response-fields": [
{
"vpos": 8,
"hpos": 4,
"required": true,
"length": 16,
"type": "alphanumeric",
"auto-submit": false,
"password": false
}
],
"response-action": {
"exec": "/opt/telstar/volume/telstar-openweather-linux-amd64",
"args": [
"myopenweatherapikey"
],
"post-action-frame": {
"page-no": 290,
"frame-id": "c"
}
}
},

=== navmessage-select ===

Allows the ''navigation'' system message to be customised at frame level. In most cases this can be left blank in order that the system default is used instead, see [[Configuration Options]].

"navmessage-select": "[B][n][Y]Select item or[W]*page# : [_+]",

=== navmessage-notfound ===

Allows the ''not found'' system message to be customised at frame level. In most cases this can be left blank in order that the system default is used instead, see [[Configuration Options]].

"navmessage-notfound": "[B][n][Y]Page not Found :[W]"

Frames

2022-05-16T20:32:57Z

John: /* content */

As is typical with interactive videotex systems, pages are numbered from 0 to 999999999 and consist of one or more frames with the suffix a-z, for example the first frame for page 200 would be 200a, the second 200b and so on (see [[Routing]]) for more details). These frames are stored within TELSTAR's database as ''JSON'' objects (see https://www.json.org/) and uploaded to Telstar using a simple command line utility.

The Telstar utility program simply interacts with the Telstar API which is a restful API. This can be used directly by any software making it simple to programitically manage pages and routing information.

Frames are defined in JSON. The simplest frame that can be viewed on TELSTAR would be as follows. This would create a simple information frame with some flashing content. In this example [[Markup]] has been used within the content, however, other content types can be used including edi.tf urls, see below.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"content": {
"data": "[D]This is page[F]101a",
"type": "markup"
}
}

Shown below is a more complete example of a JSON defined frame. With this particular frame, the actual viewdata content has been created using the editor at http://edit.tf, this can be seen in the ''content.data'' and ''content.type'' keys. Both the edit.tf and zxnet (https://zxnet.co.uk/teletext/editor/) editors are supported. The example below is a simple information page with some simple routing (see [[Routing]]). Clicking the ''content.data'' link, or pasteing the value into a browser will show the page and allow it to be edited. It is not necessary to use the http://edit.tf editor, this is just one possible option.

{
"pid": {
"page-no": 0,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"content": {
"data": "http://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMMKAbNw6dyCTuyZfCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgKJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRAxQR4s6LSgzEEmdUi0otOogkzo0-lNg1JM-cCg8unNYgQIASBBj67OnXllWIMu7pl5dMOndty7uixBoy4dnTQsQIECBAgBIEHfLh2dNCDDuyINmnNl59POzKuQIECBAgQIECBAgQIECBAyQTotemggzoiCvFg1JEWkCnYemnfuw7EGHdkQIECBAgQIASBBp3dMvLdh6ad-7DsQbsvfmgw7siDvlw9NGXkuQIECBAgQM0EKrTkzotOmgkzo0-lNg1JM-cCh79vDDu8oMO7IgQIECAEgQYuvPTuy8-aDdl781wM6EjVKcVBMw9MvPogoctOPLzQIEDRBHn1otKdNizqiCTOjT6U2DUkz5wKlvw5OaxByw6dixAgBIEGHdkQUMPLZpw7cu7ouQIECBAgQIECBAgQIECBAgQIECBA2QR4NSLXg2UFOLSrSYcWmCnWKkWYsQVIsWNBsLEEOHMaIASBBh3ZEHTRlQQ9-zfz54diCHh7ZUGHJ2y7unXllXIECBAgQN0EifMkxINmmCqcsPbLsQYd2RBI37NOTD5QbsvfmuQIECBA4CHQc2TDpT50WogcMGCAScgoOnLTi69MqDpvQdNGnmgQIAaBBzy8u2nHlQd9PTQgqZdmXnvzdO-HllQYd2RBt38sq5AgQOQ0yfHQT40ZYgp2adSLNQSZ0aegTIKkWnUQUIMeLTQIECAokSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEFeLBqSItJBGn0osODTqIBIM6EQIEFDDnyoFTJywvoECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf"
},
"routing-table": [0,1,11,3,400,5,6,7,800,9,0],
"cursor": false,
}

== Adding Frames to the System ==

Frames can be added to the system using either the Telstar API.

The Telstar API, in conjunction with the cross platform Telstar Util software, provides a simple method of creating and managing pages.

The API can be used to retrieve and update frames and configuring routing. The API is a restful API that uses the GET, PUT, POST and DELETE HTTP methods and as such can be used from any application.

Data is passed to and from the API in JSON format, making the system very simple to use in any programming language. The whole API could be used without any programming at all by using a command line utility such as CURL.

''Further details of the Telstar API can be found in the section [[The Telstar API]].''

== Adding Content with the Edit.tf editor ==

There are several ways to add content to a page. One of the easiest is to create the page in an editor such as http://edit.tf.

The JSON file would look something like the one showm below. Note that the content type is set to editf and the content data contains the edit.tf url.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"content": {
"data": "http://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICn_OmTJkSJApUqVKlSpUlcHApiTJkyZEiRIkyZMmTIkSJFmKf3JX58____RBg-fPnzog__2iBBo-fNX9qgQcOHDh8-fGiAp_zFf______2v7_____7X___oEGr__Qa0ur_________QoCn9ywK__6D__a__7dH__tf___1QIv_9AiQIkaPX_bo0aMpiKf_-Yr__oP_9r__tUH_-1____9og__yjnz5cldX9qUc-fPkp__uSv_-g__2v_-1Qf_7X__aIv____KZv_dIV__2pTN___yn__mK___z__a____5__tf_9qgVf__8o5_vWJX__alHP___Kf_7kr____6dBr_____-h__2qBBr__ymbPnSFf69CUzf__8pnz5iq9ejRoECBWvXr0KBGjQYOHBHz4cECBAgwcCily7__yqDhw4ePnzogQeP7RAg0fPiBB___9X___QYPH___-sCmb__KoP________3B__tUCDV__tUH___1f36XB-_______KOf_8qgRo__9B__v9X___QINX___Qav__B8-NNX_-jR___8pm__ymYrq______h_odX9qg1f___7q__9X_-h1f_5TBgwYM37__KOSur-_Ro0Pr_8_f_qDV_b___r__1f_6D___lFKlSpUu__8pmK_v7VAgwf______tNX9r______V__oP__-gQaPnwpm__yqDB__tUCD__QIEG___1f2qL____9X_-g____z5-__ymb__KoNX_-lQKl6VAgQav6_V__oNf___1f2qBX_____9-hKOf_8qgVJ0JRw4cOPLkqiQoESNGgVL0aFEjQoECJGjRoymDNm__ymTJkzZv3_____-3bt27du3Thw8efPnz58-fPnz58-fP___QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf"
}
}

== Adding Content using Markup ==

Content can be added directly to the JSON file using a very simple markup. For example consider the following frame definition.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"title": {
"data": "[D]Welcome\r\n\r\n",
"type": "markup"
},
"content": {
"data": "[Y]Hello[C]Telstar[M]World",
"type": "markup"
}
}

This frame uses markup in the title and the content, The title is specified as [D]ouble height and the three words used in the content are coloured yellow, cyan and magenta respectively.

Full details of markup can be found in the [[Markup]] section.

== Complete Frame Description ==

The frame below is a standard information page from the TELSTAR system shown in its JSON format. It represents the first frame of page 9. Taking this frame as an example, a description of the fields and their meaning is decribed below.

''The full json schema can be found [[Frame Schema|here]].''

{
"pid": {
"page-no": 9,
"frame-id": "a"
},
"visible": true,
"header-text": "",
"cost": 0,
"frame-type": "information",
"redirect": {
"page-no": 0,
"frame-id": ""
},
"content": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgc4UCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAxQIIs6PJnRYtKTOjoKkWnUQUIMeLTQIECBAgQIECBAgQIEDRAgp2adSLNQSZ0aegQIECBAgQIECBAgQIECBAgQIECBAgQNkCCPBqRa8GygpxaVaTDi00CBAgQIECBAgQIECBAgQIECBA4QIIc-dUgw6iCJFqQZMymgQIECBAgQIECBAgQIECBAgQIEDlAgmT46CfOQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMECCZPjoJ8aMgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgBVAMUNMQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIAVQDFDTAlMPUQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUAxQ0wJTD1A0EHSQIECBAgQIECBAgQIECBAgQIECBAgQIECANMCUw9QNBB0kCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAPUDQQdJAgQIECBAgQIECBAgQIECAosWLFixYsWLFixYsQIECAHSQIECAosWLFixYsWLFixYsWIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf'
},
"title": {
"data": "",
"type": "",
"merge-data": []
},
"routing-table": [
90,
91,
92,
93,
94,
95,
96,
97,
98,
990,
0
],
"cursor": false,
"connection": {
"address": "",
"mode": "",
"port": 0
},
"author-id": "",
"response-data": {
"responses": null,
"response-action": {
"exec": "",
"args": null,
"post-action-frame": {
"page-no": 0,
"frame-id": ''
},
"post-cancel-frame": {
"page-no": 0,
"frame-id": ""
}
}
},
"navmessage-select": "[B][n][Y]Select item or[W]*page# : [_+]",
"navmessage-notfound": "[B][n][Y]Page not Found :[W]"
}

=== pid ===

Specifies the page number and frame id for the frame.

"pid": {
"page-no": 9,
"frame-id": "a"
},

=== visible ===

When set to false, the frame will not be accessible and will return the ''not found'' system message to the user if an attempt is made to access it.

"visible": true,

=== header-text ===

Allows the default header text to be ovwerridden at frame level. If this is left blank the default header will be used, see configuration.

"header-text": "[Y]MICRONETn 800 (C)",

=== cost ===

"cost": 0,

=== frame-type ===

The API supports the following frame types ''initial'', ''mainindex'', ''information'', ''exit'', ''gateway'', ''test'' and ''response''.

"frame-type": "information",

* '''initial''': This frame type is used on the start page, see [[Configuration Options]]. Typically only one of these frames would exist within a system.
* '''mainindex''': This frame type is used on the main index page. , see [[Configuration Options]]. Only one of these frames should exist within a system.
* '''information''': This frame type is used for all normal content frames.
* '''exit''': This frame type is used for an exit page, any number of exit pages can be defined. When an exit page is rendered it will close the connection.
* '''gateway''': This page type is used to define a gateway page and is used in conjunction with the connection element (see below).
* '''test''': This page type indicates a test page and prevents navigation and system messages from being shown. this is typically used for frames that need to use the whole display such as 'test cards' etc.
* '''telesoftware''': Telesoftware frames (see [[Telesoftware]]).
* '''response''': This frame type is used for response frames. See [[Implementing Response Frames]].
* '''system''': Reserved for use internally.
* '''exception''': Reserved for use internally.

=== redirect ===

If set it simply means that the user is redirected to the specified frame. This can be a useful alternative form of navigation to the routing table.

"redirect": {
"page-no": 9,
"frame-id": "a"
},

The following is an example of a complete redirect page.

{
"PID": {
"page-no": 2,
"frame-id": "a"
},
"redirect": {
"page-no": 11,
"frame-id": "a"
},
"visible": true
}

=== content ===

These elements define the content. The example below shows the content.type to be an edit.tf url. The available types are shown below.

"content": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgc4UCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAxQIIs6PJnRYtKTOjoKkWnUQUIMeLTQIECBAgQIECBAgQIEDRAgp2adSLNQSZ0aegQIECBAgQIECBAgQIECBAgQIECBAgQNkCCPBqRa8GygpxaVaTDi00CBAgQIECBAgQIECBAgQIECBA4QIIc-dUgw6iCJFqQZMymgQIECBAgQIECBAgQIECBAgQIEDlAgmT46CfOQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMECCZPjoJ8aMgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgBVAMUNMQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIAVQDFDTAlMPUQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUAxQ0wJTD1A0EHSQIECBAgQIECBAgQIECBAgQIECBAgQIECANMCUw9QNBB0kCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAPUDQQdJAgQIECBAgQIECBAgQIECAosWLFixYsWLFixYsQIECAHSQIECAosWLFixYsWLFixYsWIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf'
},

Content types:

* '''zxnet''': If set, then the content will be treated as an zxnet editor url. This is converted to RawV before being rendered.
* '''edit.tf''': If set, then the content will be treated as an edit.tf url. This is converted to RawV before being rendered.
* '''markup''': If set, then the content will be treated as ''markup'' content. Full details of ''markup'' can be found in the section [[Markup]]
* '''rawV''': If set, then the content will be treated as raw videotex data. This is 7bit (00-7F) videotex format with control chars between 00-1F and escaped codes for alpha and graphic attributes. Ideally rows should have any trailing spaces removed and replaced with with a CR/LF combination. This will be rendered as is.
* '''rawT''': If set, then the content will be treated as raw teletex data. This is a 24 x 40 block of 7 bits chars (960 chars) in Teletext format (range 00-7F). This format is used internally when manipulating page data. It will be converted to RawV before being rendered.

=== title ===

This sets the title of the page. In many cases this may be left blank with all of the content specified in the ''content'' section (see above) however, the ''title'' section gives additional flexibility when creating frames.

Values for ''title-type'' are the same as defined for the content section, however, if the type ''edit-tf'' is used then only the first four (default) lines of the edit.tf defined page are used.

Separating title from content in this way allows logos and header sections to be created for the title whilst using markup for the main content or visa-versa.

==== Example 1 ====

In thi example the fields are blank meaning that only the data in the ''content'' section is displayed.

"title": {
"data": "",
"type": "",
"merge-data": []
},

==== Example 2 ====

In this example, the top 4 lines of the edit.tf content is displayed at the top of the page.

"title": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAvobotqBX__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIC_9AgQIEGv-gQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgL_0Cj4kQav6BAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAuq64P6Dx__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf",
"merge-data": []
},

To take the top 5 lines, the ''type'' field can be extended as follows.

"type": "edit.tf,5"

Note that this extended form of ''type'' only applies to edit.tf types.

==== Example 3 ====

The merge data field can be used to add ''layers'' of markup data to the title area. For example the example above shows the Guardian logo. To add some alphagraphics text to this, an additional layer could be used e.g.

"title": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAvobotqBX__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIC_9AgQIEGv-gQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgL_0Cj4kQav6BAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAuq64P6Dx__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf,5",
"merge-data": [
"[w[ UK News]]"
]
},

Note that any number of layers can be added, however, the merge layer must be defined as markup.

=== routing table ===

The routing table defines which pages are navigated to when a user presses a key whilst viewing the frame. The table has 11 entries with the first 10 representing the keys 0-9, the final entry refers to the ''hash'' (return) key.

The example below shows the default routing table for frame 9a. If the user is viewing this frame and presses 1 the frame 91a will be loaded, assuming it exists. Pressing the ''hash'' (return) key will take the user back to frame 0a, the main index.

"routing-table": [
90,
91,
92,
93,
94,
95,
96,
97,
98,
99,
0
],

=== cursor ===

This element determines whether a cursor is shown on the page. Typically a cursor would only be shown on response frames.

"cursor": false,

=== connection ===

This elements specifies the connection object used for gateway pages.

"connection": {
"address": "fish.ccl4.org",
"mode": "viewdata",
"port": 23
},

The values for ''address and port'' represent the endpoint of the system being accessed and the value for ''mode'' determines how the system is accessed, the options are:

viewdata
full_duplex
full_duplex_no_echo

=== author-id ===

This is an optional field that can be used to indicate the author of the page or other source.

"author-id": "john",

=== response-data ===

These fields should be used when the frame type is set to be a ''response-frame''.

There are two main sections, ''response-data'' and ''response-action''. Below is an example of a response frame used for the Telstar weather page. The frame is created in the normal way using ''markup'' or ''edit.tf''. In this example the text ''Town/Cty'' has been positioned near the centre of the page. Immediately to the right of this is a field for the user to enter either a Town or City, the ''response-data'' section defines that field. Once the user submits the frame the section ''response-action'' determines what happens. In the example here a binary file (''telstar-openweather-linux-amd64''), stored in the containers volume directory is executed with a single argument (''myopenweatherapikey''). Note that the ''post-action-frame'' is set to 290b, in this example frame 290b is dynamically generated by the binary file ''telstar-openweather-linux-amd64'' and contains the weather forecast.

Full details of how to implement response frames are detailed in the section [[Implementing Response Frames]].
"response-data": {
"response-fields": [
{
"vpos": 8,
"hpos": 4,
"required": true,
"length": 16,
"type": "alphanumeric",
"auto-submit": false,
"password": false
}
],
"response-action": {
"exec": "/opt/telstar/volume/telstar-openweather-linux-amd64",
"args": [
"myopenweatherapikey"
],
"post-action-frame": {
"page-no": 290,
"frame-id": "c"
}
}
},

=== navmessage-select ===

Allows the ''navigation'' system message to be customised at frame level. In most cases this can be left blank in order that the system default is used instead, see [[Configuration Options]].

"navmessage-select": "[B][n][Y]Select item or[W]*page# : [_+]",

=== navmessage-notfound ===

Allows the ''not found'' system message to be customised at frame level. In most cases this can be left blank in order that the system default is used instead, see [[Configuration Options]].

"navmessage-notfound": "[B][n][Y]Page not Found :[W]"

Frames

2022-05-16T20:32:08Z

John:

As is typical with interactive videotex systems, pages are numbered from 0 to 999999999 and consist of one or more frames with the suffix a-z, for example the first frame for page 200 would be 200a, the second 200b and so on (see [[Routing]]) for more details). These frames are stored within TELSTAR's database as ''JSON'' objects (see https://www.json.org/) and uploaded to Telstar using a simple command line utility.

The Telstar utility program simply interacts with the Telstar API which is a restful API. This can be used directly by any software making it simple to programitically manage pages and routing information.

Frames are defined in JSON. The simplest frame that can be viewed on TELSTAR would be as follows. This would create a simple information frame with some flashing content. In this example [[Markup]] has been used within the content, however, other content types can be used including edi.tf urls, see below.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"content": {
"data": "[D]This is page[F]101a",
"type": "markup"
}
}

Shown below is a more complete example of a JSON defined frame. With this particular frame, the actual viewdata content has been created using the editor at http://edit.tf, this can be seen in the ''content.data'' and ''content.type'' keys. Both the edit.tf and zxnet (https://zxnet.co.uk/teletext/editor/) editors are supported. The example below is a simple information page with some simple routing (see [[Routing]]). Clicking the ''content.data'' link, or pasteing the value into a browser will show the page and allow it to be edited. It is not necessary to use the http://edit.tf editor, this is just one possible option.

{
"pid": {
"page-no": 0,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"content": {
"data": "http://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMMKAbNw6dyCTuyZfCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgKJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRAxQR4s6LSgzEEmdUi0otOogkzo0-lNg1JM-cCg8unNYgQIASBBj67OnXllWIMu7pl5dMOndty7uixBoy4dnTQsQIECBAgBIEHfLh2dNCDDuyINmnNl59POzKuQIECBAgQIECBAgQIECBAyQTotemggzoiCvFg1JEWkCnYemnfuw7EGHdkQIECBAgQIASBBp3dMvLdh6ad-7DsQbsvfmgw7siDvlw9NGXkuQIECBAgQM0EKrTkzotOmgkzo0-lNg1JM-cCh79vDDu8oMO7IgQIECAEgQYuvPTuy8-aDdl781wM6EjVKcVBMw9MvPogoctOPLzQIEDRBHn1otKdNizqiCTOjT6U2DUkz5wKlvw5OaxByw6dixAgBIEGHdkQUMPLZpw7cu7ouQIECBAgQIECBAgQIECBAgQIECBA2QR4NSLXg2UFOLSrSYcWmCnWKkWYsQVIsWNBsLEEOHMaIASBBh3ZEHTRlQQ9-zfz54diCHh7ZUGHJ2y7unXllXIECBAgQN0EifMkxINmmCqcsPbLsQYd2RBI37NOTD5QbsvfmuQIECBA4CHQc2TDpT50WogcMGCAScgoOnLTi69MqDpvQdNGnmgQIAaBBzy8u2nHlQd9PTQgqZdmXnvzdO-HllQYd2RBt38sq5AgQOQ0yfHQT40ZYgp2adSLNQSZ0aegTIKkWnUQUIMeLTQIECAokSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEFeLBqSItJBGn0osODTqIBIM6EQIEFDDnyoFTJywvoECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf"
},
"routing-table": [0,1,11,3,400,5,6,7,800,9,0],
"cursor": false,
}

== Adding Frames to the System ==

Frames can be added to the system using either the Telstar API.

The Telstar API, in conjunction with the cross platform Telstar Util software, provides a simple method of creating and managing pages.

The API can be used to retrieve and update frames and configuring routing. The API is a restful API that uses the GET, PUT, POST and DELETE HTTP methods and as such can be used from any application.

Data is passed to and from the API in JSON format, making the system very simple to use in any programming language. The whole API could be used without any programming at all by using a command line utility such as CURL.

''Further details of the Telstar API can be found in the section [[The Telstar API]].''

== Adding Content with the Edit.tf editor ==

There are several ways to add content to a page. One of the easiest is to create the page in an editor such as http://edit.tf.

The JSON file would look something like the one showm below. Note that the content type is set to editf and the content data contains the edit.tf url.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"content": {
"data": "http://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICn_OmTJkSJApUqVKlSpUlcHApiTJkyZEiRIkyZMmTIkSJFmKf3JX58____RBg-fPnzog__2iBBo-fNX9qgQcOHDh8-fGiAp_zFf______2v7_____7X___oEGr__Qa0ur_________QoCn9ywK__6D__a__7dH__tf___1QIv_9AiQIkaPX_bo0aMpiKf_-Yr__oP_9r__tUH_-1____9og__yjnz5cldX9qUc-fPkp__uSv_-g__2v_-1Qf_7X__aIv____KZv_dIV__2pTN___yn__mK___z__a____5__tf_9qgVf__8o5_vWJX__alHP___Kf_7kr____6dBr_____-h__2qBBr__ymbPnSFf69CUzf__8pnz5iq9ejRoECBWvXr0KBGjQYOHBHz4cECBAgwcCily7__yqDhw4ePnzogQeP7RAg0fPiBB___9X___QYPH___-sCmb__KoP________3B__tUCDV__tUH___1f36XB-_______KOf_8qgRo__9B__v9X___QINX___Qav__B8-NNX_-jR___8pm__ymYrq______h_odX9qg1f___7q__9X_-h1f_5TBgwYM37__KOSur-_Ro0Pr_8_f_qDV_b___r__1f_6D___lFKlSpUu__8pmK_v7VAgwf______tNX9r______V__oP__-gQaPnwpm__yqDB__tUCD__QIEG___1f2qL____9X_-g____z5-__ymb__KoNX_-lQKl6VAgQav6_V__oNf___1f2qBX_____9-hKOf_8qgVJ0JRw4cOPLkqiQoESNGgVL0aFEjQoECJGjRoymDNm__ymTJkzZv3_____-3bt27du3Thw8efPnz58-fPnz58-fP___QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf"
}
}

== Adding Content using Markup ==

Content can be added directly to the JSON file using a very simple markup. For example consider the following frame definition.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"title": {
"data": "[D]Welcome\r\n\r\n",
"type": "markup"
},
"content": {
"data": "[Y]Hello[C]Telstar[M]World",
"type": "markup"
}
}

This frame uses markup in the title and the content, The title is specified as [D]ouble height and the three words used in the content are coloured yellow, cyan and magenta respectively.

Full details of markup can be found in the [[Markup]] section.

== Complete Frame Description ==

The frame below is a standard information page from the TELSTAR system shown in its JSON format. It represents the first frame of page 9. Taking this frame as an example, a description of the fields and their meaning is decribed below.

''The full json schema can be found [[Frame Schema|here]].''

{
"pid": {
"page-no": 9,
"frame-id": "a"
},
"visible": true,
"header-text": "",
"cost": 0,
"frame-type": "information",
"redirect": {
"page-no": 0,
"frame-id": ""
},
"content": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgc4UCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAxQIIs6PJnRYtKTOjoKkWnUQUIMeLTQIECBAgQIECBAgQIEDRAgp2adSLNQSZ0aegQIECBAgQIECBAgQIECBAgQIECBAgQNkCCPBqRa8GygpxaVaTDi00CBAgQIECBAgQIECBAgQIECBA4QIIc-dUgw6iCJFqQZMymgQIECBAgQIECBAgQIECBAgQIEDlAgmT46CfOQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMECCZPjoJ8aMgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgBVAMUNMQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIAVQDFDTAlMPUQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUAxQ0wJTD1A0EHSQIECBAgQIECBAgQIECBAgQIECBAgQIECANMCUw9QNBB0kCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAPUDQQdJAgQIECBAgQIECBAgQIECAosWLFixYsWLFixYsQIECAHSQIECAosWLFixYsWLFixYsWIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf'
},
"title": {
"data": "",
"type": "",
"merge-data": []
},
"routing-table": [
90,
91,
92,
93,
94,
95,
96,
97,
98,
990,
0
],
"cursor": false,
"connection": {
"address": "",
"mode": "",
"port": 0
},
"author-id": "",
"response-data": {
"responses": null,
"response-action": {
"exec": "",
"args": null,
"post-action-frame": {
"page-no": 0,
"frame-id": ''
},
"post-cancel-frame": {
"page-no": 0,
"frame-id": ""
}
}
},
"navmessage-select": "[B][n][Y]Select item or[W]*page# : [_+]",
"navmessage-notfound": "[B][n][Y]Page not Found :[W]"
}

=== pid ===

Specifies the page number and frame id for the frame.

"pid": {
"page-no": 9,
"frame-id": "a"
},

=== visible ===

When set to false, the frame will not be accessible and will return the ''not found'' system message to the user if an attempt is made to access it.

"visible": true,

=== header-text ===

Allows the default header text to be ovwerridden at frame level. If this is left blank the default header will be used, see configuration.

"header-text": "[Y]MICRONETn 800 (C)",

=== cost ===

"cost": 0,

=== frame-type ===

The API supports the following frame types ''initial'', ''mainindex'', ''information'', ''exit'', ''gateway'', ''test'' and ''response''.

"frame-type": "information",

* '''initial''': This frame type is used on the start page, see [[Configuration Options]]. Typically only one of these frames would exist within a system.
* '''mainindex''': This frame type is used on the main index page. , see [[Configuration Options]]. Only one of these frames should exist within a system.
* '''information''': This frame type is used for all normal content frames.
* '''exit''': This frame type is used for an exit page, any number of exit pages can be defined. When an exit page is rendered it will close the connection.
* '''gateway''': This page type is used to define a gateway page and is used in conjunction with the connection element (see below).
* '''test''': This page type indicates a test page and prevents navigation and system messages from being shown. this is typically used for frames that need to use the whole display such as 'test cards' etc.
* '''telesoftware''': Telesoftware frames (see [[Telesoftware]]).
* '''response''': This frame type is used for response frames. See [[Implementing Response Frames]].
* '''system''': Reserved for use internally.
* '''exception''': Reserved for use internally.

=== redirect ===

If set it simply means that the user is redirected to the specified frame. This can be a useful alternative form of navigation to the routing table.

"redirect": {
"page-no": 9,
"frame-id": "a"
},

The following is an example of a complete redirect page.

{
"PID": {
"page-no": 2,
"frame-id": "a"
},
"redirect": {
"page-no": 11,
"frame-id": "a"
},
"visible": true
}

=== content ===

These elements define the content. The example below shows the content.type to be an edit.tf url. The available types are shown below.

"content": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgc4UCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAxQIIs6PJnRYtKTOjoKkWnUQUIMeLTQIECBAgQIECBAgQIEDRAgp2adSLNQSZ0aegQIECBAgQIECBAgQIECBAgQIECBAgQNkCCPBqRa8GygpxaVaTDi00CBAgQIECBAgQIECBAgQIECBA4QIIc-dUgw6iCJFqQZMymgQIECBAgQIECBAgQIECBAgQIEDlAgmT46CfOQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMECCZPjoJ8aMgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgBVAMUNMQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIAVQDFDTAlMPUQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUAxQ0wJTD1A0EHSQIECBAgQIECBAgQIECBAgQIECBAgQIECANMCUw9QNBB0kCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAPUDQQdJAgQIECBAgQIECBAgQIECAosWLFixYsWLFixYsQIECAHSQIECAosWLFixYsWLFixYsWIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf'
},

Content types:

* '''edit.tf''': If set, then the content will be treated as an edit.tf url. This is converted to RawV before being rendered.
* '''markup''': If set, then the content will be treated as ''markup'' content. Full details of ''markup'' can be found in the section [[Markup]]
* '''rawV''': If set, then the content will be treated as raw videotex data. This is 7bit (00-7F) videotex format with control chars between 00-1F and escaped codes for alpha and graphic attributes. Ideally rows should have any trailing spaces removed and replaced with with a CR/LF combination. This will be rendered as is.
* '''rawT''': If set, then the content will be treated as raw teletex data. This is a 24 x 40 block of 7 bits chars (960 chars) in Teletext format (range 00-7F). This format is used internally when manipulating page data. It will be converted to RawV before being rendered.

=== title ===

This sets the title of the page. In many cases this may be left blank with all of the content specified in the ''content'' section (see above) however, the ''title'' section gives additional flexibility when creating frames.

Values for ''title-type'' are the same as defined for the content section, however, if the type ''edit-tf'' is used then only the first four (default) lines of the edit.tf defined page are used.

Separating title from content in this way allows logos and header sections to be created for the title whilst using markup for the main content or visa-versa.

==== Example 1 ====

In thi example the fields are blank meaning that only the data in the ''content'' section is displayed.

"title": {
"data": "",
"type": "",
"merge-data": []
},

==== Example 2 ====

In this example, the top 4 lines of the edit.tf content is displayed at the top of the page.

"title": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAvobotqBX__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIC_9AgQIEGv-gQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgL_0Cj4kQav6BAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAuq64P6Dx__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf",
"merge-data": []
},

To take the top 5 lines, the ''type'' field can be extended as follows.

"type": "edit.tf,5"

Note that this extended form of ''type'' only applies to edit.tf types.

==== Example 3 ====

The merge data field can be used to add ''layers'' of markup data to the title area. For example the example above shows the Guardian logo. To add some alphagraphics text to this, an additional layer could be used e.g.

"title": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAvobotqBX__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIC_9AgQIEGv-gQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgL_0Cj4kQav6BAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAuq64P6Dx__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf,5",
"merge-data": [
"[w[ UK News]]"
]
},

Note that any number of layers can be added, however, the merge layer must be defined as markup.

=== routing table ===

The routing table defines which pages are navigated to when a user presses a key whilst viewing the frame. The table has 11 entries with the first 10 representing the keys 0-9, the final entry refers to the ''hash'' (return) key.

The example below shows the default routing table for frame 9a. If the user is viewing this frame and presses 1 the frame 91a will be loaded, assuming it exists. Pressing the ''hash'' (return) key will take the user back to frame 0a, the main index.

"routing-table": [
90,
91,
92,
93,
94,
95,
96,
97,
98,
99,
0
],

=== cursor ===

This element determines whether a cursor is shown on the page. Typically a cursor would only be shown on response frames.

"cursor": false,

=== connection ===

This elements specifies the connection object used for gateway pages.

"connection": {
"address": "fish.ccl4.org",
"mode": "viewdata",
"port": 23
},

The values for ''address and port'' represent the endpoint of the system being accessed and the value for ''mode'' determines how the system is accessed, the options are:

viewdata
full_duplex
full_duplex_no_echo

=== author-id ===

This is an optional field that can be used to indicate the author of the page or other source.

"author-id": "john",

=== response-data ===

These fields should be used when the frame type is set to be a ''response-frame''.

There are two main sections, ''response-data'' and ''response-action''. Below is an example of a response frame used for the Telstar weather page. The frame is created in the normal way using ''markup'' or ''edit.tf''. In this example the text ''Town/Cty'' has been positioned near the centre of the page. Immediately to the right of this is a field for the user to enter either a Town or City, the ''response-data'' section defines that field. Once the user submits the frame the section ''response-action'' determines what happens. In the example here a binary file (''telstar-openweather-linux-amd64''), stored in the containers volume directory is executed with a single argument (''myopenweatherapikey''). Note that the ''post-action-frame'' is set to 290b, in this example frame 290b is dynamically generated by the binary file ''telstar-openweather-linux-amd64'' and contains the weather forecast.

Full details of how to implement response frames are detailed in the section [[Implementing Response Frames]].
"response-data": {
"response-fields": [
{
"vpos": 8,
"hpos": 4,
"required": true,
"length": 16,
"type": "alphanumeric",
"auto-submit": false,
"password": false
}
],
"response-action": {
"exec": "/opt/telstar/volume/telstar-openweather-linux-amd64",
"args": [
"myopenweatherapikey"
],
"post-action-frame": {
"page-no": 290,
"frame-id": "c"
}
}
},

=== navmessage-select ===

Allows the ''navigation'' system message to be customised at frame level. In most cases this can be left blank in order that the system default is used instead, see [[Configuration Options]].

"navmessage-select": "[B][n][Y]Select item or[W]*page# : [_+]",

=== navmessage-notfound ===

Allows the ''not found'' system message to be customised at frame level. In most cases this can be left blank in order that the system default is used instead, see [[Configuration Options]].

"navmessage-notfound": "[B][n][Y]Page not Found :[W]"

Configuration Options

2022-05-16T14:46:18Z

John: /* Environment Variables */

== Container Types ==

The same Telstar image is used to host different container types, for example a the Telstar image can be used to create videotex server container and an API server container. The first argument passed to the container determines the specific configuration of the container. Currently the container supports the following values;

server Creates the standard videotex server container
api Creates an API server allowing the videotex system to be managed using a restful API.

For example the following Docker run command starts a videotex server listening on port 6502 (see TCP Port below) with an initial set of example system pages.

docker run --rm -d --name telstar-server --network telstar-network -p 6512:6512 -v telstar-volume:/opt/telstar/volume johnnewcombe/telstar server --port=6502 --init

== TCP Port Number ==

The ''--port'' argument must be specified for the Telstar server and API containers. The port parameter specifies the TCP port number that the server or api application should be listening on. This can be any suitable port.

== Optional Arguments ==

The following is a list of optional arguments for both the Telstar server and Telstar API containers.

--init This will create/recreate the basic telstar content.

The ''--init'' parameter, when starting a videotex server will create/recreate the standard telstar system pages along with some example gateway pages. If this parameter is used when starting an API server, it will create an API user using the userid '''"2222222222"''' and password '''"1234"'''.

== Environment Variables ==

The full description of each of these can be found below.

Name | Default
-----------------------------------------------------------------------------------------
TELSTAR_API_HOST | 0.0.0.0
TELSTAR_PAD_HOST | 0.0.0.0
TELSTAR_PAD_DLE | 0x10
TELSTAR_SERVER_HOST | 0.0.0.0
TELSTAR_SERVER_DISPLAY_NAME | DUKE
TELSTAR_HIDE_PAGE_ID | FALSE
TELSTAR_HIDE_COST | FALSE
TELSTAR_DISABLE_VERTICAL_ROLLOVER | TRUE
TELSTAR_EDITTF_TITLE_ROWS | 4
TELSTAR_DBCON | mongodb://mongoadmin:secret@telstar-mongo:27017
TELSTAR_DBCOLLECTION | SECONDARY
TELSTAR_START_PAGE | 99
TELSTAR_LOGIN_PAGE | 990
TELSTAR_MAIN_INDEX_PAGE | 0
TELSTAR_REQUIRES_AUTHENTICATION | FALSE
TELSTAR_ROOT_USER_ID | 0
TELSTAR_PARITY | FALSE
TELSTAR_VOLUME_DIRECTORY | /opt/telstar/volume/
TELSTAR_DEFAULT_NAV_MESSAGE | [B][n][Y]Select item or[W]*page# : [_+]
TELSTAR_DEFAULT_PAGE_NOT_FOUND_MESSAGE | [B][n][Y]Page not Found :[W]
TELSTAR_DEFAULT_HEADER_TEXT | [G]T[R]E[C]L[B]S[W]T[M]A[Y]R

The default settings for the settings above are stored in the ''telstar.yaml'' configuration file which is stored in the ''/opt/telstar'' directory of the respective container. It is recommended that Telstar is run in a Docker container in which case the above environment variables should be used to override the standard configuration file.

=== TELSTAR_API_HOST ===

This is for future use and can be ignored the default setting is:

0.0.0.0

=== TELSTAR_PAD_HOST ===

This is for future use and can be ignored the default setting is:

0.0.0.0

=== TELSTAR_PAD_DLE ===

This is the Data Link Escape character used to exit a Gateway connection, the default value is:

0x10 (Ctrl P)

=== TELSTAR_SERVER_HOST ===

This is for future use and can be ignored the default setting is:

0.0.0.0

=== TELSTAR_SERVER_DISPLAY_NAME ===

This is the display name of the viewdata server and is used in place of the [SERVER] placeholder tag, see [[Frames]] for more details on placeholder tags. The default value is:

DUKE

=== TELSTAR_HIDE_PAGE_ID ===

Setting this value to true will hide the Page ID displayed in the top line header of the frame. The default value is:

FALSE

=== TELSTAR_HIDE_COST ===

Setting this value to true will hide the frame cost displayed in the top line header of the frame. The default value is:

FALSE

=== TELSTAR_DISABLE_VERTICAL_ROLLOVER ===

Setting this value to true will enable Vertical Rollover. The default value is:

TRUE

Vertical Rollover is used as a means for Telstar to move the cursor to a point on the screen in the most efficient way possible. For example to get to the start of the bottom row, it may be quicker to send the commands HOME followed by VT. This would cause a vertical rollover to the bottom row. Not all clients currently support this correctly.

=== TELSTAR_EDITTF_TITLE_ROWS ===

The https://edit.tf frame editor can be used to create pages and titles. When used to create a title, the number of rows taken fron the edit.tf data can be specified with this variable. The default settings is:

4

=== TELSTAR_DBCON ===

This is the database connection and points to a mongo Docker container on the Docker telstar-network, see [[Installing Telstar]]. The default value is:

mongodb://mongoadmin:secret@telstar-mongo:27017

=== TELSTAR_DBCOLLECTION ===

The database is divided into two logical partitions, PRIMARY and SECONDARY. Typically PRIMARY would be used for a production system with SECONDARY being used for a test system. When adding pages to the database via the API, these would typically be send to the SECONDARY database, reviewed on a test system and then ''published'' to the PRIMARY database. The default value is:

SECONDARY

=== TELSTAR_START_PAGE ===

The start page to be used by the system. This would typically be a welcome screen. The default value is:

99

=== TELSTAR_LOGIN_PAGE ===

The login page to be used by the system. This would typically be a welcome screen set up as a response page. The default value is:

990

=== TELSTAR_MAIN_INDEX_PAGE ===

The main index page to be used by the system. This would typically be the top level menu. The default value is:

0

=== TELSTAR_REQUIRES_AUTHENTICATION ===

If set to true, the user is directed to the TELSTAR_LOGIN_PAGE, rather than the TELSTAR_START_PAGE. The default value is:

FALSE

=== TELSTAR_ROOT_USER_ID ===

This is for future use and should be ignored. The Default value is:

0

=== TELSTAR_PARITY ===

If set to true then 7bit Even Parity is invoked over the TCP connection. Typically this would not be required. The default value is:

FALSE

=== TELSTAR_VOLUME_DIRECTORY ===

This is the folder within the container that is used for the Docker Volume. The default value is:

/opt/telstar/volume/

=== TELSTAR_DEFAULT_NAV_MESSAGE ===

This is the default message to be used for navigation. This can be overridden on a frame by frame basis as required and can be specified using ''markup''. See [[Frames]] for more details of this setting and details of ''markup'' text.

[B][n][Y]Select item or[W]*page# : [_+]

=== TELSTAR_DEFAULT_PAGE_NOT_FOUND_MESSAGE ===

This is the default message to be used when a page is not found. This can be overridden on a frame by frame basis as required and can be specified using ''markup''. See [[Frames]] for more details of this setting and details of ''markup'' text.

[B][n][Y]Page not Found :[W]

=== TELSTAR_DEFAULT_HEADER_TEXT ===

This is the default top row header text for each frame. This can be overridden on a frame by frame basis as required and can be specified using ''markup''. See [[Frames]] for more details of this setting and details of ''markup'' text.

[G]T[R]E[C]L[B]S[W]T[M]A[Y]R

Configuration Options

2022-05-16T14:45:31Z

John: /* Environment Variables */

== Container Types ==

The same Telstar image is used to host different container types, for example a the Telstar image can be used to create videotex server container and an API server container. The first argument passed to the container determines the specific configuration of the container. Currently the container supports the following values;

server Creates the standard videotex server container
api Creates an API server allowing the videotex system to be managed using a restful API.

For example the following Docker run command starts a videotex server listening on port 6502 (see TCP Port below) with an initial set of example system pages.

docker run --rm -d --name telstar-server --network telstar-network -p 6512:6512 -v telstar-volume:/opt/telstar/volume johnnewcombe/telstar server --port=6502 --init

== TCP Port Number ==

The ''--port'' argument must be specified for the Telstar server and API containers. The port parameter specifies the TCP port number that the server or api application should be listening on. This can be any suitable port.

== Optional Arguments ==

The following is a list of optional arguments for both the Telstar server and Telstar API containers.

--init This will create/recreate the basic telstar content.

The ''--init'' parameter, when starting a videotex server will create/recreate the standard telstar system pages along with some example gateway pages. If this parameter is used when starting an API server, it will create an API user using the userid '''"2222222222"''' and password '''"1234"'''.

== Environment Variables ==

The full description of each of these can be found below.

Name | Default
-----------------------------------------------------------------------------------------
TELSTAR_API_HOST | 0.0.0.0
TELSTAR_PAD_HOST | 0.0.0.0
TELSTAR_PAD_DLE | 0x10
TELSTAR_SERVER_HOST | 0.0.0.0
TELSTAR_SERVER_DISPLAY_NAME | DUKE
TELSTAR_HIDE_PAGE_ID | FALSE
TELSTAR_HIDE_COST | FALSE
TELSTAR_DISABLE_VERTICAL_ROLLOVER | TRUE
TELSTAR_EDITTF_TITLE_ROWS | 4
TELSTAR_DBCON | mongodb://mongoadmin:secret@telstar-mongo:27017
TELSTAR_DBCOLLECTION | SECONDARY
TELSTAR_START_PAGE | 99
TELSTAR_LOGIN_PAGE | 990
TELSTAR_MAIN_INDEX_PAGE | 0
TELSTAR_REQUIRES_AUTHENTICATION | FALSE
TELSTAR_ROOT_USER_ID | 0
TELSTAR_PARITY | FALSE
TELSTAR_VOLUME_DIRECTORY | /opt/telstar/volume/
TELSTAR_DEFAULT_NAV_MESSAGE | [B][n][Y]Select item or[W]*page# : [_+]
TELSTAR_DEFAULT_PAGE_NOT_FOUND_MESSAGE | [B][n][Y]Page not Found :[W]
TELSTAR_DEFAULT_HEADER_TEXT | [G]T[R]E[C]L[B]S[W]T[M]A[Y]R
TELSTAR_ANTIOPE | FALSE

The default settings for the settings above are stored in the ''telstar.yaml'' configuration file which is stored in the ''/opt/telstar'' directory of the respective container. It is recommended that Telstar is run in a Docker container in which case the above environment variables should be used to override the standard configuration file.

=== TELSTAR_API_HOST ===

This is for future use and can be ignored the default setting is:

0.0.0.0

=== TELSTAR_PAD_HOST ===

This is for future use and can be ignored the default setting is:

0.0.0.0

=== TELSTAR_PAD_DLE ===

This is the Data Link Escape character used to exit a Gateway connection, the default value is:

0x10 (Ctrl P)

=== TELSTAR_SERVER_HOST ===

This is for future use and can be ignored the default setting is:

0.0.0.0

=== TELSTAR_SERVER_DISPLAY_NAME ===

This is the display name of the viewdata server and is used in place of the [SERVER] placeholder tag, see [[Frames]] for more details on placeholder tags. The default value is:

DUKE

=== TELSTAR_HIDE_PAGE_ID ===

Setting this value to true will hide the Page ID displayed in the top line header of the frame. The default value is:

FALSE

=== TELSTAR_HIDE_COST ===

Setting this value to true will hide the frame cost displayed in the top line header of the frame. The default value is:

FALSE

=== TELSTAR_DISABLE_VERTICAL_ROLLOVER ===

Setting this value to true will enable Vertical Rollover. The default value is:

TRUE

Vertical Rollover is used as a means for Telstar to move the cursor to a point on the screen in the most efficient way possible. For example to get to the start of the bottom row, it may be quicker to send the commands HOME followed by VT. This would cause a vertical rollover to the bottom row. Not all clients currently support this correctly.

=== TELSTAR_EDITTF_TITLE_ROWS ===

The https://edit.tf frame editor can be used to create pages and titles. When used to create a title, the number of rows taken fron the edit.tf data can be specified with this variable. The default settings is:

4

=== TELSTAR_DBCON ===

This is the database connection and points to a mongo Docker container on the Docker telstar-network, see [[Installing Telstar]]. The default value is:

mongodb://mongoadmin:secret@telstar-mongo:27017

=== TELSTAR_DBCOLLECTION ===

The database is divided into two logical partitions, PRIMARY and SECONDARY. Typically PRIMARY would be used for a production system with SECONDARY being used for a test system. When adding pages to the database via the API, these would typically be send to the SECONDARY database, reviewed on a test system and then ''published'' to the PRIMARY database. The default value is:

SECONDARY

=== TELSTAR_START_PAGE ===

The start page to be used by the system. This would typically be a welcome screen. The default value is:

99

=== TELSTAR_LOGIN_PAGE ===

The login page to be used by the system. This would typically be a welcome screen set up as a response page. The default value is:

990

=== TELSTAR_MAIN_INDEX_PAGE ===

The main index page to be used by the system. This would typically be the top level menu. The default value is:

0

=== TELSTAR_REQUIRES_AUTHENTICATION ===

If set to true, the user is directed to the TELSTAR_LOGIN_PAGE, rather than the TELSTAR_START_PAGE. The default value is:

FALSE

=== TELSTAR_ROOT_USER_ID ===

This is for future use and should be ignored. The Default value is:

0

=== TELSTAR_PARITY ===

If set to true then 7bit Even Parity is invoked over the TCP connection. Typically this would not be required. The default value is:

FALSE

=== TELSTAR_VOLUME_DIRECTORY ===

This is the folder within the container that is used for the Docker Volume. The default value is:

/opt/telstar/volume/

=== TELSTAR_DEFAULT_NAV_MESSAGE ===

This is the default message to be used for navigation. This can be overridden on a frame by frame basis as required and can be specified using ''markup''. See [[Frames]] for more details of this setting and details of ''markup'' text.

[B][n][Y]Select item or[W]*page# : [_+]

=== TELSTAR_DEFAULT_PAGE_NOT_FOUND_MESSAGE ===

This is the default message to be used when a page is not found. This can be overridden on a frame by frame basis as required and can be specified using ''markup''. See [[Frames]] for more details of this setting and details of ''markup'' text.

[B][n][Y]Page not Found :[W]

=== TELSTAR_DEFAULT_HEADER_TEXT ===

This is the default top row header text for each frame. This can be overridden on a frame by frame basis as required and can be specified using ''markup''. See [[Frames]] for more details of this setting and details of ''markup'' text.

[G]T[R]E[C]L[B]S[W]T[M]A[Y]R

Installing Telstar

2022-05-07T17:04:20Z

John: /* Pull the Images and Run the Containers */

It is recommended that Telstar is installed into a Docker environment. The required images are available from https://hub.docker.com/repository/docker/johnnewcombe/telstar. The following examples can be used to install and run Telstar. In addition
examples are also given for orchestrating the services using both Docker Compose and Kubernetes.

To run Telstar using Docker, a minimum of two Docker images are required.

* The official Docker image '''mongodb'''
* The Docker image '''telstar'''

In addition, a Docker network will need to created to allow the images to communicate, and a Docker volume is desirable to allow for configuration changes and the addition of plugins.

== Create the Docker Network and Volumes ==

The Docker network is used to allow communication between the TELSTAR application and the ''mongo'' database. The volumes provide a means to persist configuration data, plugins to be added and the ''mongo'' databse itself.

The following commands will create the resources required.

$ docker network create telstar-network
$ docker volume create telstar-volume
$ docker volume create mongo-volume

== Pull the Images and Run the Containers ==

It is highly recommended that the Stacks feature of Portainer, inconjunction with a compose file is used to install and manage Telstar. But to get started quickly the following docker commands can be used. See [[Managing Telstar with Portainer]] and [[Orchestrating Telstar with Docker Compose]].

Pull the required images as follows (example shows amd64 image, see https://hub.docker.com/repository/docker/johnnewcombe/telstar/tags?page=1&ordering=last_updated) for the latest version for your architecture.

$ docker pull johnnewcombe/telstar:amd64-2.0-RC3.23 .
$ docker pull mongo

''Please note that the tag used with the official mongo image may need to be set to the system architecture that is to be used. Please see https://hub.docker.com/_/mongo.//

Start the ''mongodb'' container and connect it to the previously created network using the command below.

''Please note that the '--name' parameter is important as it is used as part of the database connection string from the TELSTAR container.''

$ docker run --name telstar-mongo --network telstar-network -v mongo-volume:/data/db -d -e MONGO_INITDB_ROOT_USERNAME=mongoadmin -e MONGO_INITDB_ROOT_PASSWORD=secret mongo

The Docker ''run'' command can be used to start the Telstar container and connect it to the previously created network. Note that in the example below the internal port is specified as 6512 and that this is mapped to the same port on the host system. This is also specified at the end of the command to inform TELSTAR that this is the port to listen on.

$ docker run --rm -d --name telstar-server --network telstar-network -p 6512:6512 -v telstar-volume:/opt/telstar/volume johnnewcombe/telstar:amd64-2.0-RC3.23 server --port=6512

In order to add some example content to the system, the ''init'' parameter can be used as in the example below.

$ docker run --rm -d --name telstar-server --network telstar-network -p 6512:6512 -v telstar-volume:/opt/telstar/volume johnnewcombe/telstar:amd64-2.0-RC3.23 server --port=6512 --init

If the ''--init'' switch is used as in the example above, the service will be running with some example content (see [[Example Content]]) and can be accessed using a suitable client.

In order to add additional content to the system the Telstar API can be used, this can be started as follows (see [[the Telstar API]] for mor details).

docker run --rm -d --name telstar-api --network telstar-network -p 8011:8011 -e TELSTAR_API_USERID=2222222222 -e TELSTAR_API_PASSWORD=1234 -e TELSTAR_COOKIE_SECRET=b6c7a826-96d6-4f45-88c4-3cf27cc2c647 johnnewcombe/telstar:amd64-2.0-RC3.23 api --port 8001 --init

The simplest way to test the system from a desktop machine is to use the [[Telstar Viewdata Client]] alternatively Telnet can be used. TELSTAR is not a Telnet application but telnet can be used to provide a ''sanity check'' e.g.

$ telnet <ip-of-docker-host> <port-used-for-telstar>

If the system is working, a display similar to the following would be shown.

Connected to glasstty.com.
Escape character is '^]'.

20201128T1316Z
L TE
ST
Welcome

$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
Welcome to theTELSTAR
videotex service.

You are connected toELIOT.
$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
...

The screen looks a little garbled simply because TELSTAR is a videotex application not a Telnet application.

== Docker Compose and Kubernetes ==

In the examples above the Docker command was used to set up the system. Howevevr, it may be more appropriate to use Docker Compose See [[Orchestrating Telstar with Docker Compose]]. Telstar could even be implemented using Kubernetes, see [[Orchestrating Telstar with Kubernetes]] sections for other examples.

== Configuration ==

Configuration options for the docker containers can be specified using environment variables, these can be specified as part of the ''docker run'' command or within the Docker Compose yaml file (see above). Full details of all of the available environment variables can be found in the section [[Configuration Options]].

== Portainer ==

The Docker environmemnt can be managed using Portainer, see [[Managing Telstar with Portainer]].

[[File:2827664245-portainer.png]]

Installing Telstar

2022-05-07T17:03:44Z

John: /* Pull the Images and Run the Containers */

It is recommended that Telstar is installed into a Docker environment. The required images are available from https://hub.docker.com/repository/docker/johnnewcombe/telstar. The following examples can be used to install and run Telstar. In addition
examples are also given for orchestrating the services using both Docker Compose and Kubernetes.

To run Telstar using Docker, a minimum of two Docker images are required.

* The official Docker image '''mongodb'''
* The Docker image '''telstar'''

In addition, a Docker network will need to created to allow the images to communicate, and a Docker volume is desirable to allow for configuration changes and the addition of plugins.

== Create the Docker Network and Volumes ==

The Docker network is used to allow communication between the TELSTAR application and the ''mongo'' database. The volumes provide a means to persist configuration data, plugins to be added and the ''mongo'' databse itself.

The following commands will create the resources required.

$ docker network create telstar-network
$ docker volume create telstar-volume
$ docker volume create mongo-volume

== Pull the Images and Run the Containers ==

It is highly recommended that the Stacks feature of Portainer, inconjunction with a compose file is used to install and manage Telstar. But to get started quickly the following docker commands can be used. See [[Managing Telstar with Portainer]] and

Pull the required images as follows (example shows amd64 image, see https://hub.docker.com/repository/docker/johnnewcombe/telstar/tags?page=1&ordering=last_updated) for the latest version for your architecture.

$ docker pull johnnewcombe/telstar:amd64-2.0-RC3.23 .
$ docker pull mongo

''Please note that the tag used with the official mongo image may need to be set to the system architecture that is to be used. Please see https://hub.docker.com/_/mongo.//

Start the ''mongodb'' container and connect it to the previously created network using the command below.

''Please note that the '--name' parameter is important as it is used as part of the database connection string from the TELSTAR container.''

$ docker run --name telstar-mongo --network telstar-network -v mongo-volume:/data/db -d -e MONGO_INITDB_ROOT_USERNAME=mongoadmin -e MONGO_INITDB_ROOT_PASSWORD=secret mongo

The Docker ''run'' command can be used to start the Telstar container and connect it to the previously created network. Note that in the example below the internal port is specified as 6512 and that this is mapped to the same port on the host system. This is also specified at the end of the command to inform TELSTAR that this is the port to listen on.

$ docker run --rm -d --name telstar-server --network telstar-network -p 6512:6512 -v telstar-volume:/opt/telstar/volume johnnewcombe/telstar:amd64-2.0-RC3.23 server --port=6512

In order to add some example content to the system, the ''init'' parameter can be used as in the example below.

$ docker run --rm -d --name telstar-server --network telstar-network -p 6512:6512 -v telstar-volume:/opt/telstar/volume johnnewcombe/telstar:amd64-2.0-RC3.23 server --port=6512 --init

If the ''--init'' switch is used as in the example above, the service will be running with some example content (see [[Example Content]]) and can be accessed using a suitable client.

In order to add additional content to the system the Telstar API can be used, this can be started as follows (see [[the Telstar API]] for mor details).

docker run --rm -d --name telstar-api --network telstar-network -p 8011:8011 -e TELSTAR_API_USERID=2222222222 -e TELSTAR_API_PASSWORD=1234 -e TELSTAR_COOKIE_SECRET=b6c7a826-96d6-4f45-88c4-3cf27cc2c647 johnnewcombe/telstar:amd64-2.0-RC3.23 api --port 8001 --init

The simplest way to test the system from a desktop machine is to use the [[Telstar Viewdata Client]] alternatively Telnet can be used. TELSTAR is not a Telnet application but telnet can be used to provide a ''sanity check'' e.g.

$ telnet <ip-of-docker-host> <port-used-for-telstar>

If the system is working, a display similar to the following would be shown.

Connected to glasstty.com.
Escape character is '^]'.

20201128T1316Z
L TE
ST
Welcome

$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
Welcome to theTELSTAR
videotex service.

You are connected toELIOT.
$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
...

The screen looks a little garbled simply because TELSTAR is a videotex application not a Telnet application.

== Docker Compose and Kubernetes ==

In the examples above the Docker command was used to set up the system. Howevevr, it may be more appropriate to use Docker Compose See [[Orchestrating Telstar with Docker Compose]]. Telstar could even be implemented using Kubernetes, see [[Orchestrating Telstar with Kubernetes]] sections for other examples.

== Configuration ==

Configuration options for the docker containers can be specified using environment variables, these can be specified as part of the ''docker run'' command or within the Docker Compose yaml file (see above). Full details of all of the available environment variables can be found in the section [[Configuration Options]].

== Portainer ==

The Docker environmemnt can be managed using Portainer, see [[Managing Telstar with Portainer]].

[[File:2827664245-portainer.png]]

Installing Telstar

2022-05-07T17:03:05Z

John: /* Pull the Images and Run the Containers */

It is recommended that Telstar is installed into a Docker environment. The required images are available from https://hub.docker.com/repository/docker/johnnewcombe/telstar. The following examples can be used to install and run Telstar. In addition
examples are also given for orchestrating the services using both Docker Compose and Kubernetes.

To run Telstar using Docker, a minimum of two Docker images are required.

* The official Docker image '''mongodb'''
* The Docker image '''telstar'''

In addition, a Docker network will need to created to allow the images to communicate, and a Docker volume is desirable to allow for configuration changes and the addition of plugins.

== Create the Docker Network and Volumes ==

The Docker network is used to allow communication between the TELSTAR application and the ''mongo'' database. The volumes provide a means to persist configuration data, plugins to be added and the ''mongo'' databse itself.

The following commands will create the resources required.

$ docker network create telstar-network
$ docker volume create telstar-volume
$ docker volume create mongo-volume

== Pull the Images and Run the Containers ==

It is highly recommended that the Stacks feature of Portainer, inconjunction with a compose file is used to install and manage Telstar. But to get started quickly the following docker commands can be used.

Pull the required images as follows (example shows amd64 image, see https://hub.docker.com/repository/docker/johnnewcombe/telstar/tags?page=1&ordering=last_updated) for the latest version for your architecture.

$ docker pull johnnewcombe/telstar:amd64-2.0-RC3.23 .
$ docker pull mongo

''Please note that the tag used with the official mongo image may need to be set to the system architecture that is to be used. Please see https://hub.docker.com/_/mongo.//

Start the ''mongodb'' container and connect it to the previously created network using the command below.

''Please note that the '--name' parameter is important as it is used as part of the database connection string from the TELSTAR container.''

$ docker run --name telstar-mongo --network telstar-network -v mongo-volume:/data/db -d -e MONGO_INITDB_ROOT_USERNAME=mongoadmin -e MONGO_INITDB_ROOT_PASSWORD=secret mongo

The Docker ''run'' command can be used to start the Telstar container and connect it to the previously created network. Note that in the example below the internal port is specified as 6512 and that this is mapped to the same port on the host system. This is also specified at the end of the command to inform TELSTAR that this is the port to listen on.

$ docker run --rm -d --name telstar-server --network telstar-network -p 6512:6512 -v telstar-volume:/opt/telstar/volume johnnewcombe/telstar:amd64-2.0-RC3.23 server --port=6512

In order to add some example content to the system, the ''init'' parameter can be used as in the example below.

$ docker run --rm -d --name telstar-server --network telstar-network -p 6512:6512 -v telstar-volume:/opt/telstar/volume johnnewcombe/telstar:amd64-2.0-RC3.23 server --port=6512 --init

If the ''--init'' switch is used as in the example above, the service will be running with some example content (see [[Example Content]]) and can be accessed using a suitable client.

In order to add additional content to the system the Telstar API can be used, this can be started as follows (see [[the Telstar API]] for mor details).

docker run --rm -d --name telstar-api --network telstar-network -p 8011:8011 -e TELSTAR_API_USERID=2222222222 -e TELSTAR_API_PASSWORD=1234 -e TELSTAR_COOKIE_SECRET=b6c7a826-96d6-4f45-88c4-3cf27cc2c647 johnnewcombe/telstar:amd64-2.0-RC3.23 api --port 8001 --init

The simplest way to test the system from a desktop machine is to use the [[Telstar Viewdata Client]] alternatively Telnet can be used. TELSTAR is not a Telnet application but telnet can be used to provide a ''sanity check'' e.g.

$ telnet <ip-of-docker-host> <port-used-for-telstar>

If the system is working, a display similar to the following would be shown.

Connected to glasstty.com.
Escape character is '^]'.

20201128T1316Z
L TE
ST
Welcome

$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
Welcome to theTELSTAR
videotex service.

You are connected toELIOT.
$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
...

The screen looks a little garbled simply because TELSTAR is a videotex application not a Telnet application.

== Docker Compose and Kubernetes ==

In the examples above the Docker command was used to set up the system. Howevevr, it may be more appropriate to use Docker Compose See [[Orchestrating Telstar with Docker Compose]]. Telstar could even be implemented using Kubernetes, see [[Orchestrating Telstar with Kubernetes]] sections for other examples.

== Configuration ==

Configuration options for the docker containers can be specified using environment variables, these can be specified as part of the ''docker run'' command or within the Docker Compose yaml file (see above). Full details of all of the available environment variables can be found in the section [[Configuration Options]].

== Portainer ==

The Docker environmemnt can be managed using Portainer, see [[Managing Telstar with Portainer]].

[[File:2827664245-portainer.png]]

Installing Telstar

2022-05-07T08:52:38Z

John: /* Pull the Images and Run the Containers */

It is recommended that Telstar is installed into a Docker environment. The required images are available from https://hub.docker.com/repository/docker/johnnewcombe/telstar. The following examples can be used to install and run Telstar. In addition
examples are also given for orchestrating the services using both Docker Compose and Kubernetes.

To run Telstar using Docker, a minimum of two Docker images are required.

* The official Docker image '''mongodb'''
* The Docker image '''telstar'''

In addition, a Docker network will need to created to allow the images to communicate, and a Docker volume is desirable to allow for configuration changes and the addition of plugins.

== Create the Docker Network and Volumes ==

The Docker network is used to allow communication between the TELSTAR application and the ''mongo'' database. The volumes provide a means to persist configuration data, plugins to be added and the ''mongo'' databse itself.

The following commands will create the resources required.

$ docker network create telstar-network
$ docker volume create telstar-volume
$ docker volume create mongo-volume

== Pull the Images and Run the Containers ==

Pull the required images as follows (example shows amd64 image, see https://hub.docker.com/repository/docker/johnnewcombe/telstar/tags?page=1&ordering=last_updated) for the latest version for your architecture.

$ docker pull johnnewcombe/telstar:amd64-2.0-RC3.23 .
$ docker pull mongo

''Please note that the tag used with the official mongo image may need to be set to the system architecture that is to be used. Please see https://hub.docker.com/_/mongo.//

Start the ''mongodb'' container and connect it to the previously created network using the command below.

''Please note that the '--name' parameter is important as it is used as part of the database connection string from the TELSTAR container.''

$ docker run --name telstar-mongo --network telstar-network -v mongo-volume:/data/db -d -e MONGO_INITDB_ROOT_USERNAME=mongoadmin -e MONGO_INITDB_ROOT_PASSWORD=secret mongo

The Docker ''run'' command can be used to start the Telstar container and connect it to the previously created network. Note that in the example below the internal port is specified as 6512 and that this is mapped to the same port on the host system. This is also specified at the end of the command to inform TELSTAR that this is the port to listen on.

$ docker run --rm -d --name telstar-server --network telstar-network -p 6512:6512 -v telstar-volume:/opt/telstar/volume johnnewcombe/telstar:amd64-2.0-RC3.23 server --port=6512

In order to add some example content to the system, the ''init'' parameter can be used as in the example below.

$ docker run --rm -d --name telstar-server --network telstar-network -p 6512:6512 -v telstar-volume:/opt/telstar/volume johnnewcombe/telstar:amd64-2.0-RC3.23 server --port=6512 --init

If the ''--init'' switch is used as in the example above, the service will be running with some example content (see [[Example Content]]) and can be accessed using a suitable client.

In order to add additional content to the system the Telstar API can be used, this can be started as follows (see [[the Telstar API]] for mor details).

docker run --rm -d --name telstar-api --network telstar-network -p 8011:8011 -e TELSTAR_API_USERID=2222222222 -e TELSTAR_API_PASSWORD=1234 -e TELSTAR_COOKIE_SECRET=b6c7a826-96d6-4f45-88c4-3cf27cc2c647 johnnewcombe/telstar:amd64-2.0-RC3.23 api --port 8001 --init

The simplest way to test the system from a desktop machine is to use the [[Telstar Viewdata Client]] alternatively Telnet can be used. TELSTAR is not a Telnet application but telnet can be used to provide a ''sanity check'' e.g.

$ telnet <ip-of-docker-host> <port-used-for-telstar>

If the system is working, a display similar to the following would be shown.

Connected to glasstty.com.
Escape character is '^]'.

20201128T1316Z
L TE
ST
Welcome

$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
Welcome to theTELSTAR
videotex service.

You are connected toELIOT.
$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
...

The screen looks a little garbled simply because TELSTAR is a videotex application not a Telnet application.

== Docker Compose and Kubernetes ==

In the examples above the Docker command was used to set up the system. Howevevr, it may be more appropriate to use Docker Compose See [[Orchestrating Telstar with Docker Compose]]. Telstar could even be implemented using Kubernetes, see [[Orchestrating Telstar with Kubernetes]] sections for other examples.

== Configuration ==

Configuration options for the docker containers can be specified using environment variables, these can be specified as part of the ''docker run'' command or within the Docker Compose yaml file (see above). Full details of all of the available environment variables can be found in the section [[Configuration Options]].

== Portainer ==

The Docker environmemnt can be managed using Portainer, see [[Managing Telstar with Portainer]].

[[File:2827664245-portainer.png]]

Installing Telstar

2022-05-07T08:51:59Z

John: /* Pull the Images and Run the Containers */

It is recommended that Telstar is installed into a Docker environment. The required images are available from https://hub.docker.com/repository/docker/johnnewcombe/telstar. The following examples can be used to install and run Telstar. In addition
examples are also given for orchestrating the services using both Docker Compose and Kubernetes.

To run Telstar using Docker, a minimum of two Docker images are required.

* The official Docker image '''mongodb'''
* The Docker image '''telstar'''

In addition, a Docker network will need to created to allow the images to communicate, and a Docker volume is desirable to allow for configuration changes and the addition of plugins.

== Create the Docker Network and Volumes ==

The Docker network is used to allow communication between the TELSTAR application and the ''mongo'' database. The volumes provide a means to persist configuration data, plugins to be added and the ''mongo'' databse itself.

The following commands will create the resources required.

$ docker network create telstar-network
$ docker volume create telstar-volume
$ docker volume create mongo-volume

== Pull the Images and Run the Containers ==

Pull the required images as follows (example shows amd64 image, see https://hub.docker.com/repository/docker/johnnewcombe/telstar/tags?page=1&ordering=last_updated) for the latest version.

$ docker pull johnnewcombe/telstar:amd64-2.0-RC3.23 .
$ docker pull mongo

''Please note that the tag used with the official mongo image may need to be set to the system architecture that is to be used. Please see https://hub.docker.com/_/mongo.//

Start the ''mongodb'' container and connect it to the previously created network using the command below.

''Please note that the '--name' parameter is important as it is used as part of the database connection string from the TELSTAR container.''

$ docker run --name telstar-mongo --network telstar-network -v mongo-volume:/data/db -d -e MONGO_INITDB_ROOT_USERNAME=mongoadmin -e MONGO_INITDB_ROOT_PASSWORD=secret mongo

The Docker ''run'' command can be used to start the Telstar container and connect it to the previously created network. Note that in the example below the internal port is specified as 6512 and that this is mapped to the same port on the host system. This is also specified at the end of the command to inform TELSTAR that this is the port to listen on.

$ docker run --rm -d --name telstar-server --network telstar-network -p 6512:6512 -v telstar-volume:/opt/telstar/volume johnnewcombe/telstar:amd64-2.0-RC3.23 server --port=6512

In order to add some example content to the system, the ''init'' parameter can be used as in the example below.

$ docker run --rm -d --name telstar-server --network telstar-network -p 6512:6512 -v telstar-volume:/opt/telstar/volume johnnewcombe/telstar:amd64-2.0-RC3.23 server --port=6512 --init

If the ''--init'' switch is used as in the example above, the service will be running with some example content (see [[Example Content]]) and can be accessed using a suitable client.

In order to add additional content to the system the Telstar API can be used, this can be started as follows (see [[the Telstar API]] for mor details).

docker run --rm -d --name telstar-api --network telstar-network -p 8011:8011 -e TELSTAR_API_USERID=2222222222 -e TELSTAR_API_PASSWORD=1234 -e TELSTAR_COOKIE_SECRET=b6c7a826-96d6-4f45-88c4-3cf27cc2c647 johnnewcombe/telstar:amd64-2.0-RC3.23 api --port 8001 --init

The simplest way to test the system from a desktop machine is to use the [[Telstar Viewdata Client]] alternatively Telnet can be used. TELSTAR is not a Telnet application but telnet can be used to provide a ''sanity check'' e.g.

$ telnet <ip-of-docker-host> <port-used-for-telstar>

If the system is working, a display similar to the following would be shown.

Connected to glasstty.com.
Escape character is '^]'.

20201128T1316Z
L TE
ST
Welcome

$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
Welcome to theTELSTAR
videotex service.

You are connected toELIOT.
$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
...

The screen looks a little garbled simply because TELSTAR is a videotex application not a Telnet application.

== Docker Compose and Kubernetes ==

In the examples above the Docker command was used to set up the system. Howevevr, it may be more appropriate to use Docker Compose See [[Orchestrating Telstar with Docker Compose]]. Telstar could even be implemented using Kubernetes, see [[Orchestrating Telstar with Kubernetes]] sections for other examples.

== Configuration ==

Configuration options for the docker containers can be specified using environment variables, these can be specified as part of the ''docker run'' command or within the Docker Compose yaml file (see above). Full details of all of the available environment variables can be found in the section [[Configuration Options]].

== Portainer ==

The Docker environmemnt can be managed using Portainer, see [[Managing Telstar with Portainer]].

[[File:2827664245-portainer.png]]

Orchestrating Telstar with Docker Compose

2022-05-07T08:49:50Z

John: /* Example Docker Compose Yaml Files */

Docker Compose is a tool for defining and running multi-container Docker applications. With Compose, you use a YAML file to configure your application’s services. Then, with a single command, you create and start all the services from your configuration. Given that a YAML file has been defined and stored in ''docker-compoe.ymal'', the following command will start the docker containers.

$ docker-compose up -d

To stop the containers, the following command can be used.

$ docker-compose down

Full details of Docker Compose can be found at https://docs.docker.com/compose/

== Example Docker Compose Yaml Files ==

The following docker-compose yaml file can be used to manage the Telstar application and associated ''mongo'' database.

version: "3.8"
services:
telstar-01:
container_name: "telstar-server"
image: "johnnewcombe/telstar:amd64-2.0-RC3.23"
command: "server --port 6512 --init"
ports:
- target: 6512
published: 6512
networks:
- telstar-network
volumes:
- type: volume
source: telstar-volume
target: /opt/telstar/volume
depends_on:
- mongodb
environment:
- TELSTAR_SERVER_DISPLAY_NAME=AUSTEN
mongodb:
container_name: "telstar-mongo"
image: "mongo"
ports:
- target: 27017
published: 27017
networks:
telstar-network:
environment:
- MONGO_INITDB_ROOT_USERNAME=mongoadmin
- MONGO_INITDB_ROOT_PASSWORD=secret
networks:
telstar-network:
name: telstar-network
volumes:
telstar-volume:
name: telstar-volume

The following docker-compose file starts three Telstar servers all talking to the same database server, however the third server (telstar-server-03) includes an environment variable that ensures that it uses the ''secondary'' database. This ''secondary'' database collection is typically used to test content before publishing it to the primary database collection. Further details of all of the available environment variables can be found in the section [[Configuration Options]]. In addition, the Telstar API is launched as a separate container.

version: "3.8"
services:
telstar-01:
container_name: "telstar-server-01"
build: .
image: "johnnewcombe/telstar:amd64-2.0-RC3.23"
command: "server --port 6512 --init" # install to the primary database
ports:
- target: 6512
published: 6512
networks:
- telstar-network
volumes:
- type: volume
source: telstar-volume
target: /opt/telstar/volume
depends_on:
- mongodb
environment:
- TELSTAR_SERVER_DISPLAY_NAME=AUSTEN
telstar-02:
container_name: "telstar-server-02"
image: "johnnewcombe/telstar:amd64-2.0-RC3.23"
command: "server --port 6513"
ports:
- target: 6513
published: 6513
networks:
- telstar-network
volumes:
- type: volume
source: telstar-volume
target: /opt/telstar/volume
depends_on:
- mongodb
environment:
- TELSTAR_SERVER_DISPLAY_NAME=ELIOT
telstar-03:
container_name: "telstar-server-03"
image: "johnnewcombe/telstar:amd64-2.0-RC3.23"
command: "server --port 6514 --init" # install to the secondary database
ports:
- target: 6514
published: 6514
networks:
- telstar-network
volumes:
- type: volume
source: telstar-volume
target: /opt/telstar/volume
depends_on:
- mongodb
environment:
- TELSTAR_SERVER_DISPLAY_NAME=HARDY
- TELSTAR_DBCOLLECTION=SECONDARY
telstar-api:
container_name: "telstar-api"
image: "johnnewcombe/telstar:amd64-2.0-RC3.23"
command: "api --port 8001 --init"
ports:
- target: 8001
published: 8001
networks:
- telstar-network
depends_on:
- mongodb
environment:
- TELSTAR_API_USERID=2222222222
- TELSTAR_API_PASSWORD=1234
- TELSTAR_COOKIE_SECRET=<place yout secret here> # define this for yourself and keep it secret, a GUID is a good option.
mongodb:
container_name: "telstar-mongo"
image: "mongo"
ports:
- target: 27017
published: 27017
networks:
telstar-network:
environment:
- MONGO_INITDB_ROOT_USERNAME=mongoadmin
- MONGO_INITDB_ROOT_PASSWORD=secret
networks:
telstar-network:
name: telstar-network
volumes:
telstar-volume:
name: telstar-volume

Installing Telstar

2022-05-07T08:49:07Z

John: /* Pull the Images and Run the Containers */

It is recommended that Telstar is installed into a Docker environment. The required images are available from https://hub.docker.com/repository/docker/johnnewcombe/telstar. The following examples can be used to install and run Telstar. In addition
examples are also given for orchestrating the services using both Docker Compose and Kubernetes.

To run Telstar using Docker, a minimum of two Docker images are required.

* The official Docker image '''mongodb'''
* The Docker image '''telstar'''

In addition, a Docker network will need to created to allow the images to communicate, and a Docker volume is desirable to allow for configuration changes and the addition of plugins.

== Create the Docker Network and Volumes ==

The Docker network is used to allow communication between the TELSTAR application and the ''mongo'' database. The volumes provide a means to persist configuration data, plugins to be added and the ''mongo'' databse itself.

The following commands will create the resources required.

$ docker network create telstar-network
$ docker volume create telstar-volume
$ docker volume create mongo-volume

== Pull the Images and Run the Containers ==

Pull the required images as follows (example shows amd64 image, see https://hub.docker.com/repository/docker/johnnewcombe/telstar/tags?page=1&ordering=last_updated).

$ docker pull johnnewcombe/telstar:amd64-2.0-RC3.23 .
$ docker pull mongo

''Please note that the tag used with the official mongo image may need to be set to the system architecture that is to be used. Please see https://hub.docker.com/_/mongo.//

Start the ''mongodb'' container and connect it to the previously created network using the command below.

''Please note that the '--name' parameter is important as it is used as part of the database connection string from the TELSTAR container.''

$ docker run --name telstar-mongo --network telstar-network -v mongo-volume:/data/db -d -e MONGO_INITDB_ROOT_USERNAME=mongoadmin -e MONGO_INITDB_ROOT_PASSWORD=secret mongo

The Docker ''run'' command can be used to start the Telstar container and connect it to the previously created network. Note that in the example below the internal port is specified as 6512 and that this is mapped to the same port on the host system. This is also specified at the end of the command to inform TELSTAR that this is the port to listen on.

$ docker run --rm -d --name telstar-server --network telstar-network -p 6512:6512 -v telstar-volume:/opt/telstar/volume johnnewcombe/telstar:amd64-2.0-RC3.23 server --port=6512

In order to add some example content to the system, the ''init'' parameter can be used as in the example below.

$ docker run --rm -d --name telstar-server --network telstar-network -p 6512:6512 -v telstar-volume:/opt/telstar/volume johnnewcombe/telstar:amd64-2.0-RC3.23 server --port=6512 --init

If the ''--init'' switch is used as in the example above, the service will be running with some example content (see [[Example Content]]) and can be accessed using a suitable client.

In order to add additional content to the system the Telstar API can be used, this can be started as follows (see [[the Telstar API]] for mor details).

docker run --rm -d --name telstar-api --network telstar-network -p 8011:8011 -e TELSTAR_API_USERID=2222222222 -e TELSTAR_API_PASSWORD=1234 -e TELSTAR_COOKIE_SECRET=b6c7a826-96d6-4f45-88c4-3cf27cc2c647 johnnewcombe/telstar:amd64-2.0-RC3.23 api --port 8001 --init

The simplest way to test the system from a desktop machine is to use the [[Telstar Viewdata Client]] alternatively Telnet can be used. TELSTAR is not a Telnet application but telnet can be used to provide a ''sanity check'' e.g.

$ telnet <ip-of-docker-host> <port-used-for-telstar>

If the system is working, a display similar to the following would be shown.

Connected to glasstty.com.
Escape character is '^]'.

20201128T1316Z
L TE
ST
Welcome

$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
Welcome to theTELSTAR
videotex service.

You are connected toELIOT.
$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
...

The screen looks a little garbled simply because TELSTAR is a videotex application not a Telnet application.

== Docker Compose and Kubernetes ==

In the examples above the Docker command was used to set up the system. Howevevr, it may be more appropriate to use Docker Compose See [[Orchestrating Telstar with Docker Compose]]. Telstar could even be implemented using Kubernetes, see [[Orchestrating Telstar with Kubernetes]] sections for other examples.

== Configuration ==

Configuration options for the docker containers can be specified using environment variables, these can be specified as part of the ''docker run'' command or within the Docker Compose yaml file (see above). Full details of all of the available environment variables can be found in the section [[Configuration Options]].

== Portainer ==

The Docker environmemnt can be managed using Portainer, see [[Managing Telstar with Portainer]].

[[File:2827664245-portainer.png]]

Frames

2022-04-24T19:25:09Z

John: /* redirect */

As is typical with interactive videotex systems, pages are numbered from 0 to 999999999 and consist of one or more frames with the suffix a-z, for example the first frame for page 200 would be 200a, the second 200b and so on (see [[Routing]]) for more details). These frames are stored within TELSTAR's database as ''JSON'' objects (see https://www.json.org/) and uploaded to Telstar using a simple command line utility.

The Telstar utility program simply interacts with the Telstar API which is a restful API. This can be used directly by any software making it simple to programitically manage pages and routing information.

Frames are defined in JSON. The simplest frame that can be viewed on TELSTAR would be as follows. This would create a simple information frame with some flashing content. In this example [[Markup]] has been used within the content, however, other content types can be used including edi.tf urls, see below.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"content": {
"data": "[D]This is page[F]101a",
"type": "markup"
}
}

Shown below is a more complete example of a JSON defined frame. With this particular frame, the actual viewdata content has been created using the editor at http://edit.tf, this can be seen in the ''content.data'' and ''content.type'' keys. The example below is a simple information page with some simple routing (see [[Routing]]). Clicking the ''content.data'' link, or pasteing the value into a browser will show the page and allow it to be edited. It is not necessary to use the http://edit.tf editor, this is just one possible option.

{
"pid": {
"page-no": 0,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"content": {
"data": "http://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMMKAbNw6dyCTuyZfCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgKJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRAxQR4s6LSgzEEmdUi0otOogkzo0-lNg1JM-cCg8unNYgQIASBBj67OnXllWIMu7pl5dMOndty7uixBoy4dnTQsQIECBAgBIEHfLh2dNCDDuyINmnNl59POzKuQIECBAgQIECBAgQIECBAyQTotemggzoiCvFg1JEWkCnYemnfuw7EGHdkQIECBAgQIASBBp3dMvLdh6ad-7DsQbsvfmgw7siDvlw9NGXkuQIECBAgQM0EKrTkzotOmgkzo0-lNg1JM-cCh79vDDu8oMO7IgQIECAEgQYuvPTuy8-aDdl781wM6EjVKcVBMw9MvPogoctOPLzQIEDRBHn1otKdNizqiCTOjT6U2DUkz5wKlvw5OaxByw6dixAgBIEGHdkQUMPLZpw7cu7ouQIECBAgQIECBAgQIECBAgQIECBA2QR4NSLXg2UFOLSrSYcWmCnWKkWYsQVIsWNBsLEEOHMaIASBBh3ZEHTRlQQ9-zfz54diCHh7ZUGHJ2y7unXllXIECBAgQN0EifMkxINmmCqcsPbLsQYd2RBI37NOTD5QbsvfmuQIECBA4CHQc2TDpT50WogcMGCAScgoOnLTi69MqDpvQdNGnmgQIAaBBzy8u2nHlQd9PTQgqZdmXnvzdO-HllQYd2RBt38sq5AgQOQ0yfHQT40ZYgp2adSLNQSZ0aegTIKkWnUQUIMeLTQIECAokSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEFeLBqSItJBGn0osODTqIBIM6EQIEFDDnyoFTJywvoECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf"
},
"routing-table": [0,1,11,3,400,5,6,7,800,9,0],
"cursor": false,
}

== Adding Frames to the System ==

Frames can be added to the system using either the Telstar API.

The Telstar API, in conjunction with the cross platform Telstar Util software, provides a simple method of creating and managing pages.

The API can be used to retrieve and update frames and configuring routing. The API is a restful API that uses the GET, PUT, POST and DELETE HTTP methods and as such can be used from any application.

Data is passed to and from the API in JSON format, making the system very simple to use in any programming language. The whole API could be used without any programming at all by using a command line utility such as CURL.

''Further details of the Telstar API can be found in the section [[The Telstar API]].''

== Adding Content with the Edit.tf editor ==

There are several ways to add content to a page. One of the easiest is to create the page in an editor such as http://edit.tf.

The JSON file would look something like the one showm below. Note that the content type is set to editf and the content data contains the edit.tf url.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"content": {
"data": "http://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICn_OmTJkSJApUqVKlSpUlcHApiTJkyZEiRIkyZMmTIkSJFmKf3JX58____RBg-fPnzog__2iBBo-fNX9qgQcOHDh8-fGiAp_zFf______2v7_____7X___oEGr__Qa0ur_________QoCn9ywK__6D__a__7dH__tf___1QIv_9AiQIkaPX_bo0aMpiKf_-Yr__oP_9r__tUH_-1____9og__yjnz5cldX9qUc-fPkp__uSv_-g__2v_-1Qf_7X__aIv____KZv_dIV__2pTN___yn__mK___z__a____5__tf_9qgVf__8o5_vWJX__alHP___Kf_7kr____6dBr_____-h__2qBBr__ymbPnSFf69CUzf__8pnz5iq9ejRoECBWvXr0KBGjQYOHBHz4cECBAgwcCily7__yqDhw4ePnzogQeP7RAg0fPiBB___9X___QYPH___-sCmb__KoP________3B__tUCDV__tUH___1f36XB-_______KOf_8qgRo__9B__v9X___QINX___Qav__B8-NNX_-jR___8pm__ymYrq______h_odX9qg1f___7q__9X_-h1f_5TBgwYM37__KOSur-_Ro0Pr_8_f_qDV_b___r__1f_6D___lFKlSpUu__8pmK_v7VAgwf______tNX9r______V__oP__-gQaPnwpm__yqDB__tUCD__QIEG___1f2qL____9X_-g____z5-__ymb__KoNX_-lQKl6VAgQav6_V__oNf___1f2qBX_____9-hKOf_8qgVJ0JRw4cOPLkqiQoESNGgVL0aFEjQoECJGjRoymDNm__ymTJkzZv3_____-3bt27du3Thw8efPnz58-fPnz58-fP___QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf"
}
}

== Adding Content using Markup ==

Content can be added directly to the JSON file using a very simple markup. For example consider the following frame definition.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"title": {
"data": "[D]Welcome\r\n\r\n",
"type": "markup"
},
"content": {
"data": "[Y]Hello[C]Telstar[M]World",
"type": "markup"
}
}

This frame uses markup in the title and the content, The title is specified as [D]ouble height and the three words used in the content are coloured yellow, cyan and magenta respectively.

Full details of markup can be found in the [[Markup]] section.

== Complete Frame Description ==

The frame below is a standard information page from the TELSTAR system shown in its JSON format. It represents the first frame of page 9. Taking this frame as an example, a description of the fields and their meaning is decribed below.

''The full json schema can be found [[Frame Schema|here]].''

{
"pid": {
"page-no": 9,
"frame-id": "a"
},
"visible": true,
"header-text": "",
"cost": 0,
"frame-type": "information",
"redirect": {
"page-no": 0,
"frame-id": ""
},
"content": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgc4UCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAxQIIs6PJnRYtKTOjoKkWnUQUIMeLTQIECBAgQIECBAgQIEDRAgp2adSLNQSZ0aegQIECBAgQIECBAgQIECBAgQIECBAgQNkCCPBqRa8GygpxaVaTDi00CBAgQIECBAgQIECBAgQIECBA4QIIc-dUgw6iCJFqQZMymgQIECBAgQIECBAgQIECBAgQIEDlAgmT46CfOQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMECCZPjoJ8aMgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgBVAMUNMQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIAVQDFDTAlMPUQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUAxQ0wJTD1A0EHSQIECBAgQIECBAgQIECBAgQIECBAgQIECANMCUw9QNBB0kCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAPUDQQdJAgQIECBAgQIECBAgQIECAosWLFixYsWLFixYsQIECAHSQIECAosWLFixYsWLFixYsWIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf'
},
"title": {
"data": "",
"type": "",
"merge-data": []
},
"routing-table": [
90,
91,
92,
93,
94,
95,
96,
97,
98,
990,
0
],
"cursor": false,
"connection": {
"address": "",
"mode": "",
"port": 0
},
"author-id": "",
"response-data": {
"responses": null,
"response-action": {
"exec": "",
"args": null,
"post-action-frame": {
"page-no": 0,
"frame-id": ''
},
"post-cancel-frame": {
"page-no": 0,
"frame-id": ""
}
}
},
"navmessage-select": "[B][n][Y]Select item or[W]*page# : [_+]",
"navmessage-notfound": "[B][n][Y]Page not Found :[W]"
}

=== pid ===

Specifies the page number and frame id for the frame.

"pid": {
"page-no": 9,
"frame-id": "a"
},

=== visible ===

When set to false, the frame will not be accessible and will return the ''not found'' system message to the user if an attempt is made to access it.

"visible": true,

=== header-text ===

Allows the default header text to be ovwerridden at frame level. If this is left blank the default header will be used, see configuration.

"header-text": "[Y]MICRONETn 800 (C)",

=== cost ===

"cost": 0,

=== frame-type ===

The API supports the following frame types ''initial'', ''mainindex'', ''information'', ''exit'', ''gateway'', ''test'' and ''response''.

"frame-type": "information",

* '''initial''': This frame type is used on the start page, see [[Configuration Options]]. Typically only one of these frames would exist within a system.
* '''mainindex''': This frame type is used on the main index page. , see [[Configuration Options]]. Only one of these frames should exist within a system.
* '''information''': This frame type is used for all normal content frames.
* '''exit''': This frame type is used for an exit page, any number of exit pages can be defined. When an exit page is rendered it will close the connection.
* '''gateway''': This page type is used to define a gateway page and is used in conjunction with the connection element (see below).
* '''test''': This page type indicates a test page and prevents navigation and system messages from being shown. this is typically used for frames that need to use the whole display such as 'test cards' etc.
* '''telesoftware''': Telesoftware frames (see [[Telesoftware]]).
* '''response''': This frame type is used for response frames. See [[Implementing Response Frames]].
* '''system''': Reserved for use internally.
* '''exception''': Reserved for use internally.

=== redirect ===

If set it simply means that the user is redirected to the specified frame. This can be a useful alternative form of navigation to the routing table.

"redirect": {
"page-no": 9,
"frame-id": "a"
},

The following is an example of a complete redirect page.

{
"PID": {
"page-no": 2,
"frame-id": "a"
},
"redirect": {
"page-no": 11,
"frame-id": "a"
},
"visible": true
}

=== content ===

These elements define the content. The example below shows the content.type to be an edit.tf url. The available types are shown below.

"content": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgc4UCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAxQIIs6PJnRYtKTOjoKkWnUQUIMeLTQIECBAgQIECBAgQIEDRAgp2adSLNQSZ0aegQIECBAgQIECBAgQIECBAgQIECBAgQNkCCPBqRa8GygpxaVaTDi00CBAgQIECBAgQIECBAgQIECBA4QIIc-dUgw6iCJFqQZMymgQIECBAgQIECBAgQIECBAgQIEDlAgmT46CfOQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMECCZPjoJ8aMgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgBVAMUNMQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIAVQDFDTAlMPUQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUAxQ0wJTD1A0EHSQIECBAgQIECBAgQIECBAgQIECBAgQIECANMCUw9QNBB0kCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAPUDQQdJAgQIECBAgQIECBAgQIECAosWLFixYsWLFixYsQIECAHSQIECAosWLFixYsWLFixYsWIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf'
},

Content types:

* '''edit.tf''': If set, then the content will be treated as an edit.tf url. This is converted to RawV before being rendered.
* '''markup''': If set, then the content will be treated as ''markup'' content. Full details of ''markup'' can be found in the section [[Markup]]
* '''rawV''': If set, then the content will be treated as raw videotex data. This is 7bit (00-7F) videotex format with control chars between 00-1F and escaped codes for alpha and graphic attributes. Ideally rows should have any trailing spaces removed and replaced with with a CR/LF combination. This will be rendered as is.
* '''rawT''': If set, then the content will be treated as raw teletex data. This is a 24 x 40 block of 7 bits chars (960 chars) in Teletext format (range 00-7F). This format is used internally when manipulating page data. It will be converted to RawV before being rendered.

=== title ===

This sets the title of the page. In many cases this may be left blank with all of the content specified in the ''content'' section (see above) however, the ''title'' section gives additional flexibility when creating frames.

Values for ''title-type'' are the same as defined for the content section, however, if the type ''edit-tf'' is used then only the first four (default) lines of the edit.tf defined page are used.

Separating title from content in this way allows logos and header sections to be created for the title whilst using markup for the main content or visa-versa.

==== Example 1 ====

In thi example the fields are blank meaning that only the data in the ''content'' section is displayed.

"title": {
"data": "",
"type": "",
"merge-data": []
},

==== Example 2 ====

In this example, the top 4 lines of the edit.tf content is displayed at the top of the page.

"title": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAvobotqBX__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIC_9AgQIEGv-gQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgL_0Cj4kQav6BAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAuq64P6Dx__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf",
"merge-data": []
},

To take the top 5 lines, the ''type'' field can be extended as follows.

"type": "edit.tf,5"

Note that this extended form of ''type'' only applies to edit.tf types.

==== Example 3 ====

The merge data field can be used to add ''layers'' of markup data to the title area. For example the example above shows the Guardian logo. To add some alphagraphics text to this, an additional layer could be used e.g.

"title": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAvobotqBX__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIC_9AgQIEGv-gQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgL_0Cj4kQav6BAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAuq64P6Dx__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf,5",
"merge-data": [
"[w[ UK News]]"
]
},

Note that any number of layers can be added, however, the merge layer must be defined as markup.

=== routing table ===

The routing table defines which pages are navigated to when a user presses a key whilst viewing the frame. The table has 11 entries with the first 10 representing the keys 0-9, the final entry refers to the ''hash'' (return) key.

The example below shows the default routing table for frame 9a. If the user is viewing this frame and presses 1 the frame 91a will be loaded, assuming it exists. Pressing the ''hash'' (return) key will take the user back to frame 0a, the main index.

"routing-table": [
90,
91,
92,
93,
94,
95,
96,
97,
98,
99,
0
],

=== cursor ===

This element determines whether a cursor is shown on the page. Typically a cursor would only be shown on response frames.

"cursor": false,

=== connection ===

This elements specifies the connection object used for gateway pages.

"connection": {
"address": "fish.ccl4.org",
"mode": "viewdata",
"port": 23
},

The values for ''address and port'' represent the endpoint of the system being accessed and the value for ''mode'' determines how the system is accessed, the options are:

viewdata
full_duplex
full_duplex_no_echo

=== author-id ===

This is an optional field that can be used to indicate the author of the page or other source.

"author-id": "john",

=== response-data ===

These fields should be used when the frame type is set to be a ''response-frame''.

There are two main sections, ''response-data'' and ''response-action''. Below is an example of a response frame used for the Telstar weather page. The frame is created in the normal way using ''markup'' or ''edit.tf''. In this example the text ''Town/Cty'' has been positioned near the centre of the page. Immediately to the right of this is a field for the user to enter either a Town or City, the ''response-data'' section defines that field. Once the user submits the frame the section ''response-action'' determines what happens. In the example here a binary file (''telstar-openweather-linux-amd64''), stored in the containers volume directory is executed with a single argument (''myopenweatherapikey''). Note that the ''post-action-frame'' is set to 290b, in this example frame 290b is dynamically generated by the binary file ''telstar-openweather-linux-amd64'' and contains the weather forecast.

Full details of how to implement response frames are detailed in the section [[Implementing Response Frames]].
"response-data": {
"response-fields": [
{
"vpos": 8,
"hpos": 4,
"required": true,
"length": 16,
"type": "alphanumeric",
"auto-submit": false,
"password": false
}
],
"response-action": {
"exec": "/opt/telstar/volume/telstar-openweather-linux-amd64",
"args": [
"myopenweatherapikey"
],
"post-action-frame": {
"page-no": 290,
"frame-id": "c"
}
}
},

=== navmessage-select ===

Allows the ''navigation'' system message to be customised at frame level. In most cases this can be left blank in order that the system default is used instead, see [[Configuration Options]].

"navmessage-select": "[B][n][Y]Select item or[W]*page# : [_+]",

=== navmessage-notfound ===

Allows the ''not found'' system message to be customised at frame level. In most cases this can be left blank in order that the system default is used instead, see [[Configuration Options]].

"navmessage-notfound": "[B][n][Y]Page not Found :[W]"

Frames

2022-04-24T19:24:19Z

John: /* redirect */

As is typical with interactive videotex systems, pages are numbered from 0 to 999999999 and consist of one or more frames with the suffix a-z, for example the first frame for page 200 would be 200a, the second 200b and so on (see [[Routing]]) for more details). These frames are stored within TELSTAR's database as ''JSON'' objects (see https://www.json.org/) and uploaded to Telstar using a simple command line utility.

The Telstar utility program simply interacts with the Telstar API which is a restful API. This can be used directly by any software making it simple to programitically manage pages and routing information.

Frames are defined in JSON. The simplest frame that can be viewed on TELSTAR would be as follows. This would create a simple information frame with some flashing content. In this example [[Markup]] has been used within the content, however, other content types can be used including edi.tf urls, see below.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"content": {
"data": "[D]This is page[F]101a",
"type": "markup"
}
}

Shown below is a more complete example of a JSON defined frame. With this particular frame, the actual viewdata content has been created using the editor at http://edit.tf, this can be seen in the ''content.data'' and ''content.type'' keys. The example below is a simple information page with some simple routing (see [[Routing]]). Clicking the ''content.data'' link, or pasteing the value into a browser will show the page and allow it to be edited. It is not necessary to use the http://edit.tf editor, this is just one possible option.

{
"pid": {
"page-no": 0,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"content": {
"data": "http://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMMKAbNw6dyCTuyZfCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgKJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRAxQR4s6LSgzEEmdUi0otOogkzo0-lNg1JM-cCg8unNYgQIASBBj67OnXllWIMu7pl5dMOndty7uixBoy4dnTQsQIECBAgBIEHfLh2dNCDDuyINmnNl59POzKuQIECBAgQIECBAgQIECBAyQTotemggzoiCvFg1JEWkCnYemnfuw7EGHdkQIECBAgQIASBBp3dMvLdh6ad-7DsQbsvfmgw7siDvlw9NGXkuQIECBAgQM0EKrTkzotOmgkzo0-lNg1JM-cCh79vDDu8oMO7IgQIECAEgQYuvPTuy8-aDdl781wM6EjVKcVBMw9MvPogoctOPLzQIEDRBHn1otKdNizqiCTOjT6U2DUkz5wKlvw5OaxByw6dixAgBIEGHdkQUMPLZpw7cu7ouQIECBAgQIECBAgQIECBAgQIECBA2QR4NSLXg2UFOLSrSYcWmCnWKkWYsQVIsWNBsLEEOHMaIASBBh3ZEHTRlQQ9-zfz54diCHh7ZUGHJ2y7unXllXIECBAgQN0EifMkxINmmCqcsPbLsQYd2RBI37NOTD5QbsvfmuQIECBA4CHQc2TDpT50WogcMGCAScgoOnLTi69MqDpvQdNGnmgQIAaBBzy8u2nHlQd9PTQgqZdmXnvzdO-HllQYd2RBt38sq5AgQOQ0yfHQT40ZYgp2adSLNQSZ0aegTIKkWnUQUIMeLTQIECAokSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEFeLBqSItJBGn0osODTqIBIM6EQIEFDDnyoFTJywvoECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf"
},
"routing-table": [0,1,11,3,400,5,6,7,800,9,0],
"cursor": false,
}

== Adding Frames to the System ==

Frames can be added to the system using either the Telstar API.

The Telstar API, in conjunction with the cross platform Telstar Util software, provides a simple method of creating and managing pages.

The API can be used to retrieve and update frames and configuring routing. The API is a restful API that uses the GET, PUT, POST and DELETE HTTP methods and as such can be used from any application.

Data is passed to and from the API in JSON format, making the system very simple to use in any programming language. The whole API could be used without any programming at all by using a command line utility such as CURL.

''Further details of the Telstar API can be found in the section [[The Telstar API]].''

== Adding Content with the Edit.tf editor ==

There are several ways to add content to a page. One of the easiest is to create the page in an editor such as http://edit.tf.

The JSON file would look something like the one showm below. Note that the content type is set to editf and the content data contains the edit.tf url.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"content": {
"data": "http://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICn_OmTJkSJApUqVKlSpUlcHApiTJkyZEiRIkyZMmTIkSJFmKf3JX58____RBg-fPnzog__2iBBo-fNX9qgQcOHDh8-fGiAp_zFf______2v7_____7X___oEGr__Qa0ur_________QoCn9ywK__6D__a__7dH__tf___1QIv_9AiQIkaPX_bo0aMpiKf_-Yr__oP_9r__tUH_-1____9og__yjnz5cldX9qUc-fPkp__uSv_-g__2v_-1Qf_7X__aIv____KZv_dIV__2pTN___yn__mK___z__a____5__tf_9qgVf__8o5_vWJX__alHP___Kf_7kr____6dBr_____-h__2qBBr__ymbPnSFf69CUzf__8pnz5iq9ejRoECBWvXr0KBGjQYOHBHz4cECBAgwcCily7__yqDhw4ePnzogQeP7RAg0fPiBB___9X___QYPH___-sCmb__KoP________3B__tUCDV__tUH___1f36XB-_______KOf_8qgRo__9B__v9X___QINX___Qav__B8-NNX_-jR___8pm__ymYrq______h_odX9qg1f___7q__9X_-h1f_5TBgwYM37__KOSur-_Ro0Pr_8_f_qDV_b___r__1f_6D___lFKlSpUu__8pmK_v7VAgwf______tNX9r______V__oP__-gQaPnwpm__yqDB__tUCD__QIEG___1f2qL____9X_-g____z5-__ymb__KoNX_-lQKl6VAgQav6_V__oNf___1f2qBX_____9-hKOf_8qgVJ0JRw4cOPLkqiQoESNGgVL0aFEjQoECJGjRoymDNm__ymTJkzZv3_____-3bt27du3Thw8efPnz58-fPnz58-fP___QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf"
}
}

== Adding Content using Markup ==

Content can be added directly to the JSON file using a very simple markup. For example consider the following frame definition.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"title": {
"data": "[D]Welcome\r\n\r\n",
"type": "markup"
},
"content": {
"data": "[Y]Hello[C]Telstar[M]World",
"type": "markup"
}
}

This frame uses markup in the title and the content, The title is specified as [D]ouble height and the three words used in the content are coloured yellow, cyan and magenta respectively.

Full details of markup can be found in the [[Markup]] section.

== Complete Frame Description ==

The frame below is a standard information page from the TELSTAR system shown in its JSON format. It represents the first frame of page 9. Taking this frame as an example, a description of the fields and their meaning is decribed below.

''The full json schema can be found [[Frame Schema|here]].''

{
"pid": {
"page-no": 9,
"frame-id": "a"
},
"visible": true,
"header-text": "",
"cost": 0,
"frame-type": "information",
"redirect": {
"page-no": 0,
"frame-id": ""
},
"content": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgc4UCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAxQIIs6PJnRYtKTOjoKkWnUQUIMeLTQIECBAgQIECBAgQIEDRAgp2adSLNQSZ0aegQIECBAgQIECBAgQIECBAgQIECBAgQNkCCPBqRa8GygpxaVaTDi00CBAgQIECBAgQIECBAgQIECBA4QIIc-dUgw6iCJFqQZMymgQIECBAgQIECBAgQIECBAgQIEDlAgmT46CfOQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMECCZPjoJ8aMgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgBVAMUNMQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIAVQDFDTAlMPUQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUAxQ0wJTD1A0EHSQIECBAgQIECBAgQIECBAgQIECBAgQIECANMCUw9QNBB0kCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAPUDQQdJAgQIECBAgQIECBAgQIECAosWLFixYsWLFixYsQIECAHSQIECAosWLFixYsWLFixYsWIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf'
},
"title": {
"data": "",
"type": "",
"merge-data": []
},
"routing-table": [
90,
91,
92,
93,
94,
95,
96,
97,
98,
990,
0
],
"cursor": false,
"connection": {
"address": "",
"mode": "",
"port": 0
},
"author-id": "",
"response-data": {
"responses": null,
"response-action": {
"exec": "",
"args": null,
"post-action-frame": {
"page-no": 0,
"frame-id": ''
},
"post-cancel-frame": {
"page-no": 0,
"frame-id": ""
}
}
},
"navmessage-select": "[B][n][Y]Select item or[W]*page# : [_+]",
"navmessage-notfound": "[B][n][Y]Page not Found :[W]"
}

=== pid ===

Specifies the page number and frame id for the frame.

"pid": {
"page-no": 9,
"frame-id": "a"
},

=== visible ===

When set to false, the frame will not be accessible and will return the ''not found'' system message to the user if an attempt is made to access it.

"visible": true,

=== header-text ===

Allows the default header text to be ovwerridden at frame level. If this is left blank the default header will be used, see configuration.

"header-text": "[Y]MICRONETn 800 (C)",

=== cost ===

"cost": 0,

=== frame-type ===

The API supports the following frame types ''initial'', ''mainindex'', ''information'', ''exit'', ''gateway'', ''test'' and ''response''.

"frame-type": "information",

* '''initial''': This frame type is used on the start page, see [[Configuration Options]]. Typically only one of these frames would exist within a system.
* '''mainindex''': This frame type is used on the main index page. , see [[Configuration Options]]. Only one of these frames should exist within a system.
* '''information''': This frame type is used for all normal content frames.
* '''exit''': This frame type is used for an exit page, any number of exit pages can be defined. When an exit page is rendered it will close the connection.
* '''gateway''': This page type is used to define a gateway page and is used in conjunction with the connection element (see below).
* '''test''': This page type indicates a test page and prevents navigation and system messages from being shown. this is typically used for frames that need to use the whole display such as 'test cards' etc.
* '''telesoftware''': Telesoftware frames (see [[Telesoftware]]).
* '''response''': This frame type is used for response frames. See [[Implementing Response Frames]].
* '''system''': Reserved for use internally.
* '''exception''': Reserved for use internally.

=== redirect ===

If set it simply means that the user is redirected to the specified frame. This can be a useful alternative form of navigation to the routing table.

"redirect": {
"page-no": 9,
"frame-id": "a"
},

The following is an example of a complete redirect page.

{
"PID": {
"page-no": 9,
"frame-id": "a"
},
"redirect": {
"page-no": 9,
"frame-id": "a"
},
"visible": true
}

=== content ===

These elements define the content. The example below shows the content.type to be an edit.tf url. The available types are shown below.

"content": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgc4UCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAxQIIs6PJnRYtKTOjoKkWnUQUIMeLTQIECBAgQIECBAgQIEDRAgp2adSLNQSZ0aegQIECBAgQIECBAgQIECBAgQIECBAgQNkCCPBqRa8GygpxaVaTDi00CBAgQIECBAgQIECBAgQIECBA4QIIc-dUgw6iCJFqQZMymgQIECBAgQIECBAgQIECBAgQIEDlAgmT46CfOQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMECCZPjoJ8aMgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgBVAMUNMQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIAVQDFDTAlMPUQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUAxQ0wJTD1A0EHSQIECBAgQIECBAgQIECBAgQIECBAgQIECANMCUw9QNBB0kCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAPUDQQdJAgQIECBAgQIECBAgQIECAosWLFixYsWLFixYsQIECAHSQIECAosWLFixYsWLFixYsWIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf'
},

Content types:

* '''edit.tf''': If set, then the content will be treated as an edit.tf url. This is converted to RawV before being rendered.
* '''markup''': If set, then the content will be treated as ''markup'' content. Full details of ''markup'' can be found in the section [[Markup]]
* '''rawV''': If set, then the content will be treated as raw videotex data. This is 7bit (00-7F) videotex format with control chars between 00-1F and escaped codes for alpha and graphic attributes. Ideally rows should have any trailing spaces removed and replaced with with a CR/LF combination. This will be rendered as is.
* '''rawT''': If set, then the content will be treated as raw teletex data. This is a 24 x 40 block of 7 bits chars (960 chars) in Teletext format (range 00-7F). This format is used internally when manipulating page data. It will be converted to RawV before being rendered.

=== title ===

This sets the title of the page. In many cases this may be left blank with all of the content specified in the ''content'' section (see above) however, the ''title'' section gives additional flexibility when creating frames.

Values for ''title-type'' are the same as defined for the content section, however, if the type ''edit-tf'' is used then only the first four (default) lines of the edit.tf defined page are used.

Separating title from content in this way allows logos and header sections to be created for the title whilst using markup for the main content or visa-versa.

==== Example 1 ====

In thi example the fields are blank meaning that only the data in the ''content'' section is displayed.

"title": {
"data": "",
"type": "",
"merge-data": []
},

==== Example 2 ====

In this example, the top 4 lines of the edit.tf content is displayed at the top of the page.

"title": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAvobotqBX__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIC_9AgQIEGv-gQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgL_0Cj4kQav6BAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAuq64P6Dx__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf",
"merge-data": []
},

To take the top 5 lines, the ''type'' field can be extended as follows.

"type": "edit.tf,5"

Note that this extended form of ''type'' only applies to edit.tf types.

==== Example 3 ====

The merge data field can be used to add ''layers'' of markup data to the title area. For example the example above shows the Guardian logo. To add some alphagraphics text to this, an additional layer could be used e.g.

"title": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAvobotqBX__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIC_9AgQIEGv-gQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgL_0Cj4kQav6BAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAuq64P6Dx__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf,5",
"merge-data": [
"[w[ UK News]]"
]
},

Note that any number of layers can be added, however, the merge layer must be defined as markup.

=== routing table ===

The routing table defines which pages are navigated to when a user presses a key whilst viewing the frame. The table has 11 entries with the first 10 representing the keys 0-9, the final entry refers to the ''hash'' (return) key.

The example below shows the default routing table for frame 9a. If the user is viewing this frame and presses 1 the frame 91a will be loaded, assuming it exists. Pressing the ''hash'' (return) key will take the user back to frame 0a, the main index.

"routing-table": [
90,
91,
92,
93,
94,
95,
96,
97,
98,
99,
0
],

=== cursor ===

This element determines whether a cursor is shown on the page. Typically a cursor would only be shown on response frames.

"cursor": false,

=== connection ===

This elements specifies the connection object used for gateway pages.

"connection": {
"address": "fish.ccl4.org",
"mode": "viewdata",
"port": 23
},

The values for ''address and port'' represent the endpoint of the system being accessed and the value for ''mode'' determines how the system is accessed, the options are:

viewdata
full_duplex
full_duplex_no_echo

=== author-id ===

This is an optional field that can be used to indicate the author of the page or other source.

"author-id": "john",

=== response-data ===

These fields should be used when the frame type is set to be a ''response-frame''.

There are two main sections, ''response-data'' and ''response-action''. Below is an example of a response frame used for the Telstar weather page. The frame is created in the normal way using ''markup'' or ''edit.tf''. In this example the text ''Town/Cty'' has been positioned near the centre of the page. Immediately to the right of this is a field for the user to enter either a Town or City, the ''response-data'' section defines that field. Once the user submits the frame the section ''response-action'' determines what happens. In the example here a binary file (''telstar-openweather-linux-amd64''), stored in the containers volume directory is executed with a single argument (''myopenweatherapikey''). Note that the ''post-action-frame'' is set to 290b, in this example frame 290b is dynamically generated by the binary file ''telstar-openweather-linux-amd64'' and contains the weather forecast.

Full details of how to implement response frames are detailed in the section [[Implementing Response Frames]].
"response-data": {
"response-fields": [
{
"vpos": 8,
"hpos": 4,
"required": true,
"length": 16,
"type": "alphanumeric",
"auto-submit": false,
"password": false
}
],
"response-action": {
"exec": "/opt/telstar/volume/telstar-openweather-linux-amd64",
"args": [
"myopenweatherapikey"
],
"post-action-frame": {
"page-no": 290,
"frame-id": "c"
}
}
},

=== navmessage-select ===

Allows the ''navigation'' system message to be customised at frame level. In most cases this can be left blank in order that the system default is used instead, see [[Configuration Options]].

"navmessage-select": "[B][n][Y]Select item or[W]*page# : [_+]",

=== navmessage-notfound ===

Allows the ''not found'' system message to be customised at frame level. In most cases this can be left blank in order that the system default is used instead, see [[Configuration Options]].

"navmessage-notfound": "[B][n][Y]Page not Found :[W]"

Frames

2022-04-24T19:23:21Z

John: /* redirect */

As is typical with interactive videotex systems, pages are numbered from 0 to 999999999 and consist of one or more frames with the suffix a-z, for example the first frame for page 200 would be 200a, the second 200b and so on (see [[Routing]]) for more details). These frames are stored within TELSTAR's database as ''JSON'' objects (see https://www.json.org/) and uploaded to Telstar using a simple command line utility.

The Telstar utility program simply interacts with the Telstar API which is a restful API. This can be used directly by any software making it simple to programitically manage pages and routing information.

Frames are defined in JSON. The simplest frame that can be viewed on TELSTAR would be as follows. This would create a simple information frame with some flashing content. In this example [[Markup]] has been used within the content, however, other content types can be used including edi.tf urls, see below.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"content": {
"data": "[D]This is page[F]101a",
"type": "markup"
}
}

Shown below is a more complete example of a JSON defined frame. With this particular frame, the actual viewdata content has been created using the editor at http://edit.tf, this can be seen in the ''content.data'' and ''content.type'' keys. The example below is a simple information page with some simple routing (see [[Routing]]). Clicking the ''content.data'' link, or pasteing the value into a browser will show the page and allow it to be edited. It is not necessary to use the http://edit.tf editor, this is just one possible option.

{
"pid": {
"page-no": 0,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"content": {
"data": "http://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMMKAbNw6dyCTuyZfCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgKJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRAxQR4s6LSgzEEmdUi0otOogkzo0-lNg1JM-cCg8unNYgQIASBBj67OnXllWIMu7pl5dMOndty7uixBoy4dnTQsQIECBAgBIEHfLh2dNCDDuyINmnNl59POzKuQIECBAgQIECBAgQIECBAyQTotemggzoiCvFg1JEWkCnYemnfuw7EGHdkQIECBAgQIASBBp3dMvLdh6ad-7DsQbsvfmgw7siDvlw9NGXkuQIECBAgQM0EKrTkzotOmgkzo0-lNg1JM-cCh79vDDu8oMO7IgQIECAEgQYuvPTuy8-aDdl781wM6EjVKcVBMw9MvPogoctOPLzQIEDRBHn1otKdNizqiCTOjT6U2DUkz5wKlvw5OaxByw6dixAgBIEGHdkQUMPLZpw7cu7ouQIECBAgQIECBAgQIECBAgQIECBA2QR4NSLXg2UFOLSrSYcWmCnWKkWYsQVIsWNBsLEEOHMaIASBBh3ZEHTRlQQ9-zfz54diCHh7ZUGHJ2y7unXllXIECBAgQN0EifMkxINmmCqcsPbLsQYd2RBI37NOTD5QbsvfmuQIECBA4CHQc2TDpT50WogcMGCAScgoOnLTi69MqDpvQdNGnmgQIAaBBzy8u2nHlQd9PTQgqZdmXnvzdO-HllQYd2RBt38sq5AgQOQ0yfHQT40ZYgp2adSLNQSZ0aegTIKkWnUQUIMeLTQIECAokSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEFeLBqSItJBGn0osODTqIBIM6EQIEFDDnyoFTJywvoECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf"
},
"routing-table": [0,1,11,3,400,5,6,7,800,9,0],
"cursor": false,
}

== Adding Frames to the System ==

Frames can be added to the system using either the Telstar API.

The Telstar API, in conjunction with the cross platform Telstar Util software, provides a simple method of creating and managing pages.

The API can be used to retrieve and update frames and configuring routing. The API is a restful API that uses the GET, PUT, POST and DELETE HTTP methods and as such can be used from any application.

Data is passed to and from the API in JSON format, making the system very simple to use in any programming language. The whole API could be used without any programming at all by using a command line utility such as CURL.

''Further details of the Telstar API can be found in the section [[The Telstar API]].''

== Adding Content with the Edit.tf editor ==

There are several ways to add content to a page. One of the easiest is to create the page in an editor such as http://edit.tf.

The JSON file would look something like the one showm below. Note that the content type is set to editf and the content data contains the edit.tf url.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"content": {
"data": "http://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICn_OmTJkSJApUqVKlSpUlcHApiTJkyZEiRIkyZMmTIkSJFmKf3JX58____RBg-fPnzog__2iBBo-fNX9qgQcOHDh8-fGiAp_zFf______2v7_____7X___oEGr__Qa0ur_________QoCn9ywK__6D__a__7dH__tf___1QIv_9AiQIkaPX_bo0aMpiKf_-Yr__oP_9r__tUH_-1____9og__yjnz5cldX9qUc-fPkp__uSv_-g__2v_-1Qf_7X__aIv____KZv_dIV__2pTN___yn__mK___z__a____5__tf_9qgVf__8o5_vWJX__alHP___Kf_7kr____6dBr_____-h__2qBBr__ymbPnSFf69CUzf__8pnz5iq9ejRoECBWvXr0KBGjQYOHBHz4cECBAgwcCily7__yqDhw4ePnzogQeP7RAg0fPiBB___9X___QYPH___-sCmb__KoP________3B__tUCDV__tUH___1f36XB-_______KOf_8qgRo__9B__v9X___QINX___Qav__B8-NNX_-jR___8pm__ymYrq______h_odX9qg1f___7q__9X_-h1f_5TBgwYM37__KOSur-_Ro0Pr_8_f_qDV_b___r__1f_6D___lFKlSpUu__8pmK_v7VAgwf______tNX9r______V__oP__-gQaPnwpm__yqDB__tUCD__QIEG___1f2qL____9X_-g____z5-__ymb__KoNX_-lQKl6VAgQav6_V__oNf___1f2qBX_____9-hKOf_8qgVJ0JRw4cOPLkqiQoESNGgVL0aFEjQoECJGjRoymDNm__ymTJkzZv3_____-3bt27du3Thw8efPnz58-fPnz58-fP___QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf"
}
}

== Adding Content using Markup ==

Content can be added directly to the JSON file using a very simple markup. For example consider the following frame definition.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"title": {
"data": "[D]Welcome\r\n\r\n",
"type": "markup"
},
"content": {
"data": "[Y]Hello[C]Telstar[M]World",
"type": "markup"
}
}

This frame uses markup in the title and the content, The title is specified as [D]ouble height and the three words used in the content are coloured yellow, cyan and magenta respectively.

Full details of markup can be found in the [[Markup]] section.

== Complete Frame Description ==

The frame below is a standard information page from the TELSTAR system shown in its JSON format. It represents the first frame of page 9. Taking this frame as an example, a description of the fields and their meaning is decribed below.

''The full json schema can be found [[Frame Schema|here]].''

{
"pid": {
"page-no": 9,
"frame-id": "a"
},
"visible": true,
"header-text": "",
"cost": 0,
"frame-type": "information",
"redirect": {
"page-no": 0,
"frame-id": ""
},
"content": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgc4UCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAxQIIs6PJnRYtKTOjoKkWnUQUIMeLTQIECBAgQIECBAgQIEDRAgp2adSLNQSZ0aegQIECBAgQIECBAgQIECBAgQIECBAgQNkCCPBqRa8GygpxaVaTDi00CBAgQIECBAgQIECBAgQIECBA4QIIc-dUgw6iCJFqQZMymgQIECBAgQIECBAgQIECBAgQIEDlAgmT46CfOQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMECCZPjoJ8aMgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgBVAMUNMQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIAVQDFDTAlMPUQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUAxQ0wJTD1A0EHSQIECBAgQIECBAgQIECBAgQIECBAgQIECANMCUw9QNBB0kCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAPUDQQdJAgQIECBAgQIECBAgQIECAosWLFixYsWLFixYsQIECAHSQIECAosWLFixYsWLFixYsWIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf'
},
"title": {
"data": "",
"type": "",
"merge-data": []
},
"routing-table": [
90,
91,
92,
93,
94,
95,
96,
97,
98,
990,
0
],
"cursor": false,
"connection": {
"address": "",
"mode": "",
"port": 0
},
"author-id": "",
"response-data": {
"responses": null,
"response-action": {
"exec": "",
"args": null,
"post-action-frame": {
"page-no": 0,
"frame-id": ''
},
"post-cancel-frame": {
"page-no": 0,
"frame-id": ""
}
}
},
"navmessage-select": "[B][n][Y]Select item or[W]*page# : [_+]",
"navmessage-notfound": "[B][n][Y]Page not Found :[W]"
}

=== pid ===

Specifies the page number and frame id for the frame.

"pid": {
"page-no": 9,
"frame-id": "a"
},

=== visible ===

When set to false, the frame will not be accessible and will return the ''not found'' system message to the user if an attempt is made to access it.

"visible": true,

=== header-text ===

Allows the default header text to be ovwerridden at frame level. If this is left blank the default header will be used, see configuration.

"header-text": "[Y]MICRONETn 800 (C)",

=== cost ===

"cost": 0,

=== frame-type ===

The API supports the following frame types ''initial'', ''mainindex'', ''information'', ''exit'', ''gateway'', ''test'' and ''response''.

"frame-type": "information",

* '''initial''': This frame type is used on the start page, see [[Configuration Options]]. Typically only one of these frames would exist within a system.
* '''mainindex''': This frame type is used on the main index page. , see [[Configuration Options]]. Only one of these frames should exist within a system.
* '''information''': This frame type is used for all normal content frames.
* '''exit''': This frame type is used for an exit page, any number of exit pages can be defined. When an exit page is rendered it will close the connection.
* '''gateway''': This page type is used to define a gateway page and is used in conjunction with the connection element (see below).
* '''test''': This page type indicates a test page and prevents navigation and system messages from being shown. this is typically used for frames that need to use the whole display such as 'test cards' etc.
* '''telesoftware''': Telesoftware frames (see [[Telesoftware]]).
* '''response''': This frame type is used for response frames. See [[Implementing Response Frames]].
* '''system''': Reserved for use internally.
* '''exception''': Reserved for use internally.

=== redirect ===

If set it simply means that the user is redirected to the specified frame. This can be a useful alternative form of navigation to the routing table.

"redirect": {
"page-no": 9,
"frame-id": "a"
},

The following is an example of a complete redirect page.

{
"PID": {
"page-no": 9,
"frame-id": "a"
},
"redirect": {
"page-no": 9,
"frame-id": "a"
},
"visible: true
}

=== content ===

These elements define the content. The example below shows the content.type to be an edit.tf url. The available types are shown below.

"content": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgc4UCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAxQIIs6PJnRYtKTOjoKkWnUQUIMeLTQIECBAgQIECBAgQIEDRAgp2adSLNQSZ0aegQIECBAgQIECBAgQIECBAgQIECBAgQNkCCPBqRa8GygpxaVaTDi00CBAgQIECBAgQIECBAgQIECBA4QIIc-dUgw6iCJFqQZMymgQIECBAgQIECBAgQIECBAgQIEDlAgmT46CfOQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMECCZPjoJ8aMgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgBVAMUNMQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIAVQDFDTAlMPUQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUAxQ0wJTD1A0EHSQIECBAgQIECBAgQIECBAgQIECBAgQIECANMCUw9QNBB0kCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAPUDQQdJAgQIECBAgQIECBAgQIECAosWLFixYsWLFixYsQIECAHSQIECAosWLFixYsWLFixYsWIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf'
},

Content types:

* '''edit.tf''': If set, then the content will be treated as an edit.tf url. This is converted to RawV before being rendered.
* '''markup''': If set, then the content will be treated as ''markup'' content. Full details of ''markup'' can be found in the section [[Markup]]
* '''rawV''': If set, then the content will be treated as raw videotex data. This is 7bit (00-7F) videotex format with control chars between 00-1F and escaped codes for alpha and graphic attributes. Ideally rows should have any trailing spaces removed and replaced with with a CR/LF combination. This will be rendered as is.
* '''rawT''': If set, then the content will be treated as raw teletex data. This is a 24 x 40 block of 7 bits chars (960 chars) in Teletext format (range 00-7F). This format is used internally when manipulating page data. It will be converted to RawV before being rendered.

=== title ===

This sets the title of the page. In many cases this may be left blank with all of the content specified in the ''content'' section (see above) however, the ''title'' section gives additional flexibility when creating frames.

Values for ''title-type'' are the same as defined for the content section, however, if the type ''edit-tf'' is used then only the first four (default) lines of the edit.tf defined page are used.

Separating title from content in this way allows logos and header sections to be created for the title whilst using markup for the main content or visa-versa.

==== Example 1 ====

In thi example the fields are blank meaning that only the data in the ''content'' section is displayed.

"title": {
"data": "",
"type": "",
"merge-data": []
},

==== Example 2 ====

In this example, the top 4 lines of the edit.tf content is displayed at the top of the page.

"title": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAvobotqBX__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIC_9AgQIEGv-gQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgL_0Cj4kQav6BAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAuq64P6Dx__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf",
"merge-data": []
},

To take the top 5 lines, the ''type'' field can be extended as follows.

"type": "edit.tf,5"

Note that this extended form of ''type'' only applies to edit.tf types.

==== Example 3 ====

The merge data field can be used to add ''layers'' of markup data to the title area. For example the example above shows the Guardian logo. To add some alphagraphics text to this, an additional layer could be used e.g.

"title": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAvobotqBX__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIC_9AgQIEGv-gQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgL_0Cj4kQav6BAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAuq64P6Dx__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf,5",
"merge-data": [
"[w[ UK News]]"
]
},

Note that any number of layers can be added, however, the merge layer must be defined as markup.

=== routing table ===

The routing table defines which pages are navigated to when a user presses a key whilst viewing the frame. The table has 11 entries with the first 10 representing the keys 0-9, the final entry refers to the ''hash'' (return) key.

The example below shows the default routing table for frame 9a. If the user is viewing this frame and presses 1 the frame 91a will be loaded, assuming it exists. Pressing the ''hash'' (return) key will take the user back to frame 0a, the main index.

"routing-table": [
90,
91,
92,
93,
94,
95,
96,
97,
98,
99,
0
],

=== cursor ===

This element determines whether a cursor is shown on the page. Typically a cursor would only be shown on response frames.

"cursor": false,

=== connection ===

This elements specifies the connection object used for gateway pages.

"connection": {
"address": "fish.ccl4.org",
"mode": "viewdata",
"port": 23
},

The values for ''address and port'' represent the endpoint of the system being accessed and the value for ''mode'' determines how the system is accessed, the options are:

viewdata
full_duplex
full_duplex_no_echo

=== author-id ===

This is an optional field that can be used to indicate the author of the page or other source.

"author-id": "john",

=== response-data ===

These fields should be used when the frame type is set to be a ''response-frame''.

There are two main sections, ''response-data'' and ''response-action''. Below is an example of a response frame used for the Telstar weather page. The frame is created in the normal way using ''markup'' or ''edit.tf''. In this example the text ''Town/Cty'' has been positioned near the centre of the page. Immediately to the right of this is a field for the user to enter either a Town or City, the ''response-data'' section defines that field. Once the user submits the frame the section ''response-action'' determines what happens. In the example here a binary file (''telstar-openweather-linux-amd64''), stored in the containers volume directory is executed with a single argument (''myopenweatherapikey''). Note that the ''post-action-frame'' is set to 290b, in this example frame 290b is dynamically generated by the binary file ''telstar-openweather-linux-amd64'' and contains the weather forecast.

Full details of how to implement response frames are detailed in the section [[Implementing Response Frames]].
"response-data": {
"response-fields": [
{
"vpos": 8,
"hpos": 4,
"required": true,
"length": 16,
"type": "alphanumeric",
"auto-submit": false,
"password": false
}
],
"response-action": {
"exec": "/opt/telstar/volume/telstar-openweather-linux-amd64",
"args": [
"myopenweatherapikey"
],
"post-action-frame": {
"page-no": 290,
"frame-id": "c"
}
}
},

=== navmessage-select ===

Allows the ''navigation'' system message to be customised at frame level. In most cases this can be left blank in order that the system default is used instead, see [[Configuration Options]].

"navmessage-select": "[B][n][Y]Select item or[W]*page# : [_+]",

=== navmessage-notfound ===

Allows the ''not found'' system message to be customised at frame level. In most cases this can be left blank in order that the system default is used instead, see [[Configuration Options]].

"navmessage-notfound": "[B][n][Y]Page not Found :[W]"

Frames

2022-04-20T22:43:43Z

John: /* = Example 3 */

As is typical with interactive videotex systems, pages are numbered from 0 to 999999999 and consist of one or more frames with the suffix a-z, for example the first frame for page 200 would be 200a, the second 200b and so on (see [[Routing]]) for more details). These frames are stored within TELSTAR's database as ''JSON'' objects (see https://www.json.org/) and uploaded to Telstar using a simple command line utility.

The Telstar utility program simply interacts with the Telstar API which is a restful API. This can be used directly by any software making it simple to programitically manage pages and routing information.

Frames are defined in JSON. The simplest frame that can be viewed on TELSTAR would be as follows. This would create a simple information frame with some flashing content. In this example [[Markup]] has been used within the content, however, other content types can be used including edi.tf urls, see below.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"content": {
"data": "[D]This is page[F]101a",
"type": "markup"
}
}

Shown below is a more complete example of a JSON defined frame. With this particular frame, the actual viewdata content has been created using the editor at http://edit.tf, this can be seen in the ''content.data'' and ''content.type'' keys. The example below is a simple information page with some simple routing (see [[Routing]]). Clicking the ''content.data'' link, or pasteing the value into a browser will show the page and allow it to be edited. It is not necessary to use the http://edit.tf editor, this is just one possible option.

{
"pid": {
"page-no": 0,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"content": {
"data": "http://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMMKAbNw6dyCTuyZfCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgKJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRAxQR4s6LSgzEEmdUi0otOogkzo0-lNg1JM-cCg8unNYgQIASBBj67OnXllWIMu7pl5dMOndty7uixBoy4dnTQsQIECBAgBIEHfLh2dNCDDuyINmnNl59POzKuQIECBAgQIECBAgQIECBAyQTotemggzoiCvFg1JEWkCnYemnfuw7EGHdkQIECBAgQIASBBp3dMvLdh6ad-7DsQbsvfmgw7siDvlw9NGXkuQIECBAgQM0EKrTkzotOmgkzo0-lNg1JM-cCh79vDDu8oMO7IgQIECAEgQYuvPTuy8-aDdl781wM6EjVKcVBMw9MvPogoctOPLzQIEDRBHn1otKdNizqiCTOjT6U2DUkz5wKlvw5OaxByw6dixAgBIEGHdkQUMPLZpw7cu7ouQIECBAgQIECBAgQIECBAgQIECBA2QR4NSLXg2UFOLSrSYcWmCnWKkWYsQVIsWNBsLEEOHMaIASBBh3ZEHTRlQQ9-zfz54diCHh7ZUGHJ2y7unXllXIECBAgQN0EifMkxINmmCqcsPbLsQYd2RBI37NOTD5QbsvfmuQIECBA4CHQc2TDpT50WogcMGCAScgoOnLTi69MqDpvQdNGnmgQIAaBBzy8u2nHlQd9PTQgqZdmXnvzdO-HllQYd2RBt38sq5AgQOQ0yfHQT40ZYgp2adSLNQSZ0aegTIKkWnUQUIMeLTQIECAokSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEFeLBqSItJBGn0osODTqIBIM6EQIEFDDnyoFTJywvoECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf"
},
"routing-table": [0,1,11,3,400,5,6,7,800,9,0],
"cursor": false,
}

== Adding Frames to the System ==

Frames can be added to the system using either the Telstar API.

The Telstar API, in conjunction with the cross platform Telstar Util software, provides a simple method of creating and managing pages.

The API can be used to retrieve and update frames and configuring routing. The API is a restful API that uses the GET, PUT, POST and DELETE HTTP methods and as such can be used from any application.

Data is passed to and from the API in JSON format, making the system very simple to use in any programming language. The whole API could be used without any programming at all by using a command line utility such as CURL.

''Further details of the Telstar API can be found in the section [[The Telstar API]].''

== Adding Content with the Edit.tf editor ==

There are several ways to add content to a page. One of the easiest is to create the page in an editor such as http://edit.tf.

The JSON file would look something like the one showm below. Note that the content type is set to editf and the content data contains the edit.tf url.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"content": {
"data": "http://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICn_OmTJkSJApUqVKlSpUlcHApiTJkyZEiRIkyZMmTIkSJFmKf3JX58____RBg-fPnzog__2iBBo-fNX9qgQcOHDh8-fGiAp_zFf______2v7_____7X___oEGr__Qa0ur_________QoCn9ywK__6D__a__7dH__tf___1QIv_9AiQIkaPX_bo0aMpiKf_-Yr__oP_9r__tUH_-1____9og__yjnz5cldX9qUc-fPkp__uSv_-g__2v_-1Qf_7X__aIv____KZv_dIV__2pTN___yn__mK___z__a____5__tf_9qgVf__8o5_vWJX__alHP___Kf_7kr____6dBr_____-h__2qBBr__ymbPnSFf69CUzf__8pnz5iq9ejRoECBWvXr0KBGjQYOHBHz4cECBAgwcCily7__yqDhw4ePnzogQeP7RAg0fPiBB___9X___QYPH___-sCmb__KoP________3B__tUCDV__tUH___1f36XB-_______KOf_8qgRo__9B__v9X___QINX___Qav__B8-NNX_-jR___8pm__ymYrq______h_odX9qg1f___7q__9X_-h1f_5TBgwYM37__KOSur-_Ro0Pr_8_f_qDV_b___r__1f_6D___lFKlSpUu__8pmK_v7VAgwf______tNX9r______V__oP__-gQaPnwpm__yqDB__tUCD__QIEG___1f2qL____9X_-g____z5-__ymb__KoNX_-lQKl6VAgQav6_V__oNf___1f2qBX_____9-hKOf_8qgVJ0JRw4cOPLkqiQoESNGgVL0aFEjQoECJGjRoymDNm__ymTJkzZv3_____-3bt27du3Thw8efPnz58-fPnz58-fP___QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf"
}
}

== Adding Content using Markup ==

Content can be added directly to the JSON file using a very simple markup. For example consider the following frame definition.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"title": {
"data": "[D]Welcome\r\n\r\n",
"type": "markup"
},
"content": {
"data": "[Y]Hello[C]Telstar[M]World",
"type": "markup"
}
}

This frame uses markup in the title and the content, The title is specified as [D]ouble height and the three words used in the content are coloured yellow, cyan and magenta respectively.

Full details of markup can be found in the [[Markup]] section.

== Complete Frame Description ==

The frame below is a standard information page from the TELSTAR system shown in its JSON format. It represents the first frame of page 9. Taking this frame as an example, a description of the fields and their meaning is decribed below.

''The full json schema can be found [[Frame Schema|here]].''

{
"pid": {
"page-no": 9,
"frame-id": "a"
},
"visible": true,
"header-text": "",
"cost": 0,
"frame-type": "information",
"redirect": {
"page-no": 0,
"frame-id": ""
},
"content": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgc4UCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAxQIIs6PJnRYtKTOjoKkWnUQUIMeLTQIECBAgQIECBAgQIEDRAgp2adSLNQSZ0aegQIECBAgQIECBAgQIECBAgQIECBAgQNkCCPBqRa8GygpxaVaTDi00CBAgQIECBAgQIECBAgQIECBA4QIIc-dUgw6iCJFqQZMymgQIECBAgQIECBAgQIECBAgQIEDlAgmT46CfOQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMECCZPjoJ8aMgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgBVAMUNMQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIAVQDFDTAlMPUQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUAxQ0wJTD1A0EHSQIECBAgQIECBAgQIECBAgQIECBAgQIECANMCUw9QNBB0kCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAPUDQQdJAgQIECBAgQIECBAgQIECAosWLFixYsWLFixYsQIECAHSQIECAosWLFixYsWLFixYsWIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf'
},
"title": {
"data": "",
"type": "",
"merge-data": []
},
"routing-table": [
90,
91,
92,
93,
94,
95,
96,
97,
98,
990,
0
],
"cursor": false,
"connection": {
"address": "",
"mode": "",
"port": 0
},
"author-id": "",
"response-data": {
"responses": null,
"response-action": {
"exec": "",
"args": null,
"post-action-frame": {
"page-no": 0,
"frame-id": ''
},
"post-cancel-frame": {
"page-no": 0,
"frame-id": ""
}
}
},
"navmessage-select": "[B][n][Y]Select item or[W]*page# : [_+]",
"navmessage-notfound": "[B][n][Y]Page not Found :[W]"
}

=== pid ===

Specifies the page number and frame id for the frame.

"pid": {
"page-no": 9,
"frame-id": "a"
},

=== visible ===

When set to false, the frame will not be accessible and will return the ''not found'' system message to the user if an attempt is made to access it.

"visible": true,

=== header-text ===

Allows the default header text to be ovwerridden at frame level. If this is left blank the default header will be used, see configuration.

"header-text": "[Y]MICRONETn 800 (C)",

=== cost ===

"cost": 0,

=== frame-type ===

The API supports the following frame types ''initial'', ''mainindex'', ''information'', ''exit'', ''gateway'', ''test'' and ''response''.

"frame-type": "information",

* '''initial''': This frame type is used on the start page, see [[Configuration Options]]. Typically only one of these frames would exist within a system.
* '''mainindex''': This frame type is used on the main index page. , see [[Configuration Options]]. Only one of these frames should exist within a system.
* '''information''': This frame type is used for all normal content frames.
* '''exit''': This frame type is used for an exit page, any number of exit pages can be defined. When an exit page is rendered it will close the connection.
* '''gateway''': This page type is used to define a gateway page and is used in conjunction with the connection element (see below).
* '''test''': This page type indicates a test page and prevents navigation and system messages from being shown. this is typically used for frames that need to use the whole display such as 'test cards' etc.
* '''telesoftware''': Telesoftware frames (see [[Telesoftware]]).
* '''response''': This frame type is used for response frames. See [[Implementing Response Frames]].
* '''system''': Reserved for use internally.
* '''exception''': Reserved for use internally.

=== redirect ===

If set it simply means that the user is redirected to the specified frame. This can be a useful alternative form of navigation to the routing table.

"redirect": {
"page-no": 9,
"frame-id": "a"
},

=== content ===

These elements define the content. The example below shows the content.type to be an edit.tf url. The available types are shown below.

"content": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgc4UCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAxQIIs6PJnRYtKTOjoKkWnUQUIMeLTQIECBAgQIECBAgQIEDRAgp2adSLNQSZ0aegQIECBAgQIECBAgQIECBAgQIECBAgQNkCCPBqRa8GygpxaVaTDi00CBAgQIECBAgQIECBAgQIECBA4QIIc-dUgw6iCJFqQZMymgQIECBAgQIECBAgQIECBAgQIEDlAgmT46CfOQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMECCZPjoJ8aMgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgBVAMUNMQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIAVQDFDTAlMPUQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUAxQ0wJTD1A0EHSQIECBAgQIECBAgQIECBAgQIECBAgQIECANMCUw9QNBB0kCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAPUDQQdJAgQIECBAgQIECBAgQIECAosWLFixYsWLFixYsQIECAHSQIECAosWLFixYsWLFixYsWIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf'
},

Content types:

* '''edit.tf''': If set, then the content will be treated as an edit.tf url. This is converted to RawV before being rendered.
* '''markup''': If set, then the content will be treated as ''markup'' content. Full details of ''markup'' can be found in the section [[Markup]]
* '''rawV''': If set, then the content will be treated as raw videotex data. This is 7bit (00-7F) videotex format with control chars between 00-1F and escaped codes for alpha and graphic attributes. Ideally rows should have any trailing spaces removed and replaced with with a CR/LF combination. This will be rendered as is.
* '''rawT''': If set, then the content will be treated as raw teletex data. This is a 24 x 40 block of 7 bits chars (960 chars) in Teletext format (range 00-7F). This format is used internally when manipulating page data. It will be converted to RawV before being rendered.

=== title ===

This sets the title of the page. In many cases this may be left blank with all of the content specified in the ''content'' section (see above) however, the ''title'' section gives additional flexibility when creating frames.

Values for ''title-type'' are the same as defined for the content section, however, if the type ''edit-tf'' is used then only the first four (default) lines of the edit.tf defined page are used.

Separating title from content in this way allows logos and header sections to be created for the title whilst using markup for the main content or visa-versa.

==== Example 1 ====

In thi example the fields are blank meaning that only the data in the ''content'' section is displayed.

"title": {
"data": "",
"type": "",
"merge-data": []
},

==== Example 2 ====

In this example, the top 4 lines of the edit.tf content is displayed at the top of the page.

"title": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAvobotqBX__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIC_9AgQIEGv-gQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgL_0Cj4kQav6BAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAuq64P6Dx__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf",
"merge-data": []
},

To take the top 5 lines, the ''type'' field can be extended as follows.

"type": "edit.tf,5"

Note that this extended form of ''type'' only applies to edit.tf types.

==== Example 3 ====

The merge data field can be used to add ''layers'' of markup data to the title area. For example the example above shows the Guardian logo. To add some alphagraphics text to this, an additional layer could be used e.g.

"title": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAvobotqBX__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIC_9AgQIEGv-gQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgL_0Cj4kQav6BAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAuq64P6Dx__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf,5",
"merge-data": [
"[w[ UK News]]"
]
},

Note that any number of layers can be added, however, the merge layer must be defined as markup.

=== routing table ===

The routing table defines which pages are navigated to when a user presses a key whilst viewing the frame. The table has 11 entries with the first 10 representing the keys 0-9, the final entry refers to the ''hash'' (return) key.

The example below shows the default routing table for frame 9a. If the user is viewing this frame and presses 1 the frame 91a will be loaded, assuming it exists. Pressing the ''hash'' (return) key will take the user back to frame 0a, the main index.

"routing-table": [
90,
91,
92,
93,
94,
95,
96,
97,
98,
99,
0
],

=== cursor ===

This element determines whether a cursor is shown on the page. Typically a cursor would only be shown on response frames.

"cursor": false,

=== connection ===

This elements specifies the connection object used for gateway pages.

"connection": {
"address": "fish.ccl4.org",
"mode": "viewdata",
"port": 23
},

The values for ''address and port'' represent the endpoint of the system being accessed and the value for ''mode'' determines how the system is accessed, the options are:

viewdata
full_duplex
full_duplex_no_echo

=== author-id ===

This is an optional field that can be used to indicate the author of the page or other source.

"author-id": "john",

=== response-data ===

These fields should be used when the frame type is set to be a ''response-frame''.

There are two main sections, ''response-data'' and ''response-action''. Below is an example of a response frame used for the Telstar weather page. The frame is created in the normal way using ''markup'' or ''edit.tf''. In this example the text ''Town/Cty'' has been positioned near the centre of the page. Immediately to the right of this is a field for the user to enter either a Town or City, the ''response-data'' section defines that field. Once the user submits the frame the section ''response-action'' determines what happens. In the example here a binary file (''telstar-openweather-linux-amd64''), stored in the containers volume directory is executed with a single argument (''myopenweatherapikey''). Note that the ''post-action-frame'' is set to 290b, in this example frame 290b is dynamically generated by the binary file ''telstar-openweather-linux-amd64'' and contains the weather forecast.

Full details of how to implement response frames are detailed in the section [[Implementing Response Frames]].
"response-data": {
"response-fields": [
{
"vpos": 8,
"hpos": 4,
"required": true,
"length": 16,
"type": "alphanumeric",
"auto-submit": false,
"password": false
}
],
"response-action": {
"exec": "/opt/telstar/volume/telstar-openweather-linux-amd64",
"args": [
"myopenweatherapikey"
],
"post-action-frame": {
"page-no": 290,
"frame-id": "c"
}
}
},

=== navmessage-select ===

Allows the ''navigation'' system message to be customised at frame level. In most cases this can be left blank in order that the system default is used instead, see [[Configuration Options]].

"navmessage-select": "[B][n][Y]Select item or[W]*page# : [_+]",

=== navmessage-notfound ===

Allows the ''not found'' system message to be customised at frame level. In most cases this can be left blank in order that the system default is used instead, see [[Configuration Options]].

"navmessage-notfound": "[B][n][Y]Page not Found :[W]"

Frames

2022-04-20T22:33:01Z

John:

As is typical with interactive videotex systems, pages are numbered from 0 to 999999999 and consist of one or more frames with the suffix a-z, for example the first frame for page 200 would be 200a, the second 200b and so on (see [[Routing]]) for more details). These frames are stored within TELSTAR's database as ''JSON'' objects (see https://www.json.org/) and uploaded to Telstar using a simple command line utility.

The Telstar utility program simply interacts with the Telstar API which is a restful API. This can be used directly by any software making it simple to programitically manage pages and routing information.

Frames are defined in JSON. The simplest frame that can be viewed on TELSTAR would be as follows. This would create a simple information frame with some flashing content. In this example [[Markup]] has been used within the content, however, other content types can be used including edi.tf urls, see below.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"content": {
"data": "[D]This is page[F]101a",
"type": "markup"
}
}

Shown below is a more complete example of a JSON defined frame. With this particular frame, the actual viewdata content has been created using the editor at http://edit.tf, this can be seen in the ''content.data'' and ''content.type'' keys. The example below is a simple information page with some simple routing (see [[Routing]]). Clicking the ''content.data'' link, or pasteing the value into a browser will show the page and allow it to be edited. It is not necessary to use the http://edit.tf editor, this is just one possible option.

{
"pid": {
"page-no": 0,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"content": {
"data": "http://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMMKAbNw6dyCTuyZfCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgKJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRAxQR4s6LSgzEEmdUi0otOogkzo0-lNg1JM-cCg8unNYgQIASBBj67OnXllWIMu7pl5dMOndty7uixBoy4dnTQsQIECBAgBIEHfLh2dNCDDuyINmnNl59POzKuQIECBAgQIECBAgQIECBAyQTotemggzoiCvFg1JEWkCnYemnfuw7EGHdkQIECBAgQIASBBp3dMvLdh6ad-7DsQbsvfmgw7siDvlw9NGXkuQIECBAgQM0EKrTkzotOmgkzo0-lNg1JM-cCh79vDDu8oMO7IgQIECAEgQYuvPTuy8-aDdl781wM6EjVKcVBMw9MvPogoctOPLzQIEDRBHn1otKdNizqiCTOjT6U2DUkz5wKlvw5OaxByw6dixAgBIEGHdkQUMPLZpw7cu7ouQIECBAgQIECBAgQIECBAgQIECBA2QR4NSLXg2UFOLSrSYcWmCnWKkWYsQVIsWNBsLEEOHMaIASBBh3ZEHTRlQQ9-zfz54diCHh7ZUGHJ2y7unXllXIECBAgQN0EifMkxINmmCqcsPbLsQYd2RBI37NOTD5QbsvfmuQIECBA4CHQc2TDpT50WogcMGCAScgoOnLTi69MqDpvQdNGnmgQIAaBBzy8u2nHlQd9PTQgqZdmXnvzdO-HllQYd2RBt38sq5AgQOQ0yfHQT40ZYgp2adSLNQSZ0aegTIKkWnUQUIMeLTQIECAokSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEFeLBqSItJBGn0osODTqIBIM6EQIEFDDnyoFTJywvoECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf"
},
"routing-table": [0,1,11,3,400,5,6,7,800,9,0],
"cursor": false,
}

== Adding Frames to the System ==

Frames can be added to the system using either the Telstar API.

The Telstar API, in conjunction with the cross platform Telstar Util software, provides a simple method of creating and managing pages.

The API can be used to retrieve and update frames and configuring routing. The API is a restful API that uses the GET, PUT, POST and DELETE HTTP methods and as such can be used from any application.

Data is passed to and from the API in JSON format, making the system very simple to use in any programming language. The whole API could be used without any programming at all by using a command line utility such as CURL.

''Further details of the Telstar API can be found in the section [[The Telstar API]].''

== Adding Content with the Edit.tf editor ==

There are several ways to add content to a page. One of the easiest is to create the page in an editor such as http://edit.tf.

The JSON file would look something like the one showm below. Note that the content type is set to editf and the content data contains the edit.tf url.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"content": {
"data": "http://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICn_OmTJkSJApUqVKlSpUlcHApiTJkyZEiRIkyZMmTIkSJFmKf3JX58____RBg-fPnzog__2iBBo-fNX9qgQcOHDh8-fGiAp_zFf______2v7_____7X___oEGr__Qa0ur_________QoCn9ywK__6D__a__7dH__tf___1QIv_9AiQIkaPX_bo0aMpiKf_-Yr__oP_9r__tUH_-1____9og__yjnz5cldX9qUc-fPkp__uSv_-g__2v_-1Qf_7X__aIv____KZv_dIV__2pTN___yn__mK___z__a____5__tf_9qgVf__8o5_vWJX__alHP___Kf_7kr____6dBr_____-h__2qBBr__ymbPnSFf69CUzf__8pnz5iq9ejRoECBWvXr0KBGjQYOHBHz4cECBAgwcCily7__yqDhw4ePnzogQeP7RAg0fPiBB___9X___QYPH___-sCmb__KoP________3B__tUCDV__tUH___1f36XB-_______KOf_8qgRo__9B__v9X___QINX___Qav__B8-NNX_-jR___8pm__ymYrq______h_odX9qg1f___7q__9X_-h1f_5TBgwYM37__KOSur-_Ro0Pr_8_f_qDV_b___r__1f_6D___lFKlSpUu__8pmK_v7VAgwf______tNX9r______V__oP__-gQaPnwpm__yqDB__tUCD__QIEG___1f2qL____9X_-g____z5-__ymb__KoNX_-lQKl6VAgQav6_V__oNf___1f2qBX_____9-hKOf_8qgVJ0JRw4cOPLkqiQoESNGgVL0aFEjQoECJGjRoymDNm__ymTJkzZv3_____-3bt27du3Thw8efPnz58-fPnz58-fP___QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf"
}
}

== Adding Content using Markup ==

Content can be added directly to the JSON file using a very simple markup. For example consider the following frame definition.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"title": {
"data": "[D]Welcome\r\n\r\n",
"type": "markup"
},
"content": {
"data": "[Y]Hello[C]Telstar[M]World",
"type": "markup"
}
}

This frame uses markup in the title and the content, The title is specified as [D]ouble height and the three words used in the content are coloured yellow, cyan and magenta respectively.

Full details of markup can be found in the [[Markup]] section.

== Complete Frame Description ==

The frame below is a standard information page from the TELSTAR system shown in its JSON format. It represents the first frame of page 9. Taking this frame as an example, a description of the fields and their meaning is decribed below.

''The full json schema can be found [[Frame Schema|here]].''

{
"pid": {
"page-no": 9,
"frame-id": "a"
},
"visible": true,
"header-text": "",
"cost": 0,
"frame-type": "information",
"redirect": {
"page-no": 0,
"frame-id": ""
},
"content": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgc4UCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAxQIIs6PJnRYtKTOjoKkWnUQUIMeLTQIECBAgQIECBAgQIEDRAgp2adSLNQSZ0aegQIECBAgQIECBAgQIECBAgQIECBAgQNkCCPBqRa8GygpxaVaTDi00CBAgQIECBAgQIECBAgQIECBA4QIIc-dUgw6iCJFqQZMymgQIECBAgQIECBAgQIECBAgQIEDlAgmT46CfOQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMECCZPjoJ8aMgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgBVAMUNMQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIAVQDFDTAlMPUQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUAxQ0wJTD1A0EHSQIECBAgQIECBAgQIECBAgQIECBAgQIECANMCUw9QNBB0kCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAPUDQQdJAgQIECBAgQIECBAgQIECAosWLFixYsWLFixYsQIECAHSQIECAosWLFixYsWLFixYsWIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf'
},
"title": {
"data": "",
"type": "",
"merge-data": []
},
"routing-table": [
90,
91,
92,
93,
94,
95,
96,
97,
98,
990,
0
],
"cursor": false,
"connection": {
"address": "",
"mode": "",
"port": 0
},
"author-id": "",
"response-data": {
"responses": null,
"response-action": {
"exec": "",
"args": null,
"post-action-frame": {
"page-no": 0,
"frame-id": ''
},
"post-cancel-frame": {
"page-no": 0,
"frame-id": ""
}
}
},
"navmessage-select": "[B][n][Y]Select item or[W]*page# : [_+]",
"navmessage-notfound": "[B][n][Y]Page not Found :[W]"
}

=== pid ===

Specifies the page number and frame id for the frame.

"pid": {
"page-no": 9,
"frame-id": "a"
},

=== visible ===

When set to false, the frame will not be accessible and will return the ''not found'' system message to the user if an attempt is made to access it.

"visible": true,

=== header-text ===

Allows the default header text to be ovwerridden at frame level. If this is left blank the default header will be used, see configuration.

"header-text": "[Y]MICRONETn 800 (C)",

=== cost ===

"cost": 0,

=== frame-type ===

The API supports the following frame types ''initial'', ''mainindex'', ''information'', ''exit'', ''gateway'', ''test'' and ''response''.

"frame-type": "information",

* '''initial''': This frame type is used on the start page, see [[Configuration Options]]. Typically only one of these frames would exist within a system.
* '''mainindex''': This frame type is used on the main index page. , see [[Configuration Options]]. Only one of these frames should exist within a system.
* '''information''': This frame type is used for all normal content frames.
* '''exit''': This frame type is used for an exit page, any number of exit pages can be defined. When an exit page is rendered it will close the connection.
* '''gateway''': This page type is used to define a gateway page and is used in conjunction with the connection element (see below).
* '''test''': This page type indicates a test page and prevents navigation and system messages from being shown. this is typically used for frames that need to use the whole display such as 'test cards' etc.
* '''telesoftware''': Telesoftware frames (see [[Telesoftware]]).
* '''response''': This frame type is used for response frames. See [[Implementing Response Frames]].
* '''system''': Reserved for use internally.
* '''exception''': Reserved for use internally.

=== redirect ===

If set it simply means that the user is redirected to the specified frame. This can be a useful alternative form of navigation to the routing table.

"redirect": {
"page-no": 9,
"frame-id": "a"
},

=== content ===

These elements define the content. The example below shows the content.type to be an edit.tf url. The available types are shown below.

"content": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgc4UCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAxQIIs6PJnRYtKTOjoKkWnUQUIMeLTQIECBAgQIECBAgQIEDRAgp2adSLNQSZ0aegQIECBAgQIECBAgQIECBAgQIECBAgQNkCCPBqRa8GygpxaVaTDi00CBAgQIECBAgQIECBAgQIECBA4QIIc-dUgw6iCJFqQZMymgQIECBAgQIECBAgQIECBAgQIEDlAgmT46CfOQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMECCZPjoJ8aMgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgBVAMUNMQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIAVQDFDTAlMPUQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUAxQ0wJTD1A0EHSQIECBAgQIECBAgQIECBAgQIECBAgQIECANMCUw9QNBB0kCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAPUDQQdJAgQIECBAgQIECBAgQIECAosWLFixYsWLFixYsQIECAHSQIECAosWLFixYsWLFixYsWIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf'
},

Content types:

* '''edit.tf''': If set, then the content will be treated as an edit.tf url. This is converted to RawV before being rendered.
* '''markup''': If set, then the content will be treated as ''markup'' content. Full details of ''markup'' can be found in the section [[Markup]]
* '''rawV''': If set, then the content will be treated as raw videotex data. This is 7bit (00-7F) videotex format with control chars between 00-1F and escaped codes for alpha and graphic attributes. Ideally rows should have any trailing spaces removed and replaced with with a CR/LF combination. This will be rendered as is.
* '''rawT''': If set, then the content will be treated as raw teletex data. This is a 24 x 40 block of 7 bits chars (960 chars) in Teletext format (range 00-7F). This format is used internally when manipulating page data. It will be converted to RawV before being rendered.

=== title ===

This sets the title of the page. In many cases this may be left blank with all of the content specified in the ''content'' section (see above) however, the ''title'' section gives additional flexibility when creating frames.

Values for ''title-type'' are the same as defined for the content section, however, if the type ''edit-tf'' is used then only the first four (default) lines of the edit.tf defined page are used.

Separating title from content in this way allows logos and header sections to be created for the title whilst using markup for the main content or visa-versa.

==== Example 1 ====

In thi example the fields are blank meaning that only the data in the ''content'' section is displayed.

"title": {
"data": "",
"type": "",
"merge-data": []
},

==== Example 2 ====

In this example, the top 4 lines of the edit.tf content is displayed at the top of the page.

"title": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAvobotqBX__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIC_9AgQIEGv-gQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgL_0Cj4kQav6BAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAuq64P6Dx__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf",
"merge-data": []
},

To take the top 5 lines, the ''type'' field can be extended as follows.

"type": "edit.tf,5"

Note that this extended form of ''type'' only applies to edit.tf types.

==== Example 3 ===

The merge data field can be used to add ''layers'' of markup data to the title area. For example the example above shows the Guardian logo. To add some alphagraphics text to this, an additional layer could be used e.g.

"title": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAvobotqBX__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIC_9AgQIEGv-gQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgL_0Cj4kQav6BAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAuq64P6Dx__oECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf,5",
"merge-data": [
"[w[ UK News]]"
]
},

Note that any number of layers can be added, however, the merge layer must be defined as markup.

=== routing table ===

The routing table defines which pages are navigated to when a user presses a key whilst viewing the frame. The table has 11 entries with the first 10 representing the keys 0-9, the final entry refers to the ''hash'' (return) key.

The example below shows the default routing table for frame 9a. If the user is viewing this frame and presses 1 the frame 91a will be loaded, assuming it exists. Pressing the ''hash'' (return) key will take the user back to frame 0a, the main index.

"routing-table": [
90,
91,
92,
93,
94,
95,
96,
97,
98,
99,
0
],

=== cursor ===

This element determines whether a cursor is shown on the page. Typically a cursor would only be shown on response frames.

"cursor": false,

=== connection ===

This elements specifies the connection object used for gateway pages.

"connection": {
"address": "fish.ccl4.org",
"mode": "viewdata",
"port": 23
},

The values for ''address and port'' represent the endpoint of the system being accessed and the value for ''mode'' determines how the system is accessed, the options are:

viewdata
full_duplex
full_duplex_no_echo

=== author-id ===

This is an optional field that can be used to indicate the author of the page or other source.

"author-id": "john",

=== response-data ===

These fields should be used when the frame type is set to be a ''response-frame''.

There are two main sections, ''response-data'' and ''response-action''. Below is an example of a response frame used for the Telstar weather page. The frame is created in the normal way using ''markup'' or ''edit.tf''. In this example the text ''Town/Cty'' has been positioned near the centre of the page. Immediately to the right of this is a field for the user to enter either a Town or City, the ''response-data'' section defines that field. Once the user submits the frame the section ''response-action'' determines what happens. In the example here a binary file (''telstar-openweather-linux-amd64''), stored in the containers volume directory is executed with a single argument (''myopenweatherapikey''). Note that the ''post-action-frame'' is set to 290b, in this example frame 290b is dynamically generated by the binary file ''telstar-openweather-linux-amd64'' and contains the weather forecast.

Full details of how to implement response frames are detailed in the section [[Implementing Response Frames]].
"response-data": {
"response-fields": [
{
"vpos": 8,
"hpos": 4,
"required": true,
"length": 16,
"type": "alphanumeric",
"auto-submit": false,
"password": false
}
],
"response-action": {
"exec": "/opt/telstar/volume/telstar-openweather-linux-amd64",
"args": [
"myopenweatherapikey"
],
"post-action-frame": {
"page-no": 290,
"frame-id": "c"
}
}
},

=== navmessage-select ===

Allows the ''navigation'' system message to be customised at frame level. In most cases this can be left blank in order that the system default is used instead, see [[Configuration Options]].

"navmessage-select": "[B][n][Y]Select item or[W]*page# : [_+]",

=== navmessage-notfound ===

Allows the ''not found'' system message to be customised at frame level. In most cases this can be left blank in order that the system default is used instead, see [[Configuration Options]].

"navmessage-notfound": "[B][n][Y]Page not Found :[W]"

The Telstar API

2022-04-16T08:46:52Z

John: /* Creating the SSH Tunnel */

== Introduction ==

Frames can be added to the system using either the Telstar API or by using a plug-in (see [[Implementing Response Frames]])

The Telstar API, in conjunction with the cross platform Telstar Util software, provides a simple method of creating and managing pages. Data is passed to and from the API in JSON format, making the system very simple to use in any programming language.

The API is a restful API that uses the GET, PUT and DELETE HTTP methods. This makes it a simple process to add new frames and update existing frames. In order to use the system a username and password combination is used to create a security token. This token is then used for subsequent requests to access the API (see below).

Data is passed to and from the API in JSON format, making the system very simple to use in any programming language. The whole API could be used without any programming at all by using a command line utility such as CURL. To make things even simpler a *bash* utility called *telstar-util* is available that wraps *curl* making things even simpler.

The utility ''telstar-util'' can be downloaded from a running server container (in this example called ''telstar-server'') using the following command

docker cp telstar-server:/opt/telstar/telstar-util-2.0.zip .

Versions exist for Linux and MacOS (amd64 and arm64), and Windows (32 and 64 bit). Note that the MacOS version may need to have the quarantine attribute reset. e.g.

xattr -d com.apple.quarantine telstar-util

The examples in this documentation demonstrate using the ''telstar-util'' command line utility.

'''NOTE:'''

The API will perform its actions on the secondary database of a Telstar system. Once a page has been created, updated or deleted on the secondary database, the API can be used to publish the changes to the primary database if required (see ''Publish'' below).

== Initialising the API ==

The Telstar API runs in a separate container. This uses the same base image but is started with a different parameter. e.g.

docker run --rm -d --name telstar-api --network telstar-network -p 8001:8001 -e TELSTAR_API_USERID=2222222222 -e TELSTAR_API_PASSWORD=1234 -e TELSTAR_COOKIE_SECRET=b6c7a826-96d6-4f45-88c4-3cf27cc2c647 johnnewcombe/telstar:amd64-2.0-RC3.4 api --port 8001 --init

This will start an api server listening on port 8001. the --init parameter will create the root user (user 0) based on the specified environment variables.

'''Remember to use a unique cookie secret for your system and keep it safe.''' The cookie secret is used to encrypt and decrypt the secure cookie within the telstar API. If this is made public, it may allow someone to create a valid authorisation cookie and impersonate a user of the system.

== Authentication ==

The docker command used above included the *--init* parameter, this parameter creates a user based on the values specified in the following environment variables.

TELSTAR_API_USERID
TELSTAR_API_PASSWORD

Typically this will be used to create the ''root'' user (user 0) and this is demonstrated in the docker-compose example ([[Orchestrating Telstar with Docker Compose]]) User ''0'' is a special user that has read, write and delete accesss to all pages within the system. Other users can be defined that have access to a specific group of pages.

All API users are common across primary and secondary databases. For example the user ID 500, will have access to pages 500 including all decendants e.g. 5001-5009, 50011, 50021, 500111 etc. on both primary and secondary databases.

Once a User ID has been created it can be used to obtain a token. This token is then used in subsequent calls to the API. For example to access the API running on the local host, with the user ID specified above, the following ''telstar-util'' command could be used.

telstar-util login localhost:8080 0 telstarapisecret

The important thing to note here is that cookies are saved to the file ''telstar-util.tok''. This file contains the secure token. Subsequent requests to the API will forward the token in the request.

## Retrievings Frames (GET)

Once authorised, any frame can be retrieved with a simple GET request.

The frame will be returned and redirected to the file *500a.json*.

telstar-util getframe localhost:8080 500a > 500a.json

== Frames and JSON ==

The simplest frame that can be viewed on TELSTAR could be defined as follows.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true
}

This frame, is so basic that it doesn't even have content. The frame below includes some flashing content.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"content": {
"data": "[D]This is page[F]101a",
"type": "markup"
}
}

Shown below is a more complete example of a JSON defined frame. With this particular frame, the actual viewdata content has been created using the editor at [http://edit.tf](http://edit.tf), this can be seen in the *content.data* and *content.type* keys. However, there are several ways to create frames other than using [http://edit.tf](http://edit.tf). For more details of the frame structure and the various settings please see [Frames in Detail](frames.md).

{
"pid": {
"page-no": 0,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"content": {
"data": "http://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMMKAbNw6dyCTuyZfCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgKJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRAxQR4s6LSgzEEmdUi0otOogkzo0-lNg1JM-cCg8unNYgQIASBBj67OnXllWIMu7pl5dMOndty7uixBoy4dnTQsQIECBAgBIEHfLh2dNCDDuyINmnNl59POzKuQIECBAgQIECBAgQIECBAyQTotemggzoiCvFg1JEWkCnYemnfuw7EGHdkQIECBAgQIASBBp3dMvLdh6ad-7DsQbsvfmgw7siDvlw9NGXkuQIECBAgQM0EKrTkzotOmgkzo0-lNg1JM-cCh79vDDu8oMO7IgQIECAEgQYuvPTuy8-aDdl781wM6EjVKcVBMw9MvPogoctOPLzQIEDRBHn1otKdNizqiCTOjT6U2DUkz5wKlvw5OaxByw6dixAgBIEGHdkQUMPLZpw7cu7ouQIECBAgQIECBAgQIECBAgQIECBA2QR4NSLXg2UFOLSrSYcWmCnWKkWYsQVIsWNBsLEEOHMaIASBBh3ZEHTRlQQ9-zfz54diCHh7ZUGHJ2y7unXllXIECBAgQN0EifMkxINmmCqcsPbLsQYd2RBI37NOTD5QbsvfmuQIECBA4CHQc2TDpT50WogcMGCAScgoOnLTi69MqDpvQdNGnmgQIAaBBzy8u2nHlQd9PTQgqZdmXnvzdO-HllQYd2RBt38sq5AgQOQ0yfHQT40ZYgp2adSLNQSZ0aegTIKkWnUQUIMeLTQIECAokSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEFeLBqSItJBGn0osODTqIBIM6EQIEFDDnyoFTJywvoECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf"
},
"routing-table": [0,1,11,3,400,5,6,7,800,9,0],
"cursor": false,
"author-id": "editf-frame-generator",
"navmsg-forecolour": "yellow",
"navmsg-backcolour": "blue",
"navmsg-highlight": "white"
}

== Adding/Updating a Frame ==

To add or update a frame the HTTP PUT request is used. If the frame already exists on TELSTAR the frame will be updated, if it does not exist then it will be created.

The following *telstar-utility* command will send the json frame stored in the file *500a.json* to the Telstar API using the Http PUT method.

telstar-util addframe localhost:8080 500a.json

== Deleting a Frame ==

A frame can be deleted using the HTTP DELETE method.

The following *telstar-utility* example will delete the frame 500a.

telstar-util deleteframe localhost:8080/frame/500a

== Publish Changes ==

As described previously, the API will perform its actions on the secondary database of a Telstar system.

Once a page has been created, updated or deleted on the secondary database, the API can be used to *publish* the changes to the primary database if required.

Publishing will update the primary database to that of the secondary for the specified frame. If the frame is deleted in the secondary and then published, it will be deleted in the primary also.

The following *telstar-utility* command will publish the frame 500a.

telstar-util publish localhost:8080/frame/500a

== Adding/Updating a User ==

Each user ID typically gives access to a single information provider page. In the case of major providers this could be one of the three digit page numbers and everything beneath it. For example the user ID 500, will have access to pages 500 including all decendants e.g. 5001-5009, 50011, 50021, 500111 etc. but not 501 or 502.

To add or update a user the HTTP PUT request is used. If the user already exists on TELSTAR the user will be updated, if it does not exist then it will be created.

The following examples add the user 800800 to the system. Note that only the *root* user (user 0) can make user changes. All passwords are stored in hashed form.

The following *telstar-utility* command will create the user *800800* with the password *mysecretpassword*.

telstar-util adduser localhost:8080 800800 mysecretpassword

== Deleting a User ==

The following examples delete the user 800800 from the system using the HTTP DELETE method. Note that only the *root* user (user 0) can make user changes.

The following *telstar-utility* command will delete the user *800800*.

telstar-util deleteuser localhost:8080 800800

== Using an SSH Tunnel ==

The API could be kept private from the public and accessed using an SSH tunnel.

From a local machine execute the following command, changing the user and server to suit your own setup.

ssh -L [LOCAL_IP:]LOCAL_PORT:DESTINATION:DESTINATION_PORT [USER@]SSH_SERVER

For example if the Telstar server was myserver.co.uk, you could use.

ssh -L 8002:myserver.co.uk:8001 john@myserver.co.uk

The above example creates an SSH connection to a server at ''myserver.co.uk'' using the username ''john''. An SSH certificate is used to access the server so no password is needed. In the command the ports are mapped such that the local port 8002, is mapped to the remote port 8001.

The API is listening by default on port 8001 on the remote server. After executing the above command, the API can be accessed using the url http//localhost:8002 on the local machine.

The Telstar API

2022-04-16T08:46:32Z

John:

== Introduction ==

Frames can be added to the system using either the Telstar API or by using a plug-in (see [[Implementing Response Frames]])

The Telstar API, in conjunction with the cross platform Telstar Util software, provides a simple method of creating and managing pages. Data is passed to and from the API in JSON format, making the system very simple to use in any programming language.

The API is a restful API that uses the GET, PUT and DELETE HTTP methods. This makes it a simple process to add new frames and update existing frames. In order to use the system a username and password combination is used to create a security token. This token is then used for subsequent requests to access the API (see below).

Data is passed to and from the API in JSON format, making the system very simple to use in any programming language. The whole API could be used without any programming at all by using a command line utility such as CURL. To make things even simpler a *bash* utility called *telstar-util* is available that wraps *curl* making things even simpler.

The utility ''telstar-util'' can be downloaded from a running server container (in this example called ''telstar-server'') using the following command

docker cp telstar-server:/opt/telstar/telstar-util-2.0.zip .

Versions exist for Linux and MacOS (amd64 and arm64), and Windows (32 and 64 bit). Note that the MacOS version may need to have the quarantine attribute reset. e.g.

xattr -d com.apple.quarantine telstar-util

The examples in this documentation demonstrate using the ''telstar-util'' command line utility.

'''NOTE:'''

The API will perform its actions on the secondary database of a Telstar system. Once a page has been created, updated or deleted on the secondary database, the API can be used to publish the changes to the primary database if required (see ''Publish'' below).

== Initialising the API ==

The Telstar API runs in a separate container. This uses the same base image but is started with a different parameter. e.g.

docker run --rm -d --name telstar-api --network telstar-network -p 8001:8001 -e TELSTAR_API_USERID=2222222222 -e TELSTAR_API_PASSWORD=1234 -e TELSTAR_COOKIE_SECRET=b6c7a826-96d6-4f45-88c4-3cf27cc2c647 johnnewcombe/telstar:amd64-2.0-RC3.4 api --port 8001 --init

This will start an api server listening on port 8001. the --init parameter will create the root user (user 0) based on the specified environment variables.

'''Remember to use a unique cookie secret for your system and keep it safe.''' The cookie secret is used to encrypt and decrypt the secure cookie within the telstar API. If this is made public, it may allow someone to create a valid authorisation cookie and impersonate a user of the system.

== Authentication ==

The docker command used above included the *--init* parameter, this parameter creates a user based on the values specified in the following environment variables.

TELSTAR_API_USERID
TELSTAR_API_PASSWORD

Typically this will be used to create the ''root'' user (user 0) and this is demonstrated in the docker-compose example ([[Orchestrating Telstar with Docker Compose]]) User ''0'' is a special user that has read, write and delete accesss to all pages within the system. Other users can be defined that have access to a specific group of pages.

All API users are common across primary and secondary databases. For example the user ID 500, will have access to pages 500 including all decendants e.g. 5001-5009, 50011, 50021, 500111 etc. on both primary and secondary databases.

Once a User ID has been created it can be used to obtain a token. This token is then used in subsequent calls to the API. For example to access the API running on the local host, with the user ID specified above, the following ''telstar-util'' command could be used.

telstar-util login localhost:8080 0 telstarapisecret

The important thing to note here is that cookies are saved to the file ''telstar-util.tok''. This file contains the secure token. Subsequent requests to the API will forward the token in the request.

## Retrievings Frames (GET)

Once authorised, any frame can be retrieved with a simple GET request.

The frame will be returned and redirected to the file *500a.json*.

telstar-util getframe localhost:8080 500a > 500a.json

== Frames and JSON ==

The simplest frame that can be viewed on TELSTAR could be defined as follows.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true
}

This frame, is so basic that it doesn't even have content. The frame below includes some flashing content.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"content": {
"data": "[D]This is page[F]101a",
"type": "markup"
}
}

Shown below is a more complete example of a JSON defined frame. With this particular frame, the actual viewdata content has been created using the editor at [http://edit.tf](http://edit.tf), this can be seen in the *content.data* and *content.type* keys. However, there are several ways to create frames other than using [http://edit.tf](http://edit.tf). For more details of the frame structure and the various settings please see [Frames in Detail](frames.md).

{
"pid": {
"page-no": 0,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"content": {
"data": "http://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMMKAbNw6dyCTuyZfCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgKJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRAxQR4s6LSgzEEmdUi0otOogkzo0-lNg1JM-cCg8unNYgQIASBBj67OnXllWIMu7pl5dMOndty7uixBoy4dnTQsQIECBAgBIEHfLh2dNCDDuyINmnNl59POzKuQIECBAgQIECBAgQIECBAyQTotemggzoiCvFg1JEWkCnYemnfuw7EGHdkQIECBAgQIASBBp3dMvLdh6ad-7DsQbsvfmgw7siDvlw9NGXkuQIECBAgQM0EKrTkzotOmgkzo0-lNg1JM-cCh79vDDu8oMO7IgQIECAEgQYuvPTuy8-aDdl781wM6EjVKcVBMw9MvPogoctOPLzQIEDRBHn1otKdNizqiCTOjT6U2DUkz5wKlvw5OaxByw6dixAgBIEGHdkQUMPLZpw7cu7ouQIECBAgQIECBAgQIECBAgQIECBA2QR4NSLXg2UFOLSrSYcWmCnWKkWYsQVIsWNBsLEEOHMaIASBBh3ZEHTRlQQ9-zfz54diCHh7ZUGHJ2y7unXllXIECBAgQN0EifMkxINmmCqcsPbLsQYd2RBI37NOTD5QbsvfmuQIECBA4CHQc2TDpT50WogcMGCAScgoOnLTi69MqDpvQdNGnmgQIAaBBzy8u2nHlQd9PTQgqZdmXnvzdO-HllQYd2RBt38sq5AgQOQ0yfHQT40ZYgp2adSLNQSZ0aegTIKkWnUQUIMeLTQIECAokSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEFeLBqSItJBGn0osODTqIBIM6EQIEFDDnyoFTJywvoECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf"
},
"routing-table": [0,1,11,3,400,5,6,7,800,9,0],
"cursor": false,
"author-id": "editf-frame-generator",
"navmsg-forecolour": "yellow",
"navmsg-backcolour": "blue",
"navmsg-highlight": "white"
}

== Adding/Updating a Frame ==

To add or update a frame the HTTP PUT request is used. If the frame already exists on TELSTAR the frame will be updated, if it does not exist then it will be created.

The following *telstar-utility* command will send the json frame stored in the file *500a.json* to the Telstar API using the Http PUT method.

telstar-util addframe localhost:8080 500a.json

== Deleting a Frame ==

A frame can be deleted using the HTTP DELETE method.

The following *telstar-utility* example will delete the frame 500a.

telstar-util deleteframe localhost:8080/frame/500a

== Publish Changes ==

As described previously, the API will perform its actions on the secondary database of a Telstar system.

Once a page has been created, updated or deleted on the secondary database, the API can be used to *publish* the changes to the primary database if required.

Publishing will update the primary database to that of the secondary for the specified frame. If the frame is deleted in the secondary and then published, it will be deleted in the primary also.

The following *telstar-utility* command will publish the frame 500a.

telstar-util publish localhost:8080/frame/500a

== Adding/Updating a User ==

Each user ID typically gives access to a single information provider page. In the case of major providers this could be one of the three digit page numbers and everything beneath it. For example the user ID 500, will have access to pages 500 including all decendants e.g. 5001-5009, 50011, 50021, 500111 etc. but not 501 or 502.

To add or update a user the HTTP PUT request is used. If the user already exists on TELSTAR the user will be updated, if it does not exist then it will be created.

The following examples add the user 800800 to the system. Note that only the *root* user (user 0) can make user changes. All passwords are stored in hashed form.

The following *telstar-utility* command will create the user *800800* with the password *mysecretpassword*.

telstar-util adduser localhost:8080 800800 mysecretpassword

== Deleting a User ==

The following examples delete the user 800800 from the system using the HTTP DELETE method. Note that only the *root* user (user 0) can make user changes.

The following *telstar-utility* command will delete the user *800800*.

telstar-util deleteuser localhost:8080 800800

== Creating the SSH Tunnel ==

The API could be kept private from the public and accessed using an SSH tunnel.

From a local machine execute the following command, changing the user and server to suit your own setup.

ssh -L [LOCAL_IP:]LOCAL_PORT:DESTINATION:DESTINATION_PORT [USER@]SSH_SERVER

For example if the Telstar server was myserver.co.uk, you could use.

ssh -L 8002:myserver.co.uk:8001 john@myserver.co.uk

The above example creates an SSH connection to a server at ''myserver.co.uk'' using the username ''john''. An SSH certificate is used to access the server so no password is needed. In the command the ports are mapped such that the local port 8002, is mapped to the remote port 8001.

The API is listening by default on port 8001 on the remote server. After executing the above command, the API can be accessed using the url http//localhost:8002 on the local machine.

Orchestrating Telstar with Docker Compose

2022-04-16T08:14:17Z

John:

Docker Compose is a tool for defining and running multi-container Docker applications. With Compose, you use a YAML file to configure your application’s services. Then, with a single command, you create and start all the services from your configuration. Given that a YAML file has been defined and stored in ''docker-compoe.ymal'', the following command will start the docker containers.

$ docker-compose up -d

To stop the containers, the following command can be used.

$ docker-compose down

Full details of Docker Compose can be found at https://docs.docker.com/compose/

== Example Docker Compose Yaml Files ==

The following docker-compose yaml file can be used to manage the Telstar application and associated ''mongo'' database.

version: "3.8"
services:
telstar-01:
container_name: "telstar-server"
image: "johnnewcombe/telstar:amd64-2.0-RC3.4"
command: "server --port 6512 --init"
ports:
- target: 6512
published: 6512
networks:
- telstar-network
volumes:
- type: volume
source: telstar-volume
target: /opt/telstar/volume
depends_on:
- mongodb
environment:
- TELSTAR_SERVER_DISPLAY_NAME=AUSTEN
mongodb:
container_name: "telstar-mongo"
image: "mongo"
ports:
- target: 27017
published: 27017
networks:
telstar-network:
environment:
- MONGO_INITDB_ROOT_USERNAME=mongoadmin
- MONGO_INITDB_ROOT_PASSWORD=secret
networks:
telstar-network:
name: telstar-network
volumes:
telstar-volume:
name: telstar-volume

The following docker-compose file starts three Telstar servers all talking to the same database server, however the third server (telstar-server-03) includes an environment variable that ensures that it uses the ''secondary'' database. This ''secondary'' database collection is typically used to test content before publishing it to the primary database collection. Further details of all of the available environment variables can be found in the section [[Configuration Options]]. In addition, the Telstar API is launched as a separate container.

version: "3.8"
services:
telstar-01:
container_name: "telstar-server-01"
build: .
image: "johnnewcombe/telstar:amd64-2.0-RC3.4"
command: "server --port 6512 --init" # install to the primary database
ports:
- target: 6512
published: 6512
networks:
- telstar-network
volumes:
- type: volume
source: telstar-volume
target: /opt/telstar/volume
depends_on:
- mongodb
environment:
- TELSTAR_SERVER_DISPLAY_NAME=AUSTEN
telstar-02:
container_name: "telstar-server-02"
image: "johnnewcombe/telstar:amd64-2.0-RC3.4"
command: "server --port 6513"
ports:
- target: 6513
published: 6513
networks:
- telstar-network
volumes:
- type: volume
source: telstar-volume
target: /opt/telstar/volume
depends_on:
- mongodb
environment:
- TELSTAR_SERVER_DISPLAY_NAME=ELIOT
telstar-03:
container_name: "telstar-server-03"
image: "johnnewcombe/telstar:amd64-2.0-RC3.4"
command: "server --port 6514 --init" # install to the secondary database
ports:
- target: 6514
published: 6514
networks:
- telstar-network
volumes:
- type: volume
source: telstar-volume
target: /opt/telstar/volume
depends_on:
- mongodb
environment:
- TELSTAR_SERVER_DISPLAY_NAME=HARDY
- TELSTAR_DBCOLLECTION=SECONDARY
telstar-api:
container_name: "telstar-api"
image: "johnnewcombe/telstar:amd64-2.0-RC3.4"
command: "api --port 8001 --init"
ports:
- target: 8001
published: 8001
networks:
- telstar-network
depends_on:
- mongodb
environment:
- TELSTAR_API_USERID=2222222222
- TELSTAR_API_PASSWORD=1234
- TELSTAR_COOKIE_SECRET=<place yout secret here> # define this for yourself and keep it secret, a GUID is a good option.
mongodb:
container_name: "telstar-mongo"
image: "mongo"
ports:
- target: 27017
published: 27017
networks:
telstar-network:
environment:
- MONGO_INITDB_ROOT_USERNAME=mongoadmin
- MONGO_INITDB_ROOT_PASSWORD=secret
networks:
telstar-network:
name: telstar-network
volumes:
telstar-volume:
name: telstar-volume

Orchestrating Telstar with Docker Compose

2022-04-15T08:17:01Z

John: /* Example Docker Compose Yaml Files */

== Example Docker Compose Yaml Files ==

The following docker-compose yaml file can be used to manage the Telstar application and associated ''mongo'' database.

version: "3.8"
services:
telstar-01:
container_name: "telstar-server"
image: "johnnewcombe/telstar:amd64-2.0-RC3.4"
command: "server --port 6512 --init"
ports:
- target: 6512
published: 6512
networks:
- telstar-network
volumes:
- type: volume
source: telstar-volume
target: /opt/telstar/volume
depends_on:
- mongodb
environment:
- TELSTAR_SERVER_DISPLAY_NAME=AUSTEN
mongodb:
container_name: "telstar-mongo"
image: "mongo"
ports:
- target: 27017
published: 27017
networks:
telstar-network:
environment:
- MONGO_INITDB_ROOT_USERNAME=mongoadmin
- MONGO_INITDB_ROOT_PASSWORD=secret
networks:
telstar-network:
name: telstar-network
volumes:
telstar-volume:
name: telstar-volume

The following docker-compose file starts three Telstar servers all talking to the same database server, however the third server (telstar-server-03) includes an environment variable that ensures that it uses the ''secondary'' database. This ''secondary'' database collection is typically used to test content before publishing it to the primary database collection. Further details of all of the available environment variables can be found in the section [[Configuration Options]]. In addition, the Telstar API is launched as a separate container.

version: "3.8"
services:
telstar-01:
container_name: "telstar-server-01"
build: .
image: "johnnewcombe/telstar:amd64-2.0-RC3.4"
command: "server --port 6512 --init" # install to the primary database
ports:
- target: 6512
published: 6512
networks:
- telstar-network
volumes:
- type: volume
source: telstar-volume
target: /opt/telstar/volume
depends_on:
- mongodb
environment:
- TELSTAR_SERVER_DISPLAY_NAME=AUSTEN
telstar-02:
container_name: "telstar-server-02"
image: "johnnewcombe/telstar:amd64-2.0-RC3.4"
command: "server --port 6513"
ports:
- target: 6513
published: 6513
networks:
- telstar-network
volumes:
- type: volume
source: telstar-volume
target: /opt/telstar/volume
depends_on:
- mongodb
environment:
- TELSTAR_SERVER_DISPLAY_NAME=ELIOT
telstar-03:
container_name: "telstar-server-03"
image: "johnnewcombe/telstar:amd64-2.0-RC3.4"
command: "server --port 6514 --init" # install to the secondary database
ports:
- target: 6514
published: 6514
networks:
- telstar-network
volumes:
- type: volume
source: telstar-volume
target: /opt/telstar/volume
depends_on:
- mongodb
environment:
- TELSTAR_SERVER_DISPLAY_NAME=HARDY
- TELSTAR_DBCOLLECTION=SECONDARY
telstar-api:
container_name: "telstar-api"
image: "johnnewcombe/telstar:amd64-2.0-RC3.4"
command: "api --port 8001 --init"
ports:
- target: 8001
published: 8001
networks:
- telstar-network
depends_on:
- mongodb
environment:
- TELSTAR_API_USERID=2222222222
- TELSTAR_API_PASSWORD=1234
- TELSTAR_COOKIE_SECRET=<place yout secret here> # define this for yourself and keep it secret, a GUID is a good option.
mongodb:
container_name: "telstar-mongo"
image: "mongo"
ports:
- target: 27017
published: 27017
networks:
telstar-network:
environment:
- MONGO_INITDB_ROOT_USERNAME=mongoadmin
- MONGO_INITDB_ROOT_PASSWORD=secret
networks:
telstar-network:
name: telstar-network
volumes:
telstar-volume:
name: telstar-volume

Orchestrating Telstar with Docker Compose

2022-04-15T08:14:46Z

John: /* Example Docker Compose Yaml Files */

== Example Docker Compose Yaml Files ==

The following docker-compose yaml file can be used to manage the Telstar application and associated ''mongo'' database.

version: "3.8"
services:
telstar-01:
container_name: "telstar-server"
image: "johnnewcombe/telstar:amd64-2.0-RC3.4"
command: "server --port 6512 --init"
ports:
- target: 6512
published: 6512
networks:
- telstar-network
volumes:
- type: volume
source: telstar-volume
target: /opt/telstar/volume
depends_on:
- mongodb
environment:
- TELSTAR_SERVER_DISPLAY_NAME=AUSTEN
mongodb:
container_name: "telstar-mongo"
image: "mongo"
ports:
- target: 27017
published: 27017
networks:
telstar-network:
environment:
- MONGO_INITDB_ROOT_USERNAME=mongoadmin
- MONGO_INITDB_ROOT_PASSWORD=secret
networks:
telstar-network:
name: telstar-network
volumes:
telstar-volume:
name: telstar-volume

The following docker-compose file starts three Telstar servers all talking to the same database server, however the third server (telstar-server-03) includes an environment variable that ensures that it uses the ''secondary'' database. This ''secondary'' database collection is typically used to test content before publishing it to the primary database collection. Further details of all of the available environment variables can be found in the section [[Configuration Options]]. In addition, the Telstar API is launched as a separate container.

version: "3.8"
services:
telstar-01:
container_name: "telstar-server-01"
build: .
image: "johnnewcombe/telstar:amd64-2.0-RC3.4"
command: "server --port 6512 --init" # install to the primary database
ports:
- target: 6512
published: 6512
networks:
- telstar-network
volumes:
- type: volume
source: telstar-volume
target: /opt/telstar/volume
depends_on:
- mongodb
environment:
- TELSTAR_SERVER_DISPLAY_NAME=AUSTEN
telstar-02:
container_name: "telstar-server-02"
image: "johnnewcombe/telstar:amd64-2.0-RC3.4"
command: "server --port 6513"
ports:
- target: 6513
published: 6513
networks:
- telstar-network
volumes:
- type: volume
source: telstar-volume
target: /opt/telstar/volume
depends_on:
- mongodb
environment:
- TELSTAR_SERVER_DISPLAY_NAME=ELIOT
telstar-03:
container_name: "telstar-server-03"
image: "johnnewcombe/telstar:amd64-2.0-RC3.4"
command: "server --port 6514 --init" # install to the secondary database
ports:
- target: 6514
published: 6514
networks:
- telstar-network
volumes:
- type: volume
source: telstar-volume
target: /opt/telstar/volume
depends_on:
- mongodb
environment:
- TELSTAR_SERVER_DISPLAY_NAME=HARDY
- TELSTAR_DBCOLLECTION=SECONDARY
telstar-api:
container_name: "telstar-api"
image: "johnnewcombe/telstar:amd64-2.0-RC3.4"
command: "api --port 8001 --init"
ports:
- target: 8001
published: 8001
networks:
- telstar-network
depends_on:
- mongodb
environment:
- TELSTAR_API_USERID=0 # User 0 has access to all pages
- TELSTAR_API_PASSWORD=telstarapisecret
- TELSTAR_COOKIE_SECRET=<place yout secret here> # define this for yourself and keep it secret!
mongodb:
container_name: "telstar-mongo"
image: "mongo"
ports:
- target: 27017
published: 27017
networks:
telstar-network:
environment:
- MONGO_INITDB_ROOT_USERNAME=mongoadmin
- MONGO_INITDB_ROOT_PASSWORD=secret
networks:
telstar-network:
name: telstar-network
volumes:
telstar-volume:
name: telstar-volume

Frames

2022-04-15T08:06:45Z

John:

As is typical with interactive videotex systems, pages are numbered from 0 to 999999999 and consist of one or more frames with the suffix a-z, for example the first frame for page 200 would be 200a, the second 200b and so on (see [[Routing]]) for more details). These frames are stored within TELSTAR's database as ''JSON'' objects (see https://www.json.org/) and uploaded to Telstar using a simple command line utility.

The Telstar utility program simply interacts with the Telstar API which is a restful API. This can be used directly by any software making it simple to programitically manage pages and routing information.

Frames are defined in JSON. The simplest frame that can be viewed on TELSTAR would be as follows. This would create a simple information frame with some flashing content. In this example [[Markup]] has been used within the content, however, other content types can be used including edi.tf urls, see below.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"content": {
"data": "[D]This is page[F]101a",
"type": "markup"
}
}

Shown below is a more complete example of a JSON defined frame. With this particular frame, the actual viewdata content has been created using the editor at http://edit.tf, this can be seen in the ''content.data'' and ''content.type'' keys. The example below is a simple information page with some simple routing (see [[Routing]]). Clicking the ''content.data'' link, or pasteing the value into a browser will show the page and allow it to be edited. It is not necessary to use the http://edit.tf editor, this is just one possible option.

{
"pid": {
"page-no": 0,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"content": {
"data": "http://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMMKAbNw6dyCTuyZfCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgKJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRAxQR4s6LSgzEEmdUi0otOogkzo0-lNg1JM-cCg8unNYgQIASBBj67OnXllWIMu7pl5dMOndty7uixBoy4dnTQsQIECBAgBIEHfLh2dNCDDuyINmnNl59POzKuQIECBAgQIECBAgQIECBAyQTotemggzoiCvFg1JEWkCnYemnfuw7EGHdkQIECBAgQIASBBp3dMvLdh6ad-7DsQbsvfmgw7siDvlw9NGXkuQIECBAgQM0EKrTkzotOmgkzo0-lNg1JM-cCh79vDDu8oMO7IgQIECAEgQYuvPTuy8-aDdl781wM6EjVKcVBMw9MvPogoctOPLzQIEDRBHn1otKdNizqiCTOjT6U2DUkz5wKlvw5OaxByw6dixAgBIEGHdkQUMPLZpw7cu7ouQIECBAgQIECBAgQIECBAgQIECBA2QR4NSLXg2UFOLSrSYcWmCnWKkWYsQVIsWNBsLEEOHMaIASBBh3ZEHTRlQQ9-zfz54diCHh7ZUGHJ2y7unXllXIECBAgQN0EifMkxINmmCqcsPbLsQYd2RBI37NOTD5QbsvfmuQIECBA4CHQc2TDpT50WogcMGCAScgoOnLTi69MqDpvQdNGnmgQIAaBBzy8u2nHlQd9PTQgqZdmXnvzdO-HllQYd2RBt38sq5AgQOQ0yfHQT40ZYgp2adSLNQSZ0aegTIKkWnUQUIMeLTQIECAokSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEFeLBqSItJBGn0osODTqIBIM6EQIEFDDnyoFTJywvoECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf"
},
"routing-table": [0,1,11,3,400,5,6,7,800,9,0],
"cursor": false,
}

== Adding Frames to the System ==

Frames can be added to the system using either the Telstar API.

The Telstar API, in conjunction with the cross platform Telstar Util software, provides a simple method of creating and managing pages.

The API can be used to retrieve and update frames and configuring routing. The API is a restful API that uses the GET, PUT, POST and DELETE HTTP methods and as such can be used from any application.

Data is passed to and from the API in JSON format, making the system very simple to use in any programming language. The whole API could be used without any programming at all by using a command line utility such as CURL.

''Further details of the Telstar API can be found in the section [[The Telstar API]].''

== Adding Content with the Edit.tf editor ==

There are several ways to add content to a page. One of the easiest is to create the page in an editor such as http://edit.tf.

The JSON file would look something like the one showm below. Note that the content type is set to editf and the content data contains the edit.tf url.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"content": {
"data": "http://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICn_OmTJkSJApUqVKlSpUlcHApiTJkyZEiRIkyZMmTIkSJFmKf3JX58____RBg-fPnzog__2iBBo-fNX9qgQcOHDh8-fGiAp_zFf______2v7_____7X___oEGr__Qa0ur_________QoCn9ywK__6D__a__7dH__tf___1QIv_9AiQIkaPX_bo0aMpiKf_-Yr__oP_9r__tUH_-1____9og__yjnz5cldX9qUc-fPkp__uSv_-g__2v_-1Qf_7X__aIv____KZv_dIV__2pTN___yn__mK___z__a____5__tf_9qgVf__8o5_vWJX__alHP___Kf_7kr____6dBr_____-h__2qBBr__ymbPnSFf69CUzf__8pnz5iq9ejRoECBWvXr0KBGjQYOHBHz4cECBAgwcCily7__yqDhw4ePnzogQeP7RAg0fPiBB___9X___QYPH___-sCmb__KoP________3B__tUCDV__tUH___1f36XB-_______KOf_8qgRo__9B__v9X___QINX___Qav__B8-NNX_-jR___8pm__ymYrq______h_odX9qg1f___7q__9X_-h1f_5TBgwYM37__KOSur-_Ro0Pr_8_f_qDV_b___r__1f_6D___lFKlSpUu__8pmK_v7VAgwf______tNX9r______V__oP__-gQaPnwpm__yqDB__tUCD__QIEG___1f2qL____9X_-g____z5-__ymb__KoNX_-lQKl6VAgQav6_V__oNf___1f2qBX_____9-hKOf_8qgVJ0JRw4cOPLkqiQoESNGgVL0aFEjQoECJGjRoymDNm__ymTJkzZv3_____-3bt27du3Thw8efPnz58-fPnz58-fP___QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf"
}
}

== Adding Content using Markup ==

Content can be added directly to the JSON file using a very simple markup. For example consider the following frame definition.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"title": {
"data": "[D]Welcome\r\n\r\n",
"type": "markup"
},
"content": {
"data": "[Y]Hello[C]Telstar[M]World",
"type": "markup"
}
}

This frame uses markup in the title and the content, The title is specified as [D]ouble height and the three words used in the content are coloured yellow, cyan and magenta respectively.

Full details of markup can be found in the [[Markup]] section.

== Complete Frame Description ==

The frame below is a standard information page from the TELSTAR system shown in its JSON format. It represents the first frame of page 9. Taking this frame as an example, a description of the fields and their meaning is decribed below.

''The full json schema can be found [[Frame Schema|here]].''

{
"pid": {
"page-no": 9,
"frame-id": "a"
},
"visible": true,
"header-text": "",
"cost": 0,
"frame-type": "information",
"redirect": {
"page-no": 0,
"frame-id": ""
},
"content": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgc4UCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAxQIIs6PJnRYtKTOjoKkWnUQUIMeLTQIECBAgQIECBAgQIEDRAgp2adSLNQSZ0aegQIECBAgQIECBAgQIECBAgQIECBAgQNkCCPBqRa8GygpxaVaTDi00CBAgQIECBAgQIECBAgQIECBA4QIIc-dUgw6iCJFqQZMymgQIECBAgQIECBAgQIECBAgQIEDlAgmT46CfOQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMECCZPjoJ8aMgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgBVAMUNMQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIAVQDFDTAlMPUQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUAxQ0wJTD1A0EHSQIECBAgQIECBAgQIECBAgQIECBAgQIECANMCUw9QNBB0kCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAPUDQQdJAgQIECBAgQIECBAgQIECAosWLFixYsWLFixYsQIECAHSQIECAosWLFixYsWLFixYsWIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf'
},
"title": {
"data": "",
"type": ""
},
"routing-table": [
90,
91,
92,
93,
94,
95,
96,
97,
98,
990,
0
],
"cursor": false,
"connection": {
"address": "",
"mode": "",
"port": 0
},
"author-id": "",
"response-data": {
"responses": null,
"response-action": {
"exec": "",
"args": null,
"post-action-frame": {
"page-no": 0,
"frame-id": ''
},
"post-cancel-frame": {
"page-no": 0,
"frame-id": ""
}
}
},
"navmessage-select": "[B][n][Y]Select item or[W]*page# : [_+]",
"navmessage-notfound": "[B][n][Y]Page not Found :[W]"
}

=== pid ===

Specifies the page number and frame id for the frame.

"pid": {
"page-no": 9,
"frame-id": "a"
},

=== visible ===

When set to false, the frame will not be accessible and will return the ''not found'' system message to the user if an attempt is made to access it.

"visible": true,

=== header-text ===

Allows the default header text to be ovwerridden at frame level. If this is left blank the default header will be used, see configuration.

"header-text": "[Y]MICRONETn 800 (C)",

=== cost ===

"cost": 0,

=== frame-type ===

The API supports the following frame types ''initial'', ''mainindex'', ''information'', ''exit'', ''gateway'', ''test'' and ''response''.

"frame-type": "information",

* '''initial''': This frame type is used on the start page, see [[Configuration Options]]. Typically only one of these frames would exist within a system.
* '''mainindex''': This frame type is used on the main index page. , see [[Configuration Options]]. Only one of these frames should exist within a system.
* '''information''': This frame type is used for all normal content frames.
* '''exit''': This frame type is used for an exit page, any number of exit pages can be defined. When an exit page is rendered it will close the connection.
* '''gateway''': This page type is used to define a gateway page and is used in conjunction with the connection element (see below).
* '''test''': This page type indicates a test page and prevents navigation and system messages from being shown. this is typically used for frames that need to use the whole display such as 'test cards' etc.
* '''telesoftware''': Telesoftware frames (see [[Telesoftware]]).
* '''response''': This frame type is used for response frames. See [[Implementing Response Frames]].
* '''system''': Reserved for use internally.
* '''exception''': Reserved for use internally.

=== redirect ===

If set it simply means that the user is redirected to the specified frame. This can be a useful alternative form of navigation to the routing table.

"redirect": {
"page-no": 9,
"frame-id": "a"
},

=== content ===

These elements define the content. The example below shows the content.type to be an edit.tf url. The available types are shown below.

"content": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgc4UCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAxQIIs6PJnRYtKTOjoKkWnUQUIMeLTQIECBAgQIECBAgQIEDRAgp2adSLNQSZ0aegQIECBAgQIECBAgQIECBAgQIECBAgQNkCCPBqRa8GygpxaVaTDi00CBAgQIECBAgQIECBAgQIECBA4QIIc-dUgw6iCJFqQZMymgQIECBAgQIECBAgQIECBAgQIEDlAgmT46CfOQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMECCZPjoJ8aMgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgBVAMUNMQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIAVQDFDTAlMPUQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUAxQ0wJTD1A0EHSQIECBAgQIECBAgQIECBAgQIECBAgQIECANMCUw9QNBB0kCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAPUDQQdJAgQIECBAgQIECBAgQIECAosWLFixYsWLFixYsQIECAHSQIECAosWLFixYsWLFixYsWIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf'
},

Content types:

* '''edit.tf''': If set, then the content will be treated as an edit.tf url. This is converted to RawV before being rendered.
* '''markup''': If set, then the content will be treated as ''markup'' content. Full details of ''markup'' can be found in the section [[Markup]]
* '''rawV''': If set, then the content will be treated as raw videotex data. This is 7bit (00-7F) videotex format with control chars between 00-1F and escaped codes for alpha and graphic attributes. Ideally rows should have any trailing spaces removed and replaced with with a CR/LF combination. This will be rendered as is.
* '''rawT''': If set, then the content will be treated as raw teletex data. This is a 24 x 40 block of 7 bits chars (960 chars) in Teletext format (range 00-7F). This format is used internally when manipulating page data. It will be converted to RawV before being rendered.

=== title ===

This sets the title of the page. In many cases this may be left blank with all of the content specified in the ''content'' section (see above) however, the ''title'' section gives additional flexibility when creating frames.

Values for ''title-type'' are the same as defined for the content section, however, if the type ''edit-tf'' is used then only the first four (default) lines of the edit.tf defined page are used.

Separating title from content in this way allows logos and header sections to be created for the title whilst using markup for the main content or visa-versa.

The example here is shown blank meaning that only the data in the ''content'' section is displayed.

"title": {
"data": "",
"type": ""
},

=== routing table ===

The routing table defines which pages are navigated towhen a user presses a key whilst viewing the frame. The table has 11 entries with the first 10 representing the keys 0-9, the final entry refers to the ''hash'' (return) key.

The example below shows the default routing table for frame 9a. If the user is viewing this frame and presses 1 the frame 91a will be loaded, assuming it exists. Pressing the ''hash'' (return) key will take the user back to frame 0a, the main index.

"routing-table": [
90,
91,
92,
93,
94,
95,
96,
97,
98,
99,
0
],

=== cursor ===

This element determines whether a cursor is shown on the page. Typically a cursor would only be shown on response frames.

"cursor": false,

=== connection ===

This elements specifies the connection object used for gateway pages.

"connection": {
"address": "fish.ccl4.org",
"mode": "viewdata",
"port": 23
},

The values for ''address and port'' represent the endpoint of the system being accessed and the value for ''mode'' determines how the system is accessed, the options are:

viewdata
full_duplex
full_duplex_no_echo

=== author-id ===

This is an optional field that can be used to indicate the author of the page or other source.

"author-id": "john",

=== response-data ===

These fields should be used when the frame type is set to be a ''response-frame''.

There are two main sections, ''response-data'' and ''response-action''. Below is an example of a response frame used for the Telstar weather page. The frame is created in the normal way using ''markup'' or ''edit.tf''. In this example the text ''Town/Cty'' has been positioned near the centre of the page. Immediately to the right of this is a field for the user to enter either a Town or City, the ''response-data'' section defines that field. Once the user submits the frame the section ''response-action'' determines what happens. In the example here a binary file (''telstar-openweather-linux-amd64''), stored in the containers volume directory is executed with a single argument (''myopenweatherapikey''). Note that the ''post-action-frame'' is set to 290b, in this example frame 290b is dynamically generated by the binary file ''telstar-openweather-linux-amd64'' and contains the weather forecast.

Full details of how to implement response frames are detailed in the section [[Implementing Response Frames]].
"response-data": {
"response-fields": [
{
"vpos": 8,
"hpos": 4,
"required": true,
"length": 16,
"type": "alphanumeric",
"auto-submit": false,
"password": false
}
],
"response-action": {
"exec": "/opt/telstar/volume/telstar-openweather-linux-amd64",
"args": [
"myopenweatherapikey"
],
"post-action-frame": {
"page-no": 290,
"frame-id": "c"
}
}
},

=== navmessage-select ===

Allows the ''navigation'' system message to be customised at frame level. In most cases this can be left blank in order that the system default is used instead, see [[Configuration Options]].

"navmessage-select": "[B][n][Y]Select item or[W]*page# : [_+]",

=== navmessage-notfound ===

Allows the ''not found'' system message to be customised at frame level. In most cases this can be left blank in order that the system default is used instead, see [[Configuration Options]].

"navmessage-notfound": "[B][n][Y]Page not Found :[W]"

Frames

2022-04-15T08:06:06Z

John:

As is typical with interactive videotex systems, pages are numbered from 0 to 999999999 and consist of one or more frames with the suffix a-z, for example the first frame for page 200 would be 200a, the second 200b and so on (see [[Routing]]) for more details). These frames are stored within TELSTAR's database as ''JSON'' objects (see https://www.json.org/) and uploaded to Telstar using a simple command line utility.

The Telstar utility program simply interacts with the Telstar API which is a restful API. This can be used directly by any software making it simple to programitically manage pages and routing information.

Frames are defined in JSON. The simplest frame that can be viewed on TELSTAR would be as follows. This would create a simple information frame with some flashing content. In this example [[Markup]] has been used within the content, however, other contant types can be used including edi.tf urls, see below.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"content": {
"data": "[D]This is page[F]101a",
"type": "markup"
}
}

Shown below is a more complete example of a JSON defined frame. With this particular frame, the actual viewdata content has been created using the editor at http://edit.tf, this can be seen in the ''content.data'' and ''content.type'' keys. The example below is a simple information page with some simple routing (see [[Routing]]). Clicking the ''content.data'' link, or pasteing the value into a browser will show the page and allow it to be edited. It is not necessary to use the http://edit.tf editor, this is just one possible option.

{
"pid": {
"page-no": 0,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"content": {
"data": "http://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMMKAbNw6dyCTuyZfCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgKJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRAxQR4s6LSgzEEmdUi0otOogkzo0-lNg1JM-cCg8unNYgQIASBBj67OnXllWIMu7pl5dMOndty7uixBoy4dnTQsQIECBAgBIEHfLh2dNCDDuyINmnNl59POzKuQIECBAgQIECBAgQIECBAyQTotemggzoiCvFg1JEWkCnYemnfuw7EGHdkQIECBAgQIASBBp3dMvLdh6ad-7DsQbsvfmgw7siDvlw9NGXkuQIECBAgQM0EKrTkzotOmgkzo0-lNg1JM-cCh79vDDu8oMO7IgQIECAEgQYuvPTuy8-aDdl781wM6EjVKcVBMw9MvPogoctOPLzQIEDRBHn1otKdNizqiCTOjT6U2DUkz5wKlvw5OaxByw6dixAgBIEGHdkQUMPLZpw7cu7ouQIECBAgQIECBAgQIECBAgQIECBA2QR4NSLXg2UFOLSrSYcWmCnWKkWYsQVIsWNBsLEEOHMaIASBBh3ZEHTRlQQ9-zfz54diCHh7ZUGHJ2y7unXllXIECBAgQN0EifMkxINmmCqcsPbLsQYd2RBI37NOTD5QbsvfmuQIECBA4CHQc2TDpT50WogcMGCAScgoOnLTi69MqDpvQdNGnmgQIAaBBzy8u2nHlQd9PTQgqZdmXnvzdO-HllQYd2RBt38sq5AgQOQ0yfHQT40ZYgp2adSLNQSZ0aegTIKkWnUQUIMeLTQIECAokSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEFeLBqSItJBGn0osODTqIBIM6EQIEFDDnyoFTJywvoECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf"
},
"routing-table": [0,1,11,3,400,5,6,7,800,9,0],
"cursor": false,
}

== Adding Frames to the System ==

Frames can be added to the system using either the Telstar API.

The Telstar API, in conjunction with the cross platform Telstar Util software, provides a simple method of creating and managing pages.

The API can be used to retrieve and update frames and configuring routing. The API is a restful API that uses the GET, PUT, POST and DELETE HTTP methods and as such can be used from any application.

Data is passed to and from the API in JSON format, making the system very simple to use in any programming language. The whole API could be used without any programming at all by using a command line utility such as CURL.

''Further details of the Telstar API can be found in the section [[The Telstar API]].''

== Adding Content with the Edit.tf editor ==

There are several ways to add content to a page. One of the easiest is to create the page in an editor such as http://edit.tf.

The JSON file would look something like the one showm below. Note that the content type is set to editf and the content data contains the edit.tf url.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"content": {
"data": "http://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICn_OmTJkSJApUqVKlSpUlcHApiTJkyZEiRIkyZMmTIkSJFmKf3JX58____RBg-fPnzog__2iBBo-fNX9qgQcOHDh8-fGiAp_zFf______2v7_____7X___oEGr__Qa0ur_________QoCn9ywK__6D__a__7dH__tf___1QIv_9AiQIkaPX_bo0aMpiKf_-Yr__oP_9r__tUH_-1____9og__yjnz5cldX9qUc-fPkp__uSv_-g__2v_-1Qf_7X__aIv____KZv_dIV__2pTN___yn__mK___z__a____5__tf_9qgVf__8o5_vWJX__alHP___Kf_7kr____6dBr_____-h__2qBBr__ymbPnSFf69CUzf__8pnz5iq9ejRoECBWvXr0KBGjQYOHBHz4cECBAgwcCily7__yqDhw4ePnzogQeP7RAg0fPiBB___9X___QYPH___-sCmb__KoP________3B__tUCDV__tUH___1f36XB-_______KOf_8qgRo__9B__v9X___QINX___Qav__B8-NNX_-jR___8pm__ymYrq______h_odX9qg1f___7q__9X_-h1f_5TBgwYM37__KOSur-_Ro0Pr_8_f_qDV_b___r__1f_6D___lFKlSpUu__8pmK_v7VAgwf______tNX9r______V__oP__-gQaPnwpm__yqDB__tUCD__QIEG___1f2qL____9X_-g____z5-__ymb__KoNX_-lQKl6VAgQav6_V__oNf___1f2qBX_____9-hKOf_8qgVJ0JRw4cOPLkqiQoESNGgVL0aFEjQoECJGjRoymDNm__ymTJkzZv3_____-3bt27du3Thw8efPnz58-fPnz58-fP___QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf"
}
}

== Adding Content using Markup ==

Content can be added directly to the JSON file using a very simple markup. For example consider the following frame definition.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"title": {
"data": "[D]Welcome\r\n\r\n",
"type": "markup"
},
"content": {
"data": "[Y]Hello[C]Telstar[M]World",
"type": "markup"
}
}

This frame uses markup in the title and the content, The title is specified as [D]ouble height and the three words used in the content are coloured yellow, cyan and magenta respectively.

Full details of markup can be found in the [[Markup]] section.

== Complete Frame Description ==

The frame below is a standard information page from the TELSTAR system shown in its JSON format. It represents the first frame of page 9. Taking this frame as an example, a description of the fields and their meaning is decribed below.

''The full json schema can be found [[Frame Schema|here]].''

{
"pid": {
"page-no": 9,
"frame-id": "a"
},
"visible": true,
"header-text": "",
"cost": 0,
"frame-type": "information",
"redirect": {
"page-no": 0,
"frame-id": ""
},
"content": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgc4UCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAxQIIs6PJnRYtKTOjoKkWnUQUIMeLTQIECBAgQIECBAgQIEDRAgp2adSLNQSZ0aegQIECBAgQIECBAgQIECBAgQIECBAgQNkCCPBqRa8GygpxaVaTDi00CBAgQIECBAgQIECBAgQIECBA4QIIc-dUgw6iCJFqQZMymgQIECBAgQIECBAgQIECBAgQIEDlAgmT46CfOQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMECCZPjoJ8aMgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgBVAMUNMQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIAVQDFDTAlMPUQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUAxQ0wJTD1A0EHSQIECBAgQIECBAgQIECBAgQIECBAgQIECANMCUw9QNBB0kCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAPUDQQdJAgQIECBAgQIECBAgQIECAosWLFixYsWLFixYsQIECAHSQIECAosWLFixYsWLFixYsWIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf'
},
"title": {
"data": "",
"type": ""
},
"routing-table": [
90,
91,
92,
93,
94,
95,
96,
97,
98,
990,
0
],
"cursor": false,
"connection": {
"address": "",
"mode": "",
"port": 0
},
"author-id": "",
"response-data": {
"responses": null,
"response-action": {
"exec": "",
"args": null,
"post-action-frame": {
"page-no": 0,
"frame-id": ''
},
"post-cancel-frame": {
"page-no": 0,
"frame-id": ""
}
}
},
"navmessage-select": "[B][n][Y]Select item or[W]*page# : [_+]",
"navmessage-notfound": "[B][n][Y]Page not Found :[W]"
}

=== pid ===

Specifies the page number and frame id for the frame.

"pid": {
"page-no": 9,
"frame-id": "a"
},

=== visible ===

When set to false, the frame will not be accessible and will return the ''not found'' system message to the user if an attempt is made to access it.

"visible": true,

=== header-text ===

Allows the default header text to be ovwerridden at frame level. If this is left blank the default header will be used, see configuration.

"header-text": "[Y]MICRONETn 800 (C)",

=== cost ===

"cost": 0,

=== frame-type ===

The API supports the following frame types ''initial'', ''mainindex'', ''information'', ''exit'', ''gateway'', ''test'' and ''response''.

"frame-type": "information",

* '''initial''': This frame type is used on the start page, see [[Configuration Options]]. Typically only one of these frames would exist within a system.
* '''mainindex''': This frame type is used on the main index page. , see [[Configuration Options]]. Only one of these frames should exist within a system.
* '''information''': This frame type is used for all normal content frames.
* '''exit''': This frame type is used for an exit page, any number of exit pages can be defined. When an exit page is rendered it will close the connection.
* '''gateway''': This page type is used to define a gateway page and is used in conjunction with the connection element (see below).
* '''test''': This page type indicates a test page and prevents navigation and system messages from being shown. this is typically used for frames that need to use the whole display such as 'test cards' etc.
* '''telesoftware''': Telesoftware frames (see [[Telesoftware]]).
* '''response''': This frame type is used for response frames. See [[Implementing Response Frames]].
* '''system''': Reserved for use internally.
* '''exception''': Reserved for use internally.

=== redirect ===

If set it simply means that the user is redirected to the specified frame. This can be a useful alternative form of navigation to the routing table.

"redirect": {
"page-no": 9,
"frame-id": "a"
},

=== content ===

These elements define the content. The example below shows the content.type to be an edit.tf url. The available types are shown below.

"content": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgc4UCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAxQIIs6PJnRYtKTOjoKkWnUQUIMeLTQIECBAgQIECBAgQIEDRAgp2adSLNQSZ0aegQIECBAgQIECBAgQIECBAgQIECBAgQNkCCPBqRa8GygpxaVaTDi00CBAgQIECBAgQIECBAgQIECBA4QIIc-dUgw6iCJFqQZMymgQIECBAgQIECBAgQIECBAgQIEDlAgmT46CfOQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMECCZPjoJ8aMgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgBVAMUNMQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIAVQDFDTAlMPUQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUAxQ0wJTD1A0EHSQIECBAgQIECBAgQIECBAgQIECBAgQIECANMCUw9QNBB0kCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAPUDQQdJAgQIECBAgQIECBAgQIECAosWLFixYsWLFixYsQIECAHSQIECAosWLFixYsWLFixYsWIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf'
},

Content types:

* '''edit.tf''': If set, then the content will be treated as an edit.tf url. This is converted to RawV before being rendered.
* '''markup''': If set, then the content will be treated as ''markup'' content. Full details of ''markup'' can be found in the section [[Markup]]
* '''rawV''': If set, then the content will be treated as raw videotex data. This is 7bit (00-7F) videotex format with control chars between 00-1F and escaped codes for alpha and graphic attributes. Ideally rows should have any trailing spaces removed and replaced with with a CR/LF combination. This will be rendered as is.
* '''rawT''': If set, then the content will be treated as raw teletex data. This is a 24 x 40 block of 7 bits chars (960 chars) in Teletext format (range 00-7F). This format is used internally when manipulating page data. It will be converted to RawV before being rendered.

=== title ===

This sets the title of the page. In many cases this may be left blank with all of the content specified in the ''content'' section (see above) however, the ''title'' section gives additional flexibility when creating frames.

Values for ''title-type'' are the same as defined for the content section, however, if the type ''edit-tf'' is used then only the first four (default) lines of the edit.tf defined page are used.

Separating title from content in this way allows logos and header sections to be created for the title whilst using markup for the main content or visa-versa.

The example here is shown blank meaning that only the data in the ''content'' section is displayed.

"title": {
"data": "",
"type": ""
},

=== routing table ===

The routing table defines which pages are navigated towhen a user presses a key whilst viewing the frame. The table has 11 entries with the first 10 representing the keys 0-9, the final entry refers to the ''hash'' (return) key.

The example below shows the default routing table for frame 9a. If the user is viewing this frame and presses 1 the frame 91a will be loaded, assuming it exists. Pressing the ''hash'' (return) key will take the user back to frame 0a, the main index.

"routing-table": [
90,
91,
92,
93,
94,
95,
96,
97,
98,
99,
0
],

=== cursor ===

This element determines whether a cursor is shown on the page. Typically a cursor would only be shown on response frames.

"cursor": false,

=== connection ===

This elements specifies the connection object used for gateway pages.

"connection": {
"address": "fish.ccl4.org",
"mode": "viewdata",
"port": 23
},

The values for ''address and port'' represent the endpoint of the system being accessed and the value for ''mode'' determines how the system is accessed, the options are:

viewdata
full_duplex
full_duplex_no_echo

=== author-id ===

This is an optional field that can be used to indicate the author of the page or other source.

"author-id": "john",

=== response-data ===

These fields should be used when the frame type is set to be a ''response-frame''.

There are two main sections, ''response-data'' and ''response-action''. Below is an example of a response frame used for the Telstar weather page. The frame is created in the normal way using ''markup'' or ''edit.tf''. In this example the text ''Town/Cty'' has been positioned near the centre of the page. Immediately to the right of this is a field for the user to enter either a Town or City, the ''response-data'' section defines that field. Once the user submits the frame the section ''response-action'' determines what happens. In the example here a binary file (''telstar-openweather-linux-amd64''), stored in the containers volume directory is executed with a single argument (''myopenweatherapikey''). Note that the ''post-action-frame'' is set to 290b, in this example frame 290b is dynamically generated by the binary file ''telstar-openweather-linux-amd64'' and contains the weather forecast.

Full details of how to implement response frames are detailed in the section [[Implementing Response Frames]].
"response-data": {
"response-fields": [
{
"vpos": 8,
"hpos": 4,
"required": true,
"length": 16,
"type": "alphanumeric",
"auto-submit": false,
"password": false
}
],
"response-action": {
"exec": "/opt/telstar/volume/telstar-openweather-linux-amd64",
"args": [
"myopenweatherapikey"
],
"post-action-frame": {
"page-no": 290,
"frame-id": "c"
}
}
},

=== navmessage-select ===

Allows the ''navigation'' system message to be customised at frame level. In most cases this can be left blank in order that the system default is used instead, see [[Configuration Options]].

"navmessage-select": "[B][n][Y]Select item or[W]*page# : [_+]",

=== navmessage-notfound ===

Allows the ''not found'' system message to be customised at frame level. In most cases this can be left blank in order that the system default is used instead, see [[Configuration Options]].

"navmessage-notfound": "[B][n][Y]Page not Found :[W]"

File:Screenshot 2022-04-15 at 09.01.22.png

2022-04-15T08:01:39Z

John:

File:Screenshot 2022-04-15 at 08.53.03.png

2022-04-15T07:55:53Z

John:

File:Screenshot 2022-04-15 at 08.46.51.png

2022-04-15T07:48:13Z

John:

The Telstar API

2022-04-15T05:35:38Z

John: /* Introduction */

The Telstar API

2022-04-15T05:35:18Z

John: /* Introduction */

== Introduction ==

Frames can be added to the system using either the Telstar API or by using a plug-in (see [[Implementing Response Frames]])

The Telstar API, in conjunction with the cross platform Telstar Util software, provides a simple method of creating and managing pages. Data is passed to and from the API in JSON format, making the system very simple to use in any programming language.

The API is a restful API that uses the GET, PUT and DELETE HTTP methods. This makes it a simple process to add new frames and update existing frames. In order to use the system a username and password combination is used to create a security token. This token is then used for subsequent requests to access the API (see below).

Data is passed to and from the API in JSON format, making the system very simple to use in any programming language. The whole API could be used without any programming at all by using a command line utility such as CURL. To make things even simpler a *bash* utility called *telstar-util* is available that wraps *curl* making things even simpler.

docker cp telstar-server-03:telstar-util-2.0.zip .
The utility ''telstar-util'' can be downloaded from a running server container (in this example called ''telstar-server'') using the following command

docker cp telstar-server:/opt/telstar/telstar-util-2.0.zip .

Versions exist for Linux and MacOS (amd64 and arm64), and Windows (32 and 64 bit). Note that the MacOS version may need to have the quarantine attribute reset. e.g.

xattr -d com.apple.quarantine telstar-util

The examples in this documentation demonstrate using the ''telstar-util'' command line utility.

'''NOTE:'''

The API will perform its actions on the secondary database of a Telstar system. Once a page has been created, updated or deleted on the secondary database, the API can be used to publish the changes to the primary database if required (see ''Publish'' below).

== Initialising the API ==

The Telstar API runs in a separate container. This uses the same base image but is started with a different parameter. e.g.

docker run --rm -d --name telstar-api --network telstar-network -p 8001:8001 -e TELSTAR_API_USERID=2222222222 -e TELSTAR_API_PASSWORD=1234 -e TELSTAR_COOKIE_SECRET=b6c7a826-96d6-4f45-88c4-3cf27cc2c647 johnnewcombe/telstar:amd64-2.0-RC3.4 api --port 8001 --init

This will start an api server listening on port 8001. the --init parameter will create the root user (user 0) based on the specified environment variables.

'''Remember to use a unique cookie secret for your system and keep it safe.''' The cookie secret is used to encrypt and decrypt the secure cookie within the telstar API. If this is made public, it may allow someone to create a valid authorisation cookie and impersonate a user of the system.

== Authentication ==

The docker command used above included the *--init* parameter, this parameter creates a user based on the values specified in the following environment variables.

TELSTAR_API_USERID
TELSTAR_API_PASSWORD

Typically this will be used to create the ''root'' user (user 0) and this is demonstrated in the docker-compose example ([[Orchestrating Telstar with Docker Compose]]) User ''0'' is a special user that has read, write and delete accesss to all pages within the system. Other users can be defined that have access to a specific group of pages.

All API users are common across primary and secondary databases. For example the user ID 500, will have access to pages 500 including all decendants e.g. 5001-5009, 50011, 50021, 500111 etc. on both primary and secondary databases.

Once a User ID has been created it can be used to obtain a token. This token is then used in subsequent calls to the API. For example to access the API running on the local host, with the user ID specified above, the following ''telstar-util'' command could be used.

telstar-util login localhost:8080 0 telstarapisecret

The important thing to note here is that cookies are saved to the file ''telstar-util.tok''. This file contains the secure token. Subsequent requests to the API will forward the token in the request.

## Retrievings Frames (GET)

Once authorised, any frame can be retrieved with a simple GET request.

The frame will be returned and redirected to the file *500a.json*.

telstar-util getframe localhost:8080 500a > 500a.json

== Frames and JSON ==

The simplest frame that can be viewed on TELSTAR could be defined as follows.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true
}

This frame, is so basic that it doesn't even have content. The frame below includes some flashing content.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"content": {
"data": "[D]This is page[F]101a",
"type": "markup"
}
}

Shown below is a more complete example of a JSON defined frame. With this particular frame, the actual viewdata content has been created using the editor at [http://edit.tf](http://edit.tf), this can be seen in the *content.data* and *content.type* keys. However, there are several ways to create frames other than using [http://edit.tf](http://edit.tf). For more details of the frame structure and the various settings please see [Frames in Detail](frames.md).

{
"pid": {
"page-no": 0,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"content": {
"data": "http://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMMKAbNw6dyCTuyZfCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgKJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRAxQR4s6LSgzEEmdUi0otOogkzo0-lNg1JM-cCg8unNYgQIASBBj67OnXllWIMu7pl5dMOndty7uixBoy4dnTQsQIECBAgBIEHfLh2dNCDDuyINmnNl59POzKuQIECBAgQIECBAgQIECBAyQTotemggzoiCvFg1JEWkCnYemnfuw7EGHdkQIECBAgQIASBBp3dMvLdh6ad-7DsQbsvfmgw7siDvlw9NGXkuQIECBAgQM0EKrTkzotOmgkzo0-lNg1JM-cCh79vDDu8oMO7IgQIECAEgQYuvPTuy8-aDdl781wM6EjVKcVBMw9MvPogoctOPLzQIEDRBHn1otKdNizqiCTOjT6U2DUkz5wKlvw5OaxByw6dixAgBIEGHdkQUMPLZpw7cu7ouQIECBAgQIECBAgQIECBAgQIECBA2QR4NSLXg2UFOLSrSYcWmCnWKkWYsQVIsWNBsLEEOHMaIASBBh3ZEHTRlQQ9-zfz54diCHh7ZUGHJ2y7unXllXIECBAgQN0EifMkxINmmCqcsPbLsQYd2RBI37NOTD5QbsvfmuQIECBA4CHQc2TDpT50WogcMGCAScgoOnLTi69MqDpvQdNGnmgQIAaBBzy8u2nHlQd9PTQgqZdmXnvzdO-HllQYd2RBt38sq5AgQOQ0yfHQT40ZYgp2adSLNQSZ0aegTIKkWnUQUIMeLTQIECAokSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEFeLBqSItJBGn0osODTqIBIM6EQIEFDDnyoFTJywvoECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf"
},
"routing-table": [0,1,11,3,400,5,6,7,800,9,0],
"cursor": false,
"author-id": "editf-frame-generator",
"navmsg-forecolour": "yellow",
"navmsg-backcolour": "blue",
"navmsg-highlight": "white"
}

== Adding/Updating a Frame ==

To add or update a frame the HTTP PUT request is used. If the frame already exists on TELSTAR the frame will be updated, if it does not exist then it will be created.

The following *telstar-utility* command will send the json frame stored in the file *500a.json* to the Telstar API using the Http PUT method.

telstar-util addframe localhost:8080 500a.json

== Deleting a Frame ==

A frame can be deleted using the HTTP DELETE method.

The following *telstar-utility* example will delete the frame 500a.

telstar-util deleteframe localhost:8080/frame/500a

== Publish Changes ==

As described previously, the API will perform its actions on the secondary database of a Telstar system.

Once a page has been created, updated or deleted on the secondary database, the API can be used to *publish* the changes to the primary database if required.

Publishing will update the primary database to that of the secondary for the specified frame. If the frame is deleted in the secondary and then published, it will be deleted in the primary also.

The following *telstar-utility* command will publish the frame 500a.

telstar-util publish localhost:8080/frame/500a

== Adding/Updating a User ==

Each user ID typically gives access to a single information provider page. In the case of major providers this could be one of the three digit page numbers and everything beneath it. For example the user ID 500, will have access to pages 500 including all decendants e.g. 5001-5009, 50011, 50021, 500111 etc. but not 501 or 502.

To add or update a user the HTTP PUT request is used. If the user already exists on TELSTAR the user will be updated, if it does not exist then it will be created.

The following examples add the user 800800 to the system. Note that only the *root* user (user 0) can make user changes. All passwords are stored in hashed form.

The following *telstar-utility* command will create the user *800800* with the password *mysecretpassword*.

telstar-util adduser localhost:8080 800800 mysecretpassword

== Deleting a User ==

The following examples delete the user 800800 from the system using the HTTP DELETE method. Note that only the *root* user (user 0) can make user changes.

The following *telstar-utility* command will delete the user *800800*.

telstar-util deleteuser localhost:8080 800800

The Telstar API

2022-04-15T05:28:12Z

John: /* Frames and JSON */

== Introduction ==

Frames can be added to the system using either the Telstar API or by using a plug-in (see [[Implementing Response Frames]])

The Telstar API, in conjunction with the cross platform Telstar Util software, provides a simple method of creating and managing pages. Data is passed to and from the API in JSON format, making the system very simple to use in any programming language.

The API is a restful API that uses the GET, PUT and DELETE HTTP methods. This makes it a simple process to add new frames and update existing frames. In order to use the system a username and password combination is used to create a security token. This token is then used for subsequent requests to access the API (see below).

Data is passed to and from the API in JSON format, making the system very simple to use in any programming language. The whole API could be used without any programming at all by using a command line utility such as CURL. To make things even simpler a *bash* utility called *telstar-util* is available that wraps *curl* making things even simpler.

The utility *telstar-util* can be downloaded from here: (https://glasstty.com/wp-content/uploads/2022/04/telstar-util-2.0.zip).

Versions exist for Linux and MacOS (amd64 and arm64), and Windows (32 and 64 bit). Note that the MacOS version may need to have the quarantine attribute reset. e.g.

xattr -d com.apple.quarantine telstar-util

The examples in this documentation demonstrate using the ''telstar-util'' command line utility.

'''NOTE:'''

The API will perform its actions on the secondary database of a Telstar system. Once a page has been created, updated or deleted on the secondary database, the API can be used to publish the changes to the primary database if required (see ''Publish'' below).

== Initialising the API ==

The Telstar API runs in a separate container. This uses the same base image but is started with a different parameter. e.g.

docker run --rm -d --name telstar-api --network telstar-network -p 8001:8001 -e TELSTAR_API_USERID=2222222222 -e TELSTAR_API_PASSWORD=1234 -e TELSTAR_COOKIE_SECRET=b6c7a826-96d6-4f45-88c4-3cf27cc2c647 johnnewcombe/telstar:amd64-2.0-RC3.4 api --port 8001 --init

This will start an api server listening on port 8001. the --init parameter will create the root user (user 0) based on the specified environment variables.

'''Remember to use a unique cookie secret for your system and keep it safe.''' The cookie secret is used to encrypt and decrypt the secure cookie within the telstar API. If this is made public, it may allow someone to create a valid authorisation cookie and impersonate a user of the system.

== Authentication ==

The docker command used above included the *--init* parameter, this parameter creates a user based on the values specified in the following environment variables.

TELSTAR_API_USERID
TELSTAR_API_PASSWORD

Typically this will be used to create the ''root'' user (user 0) and this is demonstrated in the docker-compose example ([[Orchestrating Telstar with Docker Compose]]) User ''0'' is a special user that has read, write and delete accesss to all pages within the system. Other users can be defined that have access to a specific group of pages.

All API users are common across primary and secondary databases. For example the user ID 500, will have access to pages 500 including all decendants e.g. 5001-5009, 50011, 50021, 500111 etc. on both primary and secondary databases.

Once a User ID has been created it can be used to obtain a token. This token is then used in subsequent calls to the API. For example to access the API running on the local host, with the user ID specified above, the following ''telstar-util'' command could be used.

telstar-util login localhost:8080 0 telstarapisecret

The important thing to note here is that cookies are saved to the file ''telstar-util.tok''. This file contains the secure token. Subsequent requests to the API will forward the token in the request.

## Retrievings Frames (GET)

Once authorised, any frame can be retrieved with a simple GET request.

The frame will be returned and redirected to the file *500a.json*.

telstar-util getframe localhost:8080 500a > 500a.json

== Frames and JSON ==

The simplest frame that can be viewed on TELSTAR could be defined as follows.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true
}

This frame, is so basic that it doesn't even have content. The frame below includes some flashing content.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"content": {
"data": "[D]This is page[F]101a",
"type": "markup"
}
}

Shown below is a more complete example of a JSON defined frame. With this particular frame, the actual viewdata content has been created using the editor at [http://edit.tf](http://edit.tf), this can be seen in the *content.data* and *content.type* keys. However, there are several ways to create frames other than using [http://edit.tf](http://edit.tf). For more details of the frame structure and the various settings please see [Frames in Detail](frames.md).

{
"pid": {
"page-no": 0,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"content": {
"data": "http://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMMKAbNw6dyCTuyZfCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgKJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRAxQR4s6LSgzEEmdUi0otOogkzo0-lNg1JM-cCg8unNYgQIASBBj67OnXllWIMu7pl5dMOndty7uixBoy4dnTQsQIECBAgBIEHfLh2dNCDDuyINmnNl59POzKuQIECBAgQIECBAgQIECBAyQTotemggzoiCvFg1JEWkCnYemnfuw7EGHdkQIECBAgQIASBBp3dMvLdh6ad-7DsQbsvfmgw7siDvlw9NGXkuQIECBAgQM0EKrTkzotOmgkzo0-lNg1JM-cCh79vDDu8oMO7IgQIECAEgQYuvPTuy8-aDdl781wM6EjVKcVBMw9MvPogoctOPLzQIEDRBHn1otKdNizqiCTOjT6U2DUkz5wKlvw5OaxByw6dixAgBIEGHdkQUMPLZpw7cu7ouQIECBAgQIECBAgQIECBAgQIECBA2QR4NSLXg2UFOLSrSYcWmCnWKkWYsQVIsWNBsLEEOHMaIASBBh3ZEHTRlQQ9-zfz54diCHh7ZUGHJ2y7unXllXIECBAgQN0EifMkxINmmCqcsPbLsQYd2RBI37NOTD5QbsvfmuQIECBA4CHQc2TDpT50WogcMGCAScgoOnLTi69MqDpvQdNGnmgQIAaBBzy8u2nHlQd9PTQgqZdmXnvzdO-HllQYd2RBt38sq5AgQOQ0yfHQT40ZYgp2adSLNQSZ0aegTIKkWnUQUIMeLTQIECAokSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEFeLBqSItJBGn0osODTqIBIM6EQIEFDDnyoFTJywvoECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf"
},
"routing-table": [0,1,11,3,400,5,6,7,800,9,0],
"cursor": false,
"author-id": "editf-frame-generator",
"navmsg-forecolour": "yellow",
"navmsg-backcolour": "blue",
"navmsg-highlight": "white"
}

== Adding/Updating a Frame ==

To add or update a frame the HTTP PUT request is used. If the frame already exists on TELSTAR the frame will be updated, if it does not exist then it will be created.

The following *telstar-utility* command will send the json frame stored in the file *500a.json* to the Telstar API using the Http PUT method.

telstar-util addframe localhost:8080 500a.json

== Deleting a Frame ==

A frame can be deleted using the HTTP DELETE method.

The following *telstar-utility* example will delete the frame 500a.

telstar-util deleteframe localhost:8080/frame/500a

== Publish Changes ==

As described previously, the API will perform its actions on the secondary database of a Telstar system.

Once a page has been created, updated or deleted on the secondary database, the API can be used to *publish* the changes to the primary database if required.

Publishing will update the primary database to that of the secondary for the specified frame. If the frame is deleted in the secondary and then published, it will be deleted in the primary also.

The following *telstar-utility* command will publish the frame 500a.

telstar-util publish localhost:8080/frame/500a

== Adding/Updating a User ==

Each user ID typically gives access to a single information provider page. In the case of major providers this could be one of the three digit page numbers and everything beneath it. For example the user ID 500, will have access to pages 500 including all decendants e.g. 5001-5009, 50011, 50021, 500111 etc. but not 501 or 502.

To add or update a user the HTTP PUT request is used. If the user already exists on TELSTAR the user will be updated, if it does not exist then it will be created.

The following examples add the user 800800 to the system. Note that only the *root* user (user 0) can make user changes. All passwords are stored in hashed form.

The following *telstar-utility* command will create the user *800800* with the password *mysecretpassword*.

telstar-util adduser localhost:8080 800800 mysecretpassword

== Deleting a User ==

The following examples delete the user 800800 from the system using the HTTP DELETE method. Note that only the *root* user (user 0) can make user changes.

The following *telstar-utility* command will delete the user *800800*.

telstar-util deleteuser localhost:8080 800800

The Telstar API

2022-04-15T05:25:59Z

John: /* Initialising the API */

== Introduction ==

Frames can be added to the system using either the Telstar API or by using a plug-in (see [[Implementing Response Frames]])

The Telstar API, in conjunction with the cross platform Telstar Util software, provides a simple method of creating and managing pages. Data is passed to and from the API in JSON format, making the system very simple to use in any programming language.

The API is a restful API that uses the GET, PUT and DELETE HTTP methods. This makes it a simple process to add new frames and update existing frames. In order to use the system a username and password combination is used to create a security token. This token is then used for subsequent requests to access the API (see below).

Data is passed to and from the API in JSON format, making the system very simple to use in any programming language. The whole API could be used without any programming at all by using a command line utility such as CURL. To make things even simpler a *bash* utility called *telstar-util* is available that wraps *curl* making things even simpler.

The utility *telstar-util* can be downloaded from here: (https://glasstty.com/wp-content/uploads/2022/04/telstar-util-2.0.zip).

Versions exist for Linux and MacOS (amd64 and arm64), and Windows (32 and 64 bit). Note that the MacOS version may need to have the quarantine attribute reset. e.g.

xattr -d com.apple.quarantine telstar-util

The examples in this documentation demonstrate using the ''telstar-util'' command line utility.

'''NOTE:'''

The API will perform its actions on the secondary database of a Telstar system. Once a page has been created, updated or deleted on the secondary database, the API can be used to publish the changes to the primary database if required (see ''Publish'' below).

== Initialising the API ==

The Telstar API runs in a separate container. This uses the same base image but is started with a different parameter. e.g.

docker run --rm -d --name telstar-api --network telstar-network -p 8001:8001 -e TELSTAR_API_USERID=2222222222 -e TELSTAR_API_PASSWORD=1234 -e TELSTAR_COOKIE_SECRET=b6c7a826-96d6-4f45-88c4-3cf27cc2c647 johnnewcombe/telstar:amd64-2.0-RC3.4 api --port 8001 --init

This will start an api server listening on port 8001. the --init parameter will create the root user (user 0) based on the specified environment variables.

'''Remember to use a unique cookie secret for your system and keep it safe.''' The cookie secret is used to encrypt and decrypt the secure cookie within the telstar API. If this is made public, it may allow someone to create a valid authorisation cookie and impersonate a user of the system.

== Authentication ==

The docker command used above included the *--init* parameter, this parameter creates a user based on the values specified in the following environment variables.

TELSTAR_API_USERID
TELSTAR_API_PASSWORD

Typically this will be used to create the ''root'' user (user 0) and this is demonstrated in the docker-compose example ([[Orchestrating Telstar with Docker Compose]]) User ''0'' is a special user that has read, write and delete accesss to all pages within the system. Other users can be defined that have access to a specific group of pages.

All API users are common across primary and secondary databases. For example the user ID 500, will have access to pages 500 including all decendants e.g. 5001-5009, 50011, 50021, 500111 etc. on both primary and secondary databases.

Once a User ID has been created it can be used to obtain a token. This token is then used in subsequent calls to the API. For example to access the API running on the local host, with the user ID specified above, the following ''telstar-util'' command could be used.

telstar-util login localhost:8080 0 telstarapisecret

The important thing to note here is that cookies are saved to the file ''telstar-util.tok''. This file contains the secure token. Subsequent requests to the API will forward the token in the request.

## Retrievings Frames (GET)

Once authorised, any frame can be retrieved with a simple GET request.

The frame will be returned and redirected to the file *500a.json*.

telstar-util getframe localhost:8080 500a > 500a.json

== Frames and JSON ==

The simplest frame that can be viewed on TELSTAR could be defined as follows.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true
}

This frame, is so basic that it doesn't even have content. However, when viewed within TELSTAR it will show a default welcome message.

Shown below is a more complete example of a JSON defined frame. With this particular frame, the actual viewdata content has been created using the editor at [http://edit.tf](http://edit.tf), this can be seen in the *content.data* and *content.type* keys. However, there are several ways to create frames other than using [http://edit.tf](http://edit.tf). For more details of the frame structure and the various settings please see [Frames in Detail](frames.md).

{
"pid": {
"page-no": 0,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"content": {
"data": "http://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMMKAbNw6dyCTuyZfCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgKJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRAxQR4s6LSgzEEmdUi0otOogkzo0-lNg1JM-cCg8unNYgQIASBBj67OnXllWIMu7pl5dMOndty7uixBoy4dnTQsQIECBAgBIEHfLh2dNCDDuyINmnNl59POzKuQIECBAgQIECBAgQIECBAyQTotemggzoiCvFg1JEWkCnYemnfuw7EGHdkQIECBAgQIASBBp3dMvLdh6ad-7DsQbsvfmgw7siDvlw9NGXkuQIECBAgQM0EKrTkzotOmgkzo0-lNg1JM-cCh79vDDu8oMO7IgQIECAEgQYuvPTuy8-aDdl781wM6EjVKcVBMw9MvPogoctOPLzQIEDRBHn1otKdNizqiCTOjT6U2DUkz5wKlvw5OaxByw6dixAgBIEGHdkQUMPLZpw7cu7ouQIECBAgQIECBAgQIECBAgQIECBA2QR4NSLXg2UFOLSrSYcWmCnWKkWYsQVIsWNBsLEEOHMaIASBBh3ZEHTRlQQ9-zfz54diCHh7ZUGHJ2y7unXllXIECBAgQN0EifMkxINmmCqcsPbLsQYd2RBI37NOTD5QbsvfmuQIECBA4CHQc2TDpT50WogcMGCAScgoOnLTi69MqDpvQdNGnmgQIAaBBzy8u2nHlQd9PTQgqZdmXnvzdO-HllQYd2RBt38sq5AgQOQ0yfHQT40ZYgp2adSLNQSZ0aegTIKkWnUQUIMeLTQIECAokSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEFeLBqSItJBGn0osODTqIBIM6EQIEFDDnyoFTJywvoECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf"
},
"routing-table": [0,1,11,3,400,5,6,7,800,9,0],
"cursor": false,
"author-id": "editf-frame-generator",
"navmsg-forecolour": "yellow",
"navmsg-backcolour": "blue",
"navmsg-highlight": "white"
}

== Adding/Updating a Frame ==

To add or update a frame the HTTP PUT request is used. If the frame already exists on TELSTAR the frame will be updated, if it does not exist then it will be created.

The following *telstar-utility* command will send the json frame stored in the file *500a.json* to the Telstar API using the Http PUT method.

telstar-util addframe localhost:8080 500a.json

== Deleting a Frame ==

A frame can be deleted using the HTTP DELETE method.

The following *telstar-utility* example will delete the frame 500a.

telstar-util deleteframe localhost:8080/frame/500a

== Publish Changes ==

As described previously, the API will perform its actions on the secondary database of a Telstar system.

Once a page has been created, updated or deleted on the secondary database, the API can be used to *publish* the changes to the primary database if required.

Publishing will update the primary database to that of the secondary for the specified frame. If the frame is deleted in the secondary and then published, it will be deleted in the primary also.

The following *telstar-utility* command will publish the frame 500a.

telstar-util publish localhost:8080/frame/500a

== Adding/Updating a User ==

Each user ID typically gives access to a single information provider page. In the case of major providers this could be one of the three digit page numbers and everything beneath it. For example the user ID 500, will have access to pages 500 including all decendants e.g. 5001-5009, 50011, 50021, 500111 etc. but not 501 or 502.

To add or update a user the HTTP PUT request is used. If the user already exists on TELSTAR the user will be updated, if it does not exist then it will be created.

The following examples add the user 800800 to the system. Note that only the *root* user (user 0) can make user changes. All passwords are stored in hashed form.

The following *telstar-utility* command will create the user *800800* with the password *mysecretpassword*.

telstar-util adduser localhost:8080 800800 mysecretpassword

== Deleting a User ==

The following examples delete the user 800800 from the system using the HTTP DELETE method. Note that only the *root* user (user 0) can make user changes.

The following *telstar-utility* command will delete the user *800800*.

telstar-util deleteuser localhost:8080 800800

Installing Telstar

2022-04-15T05:25:38Z

John: /* Pull the Images and Run the Containers */

It is recommended that Telstar is installed into a Docker environment. The required images are available from https://hub.docker.com/repository/docker/johnnewcombe/telstar. The following examples can be used to install and run Telstar. In addition
examples are also given for orchestrating the services using both Docker Compose and Kubernetes.

To run Telstar using Docker, a minimum of two Docker images are required.

* The official Docker image '''mongodb'''
* The Docker image '''telstar'''

In addition, a Docker network will need to created to allow the images to communicate, and a Docker volume is desirable to allow for configuration changes and the addition of plugins.

== Create the Docker Network and Volumes ==

The Docker network is used to allow communication between the TELSTAR application and the ''mongo'' database. The volumes provide a means to persist configuration data, plugins to be added and the ''mongo'' databse itself.

The following commands will create the resources required.

$ docker network create telstar-network
$ docker volume create telstar-volume
$ docker volume create mongo-volume

== Pull the Images and Run the Containers ==

Pull the required images as follows (example shows amd64 image, see https://hub.docker.com/repository/docker/johnnewcombe/telstar/tags?page=1&ordering=last_updated).

$ docker pull johnnewcombe/telstar:amd64-2.0-RC3.4 .
$ docker pull mongo

''Please note that the tag used with the official mongo image may need to be set to the system architecture that is to be used. Please see https://hub.docker.com/_/mongo.//

Start the ''mongodb'' container and connect it to the previously created network using the command below.

''Please note that the '--name' parameter is important as it is used as part of the database connection string from the TELSTAR container.''

$ docker run --name telstar-mongo --network telstar-network -v mongo-volume:/data/db -d -e MONGO_INITDB_ROOT_USERNAME=mongoadmin -e MONGO_INITDB_ROOT_PASSWORD=secret mongo

The Docker ''run'' command can be used to start the Telstar container and connect it to the previously created network. Note that in the example below the internal port is specified as 6512 and that this is mapped to the same port on the host system. This is also specified at the end of the command to inform TELSTAR that this is the port to listen on.

$ docker run --rm -d --name telstar-server --network telstar-network -p 6512:6512 -v telstar-volume:/opt/telstar/volume johnnewcombe/telstar:amd64-2.0-RC3.4 server --port=6512

In order to add some example content to the system, the ''init'' parameter can be used as in the example below.

$ docker run --rm -d --name telstar-server --network telstar-network -p 6512:6512 -v telstar-volume:/opt/telstar/volume johnnewcombe/telstar:amd64-2.0-RC3.4 server --port=6512 --init

If the ''--init'' switch is used as in the example above, the service will be running with some example content (see [[Example Content]]) and can be accessed using a suitable client.

In order to add additional content to the system the Telstar API can be used, this can be started as follows (see [[the Telstar API]] for mor details).

docker run --rm -d --name telstar-api --network telstar-network -p 8011:8011 -e TELSTAR_API_USERID=2222222222 -e TELSTAR_API_PASSWORD=1234 -e TELSTAR_COOKIE_SECRET=b6c7a826-96d6-4f45-88c4-3cf27cc2c647 johnnewcombe/telstar:amd64-2.0-RC3.4 api --port 8001 --init

The simplest way to test the system from a desktop machine is to use the [[Telstar Viewdata Client]] alternatively Telnet can be used. TELSTAR is not a Telnet application but telnet can be used to provide a ''sanity check'' e.g.

$ telnet <ip-of-docker-host> <port-used-for-telstar>

If the system is working, a display similar to the following would be shown.

Connected to glasstty.com.
Escape character is '^]'.

20201128T1316Z
L TE
ST
Welcome

$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
Welcome to theTELSTAR
videotex service.

You are connected toELIOT.
$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
...

The screen looks a little garbled simply because TELSTAR is a videotex application not a Telnet application.

== Docker Compose and Kubernetes ==

In the examples above the Docker command was used to set up the system. Howevevr, it may be more appropriate to use Docker Compose See [[Orchestrating Telstar with Docker Compose]]. Telstar could even be implemented using Kubernetes, see [[Orchestrating Telstar with Kubernetes]] sections for other examples.

== Configuration ==

Configuration options for the docker containers can be specified using environment variables, these can be specified as part of the ''docker run'' command or within the Docker Compose yaml file (see above). Full details of all of the available environment variables can be found in the section [[Configuration Options]].

== Portainer ==

The Docker environmemnt can be managed using Portainer, see [[Managing Telstar with Portainer]].

[[File:2827664245-portainer.png]]

Frames

2022-04-15T04:40:55Z

John:

As is typical with interactive videotex systems, pages are numbered from 0 to 999999999 and consist of one or more frames with the suffix a-z, for example the first frame for page 200 would be 200a, the second 200b and so on (see [[Routing]]) for more details). These frames are stored within TELSTAR's database as ''JSON'' objects (see https://www.json.org/) and uploaded to Telstar using a simple command line utility.

The Telstar utility program simply interacts with the Telstar API which is a restful API. This can be used directly by any software making it simple to programitically manage pages and routing information.

Frames are defined in JSON. The simplest frame that can be viewed on TELSTAR would be as follows. This would create a simple information frame with some flashing content.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"content": {
"data": "[D]This is page[F]101a",
"type": "markup"
}
}

Shown below is a more complete example of a JSON defined frame. With this particular frame, the actual viewdata content has been created using the editor at http://edit.tf, this can be seen in the ''content.data'' and ''content.type'' keys. The example below is a simple information page with some simple routing (see [[Routing]]). Clicking the ''content.data'' link, or pasteing the value into a browser will show the page and allow it to be edited. It is not necessary to use the http://edit.tf editor, this is just one possible option.

{
"pid": {
"page-no": 0,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"content": {
"data": "http://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMMKAbNw6dyCTuyZfCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgKJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRAxQR4s6LSgzEEmdUi0otOogkzo0-lNg1JM-cCg8unNYgQIASBBj67OnXllWIMu7pl5dMOndty7uixBoy4dnTQsQIECBAgBIEHfLh2dNCDDuyINmnNl59POzKuQIECBAgQIECBAgQIECBAyQTotemggzoiCvFg1JEWkCnYemnfuw7EGHdkQIECBAgQIASBBp3dMvLdh6ad-7DsQbsvfmgw7siDvlw9NGXkuQIECBAgQM0EKrTkzotOmgkzo0-lNg1JM-cCh79vDDu8oMO7IgQIECAEgQYuvPTuy8-aDdl781wM6EjVKcVBMw9MvPogoctOPLzQIEDRBHn1otKdNizqiCTOjT6U2DUkz5wKlvw5OaxByw6dixAgBIEGHdkQUMPLZpw7cu7ouQIECBAgQIECBAgQIECBAgQIECBA2QR4NSLXg2UFOLSrSYcWmCnWKkWYsQVIsWNBsLEEOHMaIASBBh3ZEHTRlQQ9-zfz54diCHh7ZUGHJ2y7unXllXIECBAgQN0EifMkxINmmCqcsPbLsQYd2RBI37NOTD5QbsvfmuQIECBA4CHQc2TDpT50WogcMGCAScgoOnLTi69MqDpvQdNGnmgQIAaBBzy8u2nHlQd9PTQgqZdmXnvzdO-HllQYd2RBt38sq5AgQOQ0yfHQT40ZYgp2adSLNQSZ0aegTIKkWnUQUIMeLTQIECAokSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEFeLBqSItJBGn0osODTqIBIM6EQIEFDDnyoFTJywvoECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf"
},
"routing-table": [0,1,11,3,400,5,6,7,800,9,0],
"cursor": false,
}

== Adding Frames to the System ==

Frames can be added to the system using either the Telstar API.

The Telstar API, in conjunction with the cross platform Telstar Util software, provides a simple method of creating and managing pages.

The API can be used to retrieve and update frames and configuring routing. The API is a restful API that uses the GET, PUT, POST and DELETE HTTP methods and as such can be used from any application.

Data is passed to and from the API in JSON format, making the system very simple to use in any programming language. The whole API could be used without any programming at all by using a command line utility such as CURL.

''Further details of the Telstar API can be found in the section [[The Telstar API]].''

== Adding Content with the Edit.tf editor ==

There are several ways to add content to a page. One of the easiest is to create the page in an editor such as http://edit.tf.

The JSON file would look something like the one showm below. Note that the content type is set to editf and the content data contains the edit.tf url.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"content": {
"data": "http://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICn_OmTJkSJApUqVKlSpUlcHApiTJkyZEiRIkyZMmTIkSJFmKf3JX58____RBg-fPnzog__2iBBo-fNX9qgQcOHDh8-fGiAp_zFf______2v7_____7X___oEGr__Qa0ur_________QoCn9ywK__6D__a__7dH__tf___1QIv_9AiQIkaPX_bo0aMpiKf_-Yr__oP_9r__tUH_-1____9og__yjnz5cldX9qUc-fPkp__uSv_-g__2v_-1Qf_7X__aIv____KZv_dIV__2pTN___yn__mK___z__a____5__tf_9qgVf__8o5_vWJX__alHP___Kf_7kr____6dBr_____-h__2qBBr__ymbPnSFf69CUzf__8pnz5iq9ejRoECBWvXr0KBGjQYOHBHz4cECBAgwcCily7__yqDhw4ePnzogQeP7RAg0fPiBB___9X___QYPH___-sCmb__KoP________3B__tUCDV__tUH___1f36XB-_______KOf_8qgRo__9B__v9X___QINX___Qav__B8-NNX_-jR___8pm__ymYrq______h_odX9qg1f___7q__9X_-h1f_5TBgwYM37__KOSur-_Ro0Pr_8_f_qDV_b___r__1f_6D___lFKlSpUu__8pmK_v7VAgwf______tNX9r______V__oP__-gQaPnwpm__yqDB__tUCD__QIEG___1f2qL____9X_-g____z5-__ymb__KoNX_-lQKl6VAgQav6_V__oNf___1f2qBX_____9-hKOf_8qgVJ0JRw4cOPLkqiQoESNGgVL0aFEjQoECJGjRoymDNm__ymTJkzZv3_____-3bt27du3Thw8efPnz58-fPnz58-fP___QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf"
}
}

== Adding Content using Markup ==

Content can be added directly to the JSON file using a very simple markup. For example consider the following frame definition.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"title": {
"data": "[D]Welcome\r\n\r\n",
"type": "markup"
},
"content": {
"data": "[Y]Hello[C]Telstar[M]World",
"type": "markup"
}
}

This frame uses markup in the title and the content, The title is specified as [D]ouble height and the three words used in the content are coloured yellow, cyan and magenta respectively.

Full details of markup can be found in the [[Markup]] section.

== Complete Frame Description ==

The frame below is a standard information page from the TELSTAR system shown in its JSON format. It represents the first frame of page 9. Taking this frame as an example, a description of the fields and their meaning is decribed below.

''The full json schema can be found [[Frame Schema|here]].''

{
"pid": {
"page-no": 9,
"frame-id": "a"
},
"visible": true,
"header-text": "",
"cost": 0,
"frame-type": "information",
"redirect": {
"page-no": 0,
"frame-id": ""
},
"content": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgc4UCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAxQIIs6PJnRYtKTOjoKkWnUQUIMeLTQIECBAgQIECBAgQIEDRAgp2adSLNQSZ0aegQIECBAgQIECBAgQIECBAgQIECBAgQNkCCPBqRa8GygpxaVaTDi00CBAgQIECBAgQIECBAgQIECBA4QIIc-dUgw6iCJFqQZMymgQIECBAgQIECBAgQIECBAgQIEDlAgmT46CfOQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMECCZPjoJ8aMgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgBVAMUNMQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIAVQDFDTAlMPUQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUAxQ0wJTD1A0EHSQIECBAgQIECBAgQIECBAgQIECBAgQIECANMCUw9QNBB0kCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAPUDQQdJAgQIECBAgQIECBAgQIECAosWLFixYsWLFixYsQIECAHSQIECAosWLFixYsWLFixYsWIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf'
},
"title": {
"data": "",
"type": ""
},
"routing-table": [
90,
91,
92,
93,
94,
95,
96,
97,
98,
990,
0
],
"cursor": false,
"connection": {
"address": "",
"mode": "",
"port": 0
},
"author-id": "",
"response-data": {
"responses": null,
"response-action": {
"exec": "",
"args": null,
"post-action-frame": {
"page-no": 0,
"frame-id": ''
},
"post-cancel-frame": {
"page-no": 0,
"frame-id": ""
}
}
},
"navmessage-select": "[B][n][Y]Select item or[W]*page# : [_+]",
"navmessage-notfound": "[B][n][Y]Page not Found :[W]"
}

=== pid ===

Specifies the page number and frame id for the frame.

"pid": {
"page-no": 9,
"frame-id": "a"
},

=== visible ===

When set to false, the frame will not be accessible and will return the ''not found'' system message to the user if an attempt is made to access it.

"visible": true,

=== header-text ===

Allows the default header text to be ovwerridden at frame level. If this is left blank the default header will be used, see configuration.

"header-text": "[Y]MICRONETn 800 (C)",

=== cost ===

"cost": 0,

=== frame-type ===

The API supports the following frame types ''initial'', ''mainindex'', ''information'', ''exit'', ''gateway'', ''test'' and ''response''.

"frame-type": "information",

* '''initial''': This frame type is used on the start page, see [[Configuration Options]]. Typically only one of these frames would exist within a system.
* '''mainindex''': This frame type is used on the main index page. , see [[Configuration Options]]. Only one of these frames should exist within a system.
* '''information''': This frame type is used for all normal content frames.
* '''exit''': This frame type is used for an exit page, any number of exit pages can be defined. When an exit page is rendered it will close the connection.
* '''gateway''': This page type is used to define a gateway page and is used in conjunction with the connection element (see below).
* '''test''': This page type indicates a test page and prevents navigation and system messages from being shown. this is typically used for frames that need to use the whole display such as 'test cards' etc.
* '''telesoftware''': Telesoftware frames (see [[Telesoftware]]).
* '''response''': This frame type is used for response frames. See [[Implementing Response Frames]].
* '''system''': Reserved for use internally.
* '''exception''': Reserved for use internally.

=== redirect ===

If set it simply means that the user is redirected to the specified frame. This can be a useful alternative form of navigation to the routing table.

"redirect": {
"page-no": 9,
"frame-id": "a"
},

=== content ===

These elements define the content. The example below shows the content.type to be an edit.tf url. The available types are shown below.

"content": {
"data": "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgc4UCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAxQIIs6PJnRYtKTOjoKkWnUQUIMeLTQIECBAgQIECBAgQIEDRAgp2adSLNQSZ0aegQIECBAgQIECBAgQIECBAgQIECBAgQNkCCPBqRa8GygpxaVaTDi00CBAgQIECBAgQIECBAgQIECBA4QIIc-dUgw6iCJFqQZMymgQIECBAgQIECBAgQIECBAgQIEDlAgmT46CfOQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMECCZPjoJ8aMgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQICixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYsWLFixYgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgBVAMUNMQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIAVQDFDTAlMPUQIECBAgQIECBAgQIECBAgQIECBAgQIECAFUAxQ0wJTD1A0EHSQIECBAgQIECBAgQIECBAgQIECBAgQIECANMCUw9QNBB0kCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECAPUDQQdJAgQIECBAgQIECBAgQIECAosWLFixYsWLFixYsQIECAHSQIECAosWLFixYsWLFixYsWIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf'
},

Content types:

* '''edit.tf''': If set, then the content will be treated as an edit.tf url. This is converted to RawV before being rendered.
* '''markup''': If set, then the content will be treated as ''markup'' content. Full details of ''markup'' can be found in the section [[Markup]]
* '''rawV''': If set, then the content will be treated as raw videotex data. This is 7bit (00-7F) videotex format with control chars between 00-1F and escaped codes for alpha and graphic attributes. Ideally rows should have any trailing spaces removed and replaced with with a CR/LF combination. This will be rendered as is.
* '''rawT''': If set, then the content will be treated as raw teletex data. This is a 24 x 40 block of 7 bits chars (960 chars) in Teletext format (range 00-7F). This format is used internally when manipulating page data. It will be converted to RawV before being rendered.

=== title ===

This sets the title of the page. In many cases this may be left blank with all of the content specified in the ''content'' section (see above) however, the ''title'' section gives additional flexibility when creating frames.

Values for ''title-type'' are the same as defined for the content section, however, if the type ''edit-tf'' is used then only the first four (default) lines of the edit.tf defined page are used.

Separating title from content in this way allows logos and header sections to be created for the title whilst using markup for the main content or visa-versa.

The example here is shown blank meaning that only the data in the ''content'' section is displayed.

"title": {
"data": "",
"type": ""
},

=== routing table ===

The routing table defines which pages are navigated towhen a user presses a key whilst viewing the frame. The table has 11 entries with the first 10 representing the keys 0-9, the final entry refers to the ''hash'' (return) key.

The example below shows the default routing table for frame 9a. If the user is viewing this frame and presses 1 the frame 91a will be loaded, assuming it exists. Pressing the ''hash'' (return) key will take the user back to frame 0a, the main index.

"routing-table": [
90,
91,
92,
93,
94,
95,
96,
97,
98,
99,
0
],

=== cursor ===

This element determines whether a cursor is shown on the page. Typically a cursor would only be shown on response frames.

"cursor": false,

=== connection ===

This elements specifies the connection object used for gateway pages.

"connection": {
"address": "fish.ccl4.org",
"mode": "viewdata",
"port": 23
},

The values for ''address and port'' represent the endpoint of the system being accessed and the value for ''mode'' determines how the system is accessed, the options are:

viewdata
full_duplex
full_duplex_no_echo

=== author-id ===

This is an optional field that can be used to indicate the author of the page or other source.

"author-id": "john",

=== response-data ===

These fields should be used when the frame type is set to be a ''response-frame''.

There are two main sections, ''response-data'' and ''response-action''. Below is an example of a response frame used for the Telstar weather page. The frame is created in the normal way using ''markup'' or ''edit.tf''. In this example the text ''Town/Cty'' has been positioned near the centre of the page. Immediately to the right of this is a field for the user to enter either a Town or City, the ''response-data'' section defines that field. Once the user submits the frame the section ''response-action'' determines what happens. In the example here a binary file (''telstar-openweather-linux-amd64''), stored in the containers volume directory is executed with a single argument (''myopenweatherapikey''). Note that the ''post-action-frame'' is set to 290b, in this example frame 290b is dynamically generated by the binary file ''telstar-openweather-linux-amd64'' and contains the weather forecast.

Full details of how to implement response frames are detailed in the section [[Implementing Response Frames]].
"response-data": {
"response-fields": [
{
"vpos": 8,
"hpos": 4,
"required": true,
"length": 16,
"type": "alphanumeric",
"auto-submit": false,
"password": false
}
],
"response-action": {
"exec": "/opt/telstar/volume/telstar-openweather-linux-amd64",
"args": [
"myopenweatherapikey"
],
"post-action-frame": {
"page-no": 290,
"frame-id": "c"
}
}
},

=== navmessage-select ===

Allows the ''navigation'' system message to be customised at frame level. In most cases this can be left blank in order that the system default is used instead, see [[Configuration Options]].

"navmessage-select": "[B][n][Y]Select item or[W]*page# : [_+]",

=== navmessage-notfound ===

Allows the ''not found'' system message to be customised at frame level. In most cases this can be left blank in order that the system default is used instead, see [[Configuration Options]].

"navmessage-notfound": "[B][n][Y]Page not Found :[W]"

The Telstar API

2022-04-14T21:16:29Z

John: /* Initialising the API */

== Introduction ==

Frames can be added to the system using either the Telstar API or by using a plug-in (see [[Implementing Response Frames]])

The Telstar API, in conjunction with the cross platform Telstar Util software, provides a simple method of creating and managing pages. Data is passed to and from the API in JSON format, making the system very simple to use in any programming language.

The API is a restful API that uses the GET, PUT and DELETE HTTP methods. This makes it a simple process to add new frames and update existing frames. In order to use the system a username and password combination is used to create a security token. This token is then used for subsequent requests to access the API (see below).

Data is passed to and from the API in JSON format, making the system very simple to use in any programming language. The whole API could be used without any programming at all by using a command line utility such as CURL. To make things even simpler a *bash* utility called *telstar-util* is available that wraps *curl* making things even simpler.

The utility *telstar-util* can be downloaded from here: (https://glasstty.com/wp-content/uploads/2022/04/telstar-util-2.0.zip).

Versions exist for Linux and MacOS (amd64 and arm64), and Windows (32 and 64 bit). Note that the MacOS version may need to have the quarantine attribute reset. e.g.

xattr -d com.apple.quarantine telstar-util

The examples in this documentation demonstrate using the ''telstar-util'' command line utility.

'''NOTE:'''

The API will perform its actions on the secondary database of a Telstar system. Once a page has been created, updated or deleted on the secondary database, the API can be used to publish the changes to the primary database if required (see ''Publish'' below).

== Initialising the API ==

The Telstar API runs in a separate container. This uses the same base image but is started with a different parameter. e.g.

docker run --rm -d --name telstar-api --network telstar-network -p 8001:8001 -e TELSTAR_API_USERID=2222222222 -e TELSTAR_API_PASSWORD=1234 -e TELSTAR_COOKIE_SECRET=b6c7a826-96d6-4f45-88c4-3cf27cc2c647 johnnewcombe/telstar:amd64-2.0-RC3.3 api --port 8001 --init

This will start an api server listening on port 8001. the --init parameter will create the root user (user 0) based on the specified environment variables.

'''Remember to use a unique cookie secret for your system and keep it safe.''' The cookie secret is used to encrypt and decrypt the secure cookie within the telstar API. If this is made public, it may allow someone to create a valid authorisation cookie and impersonate a user of the system.

== Authentication ==

The docker command used above included the *--init* parameter, this parameter creates a user based on the values specified in the following environment variables.

TELSTAR_API_USERID
TELSTAR_API_PASSWORD

Typically this will be used to create the ''root'' user (user 0) and this is demonstrated in the docker-compose example ([[Orchestrating Telstar with Docker Compose]]) User ''0'' is a special user that has read, write and delete accesss to all pages within the system. Other users can be defined that have access to a specific group of pages.

All API users are common across primary and secondary databases. For example the user ID 500, will have access to pages 500 including all decendants e.g. 5001-5009, 50011, 50021, 500111 etc. on both primary and secondary databases.

Once a User ID has been created it can be used to obtain a token. This token is then used in subsequent calls to the API. For example to access the API running on the local host, with the user ID specified above, the following ''telstar-util'' command could be used.

telstar-util login localhost:8080 0 telstarapisecret

The important thing to note here is that cookies are saved to the file ''telstar-util.tok''. This file contains the secure token. Subsequent requests to the API will forward the token in the request.

## Retrievings Frames (GET)

Once authorised, any frame can be retrieved with a simple GET request.

The frame will be returned and redirected to the file *500a.json*.

telstar-util getframe localhost:8080 500a > 500a.json

== Frames and JSON ==

The simplest frame that can be viewed on TELSTAR could be defined as follows.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true
}

This frame, is so basic that it doesn't even have content. However, when viewed within TELSTAR it will show a default welcome message.

Shown below is a more complete example of a JSON defined frame. With this particular frame, the actual viewdata content has been created using the editor at [http://edit.tf](http://edit.tf), this can be seen in the *content.data* and *content.type* keys. However, there are several ways to create frames other than using [http://edit.tf](http://edit.tf). For more details of the frame structure and the various settings please see [Frames in Detail](frames.md).

{
"pid": {
"page-no": 0,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"content": {
"data": "http://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMMKAbNw6dyCTuyZfCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgKJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRAxQR4s6LSgzEEmdUi0otOogkzo0-lNg1JM-cCg8unNYgQIASBBj67OnXllWIMu7pl5dMOndty7uixBoy4dnTQsQIECBAgBIEHfLh2dNCDDuyINmnNl59POzKuQIECBAgQIECBAgQIECBAyQTotemggzoiCvFg1JEWkCnYemnfuw7EGHdkQIECBAgQIASBBp3dMvLdh6ad-7DsQbsvfmgw7siDvlw9NGXkuQIECBAgQM0EKrTkzotOmgkzo0-lNg1JM-cCh79vDDu8oMO7IgQIECAEgQYuvPTuy8-aDdl781wM6EjVKcVBMw9MvPogoctOPLzQIEDRBHn1otKdNizqiCTOjT6U2DUkz5wKlvw5OaxByw6dixAgBIEGHdkQUMPLZpw7cu7ouQIECBAgQIECBAgQIECBAgQIECBA2QR4NSLXg2UFOLSrSYcWmCnWKkWYsQVIsWNBsLEEOHMaIASBBh3ZEHTRlQQ9-zfz54diCHh7ZUGHJ2y7unXllXIECBAgQN0EifMkxINmmCqcsPbLsQYd2RBI37NOTD5QbsvfmuQIECBA4CHQc2TDpT50WogcMGCAScgoOnLTi69MqDpvQdNGnmgQIAaBBzy8u2nHlQd9PTQgqZdmXnvzdO-HllQYd2RBt38sq5AgQOQ0yfHQT40ZYgp2adSLNQSZ0aegTIKkWnUQUIMeLTQIECAokSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEFeLBqSItJBGn0osODTqIBIM6EQIEFDDnyoFTJywvoECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf"
},
"routing-table": [0,1,11,3,400,5,6,7,800,9,0],
"cursor": false,
"author-id": "editf-frame-generator",
"navmsg-forecolour": "yellow",
"navmsg-backcolour": "blue",
"navmsg-highlight": "white"
}

== Adding/Updating a Frame ==

To add or update a frame the HTTP PUT request is used. If the frame already exists on TELSTAR the frame will be updated, if it does not exist then it will be created.

The following *telstar-utility* command will send the json frame stored in the file *500a.json* to the Telstar API using the Http PUT method.

telstar-util addframe localhost:8080 500a.json

== Deleting a Frame ==

A frame can be deleted using the HTTP DELETE method.

The following *telstar-utility* example will delete the frame 500a.

telstar-util deleteframe localhost:8080/frame/500a

== Publish Changes ==

As described previously, the API will perform its actions on the secondary database of a Telstar system.

Once a page has been created, updated or deleted on the secondary database, the API can be used to *publish* the changes to the primary database if required.

Publishing will update the primary database to that of the secondary for the specified frame. If the frame is deleted in the secondary and then published, it will be deleted in the primary also.

The following *telstar-utility* command will publish the frame 500a.

telstar-util publish localhost:8080/frame/500a

== Adding/Updating a User ==

Each user ID typically gives access to a single information provider page. In the case of major providers this could be one of the three digit page numbers and everything beneath it. For example the user ID 500, will have access to pages 500 including all decendants e.g. 5001-5009, 50011, 50021, 500111 etc. but not 501 or 502.

To add or update a user the HTTP PUT request is used. If the user already exists on TELSTAR the user will be updated, if it does not exist then it will be created.

The following examples add the user 800800 to the system. Note that only the *root* user (user 0) can make user changes. All passwords are stored in hashed form.

The following *telstar-utility* command will create the user *800800* with the password *mysecretpassword*.

telstar-util adduser localhost:8080 800800 mysecretpassword

== Deleting a User ==

The following examples delete the user 800800 from the system using the HTTP DELETE method. Note that only the *root* user (user 0) can make user changes.

The following *telstar-utility* command will delete the user *800800*.

telstar-util deleteuser localhost:8080 800800

The Telstar API

2022-04-14T21:03:46Z

John: /* Initialising the API */

== Introduction ==

Frames can be added to the system using either the Telstar API or by using a plug-in (see [[Implementing Response Frames]])

The Telstar API, in conjunction with the cross platform Telstar Util software, provides a simple method of creating and managing pages. Data is passed to and from the API in JSON format, making the system very simple to use in any programming language.

The API is a restful API that uses the GET, PUT and DELETE HTTP methods. This makes it a simple process to add new frames and update existing frames. In order to use the system a username and password combination is used to create a security token. This token is then used for subsequent requests to access the API (see below).

Data is passed to and from the API in JSON format, making the system very simple to use in any programming language. The whole API could be used without any programming at all by using a command line utility such as CURL. To make things even simpler a *bash* utility called *telstar-util* is available that wraps *curl* making things even simpler.

The utility *telstar-util* can be downloaded from here: (https://glasstty.com/wp-content/uploads/2022/04/telstar-util-2.0.zip).

Versions exist for Linux and MacOS (amd64 and arm64), and Windows (32 and 64 bit). Note that the MacOS version may need to have the quarantine attribute reset. e.g.

xattr -d com.apple.quarantine telstar-util

The examples in this documentation demonstrate using the ''telstar-util'' command line utility.

'''NOTE:'''

The API will perform its actions on the secondary database of a Telstar system. Once a page has been created, updated or deleted on the secondary database, the API can be used to publish the changes to the primary database if required (see ''Publish'' below).

== Initialising the API ==

The Telstar API runs in a separate container. This uses the same base image but is started with a different parameter. e.g.

docker run --rm -d --name telstar-api --network telstar-network -p 8011:8011 -e TELSTAR_API_USERID=2222222222 -e TELSTAR_API_PASSWORD=1234 -e TELSTAR_COOKIE_SECRET=b6c7a826-96d6-4f45-88c4-3cf27cc2c647 johnnewcombe/telstar:amd64-2.0-RC3.3 api --port 8001 --init

This will start an api server listening on port 8001. the --init parameter will create the root user (user 0) based on the specified environment variables.

'''Remember to use a unique cookie secret for your system and keep it safe.''' The cookie secret is used to encrypt and decrypt the secure cookie within the telstar API. If this is made public, it may allow someone to create a valid authorisation cookie and impersonate a user of the system.

== Authentication ==

The docker command used above included the *--init* parameter, this parameter creates a user based on the values specified in the following environment variables.

TELSTAR_API_USERID
TELSTAR_API_PASSWORD

Typically this will be used to create the ''root'' user (user 0) and this is demonstrated in the docker-compose example ([[Orchestrating Telstar with Docker Compose]]) User ''0'' is a special user that has read, write and delete accesss to all pages within the system. Other users can be defined that have access to a specific group of pages.

All API users are common across primary and secondary databases. For example the user ID 500, will have access to pages 500 including all decendants e.g. 5001-5009, 50011, 50021, 500111 etc. on both primary and secondary databases.

Once a User ID has been created it can be used to obtain a token. This token is then used in subsequent calls to the API. For example to access the API running on the local host, with the user ID specified above, the following ''telstar-util'' command could be used.

telstar-util login localhost:8080 0 telstarapisecret

The important thing to note here is that cookies are saved to the file ''telstar-util.tok''. This file contains the secure token. Subsequent requests to the API will forward the token in the request.

## Retrievings Frames (GET)

Once authorised, any frame can be retrieved with a simple GET request.

The frame will be returned and redirected to the file *500a.json*.

telstar-util getframe localhost:8080 500a > 500a.json

== Frames and JSON ==

The simplest frame that can be viewed on TELSTAR could be defined as follows.

{
"pid": {
"page-no": 101,
"frame-id": "a"
},
"visible": true
}

This frame, is so basic that it doesn't even have content. However, when viewed within TELSTAR it will show a default welcome message.

Shown below is a more complete example of a JSON defined frame. With this particular frame, the actual viewdata content has been created using the editor at [http://edit.tf](http://edit.tf), this can be seen in the *content.data* and *content.type* keys. However, there are several ways to create frames other than using [http://edit.tf](http://edit.tf). For more details of the frame structure and the various settings please see [Frames in Detail](frames.md).

{
"pid": {
"page-no": 0,
"frame-id": "a"
},
"visible": true,
"frame-type": "information",
"content": {
"data": "http://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMMKAbNw6dyCTuyZfCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgKJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRAxQR4s6LSgzEEmdUi0otOogkzo0-lNg1JM-cCg8unNYgQIASBBj67OnXllWIMu7pl5dMOndty7uixBoy4dnTQsQIECBAgBIEHfLh2dNCDDuyINmnNl59POzKuQIECBAgQIECBAgQIECBAyQTotemggzoiCvFg1JEWkCnYemnfuw7EGHdkQIECBAgQIASBBp3dMvLdh6ad-7DsQbsvfmgw7siDvlw9NGXkuQIECBAgQM0EKrTkzotOmgkzo0-lNg1JM-cCh79vDDu8oMO7IgQIECAEgQYuvPTuy8-aDdl781wM6EjVKcVBMw9MvPogoctOPLzQIEDRBHn1otKdNizqiCTOjT6U2DUkz5wKlvw5OaxByw6dixAgBIEGHdkQUMPLZpw7cu7ouQIECBAgQIECBAgQIECBAgQIECBA2QR4NSLXg2UFOLSrSYcWmCnWKkWYsQVIsWNBsLEEOHMaIASBBh3ZEHTRlQQ9-zfz54diCHh7ZUGHJ2y7unXllXIECBAgQN0EifMkxINmmCqcsPbLsQYd2RBI37NOTD5QbsvfmuQIECBA4CHQc2TDpT50WogcMGCAScgoOnLTi69MqDpvQdNGnmgQIAaBBzy8u2nHlQd9PTQgqZdmXnvzdO-HllQYd2RBt38sq5AgQOQ0yfHQT40ZYgp2adSLNQSZ0aegTIKkWnUQUIMeLTQIECAokSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEFeLBqSItJBGn0osODTqIBIM6EQIEFDDnyoFTJywvoECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
"type": "edit.tf"
},
"routing-table": [0,1,11,3,400,5,6,7,800,9,0],
"cursor": false,
"author-id": "editf-frame-generator",
"navmsg-forecolour": "yellow",
"navmsg-backcolour": "blue",
"navmsg-highlight": "white"
}

== Adding/Updating a Frame ==

To add or update a frame the HTTP PUT request is used. If the frame already exists on TELSTAR the frame will be updated, if it does not exist then it will be created.

The following *telstar-utility* command will send the json frame stored in the file *500a.json* to the Telstar API using the Http PUT method.

telstar-util addframe localhost:8080 500a.json

== Deleting a Frame ==

A frame can be deleted using the HTTP DELETE method.

The following *telstar-utility* example will delete the frame 500a.

telstar-util deleteframe localhost:8080/frame/500a

== Publish Changes ==

As described previously, the API will perform its actions on the secondary database of a Telstar system.

Once a page has been created, updated or deleted on the secondary database, the API can be used to *publish* the changes to the primary database if required.

Publishing will update the primary database to that of the secondary for the specified frame. If the frame is deleted in the secondary and then published, it will be deleted in the primary also.

The following *telstar-utility* command will publish the frame 500a.

telstar-util publish localhost:8080/frame/500a

== Adding/Updating a User ==

Each user ID typically gives access to a single information provider page. In the case of major providers this could be one of the three digit page numbers and everything beneath it. For example the user ID 500, will have access to pages 500 including all decendants e.g. 5001-5009, 50011, 50021, 500111 etc. but not 501 or 502.

To add or update a user the HTTP PUT request is used. If the user already exists on TELSTAR the user will be updated, if it does not exist then it will be created.

The following examples add the user 800800 to the system. Note that only the *root* user (user 0) can make user changes. All passwords are stored in hashed form.

The following *telstar-utility* command will create the user *800800* with the password *mysecretpassword*.

telstar-util adduser localhost:8080 800800 mysecretpassword

== Deleting a User ==

The following examples delete the user 800800 from the system using the HTTP DELETE method. Note that only the *root* user (user 0) can make user changes.

The following *telstar-utility* command will delete the user *800800*.

telstar-util deleteuser localhost:8080 800800

Installing Telstar

2022-04-14T21:03:21Z

John: /* Pull the Images and Run the Containers */

It is recommended that Telstar is installed into a Docker environment. The required images are available from https://hub.docker.com/repository/docker/johnnewcombe/telstar. The following examples can be used to install and run Telstar. In addition
examples are also given for orchestrating the services using both Docker Compose and Kubernetes.

To run Telstar using Docker, a minimum of two Docker images are required.

* The official Docker image '''mongodb'''
* The Docker image '''telstar'''

In addition, a Docker network will need to created to allow the images to communicate, and a Docker volume is desirable to allow for configuration changes and the addition of plugins.

== Create the Docker Network and Volumes ==

The Docker network is used to allow communication between the TELSTAR application and the ''mongo'' database. The volumes provide a means to persist configuration data, plugins to be added and the ''mongo'' databse itself.

The following commands will create the resources required.

$ docker network create telstar-network
$ docker volume create telstar-volume
$ docker volume create mongo-volume

== Pull the Images and Run the Containers ==

Pull the required images as follows (example shows amd64 image, see https://hub.docker.com/repository/docker/johnnewcombe/telstar/tags?page=1&ordering=last_updated).

$ docker pull johnnewcombe/telstar:amd64-2.0-RC3.3 .
$ docker pull mongo

''Please note that the tag used with the official mongo image may need to be set to the system architecture that is to be used. Please see https://hub.docker.com/_/mongo.//

Start the ''mongodb'' container and connect it to the previously created network using the command below.

''Please note that the '--name' parameter is important as it is used as part of the database connection string from the TELSTAR container.''

$ docker run --name telstar-mongo --network telstar-network -v mongo-volume:/data/db -d -e MONGO_INITDB_ROOT_USERNAME=mongoadmin -e MONGO_INITDB_ROOT_PASSWORD=secret mongo

The Docker ''run'' command can be used to start the Telstar container and connect it to the previously created network. Note that in the example below the internal port is specified as 6512 and that this is mapped to the same port on the host system. This is also specified at the end of the command to inform TELSTAR that this is the port to listen on.

$ docker run --rm -d --name telstar-server --network telstar-network -p 6512:6512 -v telstar-volume:/opt/telstar/volume johnnewcombe/telstar:amd64-2.0-RC3.3 server --port=6512

In order to add some example content to the system, the ''init'' parameter can be used as in the example below.

$ docker run --rm -d --name telstar-server --network telstar-network -p 6512:6512 -v telstar-volume:/opt/telstar/volume johnnewcombe/telstar:amd64-2.0-RC3.3 server --port=6512 --init

If the ''--init'' switch is used as in the example above, the service will be running with some example content (see [[Example Content]]) and can be accessed using a suitable client.

In order to add additional content to the system the Telstar API can be used, this can be started as follows (see [[the Telstar API]] for mor details).

docker run --rm -d --name telstar-api --network telstar-network -p 8011:8011 -e TELSTAR_API_USERID=2222222222 -e TELSTAR_API_PASSWORD=1234 -e TELSTAR_COOKIE_SECRET=b6c7a826-96d6-4f45-88c4-3cf27cc2c647 johnnewcombe/telstar:amd64-2.0-RC3.3 api --port 8001 --init

The simplest way to test the system from a desktop machine is to use the [[Telstar Viewdata Client]] alternatively Telnet can be used. TELSTAR is not a Telnet application but telnet can be used to provide a ''sanity check'' e.g.

$ telnet <ip-of-docker-host> <port-used-for-telstar>

If the system is working, a display similar to the following would be shown.

Connected to glasstty.com.
Escape character is '^]'.

20201128T1316Z
L TE
ST
Welcome

$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
Welcome to theTELSTAR
videotex service.

You are connected toELIOT.
$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
...

The screen looks a little garbled simply because TELSTAR is a videotex application not a Telnet application.

== Docker Compose and Kubernetes ==

In the examples above the Docker command was used to set up the system. Howevevr, it may be more appropriate to use Docker Compose See [[Orchestrating Telstar with Docker Compose]]. Telstar could even be implemented using Kubernetes, see [[Orchestrating Telstar with Kubernetes]] sections for other examples.

== Configuration ==

Configuration options for the docker containers can be specified using environment variables, these can be specified as part of the ''docker run'' command or within the Docker Compose yaml file (see above). Full details of all of the available environment variables can be found in the section [[Configuration Options]].

== Portainer ==

The Docker environmemnt can be managed using Portainer, see [[Managing Telstar with Portainer]].

[[File:2827664245-portainer.png]]