My basic setup of ProcessWire
In this post I'm going to explain what I find important before I actually start to implement anything on my own. This way you can get a taste of developing with ProcessWire and might also learn something new along the way.
In my previous blog post, I left off installing ProcessWire when it was up and running with the Regular Blog Site Profile. However, I myself do not install pre-made site profiles too often and even in the case of such a profile, you will probably want to adjust some settings and install your favorite modules too.
Normally I install the Blank Profile (introduced in v2.5) to start development with a blank slate. If you install this so called Blank Profile, you will get the following in your /site directory:
- config.php (file)
- assets (dir)
- modules (dir)
- templates (dir)
Setting up PHP date localization with setlocale
The file /site/config.php is the most important one to begin with, of course :) In recent versions of ProcessWire you will be asked to change it right after logging in the first time (you will get it right after logging into the admin). Specifically we are asked to add a PHP function call called setlocale() to it. The exact waring message looks like this: "Warning: your server locale is undefined and may cause issues. Please add this to /site/config.php file (adjust “en_US.UTF-8” as needed): setlocale(LC_ALL,'en_US.UTF-8');"
To learn more about setlocal(), read this forum post written by forum member Matjazp and his GitHub post too. Also, if you are interested in the importance of setlocal in PHP, I recommend reading this post as well.
TL;DR version: ProcessWire developer LostKobrakai says: Adding the setlocale statement is not a hard requirement, but you'd need to live with the ProcessWire notice each time you log in. It's been added not because of anything related to multi-language sites, but because of issues with file handling of processwire involving utf-8 characters like cyrillic ones. These can happen on all processwire sites not just multi language ones.
Which means that you should only set the proper sitelocale if it will be likely that files with non-ASCII characters will be uploaded via the admin area. If you just want to get rid of the error message, you can simply use setlocale(LC_ALL, "C.UTF-8", "C.utf8"); for example.
So, if you need to upload files with non-ASCII characters, the most important thing to do is to find out what locales are available for you to use, ie. what is supported by the sever. There are various ways to figure it out, let's list some of them:
- If you have CLI/SSH access, type locale -a on the command line.
- If you do not have CLI/SSH access, then create a file called something like testlocale.php in your website's root, and paste this into the file:
<?php echo "<pre>Current locale:\n"; var_dump(setlocale(LC_ALL, '0')); echo "\n\nAvailable locales:\n"; echo exec('locale -a');
After that point your browser to http://mydomain/testlocale.php
If you do not get any results then it is possible that no locales are installed. You should contact your hosting provider to resolve the issue. After you have figured out what locales are available to you, it is time to decide which one to use.
Changing the Admin Theme
ProcessWire's administration area supports different themes. It comes with two themes; the Default Theme and the Reno Theme. The latter is not "installed" (activated) by default, but just like me a lot of ProcessWire users use it instead of the default one. To install it go to Modules > Core and look for Reno. Click install and your are almost done. To make this theme the default one, add this to you /site/config.php file: $config->defaultAdminTheme = 'AdminThemeReno'; Next reload the admin and ta-da... done :)
Note: Currently a brand new Uikit-based admin theme is in the works, already in beta sate.
Pimping my admin area
We are going to add extra functionality to the already great number of features provided by the Reno theme. We will also tweak settings to our likings.
Recommended modules for the administration area:
- System Notifications: Core module bundled with the installer. Just click install and you are ready to go. It changes the way system messages are displayed. ProcessWire would drive me crazy without this module in action.
- Process Wire Upgrade: its class name is ProcessWireUpgrade. does not come with the installer, but can be considered to be an "official ProcessWire module". It can be installed from the official ProcessWire Module Directory. See below to learn how to install modules from the Module Directory. It enables you to look for system and module updates/upgrades either manually or (optionally) automatically at each admin login event.
- Process Database Backups: its class name is ProcessDatabaseBackups. Same as before, a "official ProcessWire module". Enables you make quick database backups which are recommended before system and module updates. ProcessWire updates are generally performed without any issues regarding the database, but it is always recommended to play safe! ProcessWireUpgrade and ProcessDatabaseBackups modules work together, meaning the former can optionally make a backup for you automatically when upgrading the system.
- Clear Cache Admin: not in the Module Directory but written by Soma, a ProcessWire veteran. It can be installed from GitHub. See below to learn how to install modules from GitHub easily. This module is quite handy when running into cache issues which can happen from time to time (however, not too often!).
- Admin On Steroids: its class name is AdminOnSteroids and available from the Modules Directory. This is a one of its kind module, developed by the most active Hungarian ProcessWire developer Tóth Roland. It provides plenty of options to tweak your admin. Highly recommended!
Installing modules form the Module Directory
The official guide to install modules can be found here. I decided to add a few more information bits to it should you get stuck:
- Go to Modules > New (tab) > Add Module From Directory > Module Class Name and in the inputbox provide the module's class name, such as ProcessWireUpgrade (and not Process Wire Upgrade) found in the Module Directory.
- Click Download and Install, which initiates the process of looking for the module in the Module Directory
- After the module has been found you need to click the Download and Install button just once more to actually download it.
- If all goes well the module is downloaded from GitHub to your server.
- Click the Install Now button just to actually install and activate the module.
Installing modules form GitHub / URL
When module is not in the Modules Directory, but the module's ZIP file is accessible from a URL, use this method. Actually, this method is completely documented on this page.
Recommended modules to support development
- Tracy Debugger: its class name is TracyDebugger. This gem is also highly recommended. It is developed and maintained by Adrian Jones who is also a veteran developer ProcessWire. It has a tremendous amount of features to make development a lot easier. You will also learn a lot about ProcessWire itself if you use it. Do not miss it!
- Text formatter Hanna Code: its class is TextformatterHannaCode, not strictly a developer tool, but I decided to include it here as the functionality it can provide can cut down development time in certain circumstances. Basically it is similar to the short code feature of WordPress, so people familiar with it can imagine what it can do. For more details read the docs here.
- Admin Actions: its class is ProcessAdminActions. This one is also developed by Adrian Jones. It ships with various functions to automate things you could normally do manually in the admin, saving tons of time. You can also implement your own actions to automate whatever you want to. Check out the docs to learn more.
Adding more files to the site profile
While the Blank Profile is great, I always add these from the site-default profile. These files can be copied over from the installer package of ProcessWire. Read the comments in the files to learn more about them:
Also, to facilitate the delayed output strategy, I copy over these ones too:
However, these files are not just placeholders, so I need to edit them in order to remove what solely belongs to site-default profile which I do not need:
- _func.php & _main.php: I keep the namespace declaration and the first block of comment. Everything else is removed from this file.
- _init.php: quite useful the way it is, so I leave it like that, in order to serve as a starting point
Additional settings which go into /site/config.php
Since I prepared the files _init.php, _func.php and _main.php in order to actually use them, I have to add the following two lines to /site/config.php:
- $config->prependTemplateFile = '_init.php';
- $config->appendTemplateFile = '_main.php';
These settings are explained in the ProcessWire docs discussing the Delayed Output. Look for the Automatic inclusions section on the page.
- $config->useMarkupRegions = true;
- $config->useFunctionsAPI = true;
Time to change /site/config.php permission settings
To strengthen the security of your ProcessWire website, please consider this.
Cleaning up the initial template files
At this stage _main.php is void of any useful code, that is why I copy over the content of basic-page.php. Meaning the default HTML markup found in /site/templates/basic-page.php is moved to /site/templates/_main.php. I also clear /site/templates/home.php.
Currently all the markup is coming from _main.php which is my indented starting point before I dive into implementing anything for the frontend.
The importance of the ProcessWire namespace
Beginning with ProcessWire 3.0.x, the system takes advantages of namespaces and it even provides a built in autoloader. The most important thing to learn here is that the global namespace is NOT used, and the easies way to develop templates files is to use the ProcessWire namespace. In order to do so – as a rule of thumb –, we have to start all our php files with <?php namespace ProcessWire;
Of course, if you want to utilize other namespaces, you are free to do so but for general development needs the ProcessWire namespace can be just enough.
That's all for now...
...see you next time when I will explore a few simple ways of working with production and development environments.