### Install and Run Pre-commit Hook

Source: https://github.com/opengisch/qfield-docs/blob/master/README.md

Before committing, install pre-commit for the current user and then install the git hook to auto-format contributions. This ensures consistent code formatting.

```sh
pip install --user pre-commit
pre-commit install
```

--------------------------------

### Local Documentation Testing (pipenv)

Source: https://github.com/opengisch/qfield-docs/blob/master/README.md

To test your documentation changes locally using pipenv, copy the example environment file, install dependencies, and serve the documentation. The local site will be available at http://localhost:8000.

```sh
cp .env.example .env
pipenv install -r requirements.txt
pipenv run mkdocs serve
```

--------------------------------

### Example QGIS Project File Structure

Source: https://github.com/opengisch/qfield-docs/blob/master/documentation/reference/qfieldcloud/projects.en.md

Illustrates a typical directory structure for a QGIS project, including data sources, symbology, attachments, and the project file itself. This structure helps organize all necessary components for a QFieldCloud project.

```text
project
├── data
│   ├── basemap.tif
│   ├── bees.gpkg
│   └── fields.gpkg
├── symbology
│   ├── icon.svg
│   └── line-pattern.png
├── DCIM
│   ├── bees-20220404121212.jpg
│   ├── bees-20220405040506.jpg
│   └── fields-20220405040607.jpg
├── project.qgs
├── project_attachments.zip
└── project.qml
```

--------------------------------

### PostgreSQL Setup for Proxy Authentication

Source: https://github.com/opengisch/qfield-docs/blob/master/documentation/reference/qfieldcloud/secrets.en.md

This SQL script sets up roles, grants permissions, creates a table with row-level security, and configures policies to enable proxy authentication. It demonstrates how a generic service account can assume specific user roles for data operations.

```sql
CREATE ROLE qfield_admin WITH LOGIN PASSWORD 'strong_password';
CREATE ROLE user_mielena WITH NOLOGIN;

GRANT user_mielena TO qfield_admin;

CREATE TABLE field_observations (
    id SERIAL PRIMARY KEY,
    geom GEOMETRY(Point, 4326),
    note TEXT,
    surveyor_name TEXT DEFAULT current_user -- Auto-fill with the effective user
);

GRANT ALL ON field_observations TO user_mielena;
GRANT USAGE, SELECT ON SEQUENCE field_observations_id_seq TO user_mielena;

ALTER TABLE field_observations ENABLE ROW LEVEL SECURITY;

CREATE POLICY surveyor_isolation_policy ON field_observations
    FOR ALL
    USING (surveyor_name = current_user)
    WITH CHECK (surveyor_name = current_user);
```

--------------------------------

### Markdown Metadata Example

Source: https://github.com/opengisch/qfield-docs/blob/master/README.md

When creating new markdown files, a unique `tx_slug` must be added to the metadata to identify the resource on Transifex. Do not change `tx_slug` in existing files.

```markdown
---
title: Advanced Setup
tx_slug: tutorial_advanced_setup_qfc
---
```

--------------------------------

### Create Database and Enable Extensions

Source: https://github.com/opengisch/qfield-docs/blob/master/documentation/reference/qfieldcloud/secrets.en.md

Initializes the PostgreSQL database and enables essential extensions like PostGIS and uuid-ossp.

```sql
CREATE DATABASE db-og-secrets OWNER qfield ENCODING 'UTF8';

-- Connect to the newly created database.
\c db-og-secrets

-- Install the required extensions if they do not already exist.
CREATE EXTENSION IF NOT EXISTS postgis;
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
```

--------------------------------

### Local Documentation Testing (Docker)

Source: https://github.com/opengisch/qfield-docs/blob/master/README.md

To test your documentation changes locally using Docker, clone the repository, create a Transifex API token file, build the Docker image, and run the container. Point your browser to http://localhost:8000 for live-reloading.

```sh
git clone https://github.com/opengisch/QField-docs
# Create or get a Transifex API token on app.transifex.com, and save it to a local .transifexrc file.
docker build . -t qfield-docs --secret id=tx_token,src=.transifexrc
docker run -it -v ${PWD}/documentation:/opt/app/documentation -p 8000:8000 qfield-docs
```

