Thursday, November 28, 2013

Day 12: kiss my backend

The day of extensions:

Today I spent the first half of the day trying to make the mm_forum not suck, the front-end module suck less, and to extend the functionality of my self-built "Snowboard Teacher" extension. I used only online documentation, and now I am going to share my wisdom with you.

I discovered that with the front-end login extension ("felogin"), the extra sub-page "Login Status", which serves as a target for redirection after a successful login or failed login, did not only NOT work in a sensible way, but was also pretty much unecessary.

Clicking on the "Members Only" page and selecting the "List" module, you can click on the page content for the login form. There, under the "Plugin" tab, there is a subtab for messages. Why create extra pages and redirect to these pages after successful login, failed login, logout, etc., when you can just click on the "Messages" subtab of "Plugin" and write these messages in text? There are "Header" and "Text" fields for "Welcome", "Login Success", "Login Error", "Status", "Logout" and even "Forgot Password".

I entered values for these, deleted the "Login Status" subpage, and tried out the login anew. It works intuitively, unlike the previous workflow of redirecting to pages after these different events. Additionally, you can set up the same thing for the English-language version of the same page-content. Everything is in ONE place, on ONE page, and flows very logically. For this particular use-case, I can highly recommend using the "Messages" subtab of the Login plugin rather than setting up seperate pages for redirect.

I then edited the Login Form template, "felogin_template.html" in "user_uploads", so that it was a bit more orderly and not so... ugly. You can set which template is going to be used for the login formular from the "List" module by clicking on the page content, then the tab "Plugin", and then the subtab "General". Something I found out while editing the template file is that if you edit it directly, after saving, you need to re-select this template from the "General" tab before clearing the cache and refreshing the frontend. Whyever.

The second thing I worked on today was the missing moderator section of the mm_forum. The online documentation for it under isn't that great, but it gave me enough insight to figure out how to set this up. Namely, you need to set up either another page (as a sub-page of "Forum") or set a new content area in the "Forum" page itself.

In the content area, select as content type "Plugin". Then as plugin type, select "mm_forum::Forum". After this selection, you will be presented with a dropdown of what to display on this page. Pick "List post queue". If you've done this on the same page as the forum, as I did, and log on as a user with moderation rights (and the forum is set up to have comments moderated before they are published), you will now see an administrative area for moderators ABOVE the forum. This is kind of busy-looking, so I think that I will set up the admin area on its own page instead.

Something else I discovered is that the reason no users showed up in the "mm_forum" module in the "Install" / "User Administration" area is that users will only do so if they are marked as "ForumUser". It doesn't matter if they are also marked as "ForumMod" or "ForumAdmin"! Once you do this, they appear in the "User Administration" area of the forum and can be edited from there.

mm_forum offers several functionalities that apparently must all be set up in a similar way to what I just described: as a mm_forum plugin content area, either on its own site (a sub-site of "Forum"), or on the "Forum" site itself. I'm going to use this knowledge to try and set up all the functionalities as a way to practice.

The final thing I did (with the first half of the day) was to try to extend my self-made "Snowboard teacher" extension. I added a new property to the teacher model in the extension builder, changed the template for listing them out, and took a while to figure out that after saving all these changes, I needed to deactivate (not remove!) and reactivate the extenstion with the "Extension Manager".

Four hours later... 

Four insanity-inducing hours of trying to set up a user registration form for the mm_forum. Here's what I did right and wrong. So, so wrong:

First: you need to set up a new page for forum user registration. Hide it from the menu. Add the content type "Plugin" and then under the "Plugin" tab, give it a "mm_forum" type plugin. After saving this, you can choose what's to be shown on the page: "mm_forum::User Registration". That was the easy part. The hard part is remembering to set up an extension template for this page, "edit the whole template", and in the "includes" tab, to include the following styles in the following order (otherwise, you will get only a page with a title and nothing else):

mm_forum Javascript: Prototyp
mm_forum Stylesheets
Page browser

I had a huge problem with how to set up a link to the forum user registration from the forum logon page (for non-logged in users). I looked around the backend for a LONG time, thinking (illogically?) that this could be configured within the mm_forum module, just as it's possible to configure whether the "forgot password" and "change password" links show up in the forum login form. No such luck.

Another problem is that in the root template, thanks to the tutorial, I've overwritten the default functionality of page headers so that they can no longer display links through their configuration mask. I finally decided just to add a new type of page content underneath the forum login formular: plain old text. In the Rich Text Editor, I simply wrote "Register for the forum", highlighted it, and made it a link to the forum user registration page within the editor itself.

Problem solved. Next problem: in the forum user registration form, there's a whole bunch of labels, but no Captcha (which I specified should be shown), and NO TEXT FIELDS next to the labels! I searched for hours why this could be and eventually just went into the template and deleted 2 marks surrounding the input fields - ###DEFUSERFIELDS###. After deleting these marks, the input fields showed up and I could fill out the form and submit it. It takes forever to validate, but at least it works. I can't believe I spent the whole second half of the day on this, but now I know the backend pretty damn well, at least.

Quick update: the validation email that arrives after having filled out the forum user registration form has only the following text:

vielen Dank für deine Anmeldung auf

Wow - GREAT. Looks like I'll be working on this on Monday, too.

Kiss my backend, Typo3.

Wednesday, November 27, 2013

Day 11: Extensions galore

Today I worked throught the setup and configuration of two popular Typo3 extensions: Piwik, for statistical analysis of website traffic, and mm_forum, for integrating user forums within the Typo3 project site. I also created my own, first (very simple) extension - a frontend plugin for displaying data from a database - with Extension Builder and Fluid.

Piwik is pretty trivial to install. In the Extension Manager under "Get Extensions", type in "Piwik" and install both "piwik" and "piwikintegration". After restarting the backend, you'll see under "Web" a new module: "Pi (Statistics)". In order to use it, however, you have to do a little configuration. Don't worry - this isn't as bad as the News module.

Click on the root page and on "Template" under "Web". Select "edit the whole template" and then in the tab "Includes", from the box "Available Items", select "Piwik Integration (piwikintegration)" and save. Now you can click on the new "Pi (Statistics)" module and click on any page to see a whole BUNCH of possible data on who, how, when, from where, and why (just kidding) users have visited that page. At first it should be empty - you have to log off as the backend administrator and then surf around as some anonymous user on the front-end in order to generate some data.

The available information is pretty overwhelming: each top-level tab (Dashboard, Visitors, Actions, Reference, Goals) has a plethora of sub-tabs. The "Dashboard" is also pretty busy, with a Wordpress style collection of "widgets" that you can organise yourself.

There are two things I'd like to explore further in Piwik that go beyond the scope of the tutorial: which metrics are valuable, and how? Also, how could you simulate high traffic in order to explore meaningful theses about website visits?

The second extension I got to play around with today, mm_forum, did not offer me the relative satisfaction I had after installing Piwik. After finishing this part of the tutorial, I was left with a lot of WTF moments about the functionality and design. But first things first:

To prepare for mm_forum, you have to create a new system folder somewhere in the page-tree - let's call it "ForumData". If you need a refresher on how to do that, here it is: right-click on the "Typo3" logo at the top of the page-tree. Select "new" from the context menu and then, in the right-hand side mask, select the location where this new folder should appear. The location of the "ForumData" folder is unimportant, so I put it at the same level as the "User" folder. The mask that appears now is where you can enter the title of the new folder. Save.

Now, click on the "User" folder we created a few days ago. Click under "Web" on the "List" module. Here you should create three new user groups specifically for the forum: "ForumAdmin", "ForumUser", and "ForumMod". Save.

