Update docs for auto js file discovery
This patch updates the docs following the merge of most of the auto js file discovery patches. It also fixes a few minor issues with the documentation. Change-Id: I419b7c861683ccb67f0cbadac666627602e3006c Partially-Implements: blueprint angular-docs
This commit is contained in:
Rob Cresswell
parent
653f85444f
commit
ef41525cef
@ -64,19 +64,26 @@ is likely to be used across many parts of horizon.
|
||||
When adding code to horizon, consider whether it is panel-specific or should be
|
||||
broken out as a reusable utility or widget.
|
||||
|
||||
Panel-specific code is in ``openstack_dashboard/static/dashboard/``.
|
||||
|
||||
The modal directive is a good example of the file structure. This is a reusable
|
||||
component:
|
||||
::
|
||||
|
||||
horizon/static/framework/widgets/modal/
|
||||
├── modal.controller.js
|
||||
├── modal.service.js
|
||||
├── modal.module.js
|
||||
├── modal.service.js
|
||||
├── modal.spec.js
|
||||
└── simple-modal.html
|
||||
|
||||
Panel-specific code is in ``openstack_dashboard/static/dashboard/``. For example:
|
||||
::
|
||||
|
||||
openstack_dashboard/static/dashboard/workflow/
|
||||
├── decorator.service.js
|
||||
├── workflow.module.js
|
||||
├── workflow.module.spec.js
|
||||
└── workflow.service.js
|
||||
|
||||
For larger components, such as workflows with multiple steps, consider breaking
|
||||
the code down further. The Angular **Launch Instance** workflow,
|
||||
for example, has one directory per step
|
||||
@ -85,10 +92,12 @@ for example, has one directory per step
|
||||
Testing
|
||||
=======
|
||||
|
||||
1. Open <dev_server_ip>/jasmine in a browser. The development server can be run
|
||||
1. Open <dev_server_ip:port>/jasmine in a browser. The development server can be run
|
||||
with``./run_tests.sh --runserver`` from the horizon root directory.
|
||||
2. ``npm run test`` from the horizon root directory.
|
||||
|
||||
The code linting job can be run with ``npm run lint``.
|
||||
|
||||
For more detailed information, see :doc:`javascript_testing`.
|
||||
|
||||
Translation (Internationalization and Localization)
|
||||
@ -124,9 +133,8 @@ Creating your own panel
|
||||
as an example.
|
||||
|
||||
.. Note::
|
||||
File inclusion is likely to be automated soon, after this
|
||||
`blueprint <https://blueprints.launchpad.net/horizon/+spec/auto-js-file-finding>`_
|
||||
is completed.
|
||||
Currently, Angular module names must still be manually declared with
|
||||
``ADD_ANGULAR_MODULES``, even when using automatic file discovery.
|
||||
|
||||
This section serves as a basic introduction to writing your own panel for
|
||||
horizon, using AngularJS. A panel may be included with the plugin system, or it may be
|
||||
@ -135,36 +143,23 @@ part of the upstream horizon project.
|
||||
Upstream
|
||||
--------
|
||||
|
||||
If you are adding a panel to horizon, add the relevant ``.js`` and ``.spec.js``
|
||||
files to one of the dashboards in ``openstack_dashboard/enabled/``.
|
||||
An example can be found at ``openstack_dashboard/enabled/_10_project.py``:
|
||||
::
|
||||
JavaScript files can be discovered automatically, handled manually, or a mix of
|
||||
the two. Where possible, use the automated mechanism.
|
||||
To use the automatic functionality, add::
|
||||
AUTO_DISCOVER_STATIC_FILES = True
|
||||
to your ``enabled/___.py``. To make this possible, you need to follow some
|
||||
structural conventions:
|
||||
|
||||
LAUNCH_INST = 'dashboard/launch-instance/'
|
||||
- Static files should be put in a ``static/`` folder, which should be found directly under
|
||||
the folder for the dashboard/panel/panel groups Python package.
|
||||
- JS code that defines an Angular module should be in a file with extension of ``.module.js``.
|
||||
- JS code for testing should be named with extension of ``.mock.js`` and of ``.spec.js``.
|
||||
- Angular templates should have extension of ``.html``.
|
||||
|
||||
ADD_JS_FILES = [
|
||||
...
|
||||
LAUNCH_INST + 'launch-instance.js',
|
||||
LAUNCH_INST + 'launch-instance.model.js',
|
||||
LAUNCH_INST + 'source/source.js',
|
||||
LAUNCH_INST + 'flavor/flavor.js',
|
||||
...
|
||||
]
|
||||
You can read more about the functionality in the
|
||||
:ref:`auto_discover_static_files` section of the settings documentation.
|
||||
|
||||
ADD_JS_SPEC_FILES = [
|
||||
...
|
||||
LAUNCH_INST + 'launch-instance.spec.js',
|
||||
LAUNCH_INST + 'launch-instance.model.spec.js',
|
||||
LAUNCH_INST + 'source/source.spec.js',
|
||||
LAUNCH_INST + 'flavor/flavor.spec.js',
|
||||
...
|
||||
]
|
||||
|
||||
Plugins
|
||||
-------
|
||||
|
||||
Add a new panel/ panel group/ dashboard (See :doc:`tutorial`). Add your files
|
||||
to the relevant arrays in your new enabled files:
|
||||
To manually add files, add the following arrays and file paths to the enabled file:
|
||||
::
|
||||
|
||||
ADD_JS_FILES = [
|
||||
@ -178,3 +173,33 @@ to the relevant arrays in your new enabled files:
|
||||
'path_to/my_angular_code.spec.js',
|
||||
...
|
||||
]
|
||||
|
||||
ADD_ANGULAR_MODULES = [
|
||||
...
|
||||
'angular.module',
|
||||
...
|
||||
]
|
||||
|
||||
Plugins
|
||||
-------
|
||||
|
||||
Add a new panel/ panel group/ dashboard (See :doc:`tutorial`). JavaScript file
|
||||
inclusion is the same as the Upstream process.
|
||||
|
||||
To include external stylesheets, you must ensure that ``ADD_SCSS_FILES`` is
|
||||
defined in your enabled file, and add the relevant filepath, as below:
|
||||
::
|
||||
|
||||
ADD_SCSS_FILES = [
|
||||
...
|
||||
'path_to/my_styles.scss',
|
||||
...
|
||||
]
|
||||
|
||||
.. warning::
|
||||
We highly recommend using a single SCSS file for your plugin. SCSS supports
|
||||
nesting with @import, so if you have multiple files (i.e. per panel styling)
|
||||
it is best to import them all into one, and include that single file. You can
|
||||
read more in the `SASS documentation`_.
|
||||
|
||||
.. _SASS documentation: http://sass-lang.com/documentation/file.SASS_REFERENCE.html#import
|
||||
|
||||
@ -30,7 +30,7 @@ Running Tests
|
||||
|
||||
Tests can be run in two ways:
|
||||
|
||||
1. Open <dev_server_ip>/jasmine in a browser. The development server can be
|
||||
1. Open <dev_server_ip:port>/jasmine in a browser. The development server can be
|
||||
run with ``./run_tests.sh --runserver`` from the horizon root directory.
|
||||
2. ``npm run test`` from the horizon root directory. This runs Karma,
|
||||
so it will run all the tests against PhantomJS and generate coverage
|
||||
@ -53,11 +53,6 @@ found at ``horizon/.coverage-karma/`` (framework tests) and
|
||||
Writing Tests
|
||||
=============
|
||||
|
||||
.. Note::
|
||||
File inclusion is likely to be automated soon, after this
|
||||
`blueprint <https://blueprints.launchpad.net/horizon/+spec/auto-js-file-finding>`_
|
||||
is completed.
|
||||
|
||||
Jasmine uses suites and specs:
|
||||
* Suites begin with a call to ``describe``, which takes two parameters; a
|
||||
string and a function. The string is a name or title for the spec suite,
|
||||
@ -68,25 +63,24 @@ Jasmine uses suites and specs:
|
||||
the code. An expectation in Jasmine is an assertion that is either true or
|
||||
false; every expectation in a spec must be true for the spec to pass.
|
||||
|
||||
Horizon Tests
|
||||
-------------
|
||||
``.spec.js`` files can be handled manually or automatically. To use the
|
||||
automatic file discovery add::
|
||||
AUTO_DISCOVER_STATIC_FILES = True
|
||||
to your enabled file. JS code for testing should use the extensions
|
||||
``.mock.js`` and ``.spec.js``.
|
||||
|
||||
Horizon tests are included in
|
||||
``horizon/test/jasmine/jasmine_tests.py``.
|
||||
You can read more about the functionality in the
|
||||
:ref:`auto_discover_static_files` section of the settings documentation.
|
||||
|
||||
Add your test to the ``specs`` array, code sources to the ``dashboard_sources``
|
||||
array, and any templates to the ``externalTemplates`` array. Horizon tests
|
||||
cover reusable components, as well as api functionality, whilst dashboard
|
||||
tests cover specific panels and their logic. The tests themselves are kept in
|
||||
the same directory as the implementation they are testing.
|
||||
To manually add specs, add the following array and relevant file paths to your
|
||||
enabled file:
|
||||
::
|
||||
|
||||
OpenStack Dashboard Tests
|
||||
-------------------------
|
||||
|
||||
Dashboard tests are included in the relevant dashboard enabled file, such as
|
||||
``openstack_dashboard/enabled/_10_project.py``.
|
||||
|
||||
Add your tests to the ``ADD_JS_SPEC_FILES`` array.
|
||||
ADD_JS_SPEC_FILES = [
|
||||
...
|
||||
'path_to/my_angular_code.spec.js',
|
||||
...
|
||||
]
|
||||
|
||||
Examples
|
||||
========
|
||||
@ -104,8 +98,8 @@ File tree:
|
||||
|
||||
horizon/static/framework/widgets/modal
|
||||
├── modal.controller.js
|
||||
├── modal.service.js
|
||||
├── modal.module.js
|
||||
├── modal.service.js
|
||||
└── modal.spec.js
|
||||
|
||||
Lines added to ``horizon/test/jasmine/jasmine_tests.py``:
|
||||
|
||||
@ -1247,6 +1247,8 @@ A list of scss files to be included in the compressed set of files that are
|
||||
loaded on every page. We recommend one scss file per dashboard, use @import if
|
||||
you need to include additional scss files for panels.
|
||||
|
||||
.. _auto_discover_static_files:
|
||||
|
||||
``AUTO_DISCOVER_STATIC_FILES``
|
||||
------------------------------
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user