“Hello World” Process Module for ProcessWire
A starting point skeleton from which to build your own Process module.
Process modules are used primarily for building admin applications and tools
in ProcessWire. This module also creates a page in the ProcessWire admin to
run itself from. Requires ProcessWire 3.x.
What this modules demonstrates
This module demonstrates everything you would need to create a Process module.
It also demonstrates many things that you may not need, but things that are
still good to know about.
- How to create an index
execute() method that are called for your Process
module’s main/index URL. - How to create
executeMethodName() methods that are automatically called
when URL segment matches method-name/. - How to return markup from your URL handling methods directly.
- How to use separate markup “view” files your URL handling methods.
- How to create message, warning and error notifications in the admin.
- How to set the admin headline, breadcrumbs and browser
<title> tag. - How to define drop-down navigation for your Process module.
- How to create and process a simple form that uses Inputfield modules.
- How to provide additional submit actions in the form submit button.
- How to make the Process module configurable.
- How to provide multi-language translations for the module.
- And more…
How to install this module
Copy all of the module files to /site/modules/ProcessHello/.
In your admin, go to Modules > Refresh.
Click “Install” for the “Process > Hello” module (on the “Site” tab).
How to test this module
Configure the module from the module configuration screen and Save.
Click to Setup > Hello.
After testing it, open the .module.php file in your editor and
see how it works. Use it as a starting point for your own Process module.
If in a multi-language environment running ProcessWire 3.0.181 or newer,
see the “install translations” link in the “Module Information” fieldset,
when on the module configuration screen. Here you can optionally install
other language translations for the module.
How to use this to make your own Process module
To see exactly what this module does, you may want to install it as-is first.
Then uninstall and follow the instructions below.
Rename the ProcessHello.module.php file to be ProcessModuleName.module.php,
replacing the ModuleName portion with your module/class name you wish to use.
In the .module.php file change the class name at the top to be to be
ProcessModuleName, again replacing the ModuleName portion with your own.
Edit the ProcessModuleName.module.php file to do what you want. In addition:
- Remove and/or repurpose methods you don’t need.
- Remove the
/extras/ dir as it only is there for extra examples. - If you don’t want to use separate view files, you can remove the
/views/ dir. - If you don’t want to bundle languages you can remove the
/languages/ dir.
If your module needs its own CSS and/or JS files, rename those included to be the same as
your module name and modify them to do whatever you want. If your module does NOT need
CSS and/or JS files then delete them.
Rename the ProcessHello.info.php file to ProcessModuleName.info.php and edit it,
updating it specific to your module and information.
If you DO want your module to be configurable:
- Update the
getModuleConfigInputfields() method at the botton of the module file. - Update the
$this->set('property', 'value') statements in the __construct()
method to specify your default configuration values. - Update the phpdoc comments above the class to document your configuration properties.
Note: If you prefer a separate configuration file, see the example and instructions in the
/extras/ProcessHello.config.php file rather than the steps above.
If you DO NOT want your module to be configurable:
- Remove the
ConfigurableModule interface/text from the module’s class definition. - Remove the
getModuleConfigInputfields() method at the bottom of the module file. - Remove the
$this->set('property', 'value') statements from the __construct() method.
If that leaves the method blank (other than the parent call) you can just remove the
method construct entirely. - Remove the phpdoc comments at the top of the class referring to configuration variables.
If you do want to bundle translations of your module for other languages see the section
after this one.
Update this README.md file to contain information specific to your module.
When you've got something you'd like to share, post your module to GitHub and to
the ProcessWire modules directory at: https://processwire.com/modules/`.
Bundling multi-language translations with your module
This requires ProcessWire 3.0.181+ and that you have multi-language support installed.
Locate the files you want to translate from your admin: Setup > Languages >
language > Site files > Find files to translate. Select the file(s) and submit.
ProcessWire will generate new empty .json files for the files you selected to
translate.
In Setup > Languages > language, click the "edit" link for file(s) added for
your module. Translate the text into the desired language and save. Near the top
of the translation screen is a link to "Download a CSV file". Click that to save
the CSV file of translations.
Copy the CSV file(s) you downloaded in the previous step into a /languages/
directory in your module’s path. For instance /site/modules/ProcessHello/languages/
is the one you'll see with this module. While not required, I recommend naming
your files with the ISO-639-1 language code. For instance, German would be
de.csv, Spanish would be es.csv, Finnish would be fi.csv, etc.
If your module has multiple translatable files, you can bundle all the translations
into a single CSV file (just copy and paste into one), or you can have multiple
.csv files for each language. For instance, if this module had both
Helloworld.module and ProcessHelloworld.module files, we might choose to name our
csv files es-main.csv and es-process.csv. Or we could just have an es.csv
file that merges that translations from both of them.
In your module’s documentation, instruct the user to install translations from
your module’s info/config screen. It’s in the “Module Information” fieldset
“Languages” row, where there is an “install translations” link. When new versions
of your module also update the translations, make note of that in your changelog
so that users will know to click the “install translations” again to update
the translations.
Other ProcessWire demo modules by Ryan:
Stop by the ProcessWire forums anytime and we will be glad
to help with any questions.
ProcessWire Copyright 2021 by Ryan Cramer