Icingaweb2: Icinga Web Development Guide

Created on 23 Mar 2020 · 10Comments · Source: Icinga/icingaweb2

Hi,

Since we're heavily lacking documentation on how Icinga Web works and how to get started with module development, I want to elaborate what's necessary for a useful guide. I think it makes sense that we settle on the index here and create the contents in a new repository, e.g. Icinga/web-development.

The following is an abstract of the main topics the guide should cover. Please add your feedback.
What's missing? What is not necessary? What should be explained in detail? ...

Icinga Web Development Guide

Introduction

We should start off with a little explanation on how Icinga web development looks like and which layers are necessary in order to build a web application:

Explain frontend development (client-side)
Explain backend development (server-side)
Explain storage features (files, database)

Programming, Markup and Database Languages

The guide should explain our used languages, i.e.

Sever-side

PHP 5.6+, preferably PHP7

Client-side

JavaScript: ES5 (ES6 once we updated our code base)

Markup

HTML5
CSS3

Storage

INI and JSON files
MySQL
PostgreSQL

Browser, OS and Web Server Support

The guide should state which browsers, operating systems and web servers the Icinga web ecosystem supports.

PHP and JavaScript Style Guide

Of course, it is never bad to mention the style guides somewhere.

Basics and Technologies

Before deep diving into writing code, we should explain necessary basics and technologies:

HTTP protocol
- This may include an explanation for our special HTTP headers and their handling, but there may also be an extra chapter for this
Cookies
- This may include information about our cookies and their handling, but there may also be an extra chapter for this
Ajax
MVC
JavaScript and CSS delivery
X-column layout
URL handling
Form redirects
Flow of requests, i.e. first request is a full-page load including the delivery of JavaScript and CSS and every subsequent request is AJAX
Convention over configuration
Translation

Git

This chapter should cover branch naming conventions and workflows, commit message anatomy and provide a cheat sheet for common Git magic that we use every day, e.g. squash, rebase, interactive rebase, git add -p.

SQL

We follow some conventions when designing databases and learned best practices during our developments which are definitely worth sharing.

Development Environment

We should have a dedicated chapter for setting up a dev environment also integrating XDebug. I do think that this will be a docker setup.

Development

This is an incomplete list of topics which the development chapter should cover, and it also only lists the main topics for the moment:

Conventions, e.g. naming, directory structure, meta information
Controllers
Auto-refresh
Views
Custom CSS
Forms
Configuration
Menu
Dashboards
Database access
Permissions and restrictions
Hooks
Translation
Custom JS
CLI

/cc @nbuchwitz @Mikesch-mp @mcktr @patrickpr @nunofernandes @archandha @cstegm @LordHepipud @friesoft @plsatin @b0e @attachmentgenie @wols @tobias-urdin

aredocumentation enhancement help wanted

Source

lippserd

👍8 ❤1

Most helpful comment

Thanks for taking the initiative! The lists looks already very compressive. Maybe it's worth mentioning which frameworks and libraries already exist in the Icinga ecosystem (IPL, react, JS frameworks etc.)

nbuchwitz on 23 Mar 2020

👍5

All 10 comments

great initiative, seems like a comprehensive list already

attachmentgenie on 23 Mar 2020

👍2

nbuchwitz on 23 Mar 2020

👍5

Thanks for taking the initiative! The lists looks already very compressive. Maybe it's worth mentioning which frameworks and libraries already exist in the Icinga ecosystem (IPL, react, JS frameworks etc.)

Yeah, absolutely makes sense. Thx. I wanted to add the IPL (Icinga PHP Library) to the list anyway since we'll add docs, guides and blog posts over the next weeks as well.

lippserd on 23 Mar 2020

👍1

Hi,

Nice idea. For now I don't see anything to add.

For the dev environment, I prefer using virtual machines instead of
docker and I can provide description/process/VM of my environment.

Regards,

Patrick Proy

Le 23/03/2020 à 22:12, Eric Lippmann a écrit :
>

Hi,

Since we're heavily lacking documentation on how Icinga Web works and
how to get started with module development, I want to elaborate what's
necessary for a useful guide. I think it makes sense that we settle on
the index here and create the contents in a new repository, e.g.
Icinga/web-development.

The following is an abstract of the main topics the guide should
cover. Please add your feedback.
What's missing? What is not necessary? What should be explained in
detail? ...

Icinga Web Development Guide
Introduction
We should start off with a little explanation on how Icinga web
development looks like and which layers are necessary in order to
build a web application:

Explain frontend development (client-side)

Explain backend development (server-side)

Explain storage features (files, database)

Programming, Markup and Database Languages

The guide should explain our used languages, i.e.

Sever-side

PHP 5.6+, preferably PHP7

Client-side

JavaScript: ES5 (ES6 once we updated our code base)

Markup

HTML5

CSS3

Storage

INI and JSON files

MySQL

PostgreSQL

Browser, OS and Web Server Support

The guide should state which browsers, operating systems and web
servers the Icinga web ecosystem supports.
PHP and JavaScript Style Guide
Of course, it is never bad to mention the style guides somewhere.
Basics and Technologies
Before deep diving into writing code, we should explain necessary
basics and technologies:

HTTP protocol
o This may include an explanation for our special HTTP headers
and their handling, but there may also be an extra chapter for
this

