DEPRECATION WARNING

This documentation is not using the current rendering mechanism and is probably outdated. The extension maintainer should switch to the new system. Details on how to use the rendering mechanism can be found here.

Administrator Manual

Installation

This extension has no special dependencies. There are two static templates:

Foundation framework
This static template should always be included. It will load necessary scripts, and give you access to some configuration constants.
Foundation framework (default CSS)
This static template will load default Foundation CSS files. You can load them for testing purposes. However, on a real website, you should consider customizing Foundation CSS, and thus you would not need to load this static template.

Upgrading

When you upgrade Foundation framework, do not forget to regenerate the CSS files of your project against the new Foundation SCSS files. It may also be necessary to clear all CSS and JavaScript caches.

Configuration

Extension Configuration

useRTE
If the option is true (default), RTE default configuration will be adapted to use Foundation stylesheets. Il will remove default classes and stylesheet of rtehtmlarea, and replace them with classes and stylesheet from Foundation. See Using Foundation in the RTE for more details.
addPanels
If the option is true (default), four options are added to the Indentation and Frames menu of content objects: Panel, Panel with radius, Callout, and Callout with radius. If you do not use those frames, or if it interfer with your own defined frames, you can disable this options, and the Indentation and Frames menu will not be altered by cb_foundation extension.

All the TypoScript constants can be edited using the constant editor.

General TypoScript constants

Under the FOUNDATION category.

plugin.tx_cbfoundation.settings.js.loadall
If true, all needed Foundation JavaScript libraries are loaded. Otherwise, this is your responsibility to load all the Foundation JavaScript components you need. Those components are located into EXT:cb_foundation/Resources/Public/JavaScript/foundation/.
plugin.tx_cbfoundation.settings.js.jquery
If typo3, loads jquery included in TYPO3 installation. If ext, loads jquery from the extension. In that case, you should take care of not loading jquery twice, from another extension for example. If no, do not loads jquery. This is then your responsibility to ensure jquery is loaded from somewhere else.
plugin.tx_cbfoundation.settings.js.modernizr
If true, includes modernizr, and add no-js class to the html tag. If false, it is your responsibility to include it. modernizr is a JavaScript script that test the browser for various HTML5 and CSS3 features.
plugin.tx_cbfoundation.settings.viewport
If true, add the viewport meta tag needed for Foundation, in the header of the document. If false, it is your responsibility to add this meta information to the document.

Orbit Slider configuration

Under the FOUNDATION.ORBIT category.