--------------------------------

### Get Picture Orientation EXIF Tag

Source: https://github.com/opengisch/qfield-docs/blob/master/documentation/how-to/project-setup/pictures.en.md

This expression retrieves the orientation of a picture using its path. Ensure the 'path' attribute correctly points to the image file within the project.

```sql
exif(@project_folder + '/' + "path", 'Exif.Image.Orientation')
```

--------------------------------

### Inspect Built Documentation (Docker)

Source: https://github.com/opengisch/qfield-docs/blob/master/README.md

To inspect the built documentation within a Docker container before serving, run the container with specific volume and port mappings, activate the virtual environment, and build the documentation. The output will be in the `./site` directory inside the container.

```sh
docker run -it -p 8000:8000 --rm localhost/qfield-docs bash
source .venv/bin/activate
mkdocs build
```

--------------------------------

### PostgreSQL Connection Error Example

Source: https://github.com/opengisch/qfield-docs/blob/master/documentation/reference/qfieldcloud/specs.en.md

This error message indicates that the PostgreSQL server is not configured to allow connections from the QFieldCloud IP address. You need to edit the pg_hba.conf file on your PostgreSQL server to resolve this.

```bash
FATAL: no pg_hba.conf entry for host "185.203.114.168", user "qfc", database "mydb_test", SSL off
WARNING:QGIS_MSGLOG:1 unavailable layer(s) found:
```

--------------------------------

### Extract Attribute from Snapping Results

Source: https://github.com/opengisch/qfield-docs/blob/master/documentation/how-to/project-setup/attributes-form.en.md

Use the `@snapping_results` variable to access snapping information after drawing a line. This example extracts the 'id' attribute of the first snapping match of a line's first point.

```sql
with_variable(
  'first_snapped_point',
  array_first( @snapping_results ),
  attribute(
    get_feature_by_id(
      @first_snapped_point['layer'],
      @first_snapped_point['feature_id']
    ),
    'id'
  )
)
```

--------------------------------

### Configure and Insert Global Variables

Source: https://github.com/opengisch/qfield-docs/blob/master/documentation/how-to/project-setup/attributes-form.en.md

Configure global variables on the device and then insert their values using this syntax.

```sql
@operator_name
```

--------------------------------

### Assign Region Code Based on Location

Source: https://github.com/opengisch/qfield-docs/blob/master/documentation/how-to/project-setup/attributes-form.en.md

Use an aggregate expression to assign a region code based on the location where a new feature is inserted. This example finds the maximum 'code' from the 'regions' layer where the feature intersects with the parent geometry.

```sql
aggregate( layer:='regions', aggregate:='max', expression:="code", filter:=intersects( $geometry, geometry( @parent ) ) )
```

--------------------------------

### Define Schema and Point Geometry Table

Source: https://github.com/opengisch/qfield-docs/blob/master/documentation/reference/qfieldcloud/secrets.en.md

Sets up the 'ninja' schema and creates the 'ninja_point' table, including a 'pg_user' column for automatic attribution.

```sql
CREATE SCHEMA IF NOT EXISTS ninja;

CREATE TABLE IF NOT EXISTS ninja.ninja_point (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  pg_user TEXT,
  some_value TEXT NOT NULL,
  geom GEOMETRY(POINT, 4326)
);
```

--------------------------------

### Default Image Stamping Template

Source: https://github.com/opengisch/qfield-docs/blob/master/documentation/how-to/project-setup/pictures.en.md

This SQL snippet defines a default template for image stamping using QGIS expressions. It includes date, time, GNSS coordinates, speed, and orientation. Use this as a starting point for customizing your stamp details.

```sql
[% format_date(now(), 'yyyy-MM-dd @ HH:mm') %]
Latitude [% coalesce(format_number(y(@gnss_coordinate), 7), 'N/A') %] | Longitude [% coalesce(format_number(x(@gnss_coordinate), 7), 'N/A') %] | Altitude [% coalesce(format_number(z(@gnss_coordinate), 3) || ' m', 'N/A') %]
Speed [% if(@gnss_ground_speed != 'nan', format_number(@gnss_ground_speed, 3) || ' m/s', 'N/A') %] | Orientation [% if(@gnss_orientation != 'nan', format_number(@gnss_orientation, 1) || ' °', 'N/A') %]
```

