.. include:: defs.txt
.. include:: images.txt

.. _librem_5_web:

Web Browsing
============

.. image:: images/web/org.gnome.Epiphany.svg
   :width: 128
   :align: right
   :alt: The Web application icon

The **Web** application is a web browser that provides access to web sites and services. It can also be used to create standalone web applications that can be run independently of the standard browser user interface.

.. contents::
   :local:

Locate the icon shown above in the app drawer and press it to launch the application.

Getting Started
---------------

When you start **Web** for the first time, you will be shown a start page with a welcome message. This is where your most-visited sites will be shown as shortcuts.

.. image:: images/web/web-start.png
   :align: center
   :scale: 50%
   :alt: Starting Web

To start browsing a site, select the empty address bar at the top of the screen to open the keyboard, then enter the address for that site and press the |enter| (Return) key.

.. image:: images/web/web-viewing-page.png
   :align: center
   :scale: 50%
   :alt: Viewing a web page

The browser behaves like one on a larger device, except that you can scroll pages by swiping them in the desired direction.

User Interface
--------------

When browsing a web page, the top part of the screen contains the address bar and application menu.

.. image:: images/web/web-top-bar.png
   :align: center
   :alt: The address bar and menu button

The address bar also contains a star which is used :ref:`to bookmark a page <librem_5_web_add_bookmark>`.

At the bottom of the screen, the toolbar contains buttons that control navigation.

.. image:: images/web/web-bottom-bar.png
   :align: center
   :alt: The bottom bar, showing navigation controls

The first two are back and forward buttons that show the previous and next pages in the browsing history. 

Next to the numbered button, the |bookmarks| (bookmarks) button opens the :ref:`list of bookmarks <librem_5_web_bookmarks>`. The numbered button shows the number of open tabs -- only 1 in the image -- and is used to :ref:`open and switch between tabs <librem_5_web_tabs>`.

.. _librem_5_web_bookmarks:

Bookmarks
---------

Press the |bookmarks| (bookmarks) button at the bottom-right of the screen to open the list of bookmarks. To start with, there are no bookmarks.

.. image:: images/web/web-no-bookmarks.png
   :align: center
   :scale: 50%
   :alt: Show the bookmarks list

If you have bookmarks, you can select one of them to open the page it refers to.

.. image:: images/web/web-bookmarks2.png
   :align: center
   :scale: 50%
   :alt: Showing a bookmark in the list

You can also filter the bookmarks by any tags that have been assigned to them.

Press the button again to close the list.

.. _librem_5_web_add_bookmark:

Adding Bookmarks
~~~~~~~~~~~~~~~~

If you want to mark a page for future reference, press the star in the address bar to open the **Bookmark** dialog. This automatically adds a bookmark for the page.

.. image:: images/web/web-add-bookmark.png
   :align: center
   :scale: 50%
   :alt: Adding a bookmark

You can customize the page information and press outside the dialog to keep the bookmark, or you can remove it immediately by pressing the **Remove Bookmark** button.

If you are viewing a bookmarked page, you can press the star to open the **Bookmark** dialog again if you want to update the bookmark details.

Editing and Removing Bookmarks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To edit a bookmark for a page, open the list of bookmarks and press the symbol to the right of the bookmark.

.. image:: images/web/web-bookmarks.png
   :align: center
   :scale: 50%
   :alt: Showing a bookmark in the list

This will open the **Bookmark Properties** page where you can edit the details for the bookmark.

.. image:: images/web/web-edit-bookmark.png
   :align: center
   :scale: 50%
   :alt: Editing a bookmark

When you have finished editing it, you can simply press the back button at the top-left of the screen.

If you want to remove it, press the **Remove** button instead.

.. _librem_5_web_tabs:

Using Tabs
----------

Tabs allow you to view more than one page at a time. To begin with, you are using only a single tab. The number shown in the tab button at the bottom-right of the screen shows how many tabs are open.

.. image:: images/web/web-bottom-bar.png
   :align: center
   :alt: The bottom bar, showing the number of tabs open

Press the numbered button to open the **Tabs** page, containing a list of open tabs.

.. image:: images/web/web-tabs.png
   :align: center
   :scale: 50%
   :alt: Open tabs

Select a tab to view its contents. This is how you switch between multiple open pages.

If you want to return to the current tab and its contents, press the back button at the top-left of the screen.

Opening and Closing Tabs
~~~~~~~~~~~~~~~~~~~~~~~~

While viewing the list of open tabs, you can press the |new-tab| (new tab) button at the top-right of the screen to open a new tab.

.. image:: images/web/web-tabs2.png
   :align: center
   :scale: 50%
   :alt: Open tabs

The number of tabs shown in the tab button will have increased. If you open the list of tabs again, the new tab will be included in the list.

To close a tab, press the |close| (close) icon to remove it from the list and close the associated page.

When you close the last tab in the last open window, **Web** will exit.

History
-------

To access your browsing history, press the |menu| (menu) button to open the main application menu, then select **History**.

.. image:: images/web/web-menu-history.png
   :align: center
   :scale: 50%
   :alt: The main application menu

When you start browing, the browsing history will be empty. Sites that you visit will be added to the list.

.. |web-history-empty| image:: images/web/web-history-empty.png
   :scale: 50%
   :alt: An empty browsing history
.. |web-history| image:: images/web/web-history.png
   :scale: 50%
   :alt: Browsing history

.. centered:: |web-history-empty| |web-history|

