Project 8: your first extension #

Extensions are how Exponential is extended without changing the kernel. In this project you build the smallest working extension, a page that greets a visitor by name, then make it safe and keep it in Git. The steps follow Extensions, section 6.

Contents #

1. At a glance
2. Goal
3. Before you start
4. Tasks
5. Hand in
6. Rubric
7. Stretch goals

At a glance #

Goal #

An extension with your own name (for example studyhello) that serves /hello/world/<name>, shows the name escaped inside your site's layout, is listed under Setup > Extensions with its version, is protected by a policy, and lives in its own Git repository.

Before you start #

• Read Extensions, sections 1, 4 and 6.1, and What an extension is.
• Pick a name that is yours: lower case, letters, digits and underscores. The guide uses myhello.

Tasks #

1. Create the folders extension/<name>/settings, modules/hello and design/standard/templates/hello.

2. Write ezinfo.php and extension.xml with the same version (0.1.0), your name in the copyright line, and "GNU General Public License v2.0 (or any later version)" as the license.

3. Write the settings: settings/module.ini.append.php with ExtensionRepositories[]=<name> under [ModuleSettings], and settings/design.ini.append.php with DesignExtensions[]=<name> under [ExtensionSettings].

4. Write the module and the view: modules/hello/module.php with one view world that takes the parameter Name, and modules/hello/world.php that passes the name to the template and returns $Result.

5. Write the template design/standard/templates/hello/world.tpl, printing the name with {$name|wash}.

6. Check the PHP: php -l on each PHP file. Expected: No syntax errors detected in <file>.

7. Switch it on and refresh:

   php bin/php/console exp:ini add 'site.ini/ExtensionSettings/ActiveExtensions[]' <name> global --allow-root-user
   php bin/php/ezpgenerateautoloads.php -e
   php bin/php/ezcache.php --clear-all --allow-root-user

8. Open /hello/world/Ada on your site. Expected: Hello, Ada inside your site's layout, and Setup > Extensions lists your extension with version 0.1.0.

9. Try to break it. Open /hello/world/<b>Ada</b> (URL encoded if needed). The name must be shown as text, not as bold markup. Explain why.

10. Protect the view. A view without a 'functions' entry has no access control: anyone who can reach the site can open it. Declare a function ($FunctionList['read'] = array(); in module.php, 'functions' => array( 'read' ) on the view) and grant it in Users > Roles and policies to a role. Check as anonymous visitor and as a user with the role (Extensions).

11. Commit the extension to its own Git repository, with a commit subject such as Added: The hello world view.

Hand in #

• The repository (or an archive of it) with every file of the extension.
• Screenshots: the greeting page; Setup > Extensions with your extension; the denied page for a visitor without the policy.
• The output of php -l for each PHP file.
• A short report: what each file does, and why the policy matters.

Rubric #

Score the four common criteria of Grading your own work, and these checks (8):

1. The extension name is the learner's own, lower case.
2. ezinfo.php and extension.xml carry the same version and the license.
3. Every PHP file passes php -l.
4. The extension was switched on with a settings override, not by editing settings/site.ini.
5. The greeting works and the name is escaped.
6. The view is protected by a function and a policy, shown for both cases.
7. The extension is in its own Git repository with readable commit subjects.
8. No kernel file was changed.

Stretch goals #

• Generate a module with the RAD wizard (/setup/moduleextension) and compare its files with yours (Extensions). Note: the wizards list every file before writing and never overwrite an existing extension.
• Add a setting of your own in settings/<name>.ini and read it with eZINI::instance( '<name>.ini' ) (Extensions).
• Add a translation of the greeting (Extensions, section 6.4).
• Publish it on GitHub as your own project (Contribute extensions back). Your own extension is not covered by the CLA (The CLA for students).

Related pages #

• Study projects: overview
• Extensions
• Learning path: developer
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.