Finally, click on the "mm_forum" module under "Web" in order to configure it. The "assistant" will ask you to choose a data storage page - choose the "ForumData" folder - and a User storage page - choose our "User" folder. Now you'll be prompted to select a user group for "default" and "admin": choose "ForumUser" and "ForumAdmin", respectively. You'll be presented with yet another page with lots of tabs and a dropdown in the upper-right hand corner. In the dropdown are choices like "Install" (that's where we are right now), "Board Administration", "User Administration", "Templates", "Tools", "Import data", "Statistics", and "User ranks".

In the "Install" mask we can setup the configuration for user, forum, private messaging, search, file-paths, contact, and cron jobs. The "Board Administration" mask is where we set up forum categories and their message boards. Both category and message board can be configured separately, but a message board will inherit the configuration from its category by default.

For both category and message board you can enter a title, the order in which entries should appear, read-access, write-access and moderation-access. For these latter three, you select user groups - this is where the "ForumMod" user group comes into play. And does not quite work or rather, works so well, that no forum comments can *ever* be approved. Even by moderators.

In order for the forum to show up in your site, you now need to create a sub-page, "Forum", under the "Members Only" (login-form protected) page. Click on the "Page" module under "Web" in order to display the content area. Add a new content area to the "main" section and in the tabs that show up where you can pick out what type of content it should be, click on the "Plugin" tab. Select "mm_forum::Forum".

Click again on "Page" under "Web" and click on "Forum" in the page-tree. Click on the "edit" symbol for the new content. Under the "Plugin" tab, there's a section called "Plugin Options" with a tab (why another tab?) called "Forum Options" with a selection of "What to display". Select "Message Board" and save. To change the styles, click on the "Template" module under "Web", click on the "Includes" tab, and then from "Available Items" select "mm_forum Javascript Prototype", "mm_forum", "mm_forum Stylesheets" and "Page Browser" - in that order. Save.

NOW you will see on the front-end any forums you may have set up in the "mm_forum" module under "Board Administration". Playing around with the forum made a few things clear to me immediately:

I can't figure out how, if comment moderation is activated, the moderater is supposed to approve comments. I set up a user called "mod", categorised them under the "ForumMod" group, and set them up with a real email address (mine). In the "mm_forum" module under "Board Administration" I set up one of the categories to have "Moderation Access" for the "ForumMod" user group. In the front-end, when I'm logged on as a normal user, I can make forum entries and am informed that the comment is awaiting activation by moderation.

The thing is, though, that in NONE of the many places where I might, as moderator, theoretically be able to approve comments, is there a list of comments to approve. Notifications are not sent to the moderator's email (mine) either. Neither in the "mm_forum" module, the page module nor the list module for "Forum" is this a possiblity. Logged on to the front end as moderator also shows nothing different from what the normal user sees.

Another problem is that the styles for the forum suck. Trying to access the forum without having logged in does not prompt you to log in. The information provided by "Praxiswissenschaft" that the mm_forum documentation is available for download under the Extension Manager is not really true, so I'm going to have to devise a plan to fix all the stuff that's bugging me about my new forum.

But not today: the next chapter of "Praxiswissenschaft" is allll about creating your own extensions, and that's what I'm really excited about! I'll spend the rest of the day on that - tomorrow on optimising the forum - and writing about creating your own extensions with Extbase and Fluid, which is pretty cool.

Tuesday, November 26, 2013

Day 10: News with the tt_news extension, more language problems

Today we're going to experience the magic of tt_news: the Typo3 extension for adding a news module to your site with minimal fuss.

Start unter "Admin Tools" / "Extension Manager". From the dropdown on the upper left-hand side, pick "Get Extensions". Type in the search field "tt_news" and click on "Go". There are a lot of extentions with this as part of their name. At the top of the list, however, is the right extension - you can verify this by looking at the column called "key". The "key" of an extension is that extensions unique name.

If you click on the little down-pointing arrow next to "tt_news", you'll get a loooong list of all the versions of tt_news, ever, and their status. Perhaps you will be as astonished as I was to see that the latest "stable" version is from early 2005: "News 2.0.6". The latest of many "beta" versions is version 3.5.1, from late 2013. I picked this one to "import and install". (To import and install, click on the left-pointing arrow under the column "Actions").

After downloading the extension, log off the backend and then log back on. You'll see now on the left-hand side under the "Web" category, a new module "News Admin". Additionally, under "Admin Tools" / "Extension Manager" / "Manage Extensions", you'll see that our list of available extensions has been supplemented with the "News" module. If you click on it, you can configure it. In the tutorial for "Praxiswissenschaft Typo3", however, the default configurations are used.

Now comes the hard fun part. Setting up an actual news site in Typo3 requires a lot of really specific steps. However, it only takes about 10 minutes, and compared to programming a news module from scratch (which I've actually had to do way too many times), the Typo3 news module is actually totally awesome. Here are the steps for setting up a site to display a list of news headers with a short excerpt of text, with a link to another site where one can read the entire article. On the page with the entire article, there's a link to go back to the list of all news.

So, pick the page from the page-tree where we want the news list. I'm going to call mine "Current". Click on the "Web" / "Page" icon on the left-hand side. You'll see the template where you can add new content records to the page. In the "main" section, click on the icon for "add a new record". Now under the tab "Plugins", pick "General Plugin". The page will ask you if you want to reload - yeah, sure, why not.

Now under the tab called "General" you can give the news-page a header. I used "Today". In the tab "Plugin", there's a dropdown labeled "Selected Plugin". Pick "News" out of this dropdown. Save! The "Plugin" tab that's now available has several sub-tabs: "General Settings", "Templates", "Category Settings", and "Other Settings". Under "General Settings" there's a dropdown labeled "What to display". Pick "Standard list view (LIST)".

Now, on the left-hand side under "Web", click on the "List" module. Click on the page "Actual" in the page tree. At the upper left-hand side of the mask, click on the plus, "add a new record". A tree-type list appears where you can pick what kind of content you want to add. Under the header "News", you can pick either "news" or "news category". Pick "news".

This is where can enter actual news content: title, text, etc. Make sure to unclick the checkbox "hide" so that our content will be visible. Save your changes.

Now we need to make a static template for the content. Unter "Web", click on "Template" and the root page. Click on "edit whole template record". You'll see some tabs: pick the tab called "Includes". On the lower right-hand side there's an area called "Available Items" where you can make selections. Select "News Settings (tt_news)" and save.

If you look at the frontend now, you'll just see an error (or in my case, nothing). That's because you still have to go through about 8 more steps to get this thing up and running. In order to see the whole news article that we would theoretically pick from the as-yet not existing news list, we need to create a sub-page under the page called "Actual". Right-click on the "Actual" page and select "Page-actions" -> "add".

In the mask, check "hide in menu", pick from the "Type" dropdpown the type "Standard", and save. Click on "Web" / "Page" now and in the content template in the main content area, click on the plus icon to "add a new record".  Click on the "Plugins" tab. Select the "News" plugin. From the mask that now appears, pick the "Plugin" tab (again - I know that it's gotten confusing) and then the tab "General Settings". There in the dropdown "What to display" pick "Detail view - SINGLE". Remeber to save, otherwise you'll have to start all over again.

Now click on "Actual" again, and "Web" / "Page". In the main content area, click on the edit symbol (the pencil) for the news content item. Click the "Plugin" Tab and then on the "Other Settings" tab. Click on the "folder" symbol next to the label called "PageId for single news display" in order to pick the page we just created for the single-news item. Save!

Think we're done yet?  WRONG. Do the whole song-and-dance for the single-news item subpage under "Actual". For whatever reason, you have to specify in the single-news item page under "PageId for single news display" that the page it should refer to is itself (eye-roll). Additionally, click on the folder symbol near the label "PageId to return to" in order to pick the parent page, "Actual" in oder to generate a useful link that will allow us to return from the single-news item detail to the news list.

NOW we have a usable news module for our frontend whose content can now be easily maintained by editors who lack the insane desire to mess around with the backend. I know that the setup seems... awkward, but it would have taken longer (and been more tedious) to program the same thing from scratch. Typo3 takes care of the things we've done a hundred times before so that we have more time to program new and challenging functionality, refactor and explore! The day's only half done and, again, I've learned something quite useful.

It was really bugging me that the images for the "trailer" had disappeared on introduction of an English-language version of all pages. The disappearance of the static-right hand content (also only from the English-language pages) was bugging me too, so after a few minutes of googling, I found 2 useless suggestions and 1 good one. I'll spare you the former but share with you the secret of my success.

Namely, the root (and other helper-pages like "static-right hand") from which subpages are supposed to inherit, need to have an English-language version too. Copy the content of helper-pages, if there is any, and as far as inherited images go, you need to click on the "Resources" tab of the English-version of the page.

There you'll see a pale version of the image that appears under the "Resources" tab of the original-language version of the page. To the right of this image there's a barely discernable icon called "localize". Click on this, wait a minute, clear the cache and refresh the front-page. Voila... now the site behaves as it should.

This seems to be more of a feature than a bug, but it would have been nice for the "Praxiswissen Typo3" tutorial - WHICH USES A MULTI-LANGUAGE SITE AS ITS EXAMPLE - to have mentioned this tiny little detail.

Next up: configure an indexed-search without being deterred by the trauma left over from setting up the "simple" search form!

Monday, November 25, 2013

Day 9: Multilinguality in Typo3 sites (stupid flags...)

Day 9, chapter 9: let's dive right in, shall we?

Today I'm working through the rest of chapter 9 of "Praxiswissen Typo3", which involves providing various text-elements of the project site in both English and German. In order to do this, all "override" properties (which can be seen in the TypoScript Object Browser) need to be removed, and all properties that have access to the method "lang" need to be so set: "".

Some properties, such as "badMess" (Javascript error message) and "wrap", do not have access to the "lang" method, so need to be set explicitly in a conditional after all "page" properties have been set. Here is how the search form looks after transformation: {
#js error if user does not fill out required field (implemented below in dataArray.10)
  badMess = Bitte füllen Sie alle erforderlichen Felder aus.

#text input: required, name ="sword", size=15, maxsize=30, label = "Ihre Suche:"
  dataArray.10 {
    type = *sword=input, 15, 30

#previously: value.override = Suchwort = Suchwort

#previously: label.override = Ihre Suche: = Ihre Suche:


#dynamically generated graphical submit button
  image = IMAGE
  image.file = GIFBUILDER
  image.file {
    XY = [10.w]+10,20
    backColor = #76001B
    10 = TEXT
    10 {
#previously: text = Suche = Suche

      fontFile = fileadmin/fonts/Ubuntu-C.ttf
      fontColor = white
      fontSize = 14
      #niceText = 1
      offset = 5,15

We have to explicitly set conditionals for the properties "badMess" (and "wrap"). This block of code comes after all page properties have been set:

page {

#if the GP (GET Parameter) is 1 (english), then set the system language id to 1,
#the configuration language to English,
#the local to G.B.

[globalVar = GP:L=1]
  config.sys_language_uid = 1
  config.language = en
  config.locale_all = gb_UK

#english translations for error message and wrap go here

#for our search field overhead on the right-hand side
  page.10.marks.SUCHE.badMess = Please fill in the following fields:
  page.10.marks.DATUM.10.wrap = |, today is the 

#for our search form in a page = Please fill in the following fields: = Search

Is this all making sense? I find it logical TODAY, but it's all built on 5 days of non-stop intensive TypoScript-learning.

The next step is to replace the language menu, whose current values are links of the text "English" and "German", with two small images of flags (of England and Germany, of course). The mark for the language menu, "###SPRACHE###", needs to be initialised as an HMENU object whose first and only level is graphical (i.e., GMENU).

Note here that there is yet another type of menu defined by "special": we've seen "special = directory" for the classical menu and "special = rootline" for an inline menu, but now we have "special = language", for a language dependent menu.

#language menu    
      SPRACHE {
        special = language
        special.value = 0,1
#normal status of first (and only) level of the language menu - it's graphical        
        1 = GMENU
        1.NO {
          XY = [10.w]+2, [10.h]+2
          backColor = white

#our language menu is made up of two images:
#the German and the English flag for German and English (duh)        
          10 = IMAGE
          10.file = fileadmin/flags/de.gif || fileadmin/flags/gb.gif
          10.offset = 2,2
#active status, language menu      
        1.ACT = 1
#take properties from the normal status of the language menu
        1.ACT < .1.NO

#override the effect so that the active (currently selected) language shows is greyed out
        1.ACT.20 = EFFECT
        1.ACT.20.value = gray | gamma=1.5

This sort of worked. On the homepage, the correct flag was greyed out depending on what language I had selected. On all other pages, however, only when "German" was selected was a flag greyed out at all (it was the correct one). The flag for "English" stayed bright an colorful on all pages, except the homepage, after being selected. WTF?

I decided to experiment and to create English versions for the other pages - at least the menu title should be translated, by my logic. This is done by clicking on "Page" under the "Web" module on the left-hand side. On the upper left-hand side of the mask that appears, there is a drop-down with the choices "Columns", "Languages" and "Quick-edit". Select "Languages". Another dropdown labelled "make a new translation of this page" allows you to select one of the languages that has been set for the site-root (represented in the page-tree with the Typo3 icon). Select "English".

You are now shown a page with the title "Create new Alternative Page Language". Enter a title in the textfield "Page Title" (obviously). Make sure that the visibility is enabled under the tab "Access" and then save your changes.

NOW, when you click on the page in the frontend of which you just created an English "translation", and pick the English flag icon - IT STAYS GREY! Logically, in order for the selected page to represent the selected language, you have to actually have a translation of that page in the selected language.

One problem with this is that now the header images are gone. (Cries). Do I have to set those up for the English-translation pages too? When I switch the language via flag to "German", yep... the images are still there. I think I'm going to work on setting up user-protected areas now: pages whose content is protected with a login form and a list of permitted users. Also: dynamically-generated print-versions of every page, with just a few lines of TypoScript in the root template.

Four hours later...

Stay tuned for tomorrow's Typo3 excitement, as I attempt to install the tt_news plugin, whose last stable, non-beta version was uploaded in 2005!

Thursday, November 21, 2013

Day 8: the search-form from hell, static-dynamic content, a customised backend

Part I: the Search-Form from Hell

I spent the first half of the day today trying to figure out why my search-form wouldn't work. Most of that time was spent wrong because I was searching for "indexed search function", whereas the functionality referred to in "Praxiswissenschaft" happens to be the normal, non-indexed one.  In the end, I did 3 things that possibly caused the form to eventually work:

1) I deinstalled the extension "indexed_search" that I had installed yesterday in the belief that it was needed.

2) in the file typo3_src/typo3/sysext/frontend/Classes/ContentObject/ContentObjectRenderer.php I changed line 732 of code from this:

$content .= $hookObj->cObjGetSingleExt($name, $conf, $TSkey, $this);

to this:

$content .= $hookObj->cObjGetSingleExt($name, (array) $conf, $TSkey, $this);

This change was based on a tip that I found via google that seems to address the error message I kept getting: that a second argument was expecting an array and receiving something else.

This change caused the page to go from displaying an exception error to displaying the page with the marks for the searchform, "###SUCHE###", instead of the actual search form itself.

3) Finally, the tip that Meyer's book gives, and also to be found in several pages via google, is to deinstall the "form" extension. When I did that yesterday, in place of an exception I got an internal server error instead, which is actually worse. Today was the same thing. Only after lunch, by following steps 1 and 2 again, and then (again) deinstalling the "form" extension, did the search form finally work.

Logically, this should have happened yesterday as I had followed steps one and two, before installing the indexed search. The ways of Typo3 are shrouded in mystery!

Now I am free to continue the "content" chapter of "Praxiswissenschaft".

I found out a way to supplement the root template TypoScript without literally typing it in the text area: under "Template" for the root page, select "TypoScript object browser" instead of "Info/Modify". Click on the TypoScript object you'd like to modify and a form comes up called "Edit object/property value". Enter the object property in the text field and click up "update". In the root template, the correct code for this property attribution can now to be seen. 

Using this method to change properties is a good way to avoid the typos and mistakes of typing code in by hand; however, it does not have the benefit of code-organisation that can be attained by doing the same thing manually. Additionally, clearing and reseting values in this way makes a mess of the TypoScript in the template textarea, much like creating HTML markup with a WYSIWYG editor. I'm going to decide for clean code and write my TypoScript by hand - I need the practice, anyway.

Part II: Static-Dynamic Content

In order to create a content area that appears on every page (for example, news items on the right-hand side of each page) whose content is dynamic, a mark within the template is necessary, but does not alone suffice. It's also necessary to, once again, set up a helper-page, just below the root page in the site structure. This new helper pages's properties include being of type "shortcut", redirecting to the homepage if called directly in the browser, having enabled visibility, and yet be hidden to the menu. This last property can be achieved by selecting the "Access" tab within the "Page" section and then checking the box "In Menus - hide". Finally, in order to bind this helper page's content into the template that is used by all pages, the following code needs to be implemented:

#make "RECHTS" (right-hand side) marker a content object array
      RECHTS = COA

#read out the content of right-hand column of the current page into the RECHTS marker in all positions
      RECHTS.10 < styles.content.getRight
      RECHTS.20 < styles.content.getRight

#the content of the right-hand-side column should, however, only be read from a list of pages whose page IDs are explicitly set below = 17

It's additionally suggested that in order to prevent the contents of this page from being cached, which would prevent new content from appearing without first manually emptying the cache, the object type COA_INT instead of COA can be used. 

Part III: customising your backend (ha!)

In order to create a customized backend layout to make content management for editors easier, click on the "List" module under "Web", and then click on the "root" page. In the upper left-hand corner to the new window, click "create new record". A list of possible types appears; select under "System records" the type "Backend layout". There, enter a name for the customised template and then click on the image next to the text field under the label "configure". This will open up a new window where columns and rows for a table can be defined: each cell of this table needs a name and a unique column number.

After saving this configuration in the new window AND in the opening window (otherwise, the work is lost - I had to find this out on my own), click on the root page and select "edit" from the context menu. Under the tab "Appearance", it's now possible to select the new template as "Backend Layout (this page only)" and "Backend Layout (subpages of this page)". Remeber to save! Clicking on the "Page" module under "Web" and selecting the root page will now show the new template for entering content, instead of the the default one. In this way, it's possible to customise content-entry forms and make them more user-friendly for editors.


Today I got through one chapter of "Praxiswissen", with one major problem (the non-functionting, error-causing search form) and two minor ones: getting the dynamic right-hand area of every page to show the same content (I had initially put the new right-hand content area in the homepage instead of in the root document) and not being able to FIND the area for adding a customised backend layout (the instructions in the book skipped the step of getting to the "System records" list of choices). I was able to solve them with a little experimentation and a lot of googling. 

The seas have calmed, wind and weather are good, routine has entered the daily course of being on board the Hackership and I am actually learning somthing practical.

The first two weeks are over, four to go. Will I have time to immerse myself in test-driven development with PHPUnit? Will I be able to figure out how to configure my Jenkins CI server to run these tests as jobs? I think I'm going to have to invest in more resources (i.e. e-books). Without "Praxiswissen" my ship would have, by now, floundered on the rocks of bad documentation with no help in sight. 

Who's sick of the seagoing metaphores already? 
Too bad!

Wednesday, November 20, 2013

Day 7: ImageMagick, Navigation, lots and lots of TypoScript

Day 7: smooth sailing with "Praxiswissen Typo3"

It was really bugging me today that the dynamic graphical part of the project wasn't working. I rechecked the code and found, first of all, that some of my code was nested falsely.  After fixing that, it still didn't work, so I read through the chapter again and figured that my problems must be with ImageMagick: namely, the mask underneath the image, "nicetext", and image inheritance from the root page as defined by TypoScript IMAGE object properties were not working.

I checked out which version of ImageMagick is installed on my computer by typing on the command line:

identify -version

According to the output, I have ImageMagick version 6.7.7-10.  After some more googling (for "ImageMagick nicetext") I found the perfect solution. Pretty much, ImageMagick will only function on the root server with a certain Typo3 configuration:

[GFX][gdlib] = 1
[GFX][gdlib_png] = 1
[GFX][im] = 1
[GFX][im_version_5] = im6
[GFX][im_negate_mask] = 1
[GFX][im_imvMaskState] = 1
[GFX][im_no_effects] = 1
[GFX][im_v5effects] = 0
[GFX][im_mask_temp_ext_gif] = 1

Especially important is the configuration "[GFX][gdlib_png] = 1". I called up the Typo3 install tool in the browser, logged on, and under "All Configuration" searched for these values to see how they were set. Lo and behold, in my configuration, [GFX][gdlib_png] was set to 0.  I changed this and refreshed my Typo3 project and voilá - it is now working as it should.

On to creating the navigation menus, dynamically of course!

Something I've discovered today is that, in order for the menus to be shown, the "helper sites" I created yesterday need to be set to VISIBLE, not, as I interpreted from the tutorial, have the visibility deactivated.

In order to create my first menu - the single-layer, overhead text menu - I had to 1) specify an object of type HMENU, 2) set the properties of this new menu object so that it is a "directory" or classical menu, 3) set the root of this "directory" to the page ID of the root page and 4) specify that the first (and only) layer of the menu is a text menu with "normal" state activated.  The TypoScript code to do this is as follows, and is inserted within the "marks" section of the TypoScript:

marks {

#upper text-menu
#directory, or classic menu
    special = directory
#page-id of the menu root      
    special.value = 2

#this menu has only one level, which is a text-menu, with normal (NO) state activated    
    1 = TMENU
    1 {
      NO = 1
      NO.linkWrap = |

The pipe symbol | stands for dynamic content that can be, if desired, "wrapped" within html code, such as bold tags, or an empty space. To seperate individual links with an empty space, write in the place of "NO.linkWrap = |" the following line of code:

NO.linkWrap = &nbsp;|

For bolded content, write:

NO.linkWrap = <b>|</b>

In order, however, to use a stylesheet on the generated menu links, use the property "ATagParams" on the "normal" property of the textmenu, for example:

NO.ATagParams = class="left_white"

Building up the left-hand side graphical menu requires a bit more code in order to dynamically generate the text as images and to have a normal, rollover, and active state for each link. My TypoScript works for the normal and active states of the generated links, but rolling over the links with the mouse in the browser has no effect. When I look at the HTML source code, I see that on "onMouseover", the same image is being called as on "onMouseout". After a lot of googling, I'm not any further. Testing in Firefox gives the same results, so it's not necessarily related to the browser.

Here's the code for generating a graphical menu. It differs only slightly from the code for a text menu, in that the object GMENU (graphical menu) is used in place of TMENU (text menu) and that within the "1" section, there are also definitions for the rollover (RO) and active (ACT) states of the links.  This menu, too, is placed within the "marks" code section.

marks {
    special = directory
    special.value = 3  
    1 = GMENU  
    1 {
#describe normal state        
      NO = 1
#define rollover (RO) state
#copy normal (NO) properties
      RO < .NO
#redfine the properties for rollover only where they differ from the normal (NO)

#define active (ACT) state
      ACT < .RO

On to developing a second level for the graphical navigation. This requires the setting of a second GMENU and its properties, along with the descriptions for its normal (NO), rollover (RO) and active (ACT) states. It's possible to do this in TypoScript without redundant typing with the following line of code

2 < .1

which means: "2", or the second level, is also a GMENU object whose properties are exactly the same as the "1" GMENU object.  We are then free to overwrite only the properties that differ from those of GMENU object "1":

2.NO {
  XY = 230,25
#white background
  5 = BOX
  5 {
    color = white
    dimensions = 10,0,200,25
#change text styles        
   10 {
#set text styles (case) back to nothing >
     fontSize = 12
     offset = 20,16
#rollover and active state
2.RO < .2.NO
2.RO.10.fontColor = #a90329
#active (ACT) state for level two in the same as the rollover (RO) state      
2.ACT < .2.RO
For setting up a breadcrumb trail, the process is similar, since it is also a type of menu. In order to differentiate between the breadcrumb-style and classic-style of menus, however, we need to set the "special" property to "rootline" instead of "directory". Here's the basic code which, you can see, is similar to the syntax for the overhead text-menu:

  special = rootline
  1 = TMENU
  1 {
    NO = 1

Blend the VISIBLE helper-pages out of the breadcrumb trail with a line of TypoScript which specifies from which level the page navigation should begin and where it should end:

special.range = 2|-1

Start at level 2, since the root helper page is at level 0 and the two helper pages for template inheritance can be found at level 1. "-1" ("forever") indicates that all remaining levels can be shown.

Changing the object type of "KLICKPFAD" from HMENU to COA (content object array) makes it additionally possible to set up a sequential list of multiple object types (like TEXT, IMAGE and, yes, HMENU) and their properties, instead of being limited to only the properties assignable to HMENU. This lends an enormous flexibility to scripting the display of a Typo3 site. Here's an example of that.

#create breadcrumb menu as content object array

#in first position, we want to see some text
  10 = TEXT
  10.value = You are here:&nbsp;
#in second position, we want a text menu
  20 = HMENU
  20 {
    special = rootline
    special.range = 2|-1
    1 = TMENU
    1 {
      NO = 1

These blog entries are getting longer (and more professional from a programming standpoint. Less so, from a literary one). I still have a few hours to go on with the tutorial, but I will continue with that tomorrow: chapter 8 of @Robert Meyer's "Praxiswissen Typo3" - "Content".

Tuesday, November 19, 2013

Day 6: like a beacon of light through the gloom

Day 6: working and getting things done with "Praxiswissen Typo3"

Feeling much more enthusiastic today, as last night I studied two chapters of @Robert Meyer's "Praxiswissen Typo3 Version 6.0": chapter 3 "Das Backend kennenlernen" and chapter 4 "Das Praxisbeispiel vorbereiten".  I got through about half of the fifth chapter, "TypoScript in der Praxis" before going to sleep.

Translation: @Robert Meyer's "Typo3 in practice" has been like a beacon of light through the gloom for me.  "Getting familiar with the backend" was review, but "preparing the practical project" once again gave me hope that I will soon be programming something useful. Namely he describes, in an acutal step-by-step manner, how to set up a Typo3 website for a fictional snowboarding school with the following features:

  • Layout in HTML and CSS, with dynamic elements written in TypoScript
  • Two dynamically-generated menus: one single-level text menu overhead and one double-level graphical menu on the left-hand side
  • A dynamically-generated grafical trailer, based on the site currently being browsed
  • A dynamically-generated information area, based on current site, with last 3 most current news items
  • Dynamically-generated news-items
  • A search function with the ability to search PDF and Word documents available through the site
  • A dynamically-generated sitemap
  • Bilinguality: each page of the site should be available in both English and German versions
  • Print-versions of every page
  • A breadcrumb-type display from which the user can always infer where they currently are within the site structure
  • Time-dependent greeting ("Good Morning", "Good Afternoon" or "Good Evening")
  • A protected area for authenticated users
  • A user-friendly backend interface for site-editors
  • Later - replacement of HTML templates with templates created by TemplaVoila

This practical project covers the basics of most Typo3 sites and gives me a concrete structure around which I can organise my learning. I'm so excited!

First steps: downloading and installing the dummy-site and source from Typo3, as well as configuring, was incredibly easy after the hellish first-run with the introductory package. After logging in to the new backend, under "File" - "Filelist", I then uploaded the directories "css", "fonts" and "css" under "fileadmin", as instructed by the tutorial.  The necessary image and css-files were available for download from the site for the book. Instead of downloading the html template with TypoScript already written, I downloaded only the static html template and made the changes demonstrated in the tutorial by hand, in order to get a feel for TypoScript "marks" in template construction.

Now it's time to build the navigation structure. In order to make a menu-tree that is as flexible as possible (for editors to supplement with additional pages), it's necessary to create a top-level menu item as a "helper page" for each menu that should appear in the website. In this case, we have two menus - one menu overhead, and one on the left-hand side. These top-level "helper pages" will not be seen by the user; rather, they serve as constructs on which to hang things (like templates, or other properties), which will be then be inherited by all sub-pages in the menu.

Because we want to avoid duplicating code, we will attach these two helper-pages not directly to the root page itself (to which templates can not be directly attached), but to a third helper site, directly attached to the root, from which both menu helper-pages will inherit. It is with this top helper page that we will associate the template to be inherited by each menu helper page and, in turn, their respective sub-pages.

Not only should these three helper-pages not be visible to the user, they should also not be callable to the user. In order to enable this, we need to set the types of these pages from "standard" to "shortcut". This ensures that, should the user call these pages explicitly (by ID), the user will be forwarded to a site that is OK to see: in this case, the homepage. I found out, though, that disabling the visibility of the root page will cause an error in the front end. I reverted it back to "visible", which allowed me to continue with the tutorial and also try out the various TypoScript examples provided by the author.

To elaborate on yesterday's puzzlement about WHERE to write TypoScript:

On the left-hand side navigation, click on "Template" under "WEB". Now click on a site you want to modify: in my case, this was the root document. A page will appear on the right-hand side with a dropdown at the top left corner of the page. From this dropdown, pick the selection "Info/Modify". Now click on the "pencil" symbol next to the word "Setup". A page will appear called "Template tools". Here, there is a textbox where you can write TypoScript! Here is a very simple example:

page = PAGE
page.10 = TEXT
page.10.value = Hello World!

After writing this TypoScript, you can save by clicking on the disk-symbol on top of the page, and then on the symbol of what looks like a page with an eye over it.

It's that simple. A real, step-by-step set of tasks that a Typo3 learner can go through, one by one.  Meyer's book even illustrates these instructions with screenshots, pretty much making the example idiot-proof.

Back to the project: the integration of the static html template (with TypoScript in certain areas) is also done via TypoScript, namely:

# Default PAGE object:
    page = PAGE
# Define output for typeNum=0, the default type.
page {
    page.config.doctype = html5

#Metatags = Robert Meyer, Martin Helmich
    meta.description = Hier steht eine Beschreibung
#integrate HTML Template
    10 = FILE
    10.file = fileadmin/vorlage.html

When I look at the generated html code for this page, I see correctly-formatted HTML tag for HTML 5 as well as meta-tags for "author" and "description". There is, however, a problem, and that is that the html template has its own html and body tags, which leads to a doubling of these tags in the source code, i.e., incorrect HTML.  Meyer goes on to explain how to solve this problem: namely, we need to work with "Teilbereiche", or... part-parts? Sub-parts, maybe. In order to do this, we need to insert a TEMPLATE object with TypoScript.  This TEMPLATE object receives a string from the FILE object and can use its property, "workOnSubpart", in order to extract the part within the html template that we have designated as being such. The code of this designation within the html template looks like this:

<!-- ###DOKUMENT### begin -->

<!-- ###DOKUMENT### end -->

with HTML code between these two designations.

Here's the TypoScript code we need to write in "Setup" text area (as described above):

# Default PAGE object:
page = PAGE
# Define output for typeNum=0, the default type.
page {
    page.config.doctype = html5

#Metatags = @Robert Meyer, @Martin Helmich
    meta.description = Hier steht eine Beschreibung
#integrate HTML Template
    10 = TEMPLATE
    10 {
        template = FILE
        template.file = fileadmin/vorlage.html
        workOnSubpart = DOKUMENT

With the TypoScript PAGE object function "includeCSS", you can include a stylesheet uploaded previously into fileadmin/css:

page {

#include css stylesheets
    includeCSS {
        screen = fileadmin/css/style.css
        screen.title = display = screen


which results in the inclusion of the following link in the HTML source-code:

<link rel="stylesheet" type="text/css" href="fileadmin/css/style.css?1384858913" media="screen" title="display">

It's only 3pm and I've accomplished more today up to this time than I did the entire day yesterday. @Robert Meyer has just become my new Typo3 hero.

Replacing the "marks" within the html template is as easy as calling the "marks" property (method, actually) within the PAGE element and setting its object type and its value:

page {
    10 {
        marks {
            DATUM = TEXT
            DATUM.value = 19. 11. 2013

The mark "DATUM" can be found in the HTML template within "div" tags as


Later, the hard-coded value for the date will be replaced with a dynamic value, made possible by the use of TypoScript functions. TypoScript functions can also be used for, among other things, reading values from fields in the database or getting POST and GET values. In order to do this, the property of the mark needs to be "data" instead of "value". The syntax for  creating a dynamic date in TypoScript shares similarities with the syntax for formatting a date with the PHP date() function:

page {
        marks {
            DATUM = TEXT
   = date:d.m.Y

For the rest of the day, I worked through chapter 6 - working with dynamic images in Typo3. Unfortunately, about 30% of the example code didn't work. Some of the hints for fixes for -older- versions of Typo3 worked for me, even though the version of Typo3 that I have is newer than that in the book. I know that there is little point in posting these questions on the Typo3 forum.  Instead, I'm going to move on to the next chapter tomorrow, about setting up dynamic navigation.

I accomplished so much more today and feel accordingly energetic and optimistic.  Thank you, @Robert Meyer!

Monday, November 18, 2013

Day 5: "Typoscript in 45 mintues", configuring Jenkins for Git

Typoscript in 45 minutes 3 hours

Today I throughly studied's "Typoscript in 45 minutes".  It took 3 hours to complete by cross-referencing my recently installed "Typo3 introductory package" site and also by reading the pages referenced in many of the links within the "tutorial".

I use the word "tutorial" in quotes, despite the fact that Typo3 considers that "this document is a Tutorial".  By their own definition -  "Tutorials are designed to be step-by-step instructions specifically created to walk a beginner through a particular task from beginning to end" - their introduction failed spectacularly at being a tutorial, as there was neither a task nor instructions, really, of any kind, much less of the "step-by-step" variety.  There were code samples, but no reference as to where/how such code could be written or applied within the structure of a Typo3 site, introductory package or otherwise. References to parts of the backend where one might be able see TypoScript in action were not done as screenshots, but as text descriptions, sometimes (I'm guessing) referencing versions of Typo3 older than the most current one, and not in the most clear English, unfortunately!

For instance, in order to take a look at some TypoScript code - some 2000 lines of it - that create the base-styles for a Typo3 template, a screenshot of how to get there would have been helpful, instead of the following text:

"In TYPO3, we have to be at the page, which has the TypoScript template with the TypoScript code in the Setup field. Then, in the module 'Template', we choose 'Template Analyzer' from the selector box on top of the window."

Or, for example, in the description of the "imgResource" function:

"The path 'uploads/media/' is the location of the files, which are inserted in the "files" section. You find it inside the page properties on the tab 'Resources'."

Try as I might, I was unable to find such a tab so that I could understand better what was actually meant by this sentence.

I've begun to google all over the place for further (non-official Typo3) clarification, and I'm reading E-books which I hope will be clearer on the subject. Maybe I'll even find some kind of "step-by-step" instructions about where I can write or apply some TypoScript myself.

The thing is, complaining about things doesn't change them - it just pisses people off. So in the spirit of "Be the change you want to see in the world", I have begun to make corrections to the English pages of the online Typo3 documentation that I have found ambiguous, unclear, difficult to understand or just too egregiously German-to-English. I intend to start including screenshots. I hope that in the process of doing so, I'll actually be learning more about the subject I'm trying to study. Searching out multiple other sources certainly helps.

Following a trail of stale breadcrumbs around the Typo3 site, I finally access the "Backend Programming Tutorial" and see that it was last updated in 2002. I find an non-offical Typo3 tutorial on how to develop a simple extension and it does NOT work as described (perhaps because it was written in 2007). The last Typo3-related thing I'm going to try today is to read the "TemplaVoila" extension documentation and hope that it does not lead me down another false path.

I WANT to love Typo3, I really do!  It's supposed to be powerful, flexible, and it's open source!  But the available documentation - disorganised, outdated, contradictory - is driving me crazy.

So... I was able to get the TemplaVoila wizard up and running, after a lot of runaround on forums where everyone is reporting the same error which has yet to be fixed... Typo3 - if I have to work with you any more today, I'm going to have to kill you. Time to move on to something else.

Configuring Jenkins for Git

For about an hour an a half. I need to decide on exactly what I'm going to do before I create a Git repository for it. Created new public and private keys for jenkins, moved them into my home .ssh directory.  Modified the owner and the permissions on this directory. Is it good practice to have more than one .ssh directory, because I'd like to have one in my lib/jenkins folder. The resources on setting this up are much better (more recent, simply described, and illustrated with screenshots) than the documentation for Typo3.  The problem is now, as stated at the beginning of the paragraph, a lack of a concrete project around wich I can build and configure all of the "best-practice" constructs I've been setting up for a week now.

Feeling a bit discouraged on the first day of the second week of Hackership, but I will do some reading tonight in my Typo3 books and start afresh tomorrow.

Thursday, November 14, 2013

Day 4: Jenkins continuous integration server, Selenium Grid, PHPUnit and Error 404

Day 4: Google Delight edition

The day is nearly half over and it's turning out to be a real bust.  Trying to struggle my way through the Typo3 / Jenkins / Selenium / PHPUnit tutorial with a lot of difficulty in - wait for it - setting up the environment.  Selenium Grid needs to be downloaded and I'm trying for the third time to do this; the rest of the day has been spent trying to find out how to basically configure Jenkins and start working with it, talking about this to some people who work with the thing, and the entire morning watching presentations that were interesting, but not helpful for what I'm trying to do. I'm getting anxious and discouraged about not having the environment ready yet so that I can start programming.

At last, the Selenium standalone jar file is finally downloaded and I can call it from the terminal:

As a hub with default arguments:
java -jar selenium-server-standalone-2.37.0.jar -role hub

As a node with default arguments:
java -jar selenium-server-standalone-2.37.0.jar -role node -hub http://localhost:4444/grid/register

You can view the status of the hub by opening a browser window and navigating to:

This is the first thing that worked today, and it helped me feel a lot better. I copied the code from the tutorial for a PHPUnit test for Selenium and called it from the command line as instructed:

phpunit selenium-tests.php

Fail! I mean, success, it ran!  But it ran and failed.  Which is OK!  It took a while to figure out what the error meant but after some help from one of the organisers and my friend Google, we found out that it had to do with the port, which needed to be changed in the code (and was not mentioned in the tutorial). In other words, in the unit test you need to not only set a variable to the browser name and host url (localhost), but also the port to which the Selenium Grid hub rePORTS (ha!) as listening to, namely 5555.

Success!  Running - and with success - my first PHPUnit test!  I refresh the Selenium Grid in Jenkins to see a long list of nodes and I'm on my way to completing the tutorial (albeit in a modified form - without virtual machines).  The organiser gave me a tip about how I could set up the virtual machines as instructed in the tutorial, in that instead of using "localhost" as the Jenkins host, I use the IP of my computer, which I can find from the command line by typing


I'm now ready to start configuring Jenkins to run the PHPUnit tests as a Job, rather from the command line.  Baby steps, baby steps.

Hours later...

OK, I finally found the solution to why my Typo3 introduction site wasn't working, but it wasn't thanks to any help (I got none) from the TYPO3 forum!  After much experimentation, googling, and a long pause to read about PHPUnit testing, configuring Jenkins, and continuous deployment, I found that in the apache2/sites_available/default file, the tags for the web docroot directory need to include "AllowOveride All", like so:

<Directory /var/www/>
Options Indexes FollowSymLinks MultiViews
AllowOverride All
Order allow,deny
allow from all

Now it works - but it's pretty slow. Maybe I'll go on over the the Typo3 forum and see if anyone feels like dealing with me, or if it's a question, once again, of endless googling.

In any case, I feel like the first week on board the Hackership was a success: I set up Typo3, a Jenkins continuous integration server, a Selenium Grid testing environment, and wrote my first PHPUnit tests. In four days I accomplished more than I have in months and months while I was working full time, taking online courses, and going to technology meetups galore.

It's time to demo!

Wednesday, November 13, 2013

Day 3: Still setting up the environment? Yep.

Today I'm putting the finishing touches on my Typo3 installation, but started the day off (pretty typically for a programmer) with the nasty surprise that none of the navigation links in my introduction package site work.  I can log into the backend though, and it is there that I see all of the pages that are supposed to exist.  I can even view them, and that's what gives me an idea about what could be wrong.

When called from the backend, the page addresses are simply, for example "mysite/index.php?id=1".   From the frontend, however, the links call pages with addresses such as "mysite/examples". Something must be wrong with mod_rewrite, or in some ._htaccess file, a rewrite... thingy is missing.  To the forums!

Re-opened up the install tool to see if it has anything to say about the matter.  From there I can see what corrections I still have to make, like updating the maximum file size and the maximum upload size in php.ini, and setting up a sendmail client on my computer and making sure I can send email with it:

sudo apt-get install sendmail
sudo sendmailconfig

It's that easy. All the red and yellow warnings are gone, the test email gets sent to my address, and everything is green.  A slight detour is made after the tool informs me that I need to install "Suhosin" which, I find out eventually after about 20 minutes of annoyance, is no longer being supported for the most current version of PHP and thus can be ignored.

Time to retackle the rerouting problem. After lunch.

During lunch: reading links I've found about how to set up a continuous integration environment, I came across some incredibly useful information concerning developing quality software with Typo3:

- Use a continuous integration platform (Jenkins)
- with continuous deployment tools
- set up PHPUnit on Jenkins as a template

- Use test-driven-development with
- automated unit testing (PHPUnit extension for Typo3)
- browser testing (Selenium extension for Typo3)

- Robust architecture - dB (?), URL Routing (trying to fix that)

- Performance tests during development - Apache jmeter

- Versioning with formatted comments (commits?) - Git

- Powerful IDE like Eclipse, PHPStorm

- Use a bug tracker (Redmine, Trac, ActivCollab, Git Issue)

- Extensions to help manage a complex Typo3 installation (caretaker, additional reports)

This is exciting, but my list of things to install continues to grow - is there no end in sight?  Will I be able to claim having a complete environment in which I can program by the end of the week?

Additionally, I found the most helpful blog, authored by @Torben Hansen. An entry from March 2013, namely, goes through a step-by-step setup of a Jenkins CI (continuous integration) server with Selenium grid and PHPUnit to perform automated testing in Typo3! Thank you, thank you, kind Sir, for making my day, and my life as a Typo3 developer, complete!

Installing Jenkins

wget -q -O - | sudo apt-key add -
sudo sh -c 'echo deb binary/ > /etc/apt/sources.list.d/jenkins.list'
sudo apt-get update
sudo apt-get install jenkins

fails hard, big-time, so time for another - by this time accustomed - detour to see what could possibly have gone wrong.

chown: Zugriff auf »/var/run/jenkins“ nicht möglich: Datei oder Verzeichnis nicht gefunden
dpkg: Fehler beim Bearbeiten von jenkins (--configure):

Translation: I can't find a folder called /var/run/jenkins, so suck it!

After some googling I find that this was a known problem just recently resolved - on Saturday. I follow the instructions for the workaround.

mkdir /var/run/jenkins
sudo apt-get update
suod apt-get install jenkins

Now I call Jenkins in the browser on port 8080 and voila - I have acquired a continuous integration server to call my very own!  In order to continue the tutorial, I have to install PHPUnit and a LOT of dependencies via PEAR.

Installing PHPUnit (and everything else)

Install PEAR itself via PHP Archive, install PHPUnit, DbUnit for unit testing databases, Selenium for testing the front-end, UnitStory for behavior-driven testing, SkeletonGenerator for generating code-stubs from test code (I'd read about this before and thought it would be an incredibly useful tool to have: always improve your environment!), and TicketListener_GitHub, for integration of PHPUnit with the GitHub Issue tracker.

That's a lot of installation. But wait - there's more!

In an attempt to start tackling the (very many) "best practices" list for Jenkins, I set up a user, spend 15 minutes trying to figure out how to expose Jenkins on the Apache server without actually daring to try it, and then start the install of the Jenkins Selenium Plugin, which "will run Selenium Grid, acting as a hub for all other Selenium nodes".  OK then.  It takes about as long to install as I spent installing all this other shit stuff today manually, but finally it's done and I can restart Jenkins.  On the command line, which is how the cool kids do it.

sudo service jenkins restart

Success.  However, I am crestfallen to see that in order to continue with the tutorial, I have to set up THREE VIRTUAL MACHINES with several different browsers on them OH NOES.  I really, really don't want to do this right now, especially since the instructions for setting up three virtual machines with several browsers on them happen to be: "For this article, 3 virtual machines with different browser configurations have been created and configured". I has a so SAD. :(

Today's captain's log has run far too long as it is, erstwhile reader.  You are probably asleep right now, as I know that it is extra-boring.  Not, however, as boring as it was to actually do all the installations. Tomorrow is the last day of the first week of Hackership.  Will I manage to free myself from this tangle of installation bondage in time for the demo?

Stay tuned, and find out.

Tuesday, November 12, 2013

Day 2: setting up the environment... still.

As continued from the previous day, with less nonsense.

Since I'm too exhausted today for literary flourish, let's review the previous day's discoveries in light of the knowledge I was fortunate enough to gain today. This time with a lot less adjectives.

System requirements for installing Typo3:

1) Image Magick - I found out today that this is NOT installed, but could remedy that easily with:

sudo apt-get update
sudo apt-get install imagemagick --fix-missing

2) GDLib / Freetype - these were already available in my PHP installation, which I found out by using:

php -i

Alternatively, you can open a PHP page in the browser that contains the function call "phpinfo()".  This will tell you EVERYTHING you need to know, and possibly more than you would like to, about your PHP and your Apache configurations.

3) zlib - same as #2

4) Apache with mod_deflate (NOT mod_gzip!) and mod_rewrite.  Initally I used

apache2 -l

(sort of), to find this out. Today I found out a more convient way to check out the Apache configuration, as referred to above in #2. This is a much, mush easier way to find out, and more readable.

To install mod_rewrite, though, just do this:

sudo a2enmod rewrite

You don't need to install mod_gzip - it is for a previous version of Apache.  The correct mod is mod_deflate.  I contacted Typo3 documentation about this and they quickly wrote back that the correction is slated to be updated very soon.

5)PHP Cache (I used APC) - this was trivial to install:

sudo apt-get install libprcre3-dev php-apc
sudo /etc/init.d/apache2 restart

Copy the file "apc.php" into your web docroot and call in the browser to see some pretty graphs.

Today I spent several hours trying to concentrate on the task at hand: install Typo3. Some of that time was spent moping after I got stuck with the incredibly informative "Server Error"... error after installation.  But let's start at the beginning:

Download the Typo3 introduction package from and unpack it to your web docroot.  This simple task took me 20 minutes, since the first download ended up being corrupted, and lack of root permissions in my web docroot forced me to revert to the command line to get things done (unzip, rename, create files, change file permissions).  Being forced to use the command line is a good thing, though - our childrens can are learning.

Calling the main install tool page, however, turned out to be my initiation of the day into a world of pain.  As expected, I was told that the install tool is locked and that I need to create an empty file called ENABLE_INSTALL_TOOL. This took a LONG time to figure out how to do, since even using

sudo cat /dev/null > ENABLE_INSTALL_TOOL

to create an empty, theoretically "extensionless" file caused the command line to tell me that I had no permissions. As root.  After a LOT of googling I learned that by first using

sudo su -

"you start an interactive shell AS 'root'".  I thought that's what preceding commands with "sudo" was supposed to be for, but whatever.  After that I could create the necessary file.  Ubuntu insisted on making it a text file, which I thought was the cause of the subsequent problem, the incredibly informative "Server Error", which I got when calling the installation page anew.  I looked everywhere on how to create an EXTENSIONLESS file, not a file that automatically gets saved as a text file.

After about 2 hours of this, I gave up and spent 30 minutes reviewing PHPUnit.  One of the organisers asked me how I was doing and I told him that I was stuck and showed him the problem.  He recommended checking out the apache error log in var/log/apache2/error.log, which informed me that the file typo3conf/LocalConfiguration.php was not writable. That was the problem, not that my ENABLE_INSTALL_TOOL file was automatically saved as text. The LocalConfiguration.php file didn't even fracking exist.  I'd already checked the write permissions on the directories and they were all OK. So he suggested listing the running processes and their owners to see if perhaps the owner of Apache did not match the owner of my web docroot. The command line to do this is

ps aux

which is totally AUXSOME. Apache claimed to be pwnd by "www-data", which was the key to why the file "LocalConfiguration.php" (which did not exist) could not be written, as the web docroot directory was owned by root.

We used "man" on the command line to check the correct syntax for "chown", which can be used to change the owner of a directory. After that we just had to navigate to the webroot directory and use

chown -R www-data .

in order to change the owner of web docroot recursively (i.e. all of web docroot's subdirectories) to "www-data", which would make all of these directories pwnable by www-data and thus enable the install TOOL to create the LocalConfiguration.php file.

After doing this, the installation page for Typo3 opened, as did the Gates of Heaven!

I found out after some grumbling over a "non-existent" database that I needed to call the install tool page with the argument "mode=123" in order to enter the non-existing database's information. I changed the site password, gave it a My Little Pony Periwinkle color, and everything was peachy (lavender) after that.

Sidenotes: in the principle of "always improve your environment", is there some kind of tool for checking the apache2 log visually?

A few minor issues are still nagging me, though, like "too low PHP script execution time", and the fact that email doesn't fracking work.  I know that these things can be changed in php.ini, but what about the "too low maximum file size" which, according to the TOOL, can be set with the parameter "TYPO3_CONF_VARS[BE][maxFileSize]".  WHERE one is supposed to do that, TOOL has failed to mention. I had to post it on a blog in hopes of getting my answer.

Yet another day at sea, and once again the day is saved but by the sage advice of a fellow seamate.  As Herman Melville once said, "he who sails alone, sails but to his death".

Actually no - Herman Melville never said that.  I just totally made it up.

Monday, November 11, 2013

Day 1: Setting up the environment

Join me in this thrilling tale of adventure on the high and stormy seas of programming!

Ok, ok... It's actually going to be (for most people) more boring than the most boring parts of "Moby Dick", and a lot less well-written. But enjoy the prose regardless, as a tale of redemption, inconsistent style, and the gross misuse of metaphores and late-19th century vocabulary.

Day 1: Setting up the environment

Before you can set out to sea, you've got to rig the sails. Something we talked about this morning during a workshop on optimised learning concerned the theory that it takes around 20 hours to learn something well.  That's 45 minutes of practice a day for about a month.  I brought up the point that often, with programming, a lot of time gets eaten up just setting up a working environment where you can succeed in practicing at all.  And like a self-fulfilling prophecy of doom, my attempt to set up the system requirements for an installation of Typo3 resulted in a detour of about 2,5 hours.  Here's the gripping narrative of the glory and the pain:

System Requirements for Typo3:
1) Graphics Magick or Image Magick
2) GDlib /Freetype
3) zlib
4) Apache with mod_gzip and mod_rewrite
5) PHP-Cache (APC, PHP Accelerator)

Requirements 1-3: I found out that these were already available on my system by checking out my PHP setup from the command line. I had to google to find out how to do this, but found results immediately that also happened to work: just type on the command line: php -i

Simple. I tried the same trick with Apache with less success. The first google results for checking the Apache version on the command line instructed: type on the command line: httpd -v

Fail. That bastard illegitimate son of a command line told me that it "couldn't find" the command. After some more searching I found that on Ubuntu you need to type the following command instead: apache2 -v.

Success! GD-support enabled!  Freetype support enabled! MySql - enabled!  ZLib enabled!  My heart soars!  "Just" two more requirements to go.  I must admit that I then succumbed to the deadly Sin of Pride, for which I duly paid the penalty: my attempt to "grep" the apache2.conf file from the command line had to be aborted after a many minutes of computation. On my word of honour, next time I shall first google the correct use of "grep". The following modest attempt to find a (legitimate) way to find out which modules are enabled in apache resulted in fruition: type on the command line: apache2 -l.

(I shall now switch to present tense to increase narrative excitement!)

Alas I have got a problem, for apparently neither the mod_gzip nor the mod_rewrite...mods are enabled.  My ever-reliable companion Google points me to Apache Toolbox, whose last update took place in the year 2006.  The instructions on the download site are delightfully simple, so I download it and unpack it in order to follow the instructions. It looks as if I am going to have to recompile Apache, which I *so very much* do not wish to do and furthermore, Apache Toolbox doesn't offer the mod_rewrite option. :( More google results on enabling mod_gzip only succeed in chilling me to the bone with a sense of premonitory doom. Toolbox is supposed to make this easy.

I will just have a look into the apache2.conf file. There I see that it handily loads all files found in the directory called "mods_enabled"... where I am crestfallen to find neither mod_rewrite nor mod_gzip. Another directory, "mods_available", wonder of wonders, reveals a "rewrite.load" file, which fills my heart with joy.  I can probably just copy that file into the "mods_available" directory and then surely I will have accomplished my task!  Ubuntu, however, insists on frusterating me in my endeavors.  I google how to enable mod_rewrite and I find some results that inform me: type on the command line: a2enmod rewrite.

Alas, abject failure. The gloom of thwarted ambitions is starting to cloud my troubled soul, and I finally decide to ask someone for help. My co-learner knows Apache and advises me to try the a2enmod rewrite command again, but this time as root:  sudo a2enmod rewrite

And that totally works, which is awesome. We both search for instructions on how to enable gzip without having to posess the qualifications of a Unix administrator.  I finally discover a precious gem of wisdom, that mod_gzip is for Apache 1.3 and that Apache 2.2 needs mod_deflate, which is as a brother, but faster.  Looking in my "mods_enabled" directory I am elated to discover a "deflate.load" file to claim as my very own.

So... two greulling hours to get two mods (one actually) enabled in Apache. Just one more system requirement to go: a PHP cache. I shall approach this task with less arrogance and more caution. Google tells me about APC (Alternative PHP Cache) and on I immediately find exact instructions on how to install everything with just three commands in the shell:

for the PCRE requirement
sudo apt-get install libpcre3-dev

to install APC
sudo apt-get install php-apc

retart apache
sudo /etc/init.d/apache2 restart

Copy the file "apc.php" into the web docroot and call it in the browser to see configuration and statistics.

With nary a few googles I have completed the system requirements necessary before one even begins to install Typo3 for demonstration purposes. Evening is beginning to fall apon my first day on board the Hackership.