A Laravel web app for registering for service opportunities.
Make sure the following are installed on your system:
- Create an app database starting with "l_". For example, "l_commsvc". Create a user who can access the database. For local, it's good to name the user and password the same name as the database. If you like, you can use
/app/database/scripts/create-database.sqlas a starting point.
.env.jsonand enter configuration options:
- Database info, matching the above
- CDN info, for where logo uploads are stored. By default, it will upload
them to a server via FTP, and you can just enter the FTP connection info
here. If you need to upload them via another protocol, you can make
- Payment connection info, if your system will be accepting payment. This
npmweb/paymentlibrary, which currently only supports Braintree as a payment provider. Enter your Braintree account info here.
npm installto install the grunt packages for this project.
- Note: on some OSes you may get this error:
Error: /usr/lib64/libstdc++.so.6: versionCXXABI_1.3.5' not found`. If so, check this GitHub issue for help. The short version is that you may be able to run the following:
sudo wget -O /etc/yum.repos.d/slc6-devtoolset.repo http://linuxsoft.cern.ch/cern/devtoolset/slc6-devtoolset.repo
sudo rpm --import http://ftp.mirrorservice.org/sites/ftp.scientificlinux.org/linux/scientific/51/i386/RPM-GPG-KEYs/RPM-GPG-KEY-cern
sudo yum install devtoolset-2-gcc.x86_64 devtoolset-2-binutils.x86_64 devtoolset-2-gcc-c++
- Then, instead of running a plain “npm install” within your project, run this:
SKIP_SASS_BINARY_DOWNLOAD_FOR_CI=1 CC=/opt/rh/devtoolset-2/root/usr/bin/gcc CXX=/opt/rh/devtoolset-2/root/usr/bin/g++ npm install
- Note: on some OSes you may get this error:
Installs PHP dependencies with
Creates symlinks for web assets with
Makes sure temp folders are writable with
Generates CSS from Sass.
Creates and populates the local database using
php artisan migrate php artisan db:seed
Runs automated tests with
- This application allows the frontend and backend to run on different domains, if you like. Set your web server to point
backendto the web address you want them at. For example, you could point http://myorganization.com/service to
endpoints/frontendand http://intranet.myorganization.com/service to
endpoints/[backend and frontend]/.htaccess, changing the RewriteBase line to the path your app is at
- Make sure both the frontend and backend come up. You can log in to the backend with the default user
- If you want the system to notify you if a registration closes without anyone being signed up for it, set up a cron to execute
php artisan occurrence:notifyCancelled
Once the app is up and running, you'll want to do some customization for your installation:
- Go to the backend Config page to edit the system name and to configure filter, registration, and payment settings.
- Go to the backend Churches page to set up one or more churches that serving will happen under.
- Go to the Users page to set up users. You can either use the built-in users table, or use a different third-party Laravel authentication driver, i.e. to authenticate against LDAP.
- For extra security, enter a new encryption key value in
The Community Service system uses the following data model:
- Campaigns are different time periods that serving happens in, allowing you to only view data for the current campaign at one time.
- Churches are organizations organizing the community service. (The name for these will eventually be configurable, so the system can be used by non-churches, such as companies.) This is not necessarily the nonprofit organization that sets up the projects itself. For example, First Baptist Church could be the church, working with Toys for Tots as a beneficiary.
- Beneficiaries are nonprofit organziations through whom the serving happens, such as "Toys For Tots".
- Service Opportunities are types of projects that can be done, such as "Sort and Pack Toy Donations". A beneficiary can have multiple service opportunities.
- Occurrences are individual dates and times that a service opportunity happens on. A service opportunity can have multiple occurrences--this keeps you from having to copy-and-paste quite so much.
- Filter Attributes are custom filterable fields for service opportunities. You can set them up to track things like whether money is required, whether children can come, etc. These correspond to filter controls on the frontend.
- Registrations are, well, registrations. It's one form submission. Depending on your settings, a registration can be for multiple participants.
- Create-Your-Own Project Registrations are for people to report time they spent on a service opportunity they came up with on their own.
- Participants are multiple people included in one registration. You have the option of setting up a service opportunity to require names to be provided for all participants.
To use the system:
- Create beneficiaries
- Create or import service opportunities and occurrences of them.
- Send users to the frontend to register for your service opportunities.
- As users register, depending on your settings, either the churches and/or the beneficiaries may receive emails notifying them of registrations.
- You can log in to the system to run reports for yourself or for the beneficiaries, to inform them about participants who will be coming.
Conventions and Gotchas
If you need to make changes to the code, these are things that are different in our usage of Laravel from the typical stuff you'll see online.
- Any time you're changing code, run
grunt watch(it will keep running in that terminal window). It will recompile CSS as Sass changes, as well as running PHPUnit tests if you set any up. You'll see an OS notification pop up if there are any problems.
- There are no
app/models/directories. Instead, all classes are under app/src/NpmWeb/CommunityService.
- However, you'll notice there aren't any controllers or models under there,
either--and not a ton of views. Most of the core application logic is in a
Composer package called
allows you to make tweaks to some of the specifics of the app like
look-and-feel, while still pulling down the latest fixes and features from the
core logic by just doing a
composer update. If you need to make changes to that core code, you can fork service-opportunities and change your
composer.jsonto point to your fork. But if you're making bug fixes, be sure to pull-request them back over to us!
- Our apps are set up to support multiple "endpoints": different domains
or paths where the app is accessible. This allows you to put the frontend
and admin interface on different servers, if you like. Instead of a
public/directory, we have
/endpoints/sharedmakes shared assets available to both.)
- Instead of basing our models on
Eloquent, they're based on an
extension of Eloquent called
Ardent. This is just the same
as Eloquent, except that validations are configured in the model and
are run automatically when you call
- We've overridden the Form:: methods to make a few changes:
- All Form:: methods will output not just the form element, but also the label, error messaging, help text, etc. They are set up to work with the Foundation CSS framework, which we're standardized on going forward.
- If you pass the option 'validate'=>true into the options of Form::model(), it will generate jQuery Validation rules for your form, generated from the validation rules configured in the model. That way validation happens on both the client and server side.
The following are issues and limitations we're aware of:
- Currently organizations display with the label "Church". We will eventually make this configurable if you are not a church and want to use this system.
- The system handles setting up different campaigns that start and end, but there is not currently a user interface for working with them. Changes need to be made directly in the database.
- Importing custom "filter attributes" is currently disabled until we improve the logic to make it dynamic for any attributes you might set up.
Like our software and want to help out? You can do any of the following:
- Send us stories about what you're using our software for at @npmdigital
- Flesh out the README.md in this app or one of our packages it uses.
- Fix bugs in this app or one of our packages.
- Submit issues for this app or one of our packages.
This application is open-sourced under the MIT license. See the
LICENSE file for more details.