Cookies
o This may include information about our cookies and their
handling, but there may also be an extra chapter for this

Ajax

MVC

JavaScript and CSS delivery

X-column layout

URL handling

Form redirects

Flow of requests, i.e. first request is a full-page load including
the delivery of JavaScript and CSS and every subsequent request is
AJAX

Convention over configuration

Translation

Git

This chapter should cover branch naming conventions and workflows,
commit message anatomy and provide a cheat sheet for common Git magic
that we use every day, e.g. squash, rebase, interactive rebase, git
add -p.
SQL
We follow some conventions when designing databases and learned best
practices during our developments which are definitely worth sharing.
Development Environment
We should have a dedicated chapter for setting up a dev environment
also integrating XDebug. I do think that this will be a docker setup.
Development
This is an incomplete list of topics which the development chapter
should cover, and it also only lists the main topics for the moment:

Conventions, e.g. naming, directory structure, meta information

Controllers

Auto-refresh

Views

Custom CSS

Forms

Configuration

Menu

Dashboards

Database access

Permissions and restrictions

Hooks

Translation

Custom JS

CLI

/cc @nbuchwitz https://github.com/nbuchwitz @Mikesch-mp
https://github.com/Mikesch-mp @mcktr https://github.com/mcktr
@patrickpr https://github.com/patrickpr @nunofernandes
https://github.com/nunofernandes @archandha
https://github.com/archandha @cstegm https://github.com/cstegm
@LordHepipud https://github.com/LordHepipud @friesoft
https://github.com/friesoft @plsatin https://github.com/plsatin
@b0e https://github.com/b0e @attachmentgenie
https://github.com/attachmentgenie @wols https://github.com/wols
@tobias-urdin https://github.com/tobias-urdin

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/Icinga/icingaweb2/issues/4109, or unsubscribe
https://github.com/notifications/unsubscribe-auth/AAWHIMWSJOBHEHYTBCY4OZDRI7GC7ANCNFSM4LSFU3LQ.

patrickpr on 24 Mar 2020

This is AWESOME

Mikesch-mp on 24 Mar 2020

That's exactly what some colleagues of me are waiting for 🙏

K0nne on 24 Mar 2020

Hi,

thanks for opening this issue and also for inviting community members for discussion. I think together with the community we establish a good development documentation.

I think it makes sense that we settle on the index here and create the contents in a new repository, e.g. Icinga/web-development.

Can we reconsider this? I would like to have the development documentation included in this repository, like it is in the repository of the core Icinga 2. I also think we should use the same approach in every project repository. Thereby new contributors know that they will always find the development documentation at a specific place, the repository where the contributor is working on.

I understand that the web repositories may differ from the core and they share a big amount of development documentation which then needs double maintenance. To tackle this problem I suggest that the _main_ development documentation is located here, the modules than only contains documentation for their specialities and for all other they refer to the main web development documentation.

I am not against the first suggestion per se, this is only what is floating around in my head while reading with an eye on new contributors and how they search for documentation. I am open for counter opinions maybe I have one aspect not on my radar.

Best regards
Michael

mcktr on 24 Mar 2020

👍1

It's not as complex as an Icinga Web 2 module, but for the new Icinga for Windows tool I tried to start with a step-by-step developer guide to give some ideas on how for example a custom background daemon can be written from scratch and some function explanations.

The documentation for that is already online: Icinga for Windows Developer Guide

It is far from finished and more hands-on guides are hopefully following soon, but at least I hope this is a good start for this certain project.

Maybe We can approach Icinga Web 2 modules in a similar way?

LordHepipud on 25 Mar 2020

👍1

We should try to avoid explaining topics in too much detail which are already well documented externally. This applies to the following:

Used languages
- That's e.g. PHP, besides mentioning its name (with a link php.org), its ecosystem (composer, packagist, etc), wanted style guide and a short description of how it's used should be enough.
- I really don't want to explain syntax elements here.
Basics and Technologies
- HTTP, Cookies, XHR, MVC, etc. Yes we use them, yes we have customizations which need mentioning, but there are hopefully still more external links than actual documentation.

Things I'd like to see added:

Custom JS
- events and best practices handling them
- what are behaviors, how do they work
Custom CSS
- Sandboxing and how/when to break out
- Themes, what they should do, what not
- Responsiveness, em/vh/etc VS px, generally how we utilize font-size here
Unittests
- How to write one
- How to run it

@mcktr The basic documentation such as installation and configuration still will be kept in each repository. Development and end-user documentation however has a way more broad coverage of common topics and needs also updates due to changing technology and, well, additional chapters (over time). That's why a separate versioning system comes in handy, you can easily create different releases (versions) of documentation. Sure, we then have to ensure contributors are aware of this place but that's not a huge problem I guess. :smile:

nilmerg on 31 Mar 2020

I was forwarded here from issue #4296. From my point of view writing documentation is tedious and the result is always stale. I'd appreciate some structured documentation in the code. Maybe generating some formatted (HTML?) output to disk saves some IDE/ symbol backtracking to reconstruct a callstack's types in my head.

The only abstract section above would be some kind of coarse grained architecture. This is only to separate the different components and principles. It also serves as a sort of foundation for decisions: where should I put some auto-refresh or where is it discouraged.