A basic starting point for concrete5 packages, with samples of code you might use. This is not intended for production, it does not do anything useful by itself.
But if you want to learn about how packages work, and save time when you develop your own sites, this is something that can help you out a lot.
- Screen to customize options or give more info before installation
- Showing a success / more details screen after installation
- How creating private functions for different tasks makes the controller easier to understand
- Using on_start()
- Add your own javascript / css on all pages
- Hooking into a custom page type's on_page_add event
- Installing Page Attributes
- Samples of each attribute type
- Assigning to a set
- Installing a Block
- Installing a Theme
- Installing Single Pages
- Updating the database table for a custom attribute that you installed with the package when upgrading (not run by default)
- Hooking into the pre-upgrade function to reject if a package isn't installed
- Creating a custom user group
- Adding a new page type with all options explained
- Adding a new page from that page type
- Assigning view / edit permisisons to admins, installing user, and the custom group
- All top-level options for editing / viewing
- How to configure which sub-pages are allowed, and how permissions for sub-pages are inherited
The single page at /dashboard/boilerplate/output_stuff is set up with a basic example of how to use the page controller, a tools file, and an element to update the content. It's kept as basic as possible to keep it easy to understand. Just a single button that sends a get request with no parameters to the tools file, which then calls a method on the page controller to get a new array, which is then passed in to a package element to format the data. Then part of the page is updated with that new HTML.
For a more a detailed example of this, which uses the built in list models to allow for sorting and paginating a database driven table, please check out my [https://github.com/herent/Custom-Objects-in-concrete5-Demo](Custom Objects Demo)
The 'boilerplate' page type will show in view.php using the file /page_types/boilerplate.php if using one of the built in themes. The included theme has a proper template, so if used it outputs slightly differently.
This is a slightly tricky one. Because the external form block does not actually look in package directories to see if there are forms there, you will have to copy the file from the package blocks directory to your outer blocks directory.
It shows:
- Validation using built in helpers
- Loading a plain text mail file from the package
- Sending an HTML email
- Some options for the mail helper
Has a custom "Callout" block that has controller side validation, rich text processing to keep links correct, etc.
- Image Picker
- Text Field
- WYSIWYG
- Link Picker
- Choose if a link is shown or not for use in the template without requiring it to be in the text content
- External link or a page picker for an internal link
- Specify text for the link, though the template may not use it.
It uses the validate() function on the page controller to provide more control of the verification and error message display.
There are templates for the autonav and page_list blocks in the package, showing how you can keep your templates organized within your package.
PLEASE NOTE : the templates here are not that detailed. They will be upgraded in future versions of this package. If people would like to send pull requests with templates they find useful for different blocks, they would be welcomed
The db.xml file shows sample options for most of the fields you can create using the [http://phplens.com/lens/adodb/docs-datadict.htm](ADODB XML) format
The boilerplate page type has an on_page_add() function that puts extra data into the table installed with the package
The theme is very skeletal, almost nothing included at all. It is intended to just be a starting point, but has the basic structure you need to develop your own themes. It's assumed that most people who would want to use a package like this would end up replacing this with their own starting point that's relevant to the way they work, their favorite grid system, etc.
The package controller (/controller.php) installs the "Dump Sample Table" job in the installJobs() function. The code for this job is located in /jobs/dump_sample_table.php. The logic for the job is defined in the run() method and simply dumps all the records from the BoilerplateSample table and returns a proper error message.
This demonstrates:
- Installing an automated job in the package controller
- Creating a class that defines the job logic
- Throwing exceptions in the job run() method
- Returning output messages in the run method
The intended for people that are developing custom sites more than people that are developing for the marketplace. So instead of locally adding a page type, then adding some attributes via the gui, then having to recreate that whole process on the live server, you have everything in one package.
When trying to find your custom templates for blocks, themes, etc, it's also much nicer to do everything in a package. If you need a new attribute or block, you can just put that into your upgrade script.
A find and replace for boilerplate within the package directory would be needed when adjusting this to work for your own site. Some folders and file names will need to be changed as well. So it's not just point and click to make your own stuff, but if you are a somewhat experienced developer it should not be a big deal to make those adjustments.
This package has been created by Jeremy Werst
https://github.com/herent/c5_boilerplate
If you like this package and would like to support further projects like these, or if you just want to buy me a beer, please send a donation through paypal to jeremy.werst@gmail.com
Thanks!