A simple contact form for koken

Shortly after my decision to ditch my former CMS (WordPress) and to set up a new site using koken I encountered one problem: there is no plugin for a contact page

A modern CMS requires such a contact form, so I decided to build a solution myself.

I defined following requirements for an extension:

  • No email address should be shown in the template
  • JavaScript-"encryption" was no option
  • The form itself should work without JavaScript
  • The form should be validated on the server
  • No tampering with FireBug should be possible
  • Wrong input data should visualized after a failed validation
  • Valid input data has to be inserted into the form after a failed validation
  • Bots should not be able to spam using this form, so it has to include a CAPTCHA
  • The CAPTCHA should be clearly readable without guessing, too :)

I added the extension to my version of the "Regale"-theme as you can see clearly on my site.

After a koken user sent me a request regarding my extension (using my contact form) I decided that it should be released to the public. I'll provide an archive containing a base version of the required files because there is clearly a need for such a solution - as can be seen in numerous discussions at help.koken.me.

There are two ways of using the archive:

  1. Add a new template and route to your theme's configuration ( info.json).
  2. Add a new page in the console and add the template code into the page. The JavaScript has to be added with the injector-plugin of koken, because as of now <script/>-tags cannot be saved within the HTML-editor.
I use the first way, because my theme will be modified more and more (timeline missing, bugs in tags/categories, different header style) and I think that this solution is better from a technical perspective: routes should be treated before a database lookup for URL-rewrites in the koken engine.

The base version of the extension can be downloaded here: koken_contact_form.zip

The files does not include any required fonts due to copyright reasons. Ask your hoster what fonts are available or use open source fonts. The base image ( captcha.png) for the CAPTCHA can be modified to your taste. Additionally you have to adjust the paths in the scripts and templates to match your installation. The source code is commented so you should be able to do this and you can also change the wording and language of validation strings and template(s).
My complete stylesheet or configuration ( info.json) is also not included in the download above. But here are two snippets with required changes...

info.json:

"templates": { "contact": { "name": "contact", "description": "Displays a contact form", "source": "page" } }, "routes": { "/contact": { "template": "contact", "navigation": { "label": "Contact", "in_primary": "true" } } },

Please make sure to use the "normal" double quotes inside a JSON-File for properties and strings; if you don't, it cannot be parsed by koken!

settings.css.lens:

p#headline.error { color: #f00; } p#headline.success { color: #0f0; } #submitButton { font-size: 0.95em; background-color: #000; color: #fff; border: 0; height: 2em; } #submitButton:hover { background-color: #666; }

Legal note:
I'm not responsible for problems my code may cause in any koken installation.


Additional notes (added 2014-09-21):

Some comments showed gaps in my original explanations. So I provide additional help for the installation using the first integration method, because this is my preferred solution and most comments I received below and by e-mail (using my form) opted also for a modification of a koken theme...

My archive should be extracted and uploaded to your server. Depending on the choice of template, some files have to be copied to every theme, only the webmailer and captcha related files remain in the root of the koken installation.

I highlighted the new files for a concrete koken installation - I am running an own template based on the regale theme called 'jm_regale'. Just upload the highlighted files to your installation and do not forget to add custom fonts to the server file system and the file captcha.php (lines 42 - 46);

I did not include my fonts ( captcha.ttf and captcha.otf) due to copyright reasons. Change the reference 'c.otf' to match your font file (if you upload the font to your koken root, only the filename has to be supplied).

In order to access the contact template some information has to be added to each template's configuration ( info.json) file. My example is based on the default regale theme, so your info.json may differ in regard to already defined templates or routes.

  1. The first snippet ('contact' in the 'templates' node) should not be changed, as the node names references the files within the template folder.
  2. The second snippet adds the route, the form should be accessible from, so the '/contact' property can be named to suit your taste as well as the label node; only the template reference has to be retained.

The necessary CSS changes should be added to your theme's settings.css.lens file or the custom CSS code section in your koken admin section. I adopted the design from the article page of the original regale theme.

If you want to change the layout or design the file contact.php in the theme's include folder can be changed

Depending on your installation of koken (domain and possibly sub-path) you have to add the contact form's URL to the file webmailer.php on line 125 (in my example 'http://mackiol.net/contact/#'). The contact form's recipient and the e-mail's subject line can be changed in lines 106 and 107 of webmailer.php.

If you keep the contact form in the first level of navigation (domain.tld/contact_router_name) no changes to any internal paths should be necessary in the contact.php template.

Templating hints:

Relative links in templates are based on the templates route not on paths of the template files, so '../ref' in any theme include of the router 'domain.tld/router_name' will reference to 'ref' in the root of your koken installation.

If you modify any original template a koken theme update will revert your changes so make sure to backup your changed template or create a custom one yourself. If you copy an existing theme, remove the file koken.guid to prevent update attempts.