Breakdown Stylesheets into Logical Parts

Registered by Jaromir Coufal on 2013-06-12

In order to assure better maintainability and better cooperation for contributors, it would be good to breakdown current stylesheet source horizon.less into multiple files based on Horizon's logical parts. Main file (horizon.less) would only include partials and actual styling should happen only in those partials. With this approach we assure that we easier find styling for particular section and if somebody will be dealing only with that section (e.g. instances) he will not have to change one big robust file, but just its related part. Suggested structure will be specified on whiteboard later on.

Blueprint information

Status:
Complete
Approver:
Matthias Runge
Priority:
Low
Drafter:
Jaromir Coufal
Direction:
Approved
Assignee:
Maxime Vidori
Definition:
Approved
Series goal:
Accepted for liberty
Implementation:
Implemented
Milestone target:
milestone icon 8.0.0
Started by
Jaromir Coufal on 2013-09-05
Completed by
David Lyle on 2015-07-15

Related branches

Sprints

Whiteboard

[jcoufal]

Structure proposal:
----------------------------
[layouts]
   | _shell.less
   | _navigation.less
   | _modal.less
   | _detail.less
[responsive]
   | _instances_responsive.less
   | ...
[vars]
   | _mixins.less
   | _vars.less
   | _vars_colors.less
...
... (etc.)
...
_overview.less
_instances.less
_instances_create.less
_instances_edit.less
_instances_detail.less
_volumes.less
...
... (etc.)
...
_responsive.less
dashboard.less
login.less
----------------------------

Basic idea is to have top level stylesheets, each representing one layout (dashboard.less and login.less). That top-level stylesheet includes all related top-level partials in following sequence:
* vars, mixins, resets
* layouts
* sections (like _overview.less, _instances.less, etc.)
* responsives

Each section in the UI needs to have one top-level partial which represents it. For example:
* _instances.less
      = top-level partial, including styling for top-level view (view for menu item Instances) and includes all related sub-partials
* _instances_create.less, instances_edit.less, _instances_detail.less
      = sub-partials are defining views which you can access from the main view (and is related to the view). So, from instances, you can get modal for creating instance, editing instance or instance detail.

Any questions, concerns or suggestions are very welcome.

***

[mvidori]
I started this one, css code is pretty messy, lots of work in propects
I first created this architecture,

[admin]
   _defaults.less
   _domains.less
   _flavors.less
  ...

[layout]
  _alert.less
  _detail.less
  _form.less
  _table.less
...
[project]
  _access_and_security.less
  _containers.less
...
[settings]
  _change_password.less
  _user_settings.less
[vars]
  _mixins.less
  _type.less
  _utils.less
  _vars.less
  _vars_colors.less

dashboard.less
login.less
horizon.less

layout files are full of code but admin, project and settings are pretty empty. I will try to tidy a bit for a first commit.

***

[jcoufal 2013-09-05]
Hey Max, thanks for taking care about this BP. The whiteboard was created before Bootstrap v3 and our upgrade to v3 will affect the file structure. I would just comment with some enhancement proposals, and @jtomasek is going to write more about integration with Bootstrap v3.

[layouts] and [vars] sounds good to me as folders. In [layouts] I would keep global page layouts (or some page subparts related to the page layout - no tables or forms).

Then _tables.less, _forms.less, _buttons.less and similar components (which are globally used) I would move to [components]. Note that we are going to base as much as possible on bootstrap and in components we are going to override and/or enhance bootstrap bits.

Then I don't think we need the separation for [admin] and [project], because they have very similar elements (e.g. instances, volumes, etc) and furthermore there is intention to enhance the IA and then this breakdown will not respect it. I would suggest to keep these in one folder for now, e.g. [specific], which would include _instances.less for example. As you mentioned, in [specific], there would be only view specific things and we need to be very sure, that things which are in specific can't be globally used, so that they belong only to that specific view and not to components.

Otherwise it sounds good to me. I hope you two guys (you and @jtomasek) won't have much conflicts in the code.

***

[jtomasek]