You can select an item to open a new tab containing that site, making it the current tab. Press the |copy| (copy) button next to each history item to copy the URL of the site to the clipboard.

Press the back button to return to the current page.

Searching for Sites
~~~~~~~~~~~~~~~~~~~

You can search for specific sites by pressing the search button at the top-right of the screen. This lets you filter the list and find sites with titles that contain certain words.

.. image:: images/web/web-history-search.png
   :align: center
   :scale: 50%
   :alt: The main application menu

Press the search button again to close the search bar.

Deleting Sites from the History
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

One or more sites can be deleted from the history by activating selection mode. This is done by pressing the |select| (select) button at the top-right of the screen.

.. |web-history-selection| image:: images/web/web-history-selection.png
   :scale: 50%
   :alt: Using selection mode to select items for deletion

.. centered:: |web-history| |web-history-selection|

Once in selection mode, you can select items for deletion. Selected items will show a ticked box next to them, and you can press the **Delete** button at the bottom of the screen to delete them. Press **Cancel** if you want to leave selection mode.

The search button in selection mode can be used to filter the selection before you start choosing items.

To discard all items in the history, press the red **Clear All** button at the bottom-left of the screen.

.. image:: images/web/web-history-clear-all.png
   :align: center
   :scale: 50%
   :alt: The main application menu

Press the **Clear** button if you really want to discard your browsing history -- this operation *cannot be undone*. Press **Cancel** if you decide to keep the history.

Private Browsing
----------------

You can open an *incognito window* to enter private browsing mode. To do this, open the application menu and select **New Incognito Window**.

.. image:: images/web/web-menu-incognito.png
   :align: center
   :alt: The New Incognito Window option is in the main application menu

This browsing mode is useful when you want to visit sites without recording them in your browsing history.

.. image:: images/web/web-incognito.png
   :align: center
   :scale: 50%
   :alt: An incognito browsing window

Private browsing does not make you anonymous online and will not hide your network activity from internet service providers. However, it can still be useful when visiting sites that use cookies and similar tokens to record your visits because private browsing will discard these tokens when you close the window.

Web Applications
----------------

**Web** can turn web sites into standalone web applications. These are shortcuts that open a simple browser interface to sites that are designed to work as mobile applications. These are often sites that provide information, such as a weather service.

Installing a Web Application
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To turn a site into a web application, you first need to open the site in **Web**. Then open the application menu and select **Install Site as Web Application…**

.. image:: images/web/web-install-web-app.png
   :align: center
   :scale: 50%
   :alt: Opening the menu

The **Create Web Application** dialog will open, letting you customize the title that will appear in the app drawer. Press **Create** to create the standalone application, or **Cancel** if you have changed your mind.

.. image:: images/web/web-install-web-app2.png
   :align: center
   :scale: 50%
   :alt: Opening the menu

The created application will appear in the app drawer and can be launched like a standard application.

.. image:: images/web/web-installed-web-app.png
   :align: center
   :scale: 50%
   :alt: The installed web application in the app drawer

When launched, the application behaves like a normal web browser, but the user interface is simpler to use.

.. image:: images/web/web-installed-web-app2.png
   :align: center
   :scale: 50%
   :alt: The simplified user interface

You can now customize the site in the web application to show the information you are interested in. Cookies and site settings for the application are kept separate from those used by your normal **Web** sessions.

Managing Web Applications
~~~~~~~~~~~~~~~~~~~~~~~~~

Web sites that are installed as web applications appear as launcher icons in the phone's app drawer. These applications are not managed like normal applications. Instead, they are managed by **Web** itself, using its application manager. 

Open the application menu and select **Open Application Manager**. By default, no applications are installed.

.. image:: images/web/web-app-manager-empty.png
   :align: center
   :scale: 50%
   :alt: The Web Application manager with no apps installed

If web applications have been installed, they will appear in a list.

.. image:: images/web/web-app-manager.png
   :align: center
   :scale: 50%
   :alt: The Web Application manager

If you want to uninstall a web application and remove its icon from the app drawer, press the **Delete** button next to its name in the list of applications. If you want to reinstall it, you will need to visit the relevant site and following the installation process again.

Preferences
-----------

The browser can be customized via the **Preferences** dialog which can be opened from the application's main menu. The **General** tab contains preferences that are relevant to the general browsing experience.

.. |web-preferences-general-top| image:: images/web/web-preferences-general-top.png
   :scale: 50%
   :alt: The General preferences tab (top)
.. |web-preferences-general-middle| image:: images/web/web-preferences-general-middle.png
   :scale: 50%
   :alt: The General preferences tab (top)
.. |web-preferences-general-bottom| image:: images/web/web-preferences-general-bottom.png
   :scale: 50%
   :alt: The General preferences tab (bottom)

.. centered:: |web-preferences-general-top| |web-preferences-general-middle| |web-preferences-general-bottom|

The **Privacy**, **Appearance** and **Sync** tabs contain preferences that are specific to these areas.

.. |web-preferences-privacy| image:: images/web/web-preferences-privacy.png
   :scale: 50%
   :alt: The Privacy preferences tab
.. |web-preferences-appearance| image:: images/web/web-preferences-appearance.png
   :scale: 50%
   :alt: The Appearance preferences tab
.. |web-preferences-sync| image:: images/web/web-preferences-sync.png
   :scale: 50%
   :alt: The Sync preferences tab

.. centered:: |web-preferences-privacy| |web-preferences-appearance| |web-preferences-sync|

When you have finished updating your preferences, press the back button at the top-left of the screen to return to the current page.
