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:
- Copy compass configuration file
config.rb
, located intoEXT: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. - Copy scss files
_settings.scss
andapp.scss
, also located intoEXT: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 inResources/Private/Scss/
of this custom extension.app.scss
can be renamed as you wish. - Modify the
config.rb
file you previously copied. Theadd_import_path
directive should point toEXT:cb_foundation/Resources/Private/Scss/foundation
.sass_dir
should point to the directory where you copied_settings.scss
andapp.scss
files.css_dir
andimages_dir
should respectively point to the public directories where CSS and images for your website are stored. Finally,javascripts_dir
should point toEXT: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 theconfig.rb
file, or absolutes. The givenconfig.rb
should work without any modifications if put in the root directory of an extension installed on the same installation that cb_foundation. - Start compass by typing
compass watch
in a terminal, in the directory containingconfig.rb
file. - 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 inconfig.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.