Development Webtrees

by Posted on

Foreword

The project has been running for many years, and has a lot of history. So it is really difficult to jump into it. However the code is very good written so with some basics, you can jump in.

You will find below an attempt to go ahead with the contribution and improvements of this software.

Introduction

It is a short approach with the essentials, so don’t expect a detailed presentation.

Installation and development will be done under Linux (Ubuntu).

Overview of the files

Here a short overview of the main files and directories

Remark about Third-party libraries and compiled files in the source tree
For historic reasons, certain third party libraries and compiled files are included in the source tree.
This is a bad practice. Perhaps this could be fixed in the future with an installer via composer.
Remark based on

  • The non-development PHP libraries from /vendor, created using the command composer install
  • As the compiled JS and CSS assets from /public/{css,js}), created using the command npm run production.

Contribute file

Let us start with the most Important information provided in the « CONTRIBUTING.md » file

  • Composer
run `composer install` before starting any development.  
This loads all the development tools

run `composer install --no-dev` 
before committing any changes, this will exclude the packages which are not mandatory.
  • NPM
After modifying any CSS or JS files, you'll need to rebuild the files in `public/js` and `public/css`.
You do this with the command :

npm run production

What is needed

The OS environment retained is Ubuntu or Windows.

Below the different chapters which will be covered

  • The basis
    • HTML
    • CSS
    • GIT
    • PRS
    • PHP
    • Composer
    • Javascript
    • npm
  • The tools needed
    • Visual Studio Code
    • Xampp
    • XDebug
  • The skeleton of the code

The Basis

Introduction

Before to start here the basis to know.

HTML

HTML, for HyperText Markup Language, is the basic language of a website. It is not a programming language but a markup language that allows you to write hypertext and thus define the semantic structure of a web page.

Some complements :

Use your « Navigator Inspector » in order to check your code.

Tool for Test HTML,CSS,Javascript

CSS

CSS, for cascading style sheet, is a language that will allow you to define the shape to be given to our document. It has a simple syntax but a fairly substantial vocabulary that you will have to learn and master.

Some Complements

Here again use your « Navigator Inspector » to control the position of the blocks.

GIT

Git is a tool for versioning and keeping track of changes made to the project.

Some Complements

Highlights

  • Fork

First of all, you have to fork the project.
Go to github web interface of ‘Webtrees’ and click on the ‘Fork’ button.

  • Clone

If you are only interested in the latest version of the code, you can use a »shallow clone », which is about 30MB. This will create directory webtrees in your current directory.

git clone --depth 5 https://github.com/ckl67/webtrees.git
  • Add an upstream

In order to synchronize with the reference repository, we are going to add in remote the reference repository with the conventional name upstream

git remote add upstream https://github.com/fisharebest/webtrees.git

After that you should have 2 remote depots

$ git remote -v
origin  https://github.com/ckl67/webtrees.git (fetch)
origin  https://github.com/ckl67/webtrees.git (push)
upstream        https://github.com/fisharebest/webtrees.git (fetch)
upstream        https://github.com/fisharebest/webtrees.git (push)
  • To recover the upstream

A good practice is to always work on a specific branch, never on the target branch (Master) of our development.

git checkout work
git fetch upstream work
git merge upstream/work

PRS

Before to start coding, take a look on the PHP Standards Recommendations

webtrees follows the PHP Standards Recommendations.

Php

Some useful information

Composer

Composer is a Dependency Manager for PHP.

Some highlights

Installation

Installation on linux.
Be careful to use php based on xampp (See below in specific chapter)

Composer

Composer can be installed from scratch, but will depend on a php version, which might not be the same as xampp. So I preferred the composer.phar solution

composer.phar

Or use composer.phar that you can download

Javascript

JavaScript (or « JS ») is a programming language used most often for dynamic client-side scripts on webpages. Javascript is running on the local machine

Ajax

Asynchronous JavaScript and XML, while not a technology in itself, is a « new » approach to using a number of existing technologies together, including HTML or XHTML, CSS, JavaScript, DOM, XML, XSLT, and most importantly the XMLHttpRequest object.
When these technologies are combined in the Ajax model, web applications are able to make quick, incremental updates to the user interface without reloading the entire browser page. This makes the application faster and more responsive to user actions.

Documents

NPM

NPM (Node Package Manager) is the official package manager for Node.js, which is also used to install, maintain, the Javascript packages.

Node.js (Server side) is an open-source, cross-platform, back-end, JavaScript runtime environment that executes JavaScript code outside a web browser.

Installation

NPM is included in NodeJS.

For Ubuntu

curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash -

sudo apt install nodejs

Tools

IDE

As integrated Development environment, let use: Visual Studio Code which is compatible Windows and Ubuntu

To avoid: Cannot validate since no PHP executable is set.
We have to indicate where is php
Open settings.json and paste this line 

"php.validate.executablePath": "c:/xampp/php/php.exe",

Extension Installed

  • PHP Intelephense
  • Git Graph
  • PHP Debug
  • ..

Xampp

Basis

XAMPP is a completely free, easy to install Apache distribution containing MariaDB, PHP, and Perl.

Xampp is compatible Windows and Linux

Ubuntu

Ubuntu will be installed under
/opt/lamp

# htdocs folder is not writable, the solution is to change ownership
whoami
id –gn
ls -ld /opt/lampp/htdocs/
sudo chown -R christian:christian /opt/lampp/htdocs
ls -ld /opt/lampp/htdocs/

# We also need to update httpd.conf file.
# Run following command to open apache configuration file: sudo gedit /opt/lampp/etc/httpd.conf

Find following lines:
User nobody --> Change
Group nogroup --> Change

To Run Xampp
sudo /opt/lampp/manager-linux-x64.run

Some remarks about php

php is installed by default, and can sometimes points to issue.

# php is installed by default in /usr/bin/
# And can need to add mysql
sudo apt-get install php-common php-mysql php-cli

# Best solution is to point to php of Xampp
# modify .profile 
# Add
export PATH=$PATH:/opt/lampp/bin/

# To activate
source .profile

How to work

Environment

Below a short overview of the work environment

git remote add back /opt/lampp/htdocs/work/repo_backup/webtrees

We add repository backup « back » in order to simulate the ftp to our htdocs/webtress local directory. For facilities, we keep branch work active on repository back

The principle is as following.

  1. Test in our working git directory (htdocs/work/webtrees)
    Test : localhost/work/webtrees
  2. git push back work
    –> to push the result to backup repository (only the indexed git files are transferred)
  3. on repository « back », (with work branch checked out)
    ftp the files to the htdocs/webtrees for testing
    Test: localhost/webtrees

Installation

Once all the tools are installed, we can install Webtrees. Run http://localhost/webtrees/ you should see Webtrees the install wizard

Code

Composer

Control

Composer will let you to control a lot of things of Webtrees

  • Mode Normal or Debug
  • Run script

Dependency

If you want to build webtrees from source, or modify the code, you’ll need to install a couple of tools first.
You will need to install the PHP dependencies.
Then run this command

php composer.phar install

NPM

First you have to run

npm install

npm audit fix

You can get a message that some dependencies are missing
Example

npm install leaflet@~1.3.1
npm audit fix

Into the Flesh

Introduction

We will go into the details

Translation

Based on The Format of PO Files

PO files: PO files are the files which contain the actual translations.
Each language will have its own PO file : messages.po

POT file: POT files are the template files for PO files.
They will have all the translation strings left empty.
A POT file is essentially an empty PO file without the translations,
with just the original strings.

Published by christian.klugesherz

Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *