Creating an extension

Posted on

While you can technically extend Torro Forms simply by using action and filter hooks, you’re encouraged to create an actual extension, following the patterns that Torro Forms supplies for this. For this very reason, Torro Forms provides a boilerplate that can be used to quickly scaffold the basic code needed for an extension. The benefits are solid interoperability, easy access to plugin services and extension-specific services, and an object-oriented foundation closely designed to follow the principles of the main plugin.

You can find the Torro Forms extension boilerplate on GitHub.

Project Setup

  1. Download a ZIP file from the above GitHub repository, and extract it into the wp-content/plugins directory of your local development environment.
  2. Rename both the new directory and the main plugin file to be the slug of your new extension.
  3. Replace all placeholder occurrences of strings referring to the “Torro Forms Plugin Boilerplate” with the respective strings referring to the actual name of your new extension. You don’t need to do this manually, there is an easy-to-use gulp init-replace command available to make the replacements for you. The boilerplate readme includes detailed instructions on how to use that command, and it also tells you how to get rid of the command afterwards so that you cannot (accidentally) execute it again.
  4. Make changes to the composer.json and package.json files as necessary, and also update the values in the configuration object in gulpfile.js to your preferences.
  5. If you plan to publish the extension in the WordPress.org plugin repository, you can remove the language-specific functionality since wordpress.org will handle it in that case. To do so, remove the /languages directory (if it exists), set the domainPath property in the gulpfile.js configuration object to false and remove the second parameter from the load_plugin_textdomain() method call. You may also wanna clean up the code for the pot task in the gulpfile.js and all references to it in that file.
  6. Run gulp build from the command line.
  7. Adjust the README.md file by replacing awsmug/torro-forms-plugin-boilerplate to your own vendor and project name – and of course adjust the general content of that file too, to whatever works for you.
  8. Remove sample code and files from the boilerplate if you don’t need it. It may be helpful to keep it there just to get started and remove it later, but if you already know what you’re doing, you might as well get rid of it now. Otherwise, do it as you implement your own functionality. To get rid of all sample functionality:
    1. Completely remove the register_date_element_type() method from the extension class.
    2. Empty the instantiate_services() and setup_hooks() methods of the extension class. Do not remove them though.
    3. Remove the import statement of the assets service from the extension class.
    4. Delete the src/element-types directory.
  9. Set up related tools for your workflow (see below). We highly recommend you to do so, and get familiar with those techniques if you aren’t. If you wanna instead get to coding immediately, you can start right now!

Additional Workflow Setup

  1. Initialize a local git repository for your new extension by executing git init in the command line. It’s recommended to do a first commit after you have done all the preparation outlined above, but before you actually start coding. Run commands git add . and git commit -m "Initial commit." to do that.
  2. Set up a remote repository for your project, for example at GitHub or Bitbucket and connect your local repository to it.
  3. Push the initial commit to the new remote repository.
  4. To automate code quality checks, create a project at CodeClimate from your repository. Create an account if you don’t have one yet. CodeClimate is free for open-source projects.
  5. Go to Travis-CI to set up continuous integration, particularly automated testing, for your repository. Just as before, create an account if you don’t have one – Travis-CI is free for open-source projects as well. The .travis.yml file included in the extension boilerplate is ready to be used for WordPress Core and Torro Forms integration tests, as well as coding standard checks.
  6. Go back to your CodeClimate project and move over to Settings > Analysis > Test Coverage. From here you can copy your test reporter ID, and with that go back to Travis-CI and Settings > Environment Variables and paste it as an environment variable with the name CODECLIMATE_REPO_TOKEN.
  7. Go to Packagist and submit your project there, so that it is available as a package to other developers using Composer. Again, Packagist is free for open-source projects. After submitting, make sure to setup auto-updates by going to your remote repository and setting up the integration with the Packagist service.
  8. You need to change some code and push it to your remote repository to trigger a refresh on the above tools. After you’ve done so, verify that everything works correctly by referring to the badges in your extension’s README.md file.

Note that the above tools are recommended to be used, since the Torro Forms extension boilerplate is already prepared for those with configuration files. However, if you’re already familiar with automated code review and continuous integration tools like those, feel free to use other tools of your preference. Be aware that, especially if this is relatively new to you, sticking with the recommended tools is probably the easiest.

Writing Code

Teaching how to write code would certainly go beyond this tutorial. Something more suitable though would be explaining some of the concepts of the plugin.

  • Torro Forms is an object-oriented plugin requiring at least PHP 5.6, thus using language features such as anonymous functions, namespaces, interfaces and traits. Since WordPress still supports the ancient PHP version 5.2 (and isn’t really object-oriented anyway), it does not currently make use of most of these things. You can though (and should)! If some of this is new to you, read through the linked introductions and browse the codebase of the Torro Forms core plugin to look at examples.
  • Torro Forms essentially includes only one regular function, which carries the name torro(). This function returns the main plugin class, and through that class you have access to all functionality that the plugin bundles – mostly through the plugin’s services made available. For example, by calling torro()->forms(), you get the form manager service used by the plugin, and you could call torro()->forms()->get( 3 ) to retrieve the form object for the ID 3. You can learn more on this topic by reading the tutorial on which services are available.
  • Torro Forms uses several main object types that represent content, each of which are stored in their own custom database table. The most obvious object type is a form, but there are several more, which are hierarchically organized:
    • containers (for the pages of a form)
    • elements (the actual input controls to fill in)
    • element choices (the possibly values for an element, for example a dropdown)
    • element settings (arbitrary settings for an element as defined by the form creator)
    • submissions (user-created data entered for a form)
    • submission values (the actual values of such a form submission)
  • All Torro Forms integration that does not deal with tweaking behavior of any of the object types in particular happens through modules. Modules provide a flexible foundation to hook into certain form events. The plugin defines a few modules that handle specific areas of a form and submission lifecycle, and for those it is particularly easy to register submodules for additional features. You could even register completely new modules if you need to do things which are really outside of the box. Learn more about working with modules.
  • Elements are the most complex object type which is part of the plugin, as they heavily rely on the behavior defined in the available element type. Each element is of a certain type, which you can essentially think of as a type of input control – for example a textarea, a dropdown or a checkbox. One of the most common use-cases for an extension is implementing your own element type.

After reading these broad introductions on some of the plugin concepts, it’s recommended that you work through the individual tutorials linked above. Once you’ve done that, there should be nothing more in your way to develop your perfect Torro Forms extension. Make sure to check back for new tutorials from time to time, as we’ll update them regularly!