README

[!NOTE] This Project is Archived!

The newer version of this system is the Filament-based package

Laravel ODK Link

This package enables you to connect your Laravel application to an ODK Central server, and to manage the deployment of ODK forms via a set of CRUD panels built with Laravel Backpack.

The benefit of this package is that it allows you to create a set of "xlsform templates", and then deploy many versions of each template to different "owners". An owner could be an individual user, or a team. This way, multiple groups can work independently and keep their data separate, while still using the same "xlsform templates", and enabling a central team to reeview data from all teams.

NOTE: This is still in development. It currently requires Laravel Backpack Pro, which is a paid product. We hope to be able to refactor this to not require a Backpack Pro licence in the future.

Installation

This package assumes you have already setup your project to use Laravel Backpack. If you haven't, please do so by following their installation guide: https://backpackforlaravel.com/docs/5.x/installation.

You can install the package via composer:

composer require stats4sd/laravel-odk-link

You can publish and run the migrations with:

php artisan vendor:publish --tag="odk-link-migrations"
php artisan migrate

You can publish the config file with:

php artisan vendor:publish --tag="odk-link-config"

This package comes with a set of CRUD panels designed to help you manage ODK forms and submissions. To add links to these into your Backpack Admin panel sidebar, run the included command:

php artisan odk:crud

This package uses Spatie's Laravel Media Library. To set that up, run the following commands (see their Installation instructions for more information and for custom setups)

php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="migrations"
php artisan migrate
php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="config"

You also need to add some Environment variables to your project. In your .env file, add the following:

### REQUIRED
# url of your ODK Central server
ODK_URL="https://example-odk-central-server.com"

# username and password of an administrator account for your ODK Central server
ODK_USERNAME="an-admin-user-account"
ODK_PASSWORD="your-password"

### OPTIONAL
# the FQDN of the PHP class in your application that is used to process an ODK submission 
SUBMISSION_PROCESS_CLASS="\\App\\Http\\Controllers\\SubmissionController"

# the method within the class. This method should:
# - be a public static function
# - accept an OdkLink\Models\Submission object as the only required variable
SUBMISSION_PROCESS_METHOD="process"

## Use
TODO: write up full documentation.



## Credits

- [David Mills](https://github.com/dave-mills)
- [All Contributors](../../contributors)

## License
The MIT Licence (MIT). Please see [Licence File](LICENSE.md) for more information.