Related to this is my work on updating to Bootstrap 3. (https://blueprints.launchpad.net/horizon/+spec/bootstrap-update) To avoid direct overwriting of Bootstrap code, I have used folowing file structure:

openstack_dashboard/static/bootstrap/less - carries pure bootstrap less code
openstack_dashboard/static/dashboard/less/bootstrap_overrides/
- here are all files that we need to override bootstrap styling, the structure here strictly resembles to bootstrap less files naming. So if we need to override variables, we create variables.less here and import the bootstrap variables file at the beginning of it. Then folder also includes bootstrap.less that looks like this:

@bootstrap-less-root: "../../../bootstrap/less/";

// Core variables and mixins
@import "variables.less";
@import "@{bootstrap-less-root}mixins.less";

// Reset
@import "@{bootstrap-less-root}normalize.less";
@import "@{bootstrap-less-root}print.less";

// Core CSS
@import "@{bootstrap-less-root}scaffolding.less";
@import "@{bootstrap-less-root}type.less";
@import "@{bootstrap-less-root}code.less";

...

in the horizon.less I then include this bootstrap.less file.

The names I pick might not resemble exactly to your desired structure, jcoufal will definitely comment on that. Important thing is that we base on overriding the bootstrap components and we strictly keep up with bootstrap.less file organization and naming.

[hayashi]
mvidori, let me ask a question, incidentally. I also tried to divide the horizon. less for my internal project, then I encountered a problem.
I tried to divide horizon.less like this.
horizon.less
|_navi.less
|_main.less
...
But it seems the less compiler watch only horizon.less, so if I change
navi.less or main.less, re-compile doesn't occur unless I change
horizon.less. Did you encounter same issue?

[mvidori]
I use my own dev environment, to develop on less, in order to avoid this kind of trouble ;). It is a normal behaviour, in _stylesheet.html you can see that only horizon.less is watched by the compress tag, if you modify any other file it would not be compiled unless horizon.less is modified.

[hayashi]
Thanks for reply. Oh, it was same as me. This is not convenient and cause confusion for developers who will update less files. They have to update something horizon.less to reflect other files's change.
Are there any way to avoid this issue? When I use Grunt or lessc, this kind of issue doesn't happen, when change the imported file, compile will be occurred.

Gerrit topic: https://review.openstack.org/#q,topic:bp/css-breakdown,n,z

Addressed by: https://review.openstack.org/45325
    Breakdown Stylesheets into Logical Parts

Addressed by: https://review.openstack.org/76284
    Use the bootstrap mixins and fix table_cell_action

Addressed by: https://review.openstack.org/82215
    Breakdown Stylesheets into Logical Parts

Gerrit topic: https://review.openstack.org/#q,topic:bug/1295847,n,z

Addressed by: https://review.openstack.org/86621
    Refactoring of Horizon navigation

Addressed by: https://review.openstack.org/86537
    Add a centralized palette to Horizon

Addressed by: https://review.openstack.org/103504
    Split workflows and wizards in dedicated files

Gerrit topic: https://review.openstack.org/#q,topic:bp/while,n,z

Addressed by: https://review.openstack.org/106186
    Breakdown CSS: split out the resource browser

Addressed by: https://review.openstack.org/103528
    Breakdown forms in a dedicated file

Addressed by: https://review.openstack.org/106476
    Breakdown CSS: split out the topologies styles

Addressed by: https://review.openstack.org/108489
    Breakdown CSS: pull variables from accordion nav

Addressed by: https://review.openstack.org/108500
    Breakdown CSS: pull varaibles from horizon charts

Addressed by: https://review.openstack.org/110796
    Lint-based cleanup of 2 scss files

Addressed by: https://review.openstack.org/115736
    Breakdown CSS: split styling for table inline edits

Gerrit topic: https://review.openstack.org/#q,topic:bug/inline-edits,n,z

Gerrit topic: https://review.openstack.org/#q,topic:bug/1351395,n,z

Addressed by: https://review.openstack.org/116442
    Fix broken network topology css

[david-lyle 2014.08.26] Moving milestone to Kilo

Addressed by: https://review.openstack.org/117118
    Restyled topbar to resemble UX guidelines

Gerrit topic: https://review.openstack.org/#q,topic:bug/1390104,n,z

Addressed by: https://review.openstack.org/133703
    Reorganized scss imports

Addressed by: https://review.openstack.org/158082
    Move variables from accordion nav to _variables.scss

Addressed by: https://review.openstack.org/159300
    WIP - Custom Horizon Theme

(?)

Work Items

Dependency tree

* Blueprints in grey have been implemented.

This blueprint contains Public information 
Everyone can see this information.