immonex Kickstart

immonex Kickstart is a WordPress plugin that provides essential customizable components (property seach, list and detail views, location maps etc.) for publishing imported OpenImmo®-based property offers in real estate websites built on multi-purpose themes in an easy and visually appealing way. Beyond that, it's also a framework for add-ons - separate plugins that extend the functionality on the same foundation.

immonex® is an umbrella brand for various real estate related software solutions and services with a focus on german-speaking countries/users.

OpenImmo-XML is the de-facto standard for exchanging real estate data in the german-speaking countries. Here, it is supported by almost every common software solution and portal for real estate agencies (as import/export interfaces).

Basics & Scope

Kickstart itself is available in the official WordPress Plugin Repository. A user documentation including detailed instructions how to install, setup and customize the plugin (in German) is available here:

https://docs.immonex.de/kickstart/

Kickstart can be extended by custom skins (template sets) and add-on plugins. The following sections relate to the development of the core plugin in this repository only.

Development

Requirements

• Git
• npm (Node.js)
• Composer
• PHP_CodeSniffer
• WordPress Coding Standards for PHP_CodeSniffer
• ready-to-go WordPress installation on a local webserver

Guidelines

We keep it simple and rely on battle-proven standards and best practices whenever possible!

• PHP compatibility: 5.6+ (switch to 7.2+ envisaged for future releases)
• Coding Standard (PHP): WordPress PHP Coding Standards
• Git branching strategy: GitHub flow
• Git commit messages: Conventional Commits
• CSS of Core Skins (template sets) shipped with this plugin are most widely built upon the BEM methodology with Two Dashes style as naming convention.
• Plugin and skin CSS files are being compiled from SCSS files during the build process using node-sass.

Setup

Setting up a simple development environment starts by cloning this repository and installing dependencies:

$ cd ~/projects
$ git clone git@github.com:immonex/kickstart.git immonex-kickstart
$ cd immonex-kickstart
$ npm install
$ composer install

⚠️ PHP_CodeSniffer and the related WP sniffs are not part of the default dependencies and should be installed globally.

Then, a symlink to the src directory has to be created in the plugins folder of the local WP installation:

$ ln -s ~/projects/immonex-kickstart/src/ ~/htdocs/wp-dev-installation/wp-content/plugins/immonex-kickstart

Now, the plugin can be activated in the WP backend.

Building

The JS/CSS build process is based on the module/asset bundler webpack. A set of simple npm scripts defined in package.json is used to perform the required steps (no Gulp or Grunt needed).

Create a production version of the sources in the build folder and a corresponding ZIP archive in dist:

$ npm run build

Create and serve a development version with automatic rebuild and browser reload whenever PHP, (S)CSS or JS files are updated:

$ npm run watch

For the latter option, a Browsersync proxy URL to the local WP dev installation has to be defined in the file .env (use .env.example as template).

Coding Standard

The PHP source code formatting corresponds to the WordPress PHP Coding Standards.

The source files can be checked with PHP_CodeSniffer (if, as recommended, installed globally as described here):

$ phpcs

To fix violations automatically as far as possible:

$ phpcbf

⚠️ The JavaScript code may differ from the (slightly dusty...) WP recommendations in favor of a more contemporary style.

Testing

Locally running unit tests (PHPUnit) requires an additional temporary WordPress installation (see infos on make.wordpress.org). To use the test install script included in this repository, the file .env containing credentials of a local test database has to be created or extended first (see .env.example).

After that, the temporary testing environment can be installed:

$ npm run test:install

Running tests in the tests folder:

$ npm run test

Translations

The regular translations for this plugin are provided via translate.wordpress.org (GlotPress).

Additionally, formal and informal German translations (PO/MO files) are available in the src/languages folder, too. This directory also contains a current POT file (as base for custom/local translations) that can be updated with the following command:

$ npm run pot

API Documentation

The API documentation based on the sources can be generated with the following command and is available in the apidoc folder afterwards:

$ npm run apidoc

To view it using a local webserver:

$ npm run apidoc:view

If these docs are not needed anymore, the respective folders can be deleted with this command:

$ npm run apidoc:delete

(The folder apidoc is meant to be used locally, it should not a part of any repository.)

User/Integrator Documentation

The source files (markdown) of the docs for users and integrators mentioned above are located in the doc folder. A globally installed doc-gen package (currently not available publicly) and a suitable user account are required for publishing...

$ npm run doc

...or publishing it under https://docs.immonex.de/kickstart/:

$ npm run doc:publish

License

GPLv2 or later

Copyright (C) 2014, 2020 inveris OHG / immonex

This plugin is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This plugin is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Trivia

The immonex Kickstart logo is a tribute to the developers of the Lorraine, prototype of the original Amiga (later known as Commodore Amiga 1000). 😏