the anatomy of typo3 sitepackages

THE ANATOMY OF SITEPACKAGES

Modern website building in TYPO3

Benjamin KottFront-end Developer at TeamWFPMember of the TYPO3 UX TeamDüsseldorf, Germany

facebook.com/benjamin.kott

twitter.com/benjaminkott

github.com/benjaminkott

bk2k.info

THE ANATOMY OF SITEPACKAGES2

Benjamin KottFront-end Developer at TeamWFPMember of the TYPO3 UX TeamDüsseldorf, Germany

facebook.com/benjamin.kott

twitter.com/benjaminkott

github.com/benjaminkott

bk2k.info

THE ANATOMY OF SITEPACKAGES3

That is Dave.

Dave is Frank Näglerspersonal Minion. Every time Frank commits bullshit to the TYPO3 Core, it was Dave.

Dave really, really wantedto be part of this presentation.

4 THE ANATOMY OF SITEPACKAGES

Build #6480 (fcec4ef) of TYPO3/TYPO3.CMS@master by Frank Nägler failed in 10 min 32 sec

It´s not my fault!

Eh. Banana?


Agenda

The what and why? Lots of technical stuff! Final Conclusion.


W

The what and why?

What is a Sitepackage?It´s all about definition.


Different names for the same @!?#&%§ shit.

Base ExtensionTemplate Extension

SitepackageSite Foundation

Distribution*…


* A Distribution normally contains a pre-set of pages and assets, in this case we will not make use of it. It´s listed for sake of completeness.

„A sitepackage is an extensionfor TYPO3 that contains

all relevant configurations for a website.“


Why should you care about a Sitepackage?It @!?#&%§ works for me™ to puteverything in the fileadmin.


Your configuration files are indexed by FAL.

All files you upload into the fileadmin are automaticallyindexed from the file abstraction layer if not disabled.

Lots of totally useless records that should notbe there at any point.


FAL records are not updated if files are uploaded via FTP.

The only way FAL recognizes file changes or deletions is if they are done using the backend or the API directly.

Files that are changed outside can cause fatal error,if this file is referenced and deleted via FTP.


Fileadmin is userspace.Files within the fileadmin directory are edited and maintained by an editor who usually does not have the knowledge to so it properly.

It´s better to protect the editor from accidentally breaking a part of the internet.


Configurations should be in your version control.

Having the configuration files in the fileadmin is a strong indicator for missing version control.

We should talk about that…



Source: http://www.commitstrip.com/en/2013/11/05/git-svn-ou/

You are not able to handle Extension dependencies.

Without dependency management you have no idea which extensions and which version is needed to maintain a running website.


DependenciesThe Extension Manager is your friend.


For example sitepackage extension could require Bootstrap Package, News & SeoBasics in the newest available version on installation.

Your TypoScriptSetup and Constants are saved

in the template record.The setup and constant field of a template record is

the last possibility to override the TypoScript configuration of your TYPO3 page within that record.



Template RecordStatic template sorting.

Instead of putting your setup and constants directly in the template record or include it there its more easy to make use of Static Templates.

General Options Includes Access

Template

Include static (from extensions)

CSS Styled Content (css_styled_content)

Selected Items Available Items

Bootstrap Package (bootstrap_package)Example Package (example_package)


Template

Constants

<INCLUDE_TYPOSCRIPT: source="…">

Setup

<INCLUDE_TYPOSCRIPT: source="…">

Static Templatesand loading order.

Your configuration is @!?#&%§ public accessible.

Most users that put their configuration files in the fileadmin folder, forget to protect it from external access.

Want so see how not to do it?Bing „fileadmin setup.txt“ or „fileadmin setup.ts“


plugin.tx_odstwitter_pi1 {consumerKey = XXXXXXconsumerSecret = XXXXXXaccessToken = XXXXXXaccessTokenSecret = XXXXXX

}


plugin.ldap.auth {username = adminpassword = XXXXXX

}


You don´t want your configuration to be public accessible!

NEVER. EVER. EVERERERERER!


… we could do this for hours.


Benefits of Sitepackages!Yummy, yummy!


Facts

Config files editable through file moduleConfig files not accessible by editorsConfig files are protected *Autoload PageTSAutoload TypoScriptStatic TypoScript TemplateDependency ManagementDistrubution through TER possibleDeployment through Extension ManagerClean Version Control possible

Sitepackage


Fileadmin

* Possible but not common practice


T

Technical Stuff

StructureStick to the Conventions.


Basic Structure

Classes Configuration Documentation Initialisation Resources ext_conf_template.txt ext_emconf.php ext_icon.png ext_localconf.php ext_tables.php ext_tables.sql

Controller, ViewHelpersTypoScript, PageTS, TCAManual in reStructuredText formatData / Assets for FileadminTemplates, Images, CSS, JS, …Extension Manager ConfigurationExtension ConfigurationExtension IconExecuted in FE and BEExecuted in BEDatabase Schema


Classes

Controller Domain

Model Repository

Hook ViewHelpers

MVC Controller

MVC Domain ModelData RepositorysCore Manipulation ScriptsCustom Fluid ViewHelper


Configuration

PageTS RTE.txt TCEFORM.txt

TCA Overrides

tt_content.php tx_myext_record.php

TypoScript setup.txt constants.txt

.htaccess

PageTS for your Website

TCA Definition for your own tablesTCA Overrides for existing tables

TypoScript Static Template

Protect your stuff!32 THE ANATOMY OF SITEPACKAGES

Documentation

docs.typo3.org/typo3cms/CoreApiReference/ExtensionArchitecture/Documentation/Index.html

Call for [email protected]/T3docTeam

Documentation is hard and we are all really bad in this. It helps you to remember and others to understand what

and how things work.


Initialisation

Files Images

Example_1.png Example_2.jpg

Example_3.txt data.t3d

Files added here, they will be copied to fileadmin/extension/ during installation

Export of your database it will be imported at page root level during installation


Resources

Private Languages Layouts Partials Templates .htaccess

Public Css Images JavaScript

Private protected filesXLIFF/XML files for localized labelsMain layouts for the viewsPartial templates for repetitive useTemplates for the viewsProtect your stuff!Public accessible filesAny CSS file used by the extensionAny images used by the extensionAny JS file used by the extension


Minimal SetupLet´s start small.


Example PackageJust enough to get the party starting.

ExtensionDependency to CSS Styled ContentBasic TypoScriptBasic PageTSFluid TemplateCSS fileJavaScript file


typo3conf/ext/example_package

Head to the directory and create a folder with a name of your choice like „example_package“. This will be the container of your sitepackage and

also your extension key.


Extension Directory Your Extension

example_package

Configuration Resources ext_emconf.php ext_icon.png ext_localconf.php ext_tables.php

TypoScript, PageTS, TCATemplates, Images, CSS, JS, …Extension ConfigurationExtension IconExecuted in FE and BEExecuted in BE


typo3conf / ext

ext_emconf.php

$EM_CONF[$_EXTKEY] = array(

'title' => 'Example Package',

'description' => '',

'category' => 'templates',

'version' => '1.0.0',

'state' => 'stable',

'clearcacheonload' => 1,

'author' => 'Benjamin Kott',

'author_email' => '[email protected]',

'author_company' => '',

'constraints' => array(

'depends' => array(

'typo3' => '6.2.12-7.99.99',

'css_styled_content' => '6.2.0-7.99.99',

),

'conflicts' => array(

'fluidpages' => '*',

'themes' => '*',

),

),

);

TitleA title for your extension.

CategoryType of category the extension should be listed in. Use template for general usage and distribution for a listing in the distributions section.

DependenciesAdditional Extensions, for example like a news extension or a specific core version.

ConflictsKnown issues with other extensions can be placed here to avoid that these extension are running parallel in your system.


typo3conf / ext / example_package

ext_icon.png


Make it pretty. Please.64x64 PNG are welcome.


ext_localconf.php

if (!defined('TYPO3_MODE')) {

die('Access denied.');

}

\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addPageTSConfig(

'<INCLUDE_TYPOSCRIPT: source="FILE:EXT:'

. $_EXTKEY . '/Configuration/PageTS/TCEFORM.txt">'

);


Add PageTS by default*

* You should really know what you are doing before adding global PageTS.After adding its set for all Websites in your TYPO3 instance.


ext_tables.php

if (!defined('TYPO3_MODE')) {

die('Access denied.');

}

\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addStaticFile(

$_EXTKEY, // Extension Key

'Configuration/TypoScript', // Path to setup.txt and constants.txt

'Example Package' // Title in the selector box

);


Add static template to the template record


Template

Include static (from extensions)

Example Package (example_package)CSS Styled Content (css_styled_content)Bootstrap Package (bootstrap_package)

Selected Items Available Items


Configuration

PageTS TCEFORM.txt

TypoScript setup.txt constants.txt

Basic PageTS

Basic SetupBasic Constants



TCEFORM.txt

## TCEFORM

TCEFORM {

pages {

layout.disabled = 1

}

tt_content {

// NOBODY wants or should edit this

// really, let them disappear

table_bgColor.disabled = 1

table_border.disabled = 1

table_cellspacing.disabled = 1

table_cellpadding.disabled = 1

pi_flexform.table.sDEF {

acctables_nostyles.disabled = 1

acctables_tableclass.disabled = 1

}

}

}


typo3conf / ext / example_package / Configuration / PageTS

You should really know what you are doing before adding global PageTSlike in this example. After adding its set for all Websites in your TYPO3 instance.

See ext_localconf.php as example how to add PageTS globally.

constants.txt

## PAGE

page {

template {

# cat=example package: advanced/100/100; type=string; label=Layout Root Path: Path to layouts

layoutRootPath = EXT:example_package/Resources/Private/Layouts/

# cat=example package: advanced/100/110; type=string; label=Partial Root Path: Path to partials

partialRootPath = EXT:example_package/Resources/Private/Partials/

# cat=example package: advanced/100/120; type=string; label=Template Root Path: Path to templates

templateRootPath = EXT:example_package/Resources/Private/Templates/

}

}


typo3conf / ext / example_package / Configuration / TypoScript

Use TypoScript Constants and configuration for the Constant Editor to have your Sitepackage ready for multisite usage or to easily make adjustments to your website.

setup.txt

## DEPENDENCIES

<INCLUDE_TYPOSCRIPT: source="FILE:EXT:css_styled_content/static/setup.txt">



Load the needed TypoScript from dependant extensions to avoid sorting of static tempates in the template record.

To avoid unnecessary work we are depending css_styled_content for the content rendering in this example.

setup.txt

## CONTENT SELECTION

lib.dynamicContent = COA

lib.dynamicContent {

5 = LOAD_REGISTER

5.colPos.cObject = TEXT

5.colPos.cObject {

field = colPos

ifEmpty.cObject = TEXT

ifEmpty.cObject {

value.current = 1

ifEmpty = 0

}

}

20 < styles.content.get

20.select.where = colPos={register:colPos}

20.select.where.insertData = 1

90 = RESTORE_REGISTER

}



Content selection for use in Fluid cObject ViewHelper with data pass-through.

<f:cObjecttyposcriptObjectPath="lib.dynamicContent“ data="{colPos: '0'}" />

setup.txt

## PAGE – Part 1

page = PAGE

page {

typeNum = 0

10 = FLUIDTEMPLATE

10 {

file.stdWrap.cObject = CASE

file.stdWrap.cObject {

key.data = levelfield:-1, backend_layout_next_level, slide

key.override.field = backend_layout

default = TEXT

default.value = {$page.template.templateRootPath}Default.html

default.insertData = 1

}

partialRootPath = {$page.template.partialRootPath}

layoutRootPath = {$page.template.layoutRootPath}

}

}



Page-Templates based on Fluid for super easy templating.

BackendLayouts used to select the Template.

setup.txt

## PAGE – Part 2

page {

includeCSS {

main = EXT:example_package/Resources/Public/Css/main.css

}

includeJSFooterlibs {

main = EXT:example_package/Resources/Public/JavaScript/main.js

}

}



Include CSS and JavaScript files with the EXT: notation from the extension directory.

Resources

Private Layouts

Default.html Templates

Default.html Public

Css main.css

JavaScript main.js

Default Layout

Default Template

Basic CSS

Basic JavaScript



Default.html

<f:render section="Main" />


typo3conf / ext / example_package / Resources / Private / Layouts

Default.html

<f:layout name="Default" />

<f:section name="Main">

HELLO WORLD

<f:cObject typoscriptObjectPath="lib.dynamicContent" data="{colPos: '0'}" />

</f:section>

typo3conf / ext / example_package / Resources / Private / Templates

Render the Section

Select the Layout

main.css

body {

background-color: #ffffff;

color: #333333;

}


typo3conf / ext / example_package / Resources / Public / Css

main.js

console.log('I LOVE TYPO3');

typo3conf / ext / example_package / Resources / Public / JavaScript

That is everything you need!A minimum configuration with 11 files in total.


Downloadgithub.com/benjaminkott/example_package


Create your very ownSitepackage now.

S/PKG/BLDsitepackagebuilder.com



F

Final Words

Wrapping upGetting to an end.


It may surprise you……but everything you find in this

presentation is not new.


Questions?Ask me anything! But not now…I think we don’t have any time left.


Thank you for your patience63 slides in 45 minutes, sorry about that.


Resources

Sitepackage Buildersitepackagebuilder.com

Example Packagegithub.com/benjaminkott/example_package

Boostrap Packagegithub.com/benjaminkott/bootstrap_package

Distribution Managementwiki.typo3.org/Blueprints/DistributionManagement

Extension Architecturedocs.typo3.org/typo3cms/CoreApiReference/ExtensionArchitecture/Index.html


www.teamwfp.de

@benjaminkott

the anatomy of typo3 sitepackages

Technology