tizenportal

TizenPortal User Guide

This guide covers all the features and functionality of TizenPortal.

Table of Contents

  1. Portal Launcher
  2. Managing Sites
  3. Browsing Sites
  4. Color Button Functions
  5. Mouse Mode
  6. Address Bar
  7. Bundle System
  8. Userscripts
  9. Diagnostics Panel
  10. Keyboard Input
  11. Tips & Tricks

Portal Launcher

The portal is your home screen — a grid of site cards you can navigate with your TV remote.

Layout

┌─────────────────────────────────────────────────────────┐
│                    TizenPortal                          │
├─────────┬─────────┬─────────┬─────────┬─────────┬──────┤
│         │         │         │         │         │      │
│  Site 1 │  Site 2 │  Site 3 │  Site 4 │  Site 5 │  +   │
│         │         │         │         │         │      │
├─────────┴─────────┴─────────┴─────────┴─────────┴──────┤
│  🔴 Address  🟢 Mouse  🟡 Preferences  🔵 Diagnostics  │
└─────────────────────────────────────────────────────────┘

Managing Sites

Adding a Site

There are two ways to add a site:

From the portal:

  1. Navigate to the + card
  2. Press Enter to open the site editor
  3. Fill in the form:
Field Description Example
Name Display name on the card “Audiobookshelf”
URL Full site URL “https://abs.myserver.com”
Site-specific Bundle Compatibility bundle “audiobookshelf”
Icon Card icon (optional) Click “Fetch Favicon”
  1. Press Close when finished (changes auto-save)

From a site (quick-add):

  1. Navigate to the site you want to add
  2. Long-press 🟡 Yellow (hold for 500ms)
  3. The current page is automatically saved as a new card (URL, title, and favicon are captured)
  4. TizenPortal returns to the portal, where the new card is immediately visible

Editing a Site

  1. Navigate to the site card
  2. Press and hold Enter (or use a menu option if available)
  3. Modify the fields as needed
  4. Press Close

Site Options (Per-Site Overrides)

In the editor, open Site Options to override global preferences for this site:

Deleting a Site

  1. Open the site editor for the card
  2. Scroll down to find Delete
  3. Confirm deletion

Reordering Sites

Sites appear in the order they were added. To reorder:

  1. Delete and re-add cards in your preferred order
  2. Or edit the order via the diagnostics console (advanced)

Browsing Sites

Opening a Site

  1. Navigate to the site card
  2. Press Enter
  3. The site loads with bundle enhancements applied
Input Action
Arrow Keys Move focus between elements
Enter Click/activate focused element
🟢 Green Toggle mouse mode for precise control
🟡 Yellow Return to portal (short press) / Add current site as card + return to portal (long press)

Card Interaction Model

Many sites display content as cards (media items, books, albums, etc.). TizenPortal provides special handling for cards with multiple interactive elements.

Single-Action Cards

Cards with one button or link:

Example: Simple list items with one “Open” button

Multi-Action Cards

Cards with multiple buttons (Play, Info, Options, etc.):

  1. Navigate to the card with Arrow Keys
  2. Press Enter to “enter” the card
  3. Use Arrow Keys to navigate between buttons inside the card
  4. Press Enter to activate a button
  5. Press Back to “exit” the card and return to card-level navigation

Example: Media cards with Play, Info, and Add to Library buttons

Visual Indicators

Tips for Card Navigation

Scrolling

When you follow a link to a different domain (e.g. from your Audiobookshelf to an external site), TizenPortal automatically carries your bundle configuration along via the URL. The same bundle and settings that were active on the original card continue to apply on the new site.

If the new site needs different settings, return to the portal and open it as its own card.

Returning to Portal

Press 🟡 Yellow (short press) to return to the portal launcher. Long-press 🟡 Yellow to save the current site as a new portal card and return to the portal.

Color Button Functions

Overview

Button Short Press Long Press
🔴 Red Open address bar Reload current page
🟢 Green Toggle mouse mode Edit focused card (portal) / Toggle focus highlight (sites)
🟡 Yellow Preferences (portal) / Return to portal (sites) Add Site (portal) / Add current site as card + return to portal (sites)
🔵 Blue Toggle diagnostics Enter safe mode

Short Press vs Long Press

Mouse Mode

Mouse mode displays an on-screen cursor that you control with the D-pad.

Activating Mouse Mode

Press 🟢 Green to toggle mouse mode on/off.

Using the Cursor

Input Action
Arrow Keys Move cursor
Enter Click at cursor position
🟢 Green Exit mouse mode

When to Use Mouse Mode

Focus Highlight

On sites, long-press 🟢 Green to toggle focus highlighting. This makes the currently focused element more visible with a bright outline.

Address Bar

The address bar provides browser-like navigation controls.

Opening the Address Bar

Press 🔴 Red to show/hide the address bar.

Address Bar Controls

┌──────────────────────────────────────────────────────────────────────────────┐
│ ⎈ │ 🏠 │ ← │ → │ ↻ │ https://example.com/page                 │ → │ ℹ │
└──────────────────────────────────────────────────────────────────────────────┘
Button Function
⎈ Return to portal
🏠 Site home URL
← Go back
→ Go forward
↻ Reload page
URL field Edit URL (select and type)
→ (Go) Navigate to URL
ℹ Open TizenPortal documentation
  1. Press 🔴 Red to open address bar
  2. Navigate to the URL field
  3. Press Enter to edit
  4. Type the new URL using the TV keyboard
  5. Press Enter or navigate to confirm

Quick Reload

Long-press 🔴 Red to reload the current page without opening the address bar.

Preferences

Open Preferences with 🟡 Yellow on the portal.

Global Preferences

Global defaults that can be overridden per-site in the editor.

Appearance

Navigation

Portal Preferences

Appearance

HUD & Hints

Site Preferences

Navigation

Compatibility

Input

Layout

Performance

Bundle System

Bundles are site-specific enhancements that improve TV compatibility.

Available Bundles

Bundle Best For Features
default Any site Basic fallback bundle
audiobookshelf Audiobookshelf Full navigation, media keys
adblock Ad-heavy sites Blocks common ads and trackers

Selecting a Bundle

When adding a site:

  1. In the site editor, use the Bundle dropdown
  2. Select the appropriate bundle
  3. Press Close

Bundle Options

Some bundles expose per-site options in the editor. For example, Adblock supports:

Userscripts

TizenPortal includes a powerful userscript system with 18 pre-built scripts organized by category. These scripts can be enabled globally or per-site to enhance your TV browsing experience.

What are Userscripts?

Userscripts are custom JavaScript code that runs when a site loads. They can:

Pre-Built Userscripts

TizenPortal comes with 18 carefully crafted userscripts organized into categories:

♿ Accessibility (2 scripts)

📖 Reading (5 scripts)

🎬 Video (4 scripts)

🧭 Navigation (5 scripts)

🔒 Privacy (2 scripts)

Managing Global Userscripts

  1. Press 🟡 Yellow on the portal to open Preferences
  2. Navigate to the User Scripts section
  3. Scripts are organized by category
  4. Toggle each script on/off:
    • ✓ Enabled - Script will run on sites where enabled
    • ○ Disabled - Script won’t run

Per-Site Userscript Control

Global userscripts can be overridden per-site:

  1. Open the site editor for a card
  2. Navigate to the User Scripts section
  3. You’ll see all userscripts with their current state:
    • ✓ Enabled (global) - Enabled globally
    • ○ Disabled (global) - Disabled globally
    • ✓ Enabled (site override) - Enabled for this site only
    • ○ Disabled (site override) - Disabled for this site only
  4. Click the action button to:
    • Enable for Site - Enable only on this site
    • Disable for Site - Disable only on this site
    • Reset to Global - Remove site override

Userscript Examples

TV Readability Booster (enabled by default):

Dark Reading Mode:

Smart Auto-Scroll:

Cookie Consent Auto-Closer:

Data Migration

If you’re upgrading from an older version:

Userscript API

Scripts have access to the TizenPortal API:

// Logging
TizenPortal.log('message');
TizenPortal.warn('warning');
TizenPortal.error('error');

// Cleanup function (called when navigating away)
userscript.cleanup = function() {
  // Remove event listeners, timers, etc.
};

Userscript Example

Here’s a simple example from one of the built-in scripts:

// Remove sticky headers that block content
var style = document.createElement('style');
style.id = 'tp-no-sticky';
style.textContent = `
  *[style*="position: fixed"],
  *[style*="position:fixed"] {
    position: static !important;
  }
  header[style*="position"],
  nav[style*="position"] {
    position: static !important;
  }
`;
document.head.appendChild(style);

userscript.cleanup = function() {
  var el = document.getElementById('tp-no-sticky');
  if (el) el.remove();
};

Userscript Security

Troubleshooting Userscripts

Script not running:

Script errors:

External script won’t load:

Diagnostics Panel

The diagnostics panel helps troubleshoot issues and view system information.

Opening Diagnostics

Press 🔵 Blue to cycle through diagnostics states:

  1. Off — Panel hidden
  2. Compact — Shows recent logs
  3. Full — Shows all logs with details

Panel Contents

┌─────────────────────────────────────────┐
│ TizenPortal - Diagnostics               │
├─────────────────────────────────────────┤
│ [LOG] Bundle activated: audiobookshelf  │
│ [LOG] Focus set to .book-card           │
│ [WARN] Element not found: .sidebar      │
│ [LOG] Scroll into view triggered        │
└─────────────────────────────────────────┘

Scrolling Logs

When the panel is open:

Log Levels

Diagnostics displays three types of log entries:

Level Color Purpose
LOG White General information
WARN Yellow Warnings and deprecations
ERROR Red Errors and failures

Log Filtering

Use Left/Right arrows to cycle through filters:

  1. All — Shows all log entries (default)
  2. Log — Shows only LOG entries
  3. Warn — Shows only WARN entries
  4. Error — Shows only ERROR entries

The current filter is shown in the panel header.

Clearing Logs

Two ways to clear the log history:

  1. Press 🟡 Yellow while diagnostics is open
  2. Use programmatically: TizenPortal.clearDiagnosticsLogs()

Log Storage

Safe Mode

Long-press 🔵 Blue to enter safe mode:

Keyboard Input

TizenPortal protects text inputs by default to prevent the on-screen keyboard from opening automatically when you focus an input field. This gives you better control over when the keyboard appears.

Text Input Protection

How it works:

Enabling/Disabling:

Using the TV Keyboard

  1. Navigate to a text input field with Arrow Keys
  2. Press Enter to activate the keyboard
  3. Use the on-screen keyboard to type
  4. Press Done (65376) or Enter to confirm
  5. Press Cancel (65385) to cancel without changes

Keyboard Tips

IME Behavior

When the keyboard is active:

Tips & Tricks

General Tips

  1. Use the right bundle — The correct bundle makes a huge difference in usability
  2. Enable focus highlight — Makes it easier to see what’s selected
  3. Check diagnostics — If something isn’t working, the logs usually explain why
  1. Tab order — Most sites navigate in reading order (left-to-right, top-to-bottom)
  2. Enter on links — Press Enter to follow links, not just to click
  3. Mouse mode for tricky UI — Some modern UI elements only work with mouse clicks

Performance Tips

  1. Fewer cards — Too many cards may slow down the portal
  2. Close unused sites — Memory is limited on older TVs
  3. Use adblock — Blocking ads improves performance significantly

Troubleshooting Tips

  1. Page not loading? — Check the URL in address bar
  2. Navigation not working? — Try switching bundles
  3. Stuck? — Press 🟡 Yellow to return to portal
  4. Completely stuck? — Long-press 🔵 Blue for safe mode

Accessibility

High Contrast

On sites, enable focus highlight (long-press 🟢 Green) for better visibility of focused elements.

Large Text

TizenPortal uses TV-optimized font sizes. Some sites may need bundle adjustments for larger text.

Screen Reader

TizenPortal does not currently support screen readers. This is a planned feature for a future release.

For technical documentation, see the Developer Guides.