Reusable components for your ProcessWire-templates.

Twack

Reusable components for your ProcessWire-templates!

Welcome to Twack! Twack helps you build well-structured and maintainable ProcessWire-projects. Inspired by angular.

Current Version Current Version Current Version

Buy Me A Coffee

Features


  • Create components ! Twack components are designed for reusability and encapsulating a set of features for easy maintainability. They can handle hierarchical or recursive use (child components).
  • Based on ProcessWire's core functionality and principles
  • HTML- and Ajax-Views - specify json output for ajax-requests
  • Define services, that handle global data. Twack manages the shared service-classes (->singleton) for you and lets you access the data from everywhere you need it.
  • Not exclusive - use Twack components to extend existing templates. You don't have to rewrite everything!

Table of Contents


Installation


Twack can be installed like every other module in ProcessWire. Check the following guide for detailed information: How-To Install or Uninstall Modules

The prerequisites are PHP>=5.5.0 and a ProcessWire version >=3.0.0. However, this is also checked during the installation of the module. No further dependencies.

Quickstart: Creating a component


Twack uses components to subdivide the website into logical components. A typical component can stand for its own and has no dependencies, which make it reusable and easy to maintain. Most components consist of a controller and a view.

If you have not done create the site/templates/components directory. Here we will place all of our future components. Add a new file hello_world.view.php inside of the directory. Create site/templates/services where all our service classes will find a home.

Open the file and fill in the following contents:

<?php
namespace ProcessWire;
?>
<h2>Hello World!</h2>

It's done! We have our first functioning component. Admittedly, the component consists of only one view, but even for simple components there are many useful purposes. We will add data-handling and functions in a moment. But first, let's learn how to use our component in one of our ProcessWire-templates.

If we had a controller-class for our view, the class would be called HelloWorld. More on that in the next chapter. To use our component in a ProcessWire-template, we have to ask the Twack-module for it and it will find and initialize it for us.

<?php
namespace ProcessWire;

// Get a new instance of our HelloWorld-component:
$myComponent = wire('twack')->getNewComponent('HelloWorld');
?>

<html>
  <head>
    <title>Hello World!</title>
  </head>
  <body>
    <?php
    // Render the component`s view:
    echo $myComponent->render();
    ?>
  </body>
</html>

As you see, including a Twack-component in traditional ProcessWire-templates is quite simple. You can build the complete HTML in Twack-views and use its full potential, but you don't have to. It is possible to gradually replace individual parts of the page.

Let's go back to our component. You created your HelloWorld-component with nothing but a view that outputs a bold "Hello World!". Most components need more than just an output. We need a controller to make the view more dynamic.

Create a new directory site/templates/components/hello_world/ and move our view-file to this destination. Additionally create a controller file with the name hello_world.class.php in this new directory.

A Twack-controller needs a bit of boilerplate-code to correctly function. Copy the following code to your controller-file (hello_world.class.php):

<?php
namespace ProcessWire;

class HelloWorld extends TwackComponent {
  public function __construct($args) {
    parent::__construct($args);
  }
}

Every Twack-controller has to extend our general TwackComponent, which brings a lot of background-functionality to our controller. With parent::__construct($args); we let the parent TwackComponent finish its general initialization work before our custom component's code will be executed.

In our constructor we will define variables, add child-components and do all logical work for the view.

An a little more advanced controller can look like this:

<?php
namespace ProcessWire;

class HelloWorld extends TwackComponent {
  public function __construct($args) {
    parent::__construct($args);

    $this->title = 'Hello World!';
    if(isset($args['title'])) {
      $this->title = $args['title'];
    }

    // Add and initialise a child-component
    $testChildArgs = [
      'myTestValue'
    ];
    $this->addComponent('TestChild', $testChildArgs);
  }
}

$this->title will be "Hello World!", as long as we get no value for $args['title'] from our constructor's $args parameter. If we had initialized the component with $twack->getNewComponent('HelloWorld', ['title' => 'My new Title.']);, we would set it to this new value.

Every attribute of the controller is also accessible in the view, you don't have to care about transferring values.

A child component can be added via $this->addComponent(). In our example, we add the Component 'TestChild', which shall be located under site/templates/components/hello_world/test_child/test_child.class.php. Twack automatically looks in the current component's directory for subdirectories. Specifying an other path is also possible. I created an array $testChildArgs to demonstrate passing additional parameters to the TestChild, which will be passed to its constructor.

Our new view could look like this:

<?php
namespace ProcessWire;
?>

<div class="hello_world_component">
  <?php
  if(!empty($this->showTitle)){
    echo "<h2>{$this->showTitle}</h2>";
  }
  ?>
  <p>Lorem ipsum</p>

  <div class="children_wrapper">
    <?php
    foreach ($this->childComponents as $childComponent) {
      echo (string) $childComponent;
    }
    ?>
  </div>
</div>

As you see, we only show the title, if $this->title has a value. Under $this->childComponents we have a list of all components that were added via $this->addComponent() in the controller.

We now have created a basic Twack-component and you now the general concepts how Twack works. But Twack has are a lot of more great features that will emend and simplify your development process.

Changelog


Changes in 2.1.4 (2021-01-04)

  • Improved documentation
    • Moved most contents of README to Wiki
    • added page-links

Changes in 2.1.3 (2020-06-14)

  • Made Twack available as API-variable like wire('twack') . (Thanks to @BernhardBaumrock)

Versioning


We use SemVer for versioning. For the versions available, see the tags on this repository.

License


This project is licensed under the Mozilla Public License Version 2.0 - see the LICENSE.md file for details.


Continue with 2: Naming conventions & component variants

Install and use modules at your own risk. Always have a site and database backup before installing new modules.

Twitter updates

  • Preliminary 2021 roadmap in progress in this week’s update— More
    8 January 2021
  • Happy New Year! Today I’ve bumped the version on the dev branch to 3.0.170, and it’s quite a lot of updates. This post covers most of them. In this post, there’s also a question for you: what would you like to see in ProcessWire in 2021? More
    1 January 2021
  • In this week’s blog post we’ll take a brief look at a powerful new ProFields module for ProcessWire that’s just around the corner—the Combo field: More
    4 December 2020

Newest forum posts

Latest news

  • ProcessWire Weekly #349
    In the 349th issue of ProcessWire Weekly we're going to cover the latest core and forum updates, introduce some recent ProcessWire resources, and more. Read on!
    Weekly.pw / 16 January 2021
  • ProcessWire 3.0.170 core updates
    Happy New Year! Today I’ve bumped the version on the dev branch to 3.0.170, and it’s quite a lot of updates. This post covers most of them. In this post, there’s also a question for you: what would you like to see in ProcessWire in 2021?
    Blog / 1 January 2021
  • Subscribe to weekly ProcessWire news

“Indeed, if ProcessWire can be considered as a CMS in its own right, it also offers all the advantages of a CMF (Content Management Framework). Unlike other solutions, the programmer is not forced to follow the proposed model and can integrate his/her ways of doing things.” —Guy Verville, Spiria Digital Inc.