diff --git a/docs/source/create_a_napp_with_ui.rst b/docs/source/create_a_napp_with_ui.rst deleted file mode 100644 index 0e2db4d..0000000 --- a/docs/source/create_a_napp_with_ui.rst +++ /dev/null @@ -1,169 +0,0 @@ -Create a NApp with UI -##################### - -Sometimes, it is necessary for a Napp to interact with the user, for -through a graphical interface (not just API REST). - -We have developed `vue-js` based components (`Vuejs `_), so -that you, developer, worry as little as possible about interface. - -In theory, you can during the construction of your NAPP UI, write any HTML code -that Kytos will render. However, we strongly recommend that you use the -components we have developed. The so-called ``k-*`` components. - - -Napp Structure with a UI -************************ - -After create a new NApp (see this `NApp tutorial -`_) the structure below will -be created. - -.. code-block:: sh - - - ├── __init__.py - └── / - ├── __init__.py - ├── kytos.json - ├── main.py - ├── README.rst - ├── settings.py - └── ui/ - ├── k-info-panel/ - ├── k-toolbar/ - └── README.rst - - -To add a new components into the kytos UI you must create a new file following -the pattern ``ui/
/.kytos``, where **
** should be -the section name where the new component will be fixed and the **** -should be the component name. - -Whether I have created a new napp component into the sections ``k-toolbar`` and -``k-info-panel`` the napp structure should have the following structure. - -.. code-block:: sh - - - ├── __init__.py - └── - ├── __init__.py - ├── kytos.json - ├── main.py - ├── README.rst - ├── settings.py - └── ui - ├── k-info-panel - │   └── main.kytos - ├── k-toolbar - │   └── main.kytos - └── README.rst - - -When the administrator enables their NApp, Kytos will automatically scan the -``ui/*`` structure to properly export to GUI. - -Component Template -****************** - -The kytos component should follow some rules. - -#. The component file should have the extention ``.kytos`` - -#. The component file need to have 3 sections: - - #. template: This section must be filled with html contents to display your graphical component.This section should have a html syntax and you can use the kytos componenets. - #. script : This section must be filled with section using javascript.This section is required to handle your component actions. - #. style (optional): section using css styles, this section is optional because all kytos components have the styles already defined. - -Below a template of kytos component is displayed. - -.. code-block:: html - - - - - - - - -You should replace the **my_icon** to an **awesome icon**, the kytos interface -will read that icon and create a new button into the **k-menu-bar**. You -can replace the string **Sample Tooltip** to display a tooltip in your -**k-menu-bar** button. - - -Sample Component -**************** - -Status-Component -================ - -Below we have a ``ui/k-toolbar/status-component.kytos`` file. This -component was build to request the kytos server and get all napps informations -and display that into the component. - -.. code-block:: html - - - - diff --git a/docs/source/creating_a_napp.rst b/docs/source/creating_a_napp.rst new file mode 100644 index 0000000..4b9ccd9 --- /dev/null +++ b/docs/source/creating_a_napp.rst @@ -0,0 +1,111 @@ +Creating a NApp with UI +####################### + +Most of the times, it is necessary for a NApp to interact with the user, for +through a graphical interface (not just REST APIs). + +We have developed `vue-js` based components (`Vuejs `_), so +that you, developer, worry as little as possible about interface. Do not worry, +you don't have to understand how `vue-js` works. + +In theory, during the construction of your NApp UI you can write any HTML code +that Kytos will render. However, we strongly recommend that you use the +components we have developed. The so-called ``k-*`` components. + + +NApp Structure with a UI +************************ + +After create a new NApp (see this `NApp tutorial +`_) the structure below +will be created. + +.. code-block:: sh + + + ├── __init__.py + └── / + ├── __init__.py + ├── kytos.json + ├── main.py + ├── README.rst + ├── settings.py + └── ui/ + ├── k-info-panel/ + ├── k-toolbar/ + └── README.rst + + +To add a new components into the kytos UI you must create a new file following +the pattern ``ui/
/.kytos``, where **
** should be +the section name where the new component will be fixed and the **** +should be the component name. You are free to choose any file name here. + +Whether you have created a new NApp component into the sections ``k-toolbar`` +and ``k-info-panel`` the NApp structure should have the following structure. + +.. code-block:: sh + + / + ├── __init__.py + └── / + ├── __init__.py + ├── kytos.json + ├── main.py + ├── README.rst + ├── settings.py + └── ui/ + ├── k-info-panel/ + │   └── main.kytos + ├── k-toolbar/ + │   └── main.kytos + └── README.rst + + +When the administrator enables your NApp, Kytos will automatically scan the +``ui/*`` structure to properly export to GUI. + +Component Template +****************** + +The Kytos component should follow some rules: + +#. The component file should have the extension ``.kytos`` + +#. The component file must have 2 sections: + + #. template: This section must be filled with html contents to display your + graphical component.This section should have a html syntax and you can + use the Kytos components. + #. script (optional): This section has javascript code that implements your + component behaviour. + +Below an example of a Kytos component (`ui/k-toolbar/main.kytos`), that will be +displayed on our UI. + +.. code-block:: html + + + + + + +You can use any **font-awesome icon**. Kytos ui interface will read that icon +and create a new button into the **k-menu-bar**. diff --git a/docs/source/index.rst b/docs/source/index.rst index ded8831..ba55564 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -17,95 +17,101 @@ screens using the Kytos platform. Kytos Graphical User Interface -Kytos UI Sections -***************** +Understanding Kytos UI Sections +******************************* Our interface is constantly changing, we are always evolving, even more at this -early stage of the project. But we believe that we arrive at a layout that we -are comfortable to evolve from it. +early stage of the project. But we believe that we reach a layout that we are +comfortable to evolve from it. -The following images we have the kytos UI sections. +The following images you can see the Kytos UI sections. .. figure:: _static/imgs/kytos-ui-parts.png :alt: Kytos Graphical User Interface :align: center +As you can see, our Kytos Toolbar can be expanded or compressed (at top of +screen). -Bar Menu +Menu Bar ======== -UI component: ``k-menu-bar`` +UI component: `k-menu-bar` The bar menu is a small vertical band that sits on the left side of the screen under the logo. This menu consists of buttons that trigger the respective -oolbars, or trigger other actions. +toolbars, or trigger other actions. -#. **k-logo**: When pressed the k-toolbar will switch between - expandeded and compacted version. -#. **Item**: Change the k-toolbar context to display the napps component. - - -The amount of buttons that will appear here will depend on how many NApps you -have enabled in Kytos. +The amount of buttons (items) that will appear here will depend on how many +NApps you have enabled in Kytos. As a NApp developer, you can register a new +entry here, creating a file and defining a new toolbar under the +`ui/k-toolbar/` folder. We will describe this better, latter. Toolbar ======= -UI component: ``k-toolbar`` +UI component: `k-toolbar` -The ``k-toolbar`` component contains the current activated ``k-menu-bar`` item. +The `k-toolbar` component contains the current activated `k-menu-bar` item. +This is the content of the toolbar component defined by the NApps. This toolbar is usually used for **input** controls. For example, if your application needs some input from the user, we strongly recommend inserting these inputs into a toolbar. This toolbar can exist in two versions: compressed and expanded. When expanded -it appears on the side of ``k-menu-bar``, and when compressed it appears at the +it appears on the side of `k-menu-bar`, and when compressed it appears at the top of the screen. .. note:: Of course, there are some components that are not good to display in - compressed form. For example it is a big challenge to display a `k-table` - inside a compressed toolbar. For this reason only components with compact - version will be displayed in the k-toolbar in compact version. - k-toolbar does not have `k-*` components in compact version. - The `k-toolbar` don't will be displayed if don't have kytos components in - compacted version. + compressed form. For instance: it is a big challenge to display a + `k-property-panel` inside a compressed toolbar. For this reason only + components with compacted versions will be displayed in the `k-toolbar` + using the compact form. + + If a component is too big to be compacted it will not be displayed on + `k-toolbar` compacted version. Map/Topology ============ -UI component: ``k-map`` +UI component: `k-map` -The k-map component is responsible to display a map and render the network -topology will all hosts and switch connected. +The `k-map` component is responsible for display a map and render the network +topology will all hosts and connected switches. For now, you, the developer of NAPP, do not have to worry about this section. -In the future we pretend to make some actions available so you can manipulate a -topology and the map. +In the future we pretend to make some actions available so you can manipulate +the topology and the map. Info Panel ========== -UI component: ``k-info-panel`` +UI component: `k-info-panel` -The ``k-info-panel`` component is responsible for show generic information. So +The `k-info-panel` component is responsible for show generic information. So for example, if you want to display the result of something, or some information, use the info panel. Tabs ==== -UI component: ``k-tabs`` +UI component: `k-tabs` -The k-tabs components is responsible to have a terminal, show switch +The `k-tabs` components is responsible to have a terminal, show switch informations, logs of kytos instance and kytos ui alerts. +For now, you, the developer of NAPP, do not have to worry about this section. +In the future we pretend to make some actions available so you can manipulate +the topology and the map. + Actions Menu ============ -UI component: ``menu-actions`` +UI component: `menu-actions` -If you try to press ``ctrl + space`` a list of actions will appear at the -center of Kytos UI. +If you try to press `ctrl + space` a list of actions will appear at the center +of Kytos UI. This is another way to trigger actions that you think that is not +suitable for the toolbar, for instance. diff --git a/docs/source/kytos_components.rst b/docs/source/kytos_components.rst deleted file mode 100644 index 5235667..0000000 --- a/docs/source/kytos_components.rst +++ /dev/null @@ -1,13 +0,0 @@ -################ -Kytos Components -################ - -The components contain the options of the base components “mixed”, such as methods and -properties. When a component uses a mixin, all -options will be “mixed” into the component’s own options, that is a -way to distribute reusable functionalities to the components. - -.. toctree:: - :glob: - - components/* diff --git a/docs/source/kytos_components_api.rst b/docs/source/kytos_components_api.rst new file mode 100644 index 0000000..18da897 --- /dev/null +++ b/docs/source/kytos_components_api.rst @@ -0,0 +1,18 @@ +#################### +Kytos Components API +#################### + +Bellow you can find all Kytos components that you can use in your code. + +K-* components +============== + +.. include:: + :glob: + + components/* + +K-* Events +========== + + k-status-bar diff --git a/docs/source/references.rst b/docs/source/references.rst index 2f39724..3b75cb2 100644 --- a/docs/source/references.rst +++ b/docs/source/references.rst @@ -3,5 +3,5 @@ :glob: index - create_a_napp_with_ui - kytos_components + creating_a_napp + kytos_components_api