First Steps to Building a TYPO3 Extension (Like QueryBuilder)
Thanks to Henrik from DFAU for sharing!
With my first TYPO3 extension QueryBuilder reaching 300 downloads, I wanted to share some of the knowledge I gained from the development and maintenance of it. I’ll explain how to set the stage for creating a TYPO3 extension and provide some links to further resources in the TYPO3 documentation.
The beginning of it all? Last year the company I work for (DFAU GmbH) gave me the the opportunity to take part in TYPO3 GmbH’s Send Your Junior! program. A truly valuable experience where I learnt tons.
Why am I writing about extensions NOW?
A new major TYPO3 LTS version was released at the beginning of October 2018 (TYPO v9 LTS). When a version gets released, extensions need to be made compatible to the new version. We’re glad to be able to serve with the updated version for the QueryBuilder - we updated hooks, cleaned up the code and published the new version only one week after the TYPO3 v9 LTS release.
The most relevant aspects of TYPO3 & extensions
TYPO3 is designed so that added extensions seamlessly supplement the TYPO3 core. A TYPO3 system will appear as "a whole" to users and visitors, while it’s actually composed of the core application and a set of extensions providing various features.
Extensive API (Application Programming Interface) support provides an easy way for us TYPO3 developers to build on and lets us expand the core functionality with extensions that are added or removed as needed, making the possibilities truly endless (other software makers may refer to them as modules, plugins or add-ons).
A TYPO3 extension is a collection of files that either adds some extra functionality to the core or changes a given function.
Where to download free TYPO3 extensions?
Being open source software, you can look under the “TYPO3 hood(...ie?!)” and add any functionality to the core that you may need. Many of the most useful TYPO3 extensions are contributed by the TYPO3 community to the TYPO3 community. Ideally you can therefore find what you need in the TYPO3 Extension Repository (TER), it's like an App Store for TYPO3. If you can't find what you need, then it's time to create an extension.
When to create an extension from scratch?
- The most straightforward reason is when a customer needs an a specific functionality that is neither in part of the TYPO3 core nor available in the TYPO3 Extension Repository (TER).
- Another good reason to create a extension is if I need a specific feature that used to be integrated in an older TYPO3 LTS version that has meanwhile been removed from the core.
- Or maybe I simply want to implement a function in a different way than the LTS version the customer’s installation is running on provides (at the time of this writing the two major versions are TYPO3 v8 and v9 LTS).
For instance, let’s take a look at the “save” buttons. This is a good example for a core function that has recently been changed but can easily be reestablished in the old way, if chosen. There used to be three buttons for saving content:
With TYPO3 v8 LTS, the three buttons were changed to a drop down menu. While this looks pretty neat, it does mean that you have to click a second time to choose one of the three options for saving content:
Some find the second click annoying. You can use one of several extensions in the TER to display the save buttons in the way they used to be. To do so, head over to the backend, go to the Extension Manager in the list module and use the search box at the top to find the extension. All you need to do is click on it and it automatically gets integrated into the TYPO3 system.
An example: the TYPO3 extension QueryBuilder
The QueryBuilder lets you use the list module to search records. The list module is a integral component of TYPO3 and lets you display data records of any kind as lists (or tables, as they are stored in a MySQL database). The QueryBuilder is an easy-to-use and powerful filter for these lists - it lets you create and run database queries, data records are retrieved accordingly. You can also extend the search or filter different characteristics of specific data records.
Take for example a tourist office and a folder full of records of trips to destinations across the globe. If you need a list of all of the trips e.g. to Germany you just enter “Germany” into the filter and the corresponding records get displayed. You can also save filters to use them again in the future.
Creating the extension structure
This tutorial explains how to create the initial extension directory for a TYPO3 extension.
Set up your development environment
First off, you need a TYPO3 installation to work with. The easiest way to install TYPO3 is by using Composer. If you don’t have Composer on your operating system, then click here and follow the instructions. For instructions on how to install TYPO3, read the step-by-step guide How to Install TYPO3 Using Composer (in Less Than 5 Minutes) or watch this video on our TYPO3 YouTube channel.
The extension has to “live” somewhere, you need a place to save your source code and where you can make it available to others. GitHub is a great place to store and share code.
Name your TYPO3 extension
The first step in creating an extension is to choose a unique, short name for it, the so-called extension key (extkey). This name is used in all of the files names and the function names in your extension. For demonstration purposes we’ll call this my_extension.
Check the rules for naming extension keys either on TYPO3.org or read the page in the TYPO3 documentation for more details. If you plan to make the extension publicly available, the next step is to register the extension key on TYPO3.org. For this, log in to TYPO3.org with your credentials and follow the path: TYPO3 CMS > Extensions > My extensions > Register extension key. Enter the name in the given field and follow the instructions.
Folder structure and configuration files
Before you write any code, you need to create the folder structure and configuration files for your local extension. For this, go to the typo3conf/ext folder in your TYPO3 installation. Then:
Create a subfolder for your extension: typo3conf/ext/my_extension
All of the extension-specific files get put into this directory.Add a PHP file at the root level of your extension folder: typo3conf/ext/my_extension/ext_emconf.php
This is the only mandatory configuration file. The ext_emconf.php file is used for storing general information about the extension (e.g. meta data like title, description name of the author, etc.) and for specifying the extension’s dependencies on other projects. The ext_emconf.php files must be in place for the Extension Manager to be able to find and load the extension in the backend.
Core extensions that ship with TYPO3 are called system extensions (e.g. the backend interface) and are kept in a different folder: typo3/sysext/.
Optional files and folders
All other folders and files for the extension are optional and depend on the functionality that your extension provides.
Some optional folders:
Classes
All of the PHP classes get stored here, with the exception of external PHP libraries.Configuration
Basic settings for the extension based on Typoscript and also PHP are stored here - however, in the special form (TCA), which is used to configure the display/definition of data records in the backend.Resources
This one’s for HTML, CSS, JavaScript, images, and other resources.
Some optional files:
ext_localconf.php
ext_tables.php
ext_tables.sql
Check this table in the TYPO3 documentation for more details on files and folders that you may need and what they’re for.
How to create an extension?
If you’re a dev too, you’ll want to create the extensions yourself and build the skills you need. To build a simple TYPO3 extension, follow this step-by-step guide in the TYPO3 documentation. It describes how to create an extension to display lists of products and includes tutorials and other information that you need to create local extension for TYPO3.
Want to learn more TYPO3 coding skills?
Here are some more resources to help you learn to get the most out of TYPO3.
TYPO3 CMS questions on Stack Overflow
Check out the questions tagged “typo3” on Stack Overflow.TYPO3 CMS Slack
The TYPO3 community collaborates on Slack. This is the place to go if you have questions. Check out the #typo3-cms channel for general chat, or find your own local group to meet others in your area.TYPO3 YouTube channel
You'll find answers to frequently asked technical questions, instructional clips and all sorts of helpful videos on our TYPO3 YouTube channel. We publish new videos on Friday.Code sprints - Check out the events listing on TYPO3.org
All TYPO3 developers are welcome to code sprints. Once you know the basics of Git, PHP, CSS, HTML, MySQL, JavaScript and Fluid you can help contribute to TYPO3 CMS. There are experienced mentors to help guide newcomers, so don’t be shy.Review Friday at TYPO3 GmbH
Every first Friday of the month, TYPO3 GmbH opens their doors for all who’d like to contribute to the TYPO3 project by doing reviews or writing patches. It’s a great opportunity to share know-how and learn more as you go.
General thoughts
In most cases, devs like me work for a company, have customer projects and need to generate turnover. When we contribute to the core or build extensions there’s no income (there are exceptions, e.g. if the functionality is used directly for a customer’s project).
The Send Your Junior! program is therefore ideal. While I was in Düsseldorf I had 100% time to focus on improving my skills and e.g. developing the QueryBuilder extension. Team members like Frank, Anja and Christian provided clear guidance: I got technical support, answers to my questions, feedback, and everything else I needed was provided for too (including energy drinks).
I genuinely appreciated the collaboration and we still have a lively exchange on technical issues although I’ve been back in my company for the best part of a year now. Communication was (and still is) uncomplicated and at eye level. We were in close daily contact about the individual steps leading towards the solution and they even encouraged me to coordinate the tasks and hand over things that needed to be dealt with. Getting such helpful support is a true motivator. It makes it easy to say yes to completing other tasks, even on a Friday evening (like this blog post).
Closure
TYPO3 is an ideal choice for building ambitious digital experiences. The commercial arm of the project, TYPO3 GmbH, offers the Send Your Junior! program. If you are an aspiring developer, this program can provide an easy on-ramp for personal growth within the TYPO3 development community.
For me, it was a truly rewarding experience, thank you TYPO3 GmbH for hosting me so well and thank you DFAU GmbH for giving me this opportunity to build both my skills and my network with other professionals.
Also, our QueryBuilder extension is live on the TYPO3 Extension Repository and I would love to get your feedback on that. If you have questions or would like to join in on conversation and/or developement, then check the TYPO3 Slack channel #ext-querybuilder. Do you think the QueryBuilder should be integrated into a future version of TYPO3?
