Layout and styling¶
Styling is probably not the first thing a programmer wants to worry about. That is why Reahl comes with some styling you can use when starting a project – perhaps to be replaced by a graphic designer later.
Let us detour to introduce layout and styling ideas because that will allow us to to make the rest of the examples in the tutorial look just a little bit better.
Layout¶
A Layout is used to change what a Widget looks like, what css
classes are attached to it for styling, or even how children Widgets are added to it – all for the purpose of influencing look and
layout.
A Widget is configured to use a particular Layout by calling
reahl.web.fw.Widget.use_layout() on the Widget after
construction. (You can also call
reahl.web.fw.WidgetFactory.use_layout() where you construct only
a WidgetFactory for later use.) For example,
the HorizontalLayout or
VerticalLayout can be used to make a
Menu appear with its items horizontally next to
each other or stacked vertically.
Some layout concepts are implemented in terms of some frontend library, others are generally applicable.
The pure module includes some layouts based on the
Pure.css framework. The ColumnLayout
changes a Widget by adding several Divs to
it that are arranged as columns next to each other. You can specify
the size of these columns, and in such a way that the size can change,
depending on the size of the device used for viewing. See the
documentation for ColumnLayout and UnitSize for more details.
(See Package reahl.web.bootstrap for Layouts and Widgets built using the
Bootstrap library.)
The layout module houses generically applicable concepts.
PageLayout is meant to be used with an
HTML5Page. It changes the page to have a header
and footer with a content area in between. If a ColumnLayout
(for example) is passed to the PageLayout constructor,
it will automatically be used as the layout of the content area of the page.
Here is an example of how PageLayout and
ColumnLayout can be used in conjunction to
create a page with some structure. In the example,
HorizontalLayout is also used to specify how
the Menu is presented.
class MyCustomPage(HTML5Page):
def __init__(self, view, bookmarks):
super(MyCustomPage, self).__init__(view, style='basic')
self.use_layout(PageLayout())
contents_layout = ColumnLayout(('secondary', UnitSize('1/4')),
('main', UnitSize('3/4'))).with_slots()
self.layout.contents.use_layout(contents_layout)
menu = Menu(view).use_layout(HorizontalLayout()).with_bookmarks(bookmarks)
self.layout.header.add_child(menu)
Special Widgets¶
There are also some Widgets with special behaviour that relate to
layout and styling:
LabelledBlockInput- This
Widgetwraps around anInput, and adds aLabelto it. The combination of theInputand itsLabelare then arranged in two columns next to each other. SuccessiveLabelledBlockInputs appear underneath each other, with all theLabels aligned and all the Inputs aligned. LabelledInlineInput- A
LabelledInlineInputalso wraps around anInputand adds aLabel. The result though is an element that flows with text and can be used as part of a paragraph (P), for example. PriorityGroupSometimes it is useful to visually highlight certain
Widgets to make them stand out amongst their peers. This concept is called the “priority” of aWidget. Normally, you would not specify the priority of aWidget. But, amongst chosen grouping ofWidgets, you may set oneWidgetas having “primary” priority, with the others having “secondary” priority.A
Widgetwith “secondary” priority will have a CSS class reahl-priority-secondary attached to it, which is normally styled such that it fades a bit into the background (perhaps lighter, or slightly greyed out). AWidgetwith “primary” priority will have CSS class reahl-priority-primary which is normally styled such that it stands out visually.The
PriorityGroupis an object to which you can addWidgets, stating their priority (or lack of it). ThePriorityGroupwill ensure that only one of theWidgets added to it will ever have primary priority. (Many could have no priority set, and many could be secondary.)
Styling¶
Complex Widgets in Reahl are written such that the Widget has an
identifiable HTML element that represents the Widget. Identifiable
means that the HTML element has an id or class attribute which can be
used as target of CSS selectors. This allows for CSS to be attached to
each Widget (or its contents). For example, the TabbedPanel is in a
<div class=”reahl-tabbedpanel”>. Widgets that map one-to-one to HTML
tags do not have special classes – they can be targeted in CSS by just
using the HTML tag name they represent: the reahl.web.ui.P Widget is just a <p>,
for example.
Any Layout can add additional CSS classes to a
Widget or change how content is added to it.
Given these ways to be able to target a Widget
(possibly modified by a specific Layout) via
CSS, you can write normal CSS to provide your own look and feel for
Reahl Widgets (if you really want to). In the
reference documentation for each Widget an
explanation is given of what the HTML for that
Widget looks like, for this purpose. (Similar
documentation is provided with Layouts.)
In order to use your own CSS on a page, you need to add a link to it on your HTML5Page subclass. For example in the __init__ of your class, you can write:
self.head.add_css(Url('/link/to/my/own.css'))
The minutiae of what Widgets look like is probably not the first thing on a
programmer’s mind however. It is useful just to start programming using some
look for the Widgets, and later customise this look to your
liking. For this reason, a stylesheet is provided which includes
styling for all the standard Reahl Widgets. You can include this style
by adding it to the Head of your HTML5Page:
self.head.add_css(Url('/styles/basic.css'))
If you are using the HTML5Page as a page, the same effect
can be accomplished by merely passing style='basic' to its
constructor (as can be seen in almost all of our code examples so
far).