--------------------------------

### Advanced COG Conversion with Custom Parameters

Source: https://github.com/opengisch/qfield-docs/blob/master/documentation/reference/data-format.en.md

This command demonstrates an advanced conversion to COG, including setting the SRS, overview resampling method, compression quality, and number of threads for optimization.

```bash
gdal_translate raster.tif raster_cog.tif -a_srs EPSG:2056 -of COG -co BLOCKSIZE=512 -co OVERVIEW_RESAMPLING=BILINEAR -co COMPRESS=JPEG -co QUALITY=75 -co NUM_THREADS=6 -co BIGTIFF=YES
```

--------------------------------

### QR Code for Compressed Local Project

Source: https://github.com/opengisch/qfield-docs/blob/master/documentation/how-to/advanced-how-tos/qr-codes.en.md

Generate a QR code for a compressed project to be imported into QField. The URI must point directly to a publicly accessible ZIP file. Scanning this code will prompt QField to import the project into the 'Imported Projects' folder.

```text
qfield://local?import=https://www.public.com/project.zip
```

--------------------------------

### Configure PostgreSQL Connection with Client Certificates

Source: https://github.com/opengisch/qfield-docs/blob/master/documentation/how-to/project-setup/pg-service.en.md

Enhance security by using client certificates for PostgreSQL connections. Include sslcert, sslkey, and sslrootcert parameters in your pg_service.conf file, ensuring certificate files are in the QField data folder.

```ini
[SERVICE_NAME]
host=your_host_or_ip
port=your_port
dbname=your_database_name
user=your_username
password=your_password
sslcert=client.crt
sslkey=client.key
sslrootcert=server.crt
```

--------------------------------

### Simplified Job Queue Sequence Diagram

Source: https://github.com/opengisch/qfield-docs/blob/master/documentation/reference/qfieldcloud/architecture.en.md

A simplified sequence diagram illustrating the basic stages of a job run in QFieldCloud's background processing system. Useful for a quick overview of the job lifecycle.

```mermaid
sequenceDiagram
    autonumber
    participant DB as QFieldCloud DB
    participant Queue as QFieldCloud Queue

    loop poll database
      Queue->>DB: select the oldest Job with `PENDING` status
      Queue->>DB: set the status of Job to `STARTED` status

      Queue->>DB: create a new temporary authentication token

      create participant Worker
      Queue->>Worker: create the worker and pass the authentication token

      note over Worker: job specific processing...

      destroy Worker
      Queue-xWorker: get worker's structured and free text logs and exit code

      Queue->>DB: set job's structured logs, free text logs and exit code

      alt Worker has zero exit status
        Queue->>DB: set the Job  status to `FINISHED`
      else Worker has non-zero exit status
        Queue->>DB: set the Job  status to `FAILED`
      end

      break when any of the steps above fails
          Queue-->DB: set the status Job to `FAILED`
      end
    end

```

--------------------------------

### Convert .agr to .gtx using qgis_process CLI

Source: https://github.com/opengisch/qfield-docs/blob/master/documentation/how-to/navigation-and-positioning/gnss.en.md

Use the qgis_process command-line tool to convert Swisstopo's geoid grid files. Ensure the input and output paths are correctly specified.

```bash
qgis_process run gdal:translate --INPUT="/path/to/your/chgeo2004_htrans_LV95.agr" --OUTPUT="/path/to/your/chgeo2004_htrans_LV95.gtx"
```

--------------------------------

### Define PostgreSQL Connection Parameters

Source: https://github.com/opengisch/qfield-docs/blob/master/documentation/how-to/project-setup/pg-service.en.md

Specify connection details for your PostgreSQL database within the pg_service.conf file. Replace placeholders with your actual database credentials.

```ini
[SERVICE_NAME]
host=your_host_or_ip
port=your_port
dbname=your_database_name
user=your_username
password=your_password
```