EXT: tollwerk Open Device Lab¶

What does it do?¶

Let's use the words of opendevicelab.com to introduce the big idea behind Open Device Labs:

Open Device Labs (ODLs, #ODL) are a grass roots community movement. They establish shared community pools of internet connected devices for testing purposes of web and app developers. In result, ODLs lead to an ultimate improvement of the web & app experience both for developers and for consumers. Since early 2012 there are lots of Open Device Labs evolving all over

the world, most of them running their own, mostly small website, while opendevicelab.com and lab-up.org being something like the “big umbrella” above it all.

This extension would like to be of use for anyone running an ODL website with the help TYPO3. It provides some features that might come handy, like e.g.:

• Detailled device management including the rendering of a frontend device list
• Generation of multi-purpose device labels via PDF using TCPDF ( http://www.tcpdf.org/ )
• Creation of branded device wallpaper images
• JSON / JSONP API for registered ODL devices

The extension was written for TYPO3 version 6+ (no support for 4.x!) and is based on extbase / fluid.

Screenshots¶

The frontend plugin renders a list of registered ODL devices. It's based on a fluid template and can be tailored to your individual needs.

The backend provides a dedicated module for label printing and wallpaper image creation.

Installation ------------

To install the extension simply download it from the TYPO3 extension repository and enable it in the Extension Manager. There's nothing to configure in the Extension Manager.

Static TypoScript¶

Include the extension's static TypoScript into the TypoScript root template of your site.

Configuration -------------

Constants¶

Most of the extension's features can be controlled via the constant editor (e.g. on the TypoScript root template). Almost any constant directly relates to a corresponding setup option that can also be set by manually crafted TypoScript. Please see the setup chapter for details on these options.

There are separate constant editor sections for the frontend plugin and the backend module. The frontend plugin parameters mainly consist of the usual settings for extbase extensions like root paths and the storage folder. Additionally you can disable the extension's JSONP API here.

The backend module constants feature additional parameters for specifying a device identifier , the root path for print label templates as well as the (publicly accessible) folder for device wallpapers .

Setup ^^^^^

Device management¶

The extension introduces a couple of record types associated with the management of ODL devices. These are:

• Devices
• Manufacturers
• Operating systems
• Operating system versions
• Web browsers
• Web browser versions
• CSS screen resolutions
• Contributors

The central record type is – of course – the device , whereas the other record types serve as auxiliary records. Each device has

• one manufacturer,
• one operating system (with an optional version),
• one or more web browsers installed (each with an optional version),
• one or two CSS screen resolutions (they might differ from the physical screen resolution and might also be different in landscape and portrait orientation)
• and one contributor.

It is suggested that you create and manage the auxiliary records explicitly instead of creating them from within a device form. While the necessary wizards are included in the forms TYPO3's support for them is somewhat limited. Most importantly all the associated records (including the devices) have to be contained on one single page in the page tree.

The single properties of the different record types in the backend forms should be pretty self explanatory. Most of the properties are also being exported through the JSON / JSONP API as well, so it might be a good idea to study a JSON export result for further understanding.

Placing a device list in the frontend¶

To place a device list on a frontend page simply select the “ODL Device List” plugin from the “New content element” wizard:

The content element created should feature the plugin type “ODL Device List”:

Printing device labels ^^^^^^^^^^^^^^^^^^^^^^

The extension provides a backend module which you can use for generating and printing device labels. You could use such labels e.g. for labeling your device display or your devices themselves. Labels are created as PDF files, as directly printing from the browser would potentially result in header and footer lines be printed as well.

Please select the Web > Open Device Lab module to the left as well as a page carrying device and auxiliary records in the page tree to print labels for those devices.

There are two exemplary label templates coming with the extension, one for using a label sticker sheet with multiple columns and rows of labels (“AVERY Zweckform 3666”) and another one for printing labels on endless paper with a dedicated label printer (“Endless paper”). The label templates are built with fluid (don't get confused by the “.pdf” file extension they carry, they're just ordinary XML) residing in the directory specified by the settings.wallpaperRootPath TypoScript parameter.

PDF generation itself is done via the freely available TCPDF library ( http://www.tcpdf.org ). The extension includes an unburdened version of TCPDF (essentially the examples and fonts have been stripped out in favor of significantly smaller file size). The extension comes with a couple of specialized view helpers for controlling TCPDF output . You can easily use your own label templates (or customize one of the default ones) by dropping appropriate fluid template files (with “.pdf” file extension) into the label template root directory.

Generating device wallpapers¶

As it might be desirable to give your devices an all-over consistent appearance the extension provides a backend module which you can use for generating wallpaper images for your devices. Please select the Web > Open Device Lab module to the left as well as a page carrying device and auxiliary records in the page tree to generate wallpapers for those devices.

The wallpaper images are rendered by means of regular TYPO3 frontend content element rendering using a GUIBUILDER TypoScript configuration which can be customized via the settings.wallpaper parameter. There are some custom markers you may use within the wallpaper configuration – see the TypoScript settings documentation for details. Most importantly, each wallpaper will be rendered in the dimensions defined by the corresponding device record (wallpaper width and height settings). Examples of wallpapers might e.g. look like:

Apple iPad 2 wallpaper

Apple MacBook Pro wallpaper

In many cases the easiest way of transferring a wallpaper to a mobile device is by retrieving and saving it with a regular web browser.In many cases the easiest way of transferring a wallpaper to a mobile device is by retrieving and saving it with a regular web browser. To accomplish this the extension generates the wallpaper images to a publicly accessible directory somewhere below your website root (by default into the directory typo3temp/odl-wallpapers – configure it via the settings.wallpaperRootPath TypoScript setting). Once generated the path to each device's wallpaper is shown in the backend module's device list. You can click on each wallpaper to open it in a separate browser window. To retrieve the wallpaper on your device simply browse to the URL shown in the address bar.

JSON / JSONP API¶

By default the extension exposes the registered devices through a JSON / JSONP API (you might disable this via the constant editor). You may query the API by requesting the TYPO3 frontend with a type parameter of value 1333:

http://your-device-lab.org/index.php?type=1333

The idea behind the JSON API is very well explained by Andre Jay Meissner ( http://opendevicelab.com / http://lab-up.org ) in response to a blog post of Africa's Nomad Device Lab : At some point in the future opendevicelab.com might start grabbing device lab data by pulling JSON files from the ODL's websites. Currently no such feature exists yet, but already having prepared a JSON API simply feels good, don't you think?

The export structure used right now is somewhat fictional and might lack certain information (e.g. the device lab residential data), but as soon as opendevicelab.com announces a standard to be used we will adapt the output. This is a current output example (excerpt):

[
   {
      "manufacturer":"Apple",
      "name":"iPad 1",
      "model":"MB292FD",
      "os":"iOS",
      "osversion":"5.1.1",
      "width":768,
      "height":1024,
      "diagonal":9.7,
      "ppcm":52,
      "ppi":132,
      "inputmethods":[
         "touchscreen"
      ],
      "resolutions":[
         {
            "width":768,
            "height":1024,
            "ratio":1,
            "orientation":3
         }
      ],
      "comment":"",
      "contributor":{
         "name":"tollwerk GmbH",
         "logo":"tollwerk-logo.png",
         "url":"tollwerk.de"
      },
      "available":1
   },
   ...
]

Use one of the GET parameters callback or jsonp to specifiy the callback function that should be used for padding the JSON data (otherwise you will get a simple JSON array as result). Example:

http://your-device- lab.org/index.php?type=1333&callback=myCallbackFunction

Creating a custom device label template¶

The fluid templates used for device label printing reside in the directory specified by the settings.labelTemplateRootPath TypoScript parameter and have to carry a “.pdf” file extension in order to be listed in the backend module (although they have ordinary XML content). Internally they make use of some special TCPDF view helpers documented below. One of the default label templates has the following content:

{namespace odl=Tollwerk\TwOdl\ViewHelpers}
<odl:tcpdf width="210" height="297" unit="mm" left="9.75" right="9.75"
    top="10.63" bottom="10.63" columns="5" rows="13" offset="{offset}">
    <odl:tcpdf.font family="DroidSans"
        fontfile="fileadmin/templates/fonts/DroidSans/DroidSans.ttf"/>
    <odl:tcpdf.font family="DroidSans"
        fontfile="fileadmin/templates/fonts/DroidSans/DroidSans-Bold.ttf"
        style="b"/>
    <f:for each="{devices}" as="device">
        <odl:tcpdf.label>
            <odl:tcpdf.image
                file="EXT:tw_odl/Resources/Public/Images/odl-nbg-hor-de-white.eps"
                width="20" top="2" left="2" right="2" align="left"/>
            <odl:tcpdf.text x="22" y="0.5" width="15.5" halign="right"
                fontfamily="DroidSans" fontstyle="b"
                fontcolor="{0:0, 1:116, 2:148}" fontsize="18">
                <odl:deviceIdentifier device="{device}" identifier="%s"
                    digits="{settings.deviceNumberDigits}"/>
            </odl:tcpdf.text>
            <odl:tcpdf.text x="1" y="9" width="10" height="2.5"
                fontfamily="DroidSans" fontsize="4" valign="bottom">
                <f:translate key="device.name"/>
            </odl:tcpdf.text>
            <odl:tcpdf.text x="10" width="27" height="3" fontfamily="DroidSans"
                fontsize="6" fontstyle="b" cursor="1" halign="right"
                >{device.manufacturer.name} {device.name}</odl:tcpdf.text>
            <odl:tcpdf.text x="1" width="10" height="2.5" fontfamily="DroidSans"
                fontsize="4" valign="bottom">
                <f:translate key="device.os"/>
            </odl:tcpdf.text>
            <odl:tcpdf.text x="10" width="27" height="3" fontfamily="DroidSans"
                fontsize="6" fontstyle="b" cursor="1" halign="right"
                >{device.os.name} {device.osversion.version}</odl:tcpdf.text>
            <odl:tcpdf.text x="1" width="10" height="2.5" fontfamily="DroidSans"
                fontsize="4" valign="bottom">
                <f:translate key="device.contributor"/>
            </odl:tcpdf.text>
            <odl:tcpdf.text x="10" width="27" height="6" fontfamily="DroidSans"
                fontsize="6" fontstyle="b" halign="right"
                >{device.contributor.name}</odl:tcpdf.text>
        </odl:tcpdf.label>
    </f:for>
</odl:tcpdf>

As you see there is no HTML, just TCPDF specific markup using fluid syntax and the TCPDF view helpers . One could describe the template with the following words:

On the top level a target medium is specified (in this case a DIN A4 sheet with 5 label columns and 13 label rows) using the odl:tcpdf view helper. Next, two custom fonts (Droid Sans) get declared via the odl:tcpdf.font view helper. Then, for each device in the list a label is created with the odl:tcpdf.label view helper, each consisting of an image ( odl:tcpdf.image ) and several text cells ( odl:tcpdf.text ). The PDF output of the template looks like this:

By studying the example template as well as the view helper documentation below you should easily be able to write your own custom label template.

TCPDF view helpers¶

The extension comes with a couple of custom view helpers that you can use in your fluid label templates. If you want to do so, you have to register the appropriate view helper namespace in the beginning of your templates like this:

{namespace odl=Tollwerk\TwOdl\ViewHelpers}

<odl:tcpdf width="210" height="297" unit="mm" left="9.75" right="9.75" top="10.63" bottom="10.63" columns="5" rows="13" offset="{offset}">
    ...
</odl:tcpdf>

<odl:tcpdf.font family="DroidSans" fontfile="fileadmin/templates/fonts/DroidSans/DroidSans.ttf"/>

<odl:tcpdf.image file="EXT:tw_odl/Resources/Public/Images/odl-nbg-hor-de-white.eps" width="20" top="2" left="2" right="2" align="left"/>

<odl:tcpdf.label>
    ...
</odl:tcpdf.label>

<odl:tcpdf.page>
    ...
</odl:tcpdf.page>

<odl:tcpdf.text x="10" width="27" height="3" fontfamily="DroidSans" fontsize="6" fontstyle="b" cursor="1" halign="right">{device.manufacturer.name} {device.name}</odl:tcpdf.text>

0.20¶

0.1.2¶

0.1.1¶

0.1.0¶