The Anatomy of TYPO3 Sitepackages

Modern website building in TYPO3

Sitepackage Builder
http://www.sitepackagebuilder.com

Example Package
https://github.com/benjaminkott/example_package

Bootstrap Package
https://github.com/benjaminkott/bootstrap_package

Transcript

1. THE ANATOMY OF SITEPACKAGES Modern website building in TYPO3
2. Benjamin Kott Front-end Developer at TeamWFP Member of the TYPO3 UX Team Düsseldorf, Germany facebook.com/benjamin.kott twitter.com/benjaminkott github.com/benjaminkott bk2k.info THE ANATOMY OF SITEPACKAGES 2
3. Benjamin Kott Front-end Developer at TeamWFP Member of the TYPO3 UX Team Düsseldorf, Germany facebook.com/benjamin.kott twitter.com/benjaminkott github.com/benjaminkott bk2k.info THE ANATOMY OF SITEPACKAGES 3 That is Dave. Dave is Frank Näglers personal Minion. Every time Frank commits bullshit to the TYPO3 Core, it was Dave. Dave really, really wanted to be part of this presentation.
4. 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?
5. 5 THE ANATOMY OF SITEPACKAGES Agenda    The what and why? Lots of technical stuff! Final Conclusion.
6. 6 THE ANATOMY OF SITEPACKAGES W The what and why?
7. What is a Sitepackage? It´s all about definition. 7 THE ANATOMY OF SITEPACKAGES
8. Different names for the same @!?#&%§ shit. Base Extension Template Extension Sitepackage Site Foundation Distribution* … 8 THE ANATOMY OF SITEPACKAGES * 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.
9. „A sitepackage is an extension for TYPO3 that contains all relevant configurations for a website.“ 9 THE ANATOMY OF SITEPACKAGES
10. Why should you care about a Sitepackage? It @!?#&%§ works for me™ to put everything in the fileadmin. 10 THE ANATOMY OF SITEPACKAGES
11. Your configuration files are indexed by FAL. All files you upload into the fileadmin are automatically indexed from the file abstraction layer if not disabled. Lots of totally useless records that should not be there at any point. 11 THE ANATOMY OF SITEPACKAGES
12. 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. 12 THE ANATOMY OF SITEPACKAGES
13. 13 THE ANATOMY OF SITEPACKAGES
14. 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. 14 THE ANATOMY OF SITEPACKAGES
15. 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… 15 THE ANATOMY OF SITEPACKAGES
16. 16 THE ANATOMY OF SITEPACKAGES Source: http://www.commitstrip.com/en/2013/11/05/git-svn-ou/
17. 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. 17 THE ANATOMY OF SITEPACKAGES
18. Dependencies The Extension Manager is your friend. 18 THE ANATOMY OF SITEPACKAGES For example sitepackage extension could require Bootstrap Package, News & Seo Basics in the newest available version on installation.
19. Your TypoScript Setup 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. 19 THE ANATOMY OF SITEPACKAGES
20. 20 THE ANATOMY OF SITEPACKAGES Template Record Static 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) General Options Includes Access Template Constants <INCLUDE_TYPOSCRIPT: source="…"> Setup <INCLUDE_TYPOSCRIPT: source="…"> Static Templates and loading order.
21. 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“ 21 THE ANATOMY OF SITEPACKAGES
22. plugin.tx_odstwitter_pi1 { consumerKey = XXXXXX consumerSecret = XXXXXX accessToken = XXXXXX accessTokenSecret = XXXXXX } 22 THE ANATOMY OF SITEPACKAGES
23. plugin.ldap.auth { username = admin password = XXXXXX } 23 THE ANATOMY OF SITEPACKAGES
24. You don´t want your configuration to be public accessible! NEVER. EVER. EVERERERERER! 24 THE ANATOMY OF SITEPACKAGES
25. … we could do this for hours. 25 THE ANATOMY OF SITEPACKAGES
26. Benefits of Sitepackages! Yummy, yummy! 26 THE ANATOMY OF SITEPACKAGES
27. Facts Config files editable through file module Config files not accessible by editors Config files are protected * Autoload PageTS Autoload TypoScript Static TypoScript Template Dependency Management Distrubution through TER possible Deployment through Extension Manager Clean Version Control possible Sitepackage           27 THE ANATOMY OF SITEPACKAGES Fileadmin           * Possible but not common practice
28. 28 THE ANATOMY OF SITEPACKAGES T Technical Stuff
29. Structure Stick to the Conventions. 29 THE ANATOMY OF SITEPACKAGES
30. 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, ViewHelpers TypoScript, PageTS, TCA Manual in reStructuredText format Data / Assets for Fileadmin Templates, Images, CSS, JS, … Extension Manager Configuration Extension Configuration Extension Icon Executed in FE and BE Executed in BE Database Schema 30 THE ANATOMY OF SITEPACKAGES
31.  Classes  Controller  Domain  Model  Repository  Hook  ViewHelpers MVC Controller MVC Domain Model Data Repositorys Core Manipulation Scripts Custom Fluid ViewHelper 31 THE ANATOMY OF SITEPACKAGES
32.  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 tables TCA Overrides for existing tables TypoScript Static Template Protect your stuff! 32 THE ANATOMY OF SITEPACKAGES
33.  Documentation docs.typo3.org/typo3cms/CoreApiReference/ExtensionArchitecture/Documentation/I ndex.html Call for help! documentation@typo3.org twitter.com/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. 33 THE ANATOMY OF SITEPACKAGES
34.  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 34 THE ANATOMY OF SITEPACKAGES
35.  Resources  Private  Languages  Layouts  Partials  Templates  .htaccess  Public  Css  Images  JavaScript Private protected files XLIFF/XML files for localized labels Main layouts for the views Partial templates for repetitive use Templates for the views Protect your stuff! Public accessible files Any CSS file used by the extension Any images used by the extension Any JS file used by the extension 35 THE ANATOMY OF SITEPACKAGES
36. Minimal Setup Let´s start small. 36 THE ANATOMY OF SITEPACKAGES
37. Example Package Just enough to get the party starting. Extension Dependency to CSS Styled Content Basic TypoScript Basic PageTS Fluid Template CSS file JavaScript file 37 THE ANATOMY OF SITEPACKAGES
38. 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. 38 THE ANATOMY OF SITEPACKAGES Extension Directory Your Extension
39.  example_package  Configuration  Resources  ext_emconf.php  ext_icon.png  ext_localconf.php  ext_tables.php TypoScript, PageTS, TCA Templates, Images, CSS, JS, … Extension Configuration Extension Icon Executed in FE and BE Executed in BE 39 THE ANATOMY OF SITEPACKAGES  typo3conf /  ext
40.  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' => 'info@bk2k.info', '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' => '*', ), ), ); Title A title for your extension. Category Type of category the extension should be listed in. Use template for general usage and distribution for a listing in the distributions section. Dependencies Additional Extensions, for example like a news extension or a specific core version. Conflicts Known issues with other extensions can be placed here to avoid that these extension are running parallel in your system. 40 THE ANATOMY OF SITEPACKAGES  typo3conf /  ext /  example_package
41.  ext_icon.png 41 THE ANATOMY OF SITEPACKAGES Make it pretty. Please. 64x64 PNG are welcome.  typo3conf /  ext /  example_package
42.  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">' ); 42 THE ANATOMY OF SITEPACKAGES 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.  typo3conf /  ext /  example_package
43.  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 ); 43 THE ANATOMY OF SITEPACKAGES Add static template to the template record General Options Includes Access Template Include static (from extensions) Example Package (example_package) CSS Styled Content (css_styled_content) Bootstrap Package (bootstrap_package) Selected Items Available Items  typo3conf /  ext /  example_package
44.  Configuration  PageTS  TCEFORM.txt  TypoScript  setup.txt  constants.txt Basic PageTS Basic Setup Basic Constants 44 THE ANATOMY OF SITEPACKAGES  typo3conf /  ext /  example_package
45.  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 } } } 45 THE ANATOMY OF SITEPACKAGES  typo3conf /  ext /  example_package /  Configuration /  PageTS You should really know what you are doing before adding global PageTS like 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. 
46.  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/ } } 46 THE ANATOMY OF SITEPACKAGES  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. 
47.  setup.txt ## DEPENDENCIES <INCLUDE_TYPOSCRIPT: source="FILE:EXT:css_styled_content/static/setup.txt"> 47 THE ANATOMY OF SITEPACKAGES  typo3conf /  ext /  example_package /  Configuration /  TypoScript 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. 
48.  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 } 48 THE ANATOMY OF SITEPACKAGES  typo3conf /  ext /  example_package /  Configuration /  TypoScript Content selection for use in Fluid cObject ViewHelper with data pass- through. <f:cObject typoscriptObjectPath="lib.dynamicCont ent“ data="{colPos: '0'}" /> 
49.  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} } } 49 THE ANATOMY OF SITEPACKAGES  typo3conf /  ext /  example_package /  Configuration /  TypoScript Page-Templates based on Fluid for super easy templating. BackendLayouts used to select the Template. 
50.  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 } } 50 THE ANATOMY OF SITEPACKAGES  typo3conf /  ext /  example_package /  Configuration /  TypoScript Include CSS and JavaScript files with the EXT: notation from the extension directory. 
51.  Resources  Private  Layouts  Default.html  Templates  Default.html  Public  Css  main.css  JavaScript  main.js Default Layout Default Template Basic CSS Basic JavaScript 51 THE ANATOMY OF SITEPACKAGES  typo3conf /  ext /  example_package
52.  Default.html <f:render section="Main" /> 52 THE ANATOMY OF SITEPACKAGES  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 
53.  main.css body { background-color: #ffffff; color: #333333; } 53 THE ANATOMY OF SITEPACKAGES  typo3conf /  ext /  example_package /  Resources /  Public /  Css  main.js console.log('I LOVE TYPO3');  typo3conf /  ext /  example_package /  Resources /  Public /  JavaScript
54. That is everything you need! A minimum configuration with 11 files in total. 54 THE ANATOMY OF SITEPACKAGES
55. Download github.com/benjaminkott/example_package 55 THE ANATOMY OF SITEPACKAGES 
56. Create your very own Sitepackage now. S/PKG/BLD sitepackagebuilder.com 56 THE ANATOMY OF SITEPACKAGES
57. 57 THE ANATOMY OF SITEPACKAGES F Final Words
58. Wrapping up Getting to an end. 58 THE ANATOMY OF SITEPACKAGES
59. It may surprise you… …but everything you find in this presentation is not new. 59 THE ANATOMY OF SITEPACKAGES
60. Questions? Ask me anything! But not now…I think we don’t have any time left. 60 THE ANATOMY OF SITEPACKAGES
61. Thank you for your patience 63 slides in 45 minutes, sorry about that. 61 THE ANATOMY OF SITEPACKAGES
62. Resources Sitepackage Builder sitepackagebuilder.com Example Package github.com/benjaminkott/example_package Boostrap Package github.com/benjaminkott/bootstrap_package Distribution Management wiki.typo3.org/Blueprints/DistributionManagement Extension Architecture docs.typo3.org/typo3cms/CoreApiReference/ExtensionArchitecture/Index.html 62 THE ANATOMY OF SITEPACKAGES
63. www.teamwfp.de  @benjaminkott