plugin.tx_cbfoundation.settings.orbit.animation
Animation style: Sets the type of animation used for transitioning between slides (default: slide).
plugin.tx_cbfoundation.settings.orbit.timer_speed
Timer speed: Sets the amount of time in milliseconds before transitioning a slide (default: 10000).
plugin.tx_cbfoundation.settings.orbit.pause_on_hover
Pause on hover: Pauses on the current slide while hovering (default: true).
plugin.tx_cbfoundation.settings.orbit.resume_on_mouseout
Resume on mouseout: If pause on hover is set to true, this setting resumes playback after mousing out of slide (default: false).
plugin.tx_cbfoundation.settings.orbit.next_on_click
Next on click: Advance to next slide on click (default: true).
plugin.tx_cbfoundation.settings.orbit.animation_speed
Animation speed: Sets the amount of time in milliseconds the transition between slides will last (default: 500).
plugin.tx_cbfoundation.settings.orbit.stack_on_small
Stack on small: (default: false).
plugin.tx_cbfoundation.settings.orbit.navigation_arrows
Navigation arrows: (default: true).
plugin.tx_cbfoundation.settings.orbit.slide_number
Slide number: (default: true).
plugin.tx_cbfoundation.settings.orbit.slide_number_text
Slide number text: (default: 'of').
plugin.tx_cbfoundation.settings.orbit.container_class
Container class: (default: 'orbit-container').
plugin.tx_cbfoundation.settings.orbit.stack_on_small_class
Stack on small class: (default: 'orbit-stack-on-small').
plugin.tx_cbfoundation.settings.orbit.next_class
Next class: Class name given to the next button (default: 'orbit-next').
plugin.tx_cbfoundation.settings.orbit.prev_class
Prev class: Class name given to the previous button (default: 'orbit-prev').
plugin.tx_cbfoundation.settings.orbit.timer_container_class
Timer container class: Class name given to the timer (default: 'orbit-timer').
plugin.tx_cbfoundation.settings.orbit.timer_paused_class
Timer paused class: Class name given to the paused button (default: 'paused').
plugin.tx_cbfoundation.settings.orbit.timer_progress_class
Timer progress class: Class name given to the progress bar (default: 'orbit-progress').
plugin.tx_cbfoundation.settings.orbit.slides_container_class
Slides container class: (default: 'orbit-slides-container').
plugin.tx_cbfoundation.settings.orbit.bullets_container_class
Bullets container class: (default: 'orbit-bullets').
plugin.tx_cbfoundation.settings.orbit.slide_selector
Slide selector: (default: 'li').
plugin.tx_cbfoundation.settings.orbit.bullets_active_class
Bullets active class: Class name given to the active bullet (default: 'active').
plugin.tx_cbfoundation.settings.orbit.slide_number_class
Slide number class: Class name given to the slide number (default: 'orbit-slide-number').
plugin.tx_cbfoundation.settings.orbit.caption_class
Caption class: Class name given to the caption (default: 'orbit-caption').
plugin.tx_cbfoundation.settings.orbit.active_slide_class
Active slide class: Class name given to the active slide (default: 'active').
plugin.tx_cbfoundation.settings.orbit.orbit_transition_class
Orbit transition class: (default: 'orbit-transitioning').
plugin.tx_cbfoundation.settings.orbit.bullets
Bullets: Does the slider have bullets visible? (default: true).
plugin.tx_cbfoundation.settings.orbit.circular
Circular: Does the slider should go to the first slide after showing the last? (default: true).
plugin.tx_cbfoundation.settings.orbit.timer
Timer: Does the slider have a timer visible? (default: true).
plugin.tx_cbfoundation.settings.orbit.variable_height
Variable height: Does the slider have variable height content? (default: false).
plugin.tx_cbfoundation.settings.orbit.swipe
Swipe: (default: true).
plugin.tx_cbfoundation.settings.orbit.before_slide_change
Before slide change: Execute a function before the slide changes (default: noop).
plugin.tx_cbfoundation.settings.orbit.after_slide_change
After slide change: Execute a function after the slide changes (default: noop).

Clearing Lightbox configuration

Under the FOUNDATION.CLEARING category.

plugin.tx_cbfoundation.settings.clearing.close_selectors
Specify the classes or IDs will close clearing when clicked. (default: '.clearing-close').
plugin.tx_cbfoundation.settings.clearing.touch_label
Label for touch environment. (default: '← Swipe to Advance →').

Magellan configuration

Under the FOUNDATION.MAGELLAN category.

plugin.tx_cbfoundation.settings.magellan.active_class
Specify the class used for active sections (default: 'active')
plugin.tx_cbfoundation.settings.magellan.threshold
How many pixels until the magellan bar sticks (default: 0 = auto).
plugin.tx_cbfoundation.settings.magellan.destination_threshold
Pixels from the top of destination for it to be considered active (default: 20).
plugin.tx_cbfoundation.settings.magellan.throttle_delay
Calculation throttling to increase framerate (default: 50)

Filter by categories

It is possible to filter images displayed in Orbit slider or in Clearing lightbox using categories assigned to the file objects. You first need some categories to be defined. You can create them in the List module. The you need to assign categories to images. You can do it when you edit file properties in the Filelist module. Finally, you assign the categories to display in plugin.tx_cbfoundation.settings.orbit.categories or plugin.tx_cbfoundation.settings.clearing.categories TypoScript setup.

For instance, if you define

plugin.tx_cbfoundation.settings.orbit.categories = 1,2

only images having category id 1 or category id 2 (or both), and images having no category assigned, will be displayed.

Customizing CSS

There are many ways you can customize Foundation style sheets to adapt them for your website. The prefered way is Using SASS, but in simpler projects, you could also simply use Default Foundation CSS, or Custom Foundation CSS.

Default Foundation CSS

