Difference between revisions of "Customization"
From PhotoVoltaic Logger new generation
m (→Coding) |
m (→vzlogger compatibility) |
||
| (50 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
| + | {{TOCright}} | ||
| + | |||
| + | [[Category:Internals]] | ||
| + | [[Category:Software]] | ||
| + | [[Category:Example]] | ||
| + | |||
| + | == Configuration == | ||
| + | |||
| + | To change system configuration, you can change everything in <tt>config/config.php</tt>. | ||
| + | |||
| + | These settings will overwrite the default settings from <tt>config/config.default.php</tt>. | ||
| + | |||
| + | '''NEVER''' edit <tt>config/config.default.php</tt>! | ||
| + | |||
== Templates == | == Templates == | ||
The web frontend templates resides at <tt>frontend/View</tt> | The web frontend templates resides at <tt>frontend/View</tt> | ||
| − | + | If you like to change a template | |
| − | * | + | * Create a folder <tt>custom</tt> in the directory, where the template resides |
| − | + | * Copy the template into the <tt>custom</tt> folder | |
| − | * | + | * Modify the template in <tt>custom</tt> folder, this will overwrite the standard template |
| − | * | + | |
| − | + | The internal search logic for the to be used template is this (assume this requested template: <tt>default.header.tpl</tt>) | |
| − | |||
| − | + | Search these directories | |
| + | * <tt>frontend/View/{module}/custom</tt> | ||
| + | * <tt>frontend/View/{module}</tt> | ||
| + | * <tt>frontend/View/custom</tt> | ||
| + | * <tt>frontend/View</tt> | ||
| + | Found template here: <tt>frontend/View/default.header.tpl</tt> | ||
| − | These directories will be ignored on update | + | The <tt>{module}</tt> stands here for the actual [[:Category:Web_frontend|web frontend]] module (can be found in the URL in your browser). (Therefor it would be possible to have e.g. an own footer for each module, if you like :-) |
| + | |||
| + | The <tt>custom</tt> sub directories are not delivered with Git repository, you have to create them if required. These directories will be ignored on update (excluded via <tt>[https://github.com/K-Ko/PVLng/blob/master/.gitignore .gitignore]</tt>) | ||
| + | |||
| + | === Predefined HTML output hooks === | ||
| + | |||
| + | To inject your own '''HTML''' into the output, 5 hooks are available by default (from v2.9.0) | ||
| + | |||
| + | {| class="wikitable" | ||
| + | |- | ||
| + | | <tt>frontend/View/hook.head.tpl</tt> || Injected just before <tt></head></tt> tag | ||
| + | |- | ||
| + | | <tt>frontend/View/hook.body.before.tpl</tt> || Injected before header inside content wrapper | ||
| + | |- | ||
| + | | <tt>frontend/View/hook.content.before.tpl</tt> || Injected between header & menu and page content | ||
| + | |- | ||
| + | | <tt>frontend/View/hook.content.after.tpl</tt> || Injected between page content and footer | ||
| + | |- | ||
| + | | <tt>frontend/View/hook.body.after.tpl</tt> || Injected after footer inside content wrapper | ||
| + | |- | ||
| + | | <tt>frontend/View/hook.end.tpl</tt> || Injected just before <tt></body></tt> tag | ||
| + | |} | ||
| + | |||
| + | To inject your own '''styles''' or '''scripts''', these 2 hooks are available. | ||
| + | |||
| + | {| class="wikitable" | ||
| + | |- | ||
| + | | <tt>frontend/View/hook.style.css</tt> | ||
| + | |- | ||
| + | | <tt>frontend/View/hook.script.js</tt> | ||
| + | |} | ||
| + | |||
| + | To enable such a hook, the logic is the same as for other templates | ||
| + | |||
| + | # test -d frontend/View/custom || mkdir -p frontend/View/custom | ||
| + | # cp frontend/View/hook.head.tpl frontend/View/custom/hook.head.tpl | ||
| + | |||
| + | Adjust now the file contents in <tt>custom</tt> directory. | ||
== Coding == | == Coding == | ||
| + | |||
| + | === Prepend/append code === | ||
* If an file <tt>prepend.php</tt> exists, it will be included '''before any''' other PHP instructions. | * If an file <tt>prepend.php</tt> exists, it will be included '''before any''' other PHP instructions. | ||
* If an file <tt>append.php</tt> exists, it will be included '''after all''' other PHP instructions. | * If an file <tt>append.php</tt> exists, it will be included '''after all''' other PHP instructions. | ||
| − | + | This works for the [[:Category:Web frontend|web frontend]] and for [[API]] (from <tt>r3</tt>), see <tt>prepend.php.dist</tt> and <tt>api/r3/prepend.php.dist</tt> for reference. (I use this for defining the application name for [http://newrelic.com/monitor-everything NewRelic] monitoring.) | |
| + | |||
| + | === Custom API routes === | ||
| + | |||
| + | For [[API]] since <tt>r3</tt> you can define your own routes in <tt>routes/custom.php</tt>. | ||
| + | |||
| + | The API is based on the [http://www.slimframework.com/ Slim framework]. | ||
| + | |||
| + | See <tt>routes/custom.php.dist</tt> for reference and refer to the other route definitions in <tt>routes/*.php</tt> for middleware helper functions and help. | ||
| + | |||
| + | === vzlogger compatibility === | ||
| + | |||
| + | PVLng can direct act as middleware for [http://volkszaehler.org/ volkszaehler.org] [http://wiki.volkszaehler.org/software/controller/vzlogger vzlogger]. | ||
| + | |||
| + | Original vzlogger request is | ||
| + | |||
| + | <nowiki>POST http://demo.volkszaehler.org/middleware.php/data/550e8400-e29b-11d4-a716-446655441352.json?ts=1284677961150&value=12</nowiki> | ||
| + | |||
| + | as described in [http://wiki.volkszaehler.org/development/api/reference#messwerte_loggen vzlogger API reference]. | ||
| + | So just change your vzlogger configurations from | ||
| + | |||
| + | ... | ||
| + | "middleware" : "<nowiki>http://localhost/</nowiki>'''''middleware.php'''''", | ||
| + | ... | ||
| + | |||
| + | to | ||
| + | |||
| + | "middleware" : "<nowiki>http://localhost/</nowiki>'''''api/latest'''''", | ||
| + | |||
| + | The coding is prepared in <tt>routes/custom.php.dist</tt>, copy to <tt>routes/custom.php</tt> and uncomment the relevant coding: | ||
| + | |||
| + | $api->post( ... | ||
| − | + | There will be no conflict with PVLng data storage logic, because PVLng uses <tt>PUT</tt> requests for that. | |
| − | + | <p style="color:red;font-weight:bold"> | |
| + | Please keep in mind, that there will be by design NO security against unwanted postings like PVLng implements with the API key concept! | ||
| + | </p> | ||
Latest revision as of 11:18, 7 July 2015
Configuration
To change system configuration, you can change everything in config/config.php.
These settings will overwrite the default settings from config/config.default.php.
NEVER edit config/config.default.php!
Templates
The web frontend templates resides at frontend/View
If you like to change a template
- Create a folder custom in the directory, where the template resides
- Copy the template into the custom folder
- Modify the template in custom folder, this will overwrite the standard template
The internal search logic for the to be used template is this (assume this requested template: default.header.tpl)
Search these directories
- frontend/View/{module}/custom
- frontend/View/{module}
- frontend/View/custom
- frontend/View
Found template here: frontend/View/default.header.tpl
The {module} stands here for the actual web frontend module (can be found in the URL in your browser). (Therefor it would be possible to have e.g. an own footer for each module, if you like :-)
The custom sub directories are not delivered with Git repository, you have to create them if required. These directories will be ignored on update (excluded via .gitignore)
Predefined HTML output hooks
To inject your own HTML into the output, 5 hooks are available by default (from v2.9.0)
| frontend/View/hook.head.tpl | Injected just before </head> tag |
| frontend/View/hook.body.before.tpl | Injected before header inside content wrapper |
| frontend/View/hook.content.before.tpl | Injected between header & menu and page content |
| frontend/View/hook.content.after.tpl | Injected between page content and footer |
| frontend/View/hook.body.after.tpl | Injected after footer inside content wrapper |
| frontend/View/hook.end.tpl | Injected just before </body> tag |
To inject your own styles or scripts, these 2 hooks are available.
| frontend/View/hook.style.css |
| frontend/View/hook.script.js |
To enable such a hook, the logic is the same as for other templates
# test -d frontend/View/custom || mkdir -p frontend/View/custom # cp frontend/View/hook.head.tpl frontend/View/custom/hook.head.tpl
Adjust now the file contents in custom directory.
Coding
Prepend/append code
- If an file prepend.php exists, it will be included before any other PHP instructions.
- If an file append.php exists, it will be included after all other PHP instructions.
This works for the web frontend and for API (from r3), see prepend.php.dist and api/r3/prepend.php.dist for reference. (I use this for defining the application name for NewRelic monitoring.)
Custom API routes
For API since r3 you can define your own routes in routes/custom.php.
The API is based on the Slim framework.
See routes/custom.php.dist for reference and refer to the other route definitions in routes/*.php for middleware helper functions and help.
vzlogger compatibility
PVLng can direct act as middleware for volkszaehler.org vzlogger.
Original vzlogger request is
POST http://demo.volkszaehler.org/middleware.php/data/550e8400-e29b-11d4-a716-446655441352.json?ts=1284677961150&value=12
as described in vzlogger API reference. So just change your vzlogger configurations from
... "middleware" : "http://localhost/middleware.php", ...
to
"middleware" : "http://localhost/api/latest",
The coding is prepared in routes/custom.php.dist, copy to routes/custom.php and uncomment the relevant coding:
$api->post( ...
There will be no conflict with PVLng data storage logic, because PVLng uses PUT requests for that.
Please keep in mind, that there will be by design NO security against unwanted postings like PVLng implements with the API key concept!