Loading Foundation framework (default CSS) static template, as described above, will give you all the CSS needed for using Foundation features. However, it comes with predefined colors and styles that could not match the design of your website. Furthermore, using default CSS causes all websites to look similar.

A first way to customize CSS would be to copy the foundation css file somewhere else, and to modify the plugin.tx_cbfoundation.settings.css_path TypoScript constant (it can be done in the constant editor) to point the modified file. However, maintaining this could be cumbersome.

Custom Foundation CSS

A other simple way to customize the CSS of your website is to generate the custom CSS file using the tool on the Foundation website. After downloading the generated zip archive, you simply need to copy the css/foundation.min.css file somewhere on your website installation, and to modify the plugin.tx_cbfoundation.settings.css_path TypoScript constant to point to it, as described before. Do not forget to load Foundation framework (default CSS) static template first.

Using SASS

Sass describes itself as the most mature, stable, and powerful professional grade CSS extension language in the world. It is a CSS pre-processor, allowing to simplify the process of managing large and complex style sheets. It includes variables, nesting, mixins, inheritance, etc.

Sass (or scss) files need to be compiled to normal CSS files, in order to use it. To do so, you need the sass processor, which is a command line tool written in Ruby. However, you do not want to think about regenerating CSS files each time you modify the scss file. This is why other tools exist to simplify the process. One of them is compass. Compass also is written in Ruby. You simply need a configuration file, then you launch the compass process, and it watches your scss files continuously. Each time you modify them, CSS files are regenerated on the fly.

To install sass and compass, you first need to have a working Ruby environment. On a Debian or Ubuntu system, you can do this using the following command:

sudo apt-get install ruby-full rubygems

Then, you need to install sass and compass:

sudo gem update --system
sudo gem install compass

Using sass is the preferred way to customize foundation style sheets. However, this require a little more setup. Here are the required steps to use it along with this TYPO3 Foundation framework extension:

  1. Copy compass configuration file config.rb, located into EXT:cb_foundation/Files/, to a convenient location. It could be a the root of your TYPO3 installation, or at the root of a custom extension you use for your website template.
  2. Copy scss files _settings.scss and app.scss, also located into EXT:cb_foundation/Files/, to a directory than will contain your scss files. If you are using a custom extension for your website template, it could be located in Resources/Private/Scss/ of this custom extension. app.scss can be renamed as you wish.
  3. Modify the config.rb file you previously copied. The add_import_path directive should point to EXT:cb_foundation/Resources/Private/Scss/foundation. sass_dir should point to the directory where you copied _settings.scss and app.scss files. css_dir and images_dir should respectively point to the public directories where CSS and images for your website are stored. Finally, javascripts_dir should point to EXT:cb_foundation/Resources/Public/JavaScript. In all those examples, EXT: refers to the path of the extensions (typo3conf/ext) and should not be written literally. All paths can be relative to the config.rb file, or absolutes. The given config.rb should work without any modifications if put in the root directory of an extension installed on the same installation that cb_foundation.
  4. Start compass by typing compass watch in a terminal, in the directory containing config.rb file.
  5. Include app.css file in your website, either using TypoScript or manually adding it to your html template. This file will be generated in the CSS directory you specified in config.rb file.

You can now start customizing the style sheets of you website, by modifying app.scss and _settings.scss files. Every scss file you will add to the Scss directory you created will automatically generate a corresponding css file int the Css directory.

Upgrading SASS

Foundation 5.5 now is compatible with Sass 3.4. Therefore, you can now upgrade both Sass and Compass to the latest version.

sudo gem install sass
sudo gem install compass

Customizing templates

As usual for Extbase extensions, paths to Fluid templates are defined in plugin.tx_cbfoundation.view.templateRootPath, plugin.tx_cbfoundation.view.partialRootPath, and plugin.tx_cbfoundation.view.layoutRootPath TypoScript setup. Those values are controlled by TypoScript constants having similar names. Currently, only templates are used (no layouts or partials).

If you want to modify the Fluid templates, you only need to copy the current Templates folder elsewhere, and to adjust TypoScript setup accordingly. Templates/CmsLayout is used for the preview in backend. You should not need to modify it.