YAML Integration

YAML is a CSS framework developped by Dirk Jesse, for modern, flexible, browser-tolerant and accessible multi-column layouts (see www.yaml.de/en/). conceptcms support for YAML basically consists in:

  1. YAML can be downloaded and installed (imported)in a conceptcms-compatible format as Open Source version.
  2. After import into conceptcms, all YAML-CSS are grouped under "YAML" (for the "core") and "MyYaml" (for CSS you could/should modify).
  3. All paths within YAML (import of CSS, paths to JavaScript and images) work in conceptcms (they are automatically converted on saving).
  4. A few images and JavaScript code is automatically provided; in this case, paths are automatically converted on saving, too.

 

Note: YAML is licensed under the Creative Commons Attribution 2.0 (CC-A 2.0) Open Source License. If you want to use YAML without cost, you have to set a link to the YAML homepage (http://www.yaml.de) in your Website footer or your imprint. As an alternative, you can buy a license. Please consider the terms and conditions of the license (see http://www.yaml.de/en/license/license-conditions.html).

Install YAML

Download the version you need under www.conceptcms.com. We offer "YAML Only" (only CSS files) or "YAML with Examples" (CSS and some example templates already working in conceptcms).

Installation in conceptcms is done via the Website/Customer-Import (see Website-Import). In fact our YAML version consists of an empty Website, just with CSS (and examples, if applicable).

Installation into an existing customer is possible without problems. Existing CSS or templates are not touched during the import, alle YAML files are just added.

After successfull import, in your stylesheet list (see Manage CSS / Stylesheet List), the groups "YAML" and "MyYaml" as well as the both CSS "master.css" and "master_ie_patches.css" will appear. If you already had these master CSS, they will be now doubledn and you should revise and "consolidate" them.

You can buy a license at any time under shop.yaml.de/index.php in order to avoid the mandatory link to the YAML homepage.

Use YAML

Basically, you can use YAML according to your personal preferences. From conceptcms point of view, the following procedures are relevant if you want to fully benefit from YAML within conceptcms.

In general, you should never modify the YAML core. All modifications should take place via separate CSS (applying the cascade). Find more information under www.yaml.de/EN/.

ImportingYAML-Entry-CSS into the Master-CSS

conceptcms requires a so-called Master-CSS (master.css) for different reasons (see Master Stylesheet / Default Stylesheet / IE Hacks). In addition, there should be a separate Master-CSS for browser patches (master_ie_patches.css). These two CSS are no YAML-CSS, but they are essential for conceptcms and are used to import the respective YAML "Entry"-CSS. Usually, we are talking about:

  • master.css imports the YAML-CSS my_layout.css
  • master_ie_patches.css imports the YAML-CSS patch_my_layout.css

Import has to take place with the real file name in conceptcms (in this case, it is not possible to automatically re-write the name/path):

  • @import url(./ID_usr_style.css); where ID is the ID of the respective YAML-CSS in conceptcms (this ID is not fixed and can vary from installation to installation; it is displayed in the stylesheet list).

 

If you make a complete import of YAML into an empty Website, both CSS, master.css and master_ie_patches.css are already included, so that you can ignore the instructions above, import is already written into the Master-CSS with the correct ID. Only if you are importing into a Website that already has a Master-CSS, you need to consider that the existing and the new Master-CSS should be checked and consolidated into one CSS (same for the Master-CSS for patches).

Appropriate Use of the Cascade for YAML CSS

If you use YAML outside of conceptcms, you probably would write all individual changes and enhancements into the respective CSS files provided for this purpose by YAML (e.g.. into basemod.css and content.css) - as long as you do not touch the core, this is perfect. You can proceed this way within conceptcms, too - especially if your Website is not very complex and everything is based on YAML.

However, sometimes it might make sense not to touch the YAML CSS at all, but to write your modifications and enhancements in separate CSS. This would create another level of the cascade, and would grant you the option to flexibly handle situations where for example a YAML-based class needs to have different values at different places in the same Website.

Example for Working with YAML for Template Sets

A typical case is working with imported Template Sets; this can best be explained with an example:

We provide - usually always YAML-based - Template Sets (see Website Export (version 5.1 and higher)). They consist of structural and HTML template/s, and bring their own styles, too, as we use styles to format everything. So we also provide a separate CSS file which then could be modified by you according to your colour schemes, measures etc. However, we have to solve two problems now:

  1. Our styles need to be delivered in a way that they can be integrated easily into every (of course YAML-based) Website without getting into conflict with existing definitions.
  2. If someone imports more than one Template Set (which might be common), it is required that you can define which CSS should be included and which not (at least in theory it is possible that different Template Sets provide different values for the same YAML-based/inherited class, so that the CSS for different Template Sets might not be compatible).

We solve these problems by delivering a separate CSS file for each Template Set (e.g. news_tpl_01.css). This CSS might/will contain definitions that refer to YAML classes (applying the cascade).

You could now do the following:

  1. Import the CSS file provided with the Template Set into the "entry" CSS of YAML (my_layout.css). This is usually the recommended action.
  2. However, you also could import this CSS directly into master.css, but this would not exactly reflect the logic of YAML.

In this case (case 1), the my_layout.css importing section could look like:

/* import core styles | Basis-Stylesheets einbinden */
@import url(./48_usr_style.css);


/* import screen layout | Screen-Layout einbinden */ 

/* basemod.css */
@import url(./55_usr_style.css);

/* content.css */
@import url(./56_usr_style.css);

/* forms.css */
@import url(./61_usr_style.css);

/* nav_shinybuttons.css */
@import url(./50_usr_style.css);
/* nav_shinybuttons.css customized*/

/* nav_slidingdoor.css */
@import url(./51_usr_style.css);
/* nav_slidingdoor.css customized*/
 
/* nav_vlist.css */
@import url(./52_usr_style.css);
/* nav_vlist.css customized*/


/* import conceptcms template set CSS | conceptcms Vorlagen CSS einbinden */
/*this is the file name of news_tpl_01.css (in this example)*/
@import url(./12_usr_style.css);
 

On the one hand, we benefit from the cascade (we did not modify any YAML CSS, but can refer to all YAML CSS), on the other hand, all our individual definitions and modifications of classes from YAML CSS are defined separately and can easily be controlled via CSS exceptions on the level of menu items (see Manually Modified Stylesheet Handling).

If we had provided our classes and modifications directly in a YAML CSS, there would be no way to include/not include them in a controlled way without affecting the rest of the Website, and in addition users would need to write "our" modifications into "their" CSS, this way mixing up things.

Note: In general - and independent from YAML -, you should only create those styles as part of master.css and master_ie_patches.css that need to be placed there to be usuable from CE (see CSS Conventions for the Master Stylesheet; and even in this case we recommend not to define the classes directly in master.css, but to do this in a separate CSS and just call them with empty values). For transparency reasons, all other styles usually should be written into separate CSS. This way, you can switch all these styles on or off via CSS exceptions in your menu item template/s (see Manually Modified Stylesheet Handling).

Paths and Names in YAML - Automatic Re-Writing

conceptcms re-writes all original paths and names contained in original YAML CSS files (import of CSS, path to JavaScript, path to images) on saving into paths/names that fit the logic of conceptcms. This works alway, whenever a YAML path/name appears, it will be converted again.

Something like

@import url(../yaml/navigation/nav_shinybuttons.css);

would be converted to e.g.

@import url(./ID_usr_style.css);

(where the ID is specific for the installtion/customer).

Or

url("images/shiny_buttons/background.png")

is converted into

url(../../external/yaml/v_3.1/yaml/navigation/images/shiny_buttons/background.png)

In CSS files you have once saved, you will never see YAML  paths or names, but paths and names compatible with conceptcms.

Important Note: Automatic recognition and re-writing of YAML paths/names only works if these paths/names match exactly the specifications from the original YAML package. If you change names of CSS delivered with the YAML package, or if you change a path, e.g. in code generated with the YAML Builder, our mechanism fails.
If you have copied something, we recommend that you check if the re-writing has worked correctly and to manually modify the paths in case there was a problem. If you do a full import of YAML once, this should not be an issue anyway.

Use YAML Builder

Due to our re-writing mechanism (see above), you can use the YAML-Builder (see builder.yaml.de) to create CSS code for the following YAML-CSS:

  • my_layout.css
  • patch_my_layout.css
  • basemod.css

You can just copy this code form YAML-Builder  and insert it into the respective CSS. All paths will automatically be converted on saving into conceptcms-compatible formats. You might also use the HTML code offered by the YAML builder as base for your menu item and document templates.

If you use YAML-Builder, of course you should take care that you don't overwrite existing individual ode in your YAML CSS.

Update YAML

There is no automated update mechanism for YAML within conceptcms, as we can never know if an update is compatible with your website implementation. However, you can make the changes for a new version manually in the code of the existing files. This is the only case where modifying the core is okay.

You should under all circumstances avoid importing YAML into a customer in conceptcms who already uses YAML. This also applies for complete Website-Templates that also usually contain YAML. If you double-import YAML, nothing will be overwritten, but all files will exist twice after the import. Automatic path rewriting won't work any longer, and the user might have serious difficulties to distinguish which files are used and which not.

YAML Versions

We usually try to make the newest YAML version available for conceptcms as soon as possible. This version is then offered under www.conceptcms.com for download. However, there are a few things inside of conceptcms that need to be modified, too: We need to create a new sub-directory for the respective YAML version and might to add images and scripts (these components might not be delivered with the download, but are part of conceptcms); in addition we might need to adapt the re-writning mechanism to the new version (names and paths might change or paths are added). In the meantime, you might already be able to use the newest YAML version, but maybe minor things don't work until we provide the update for conceptcms, too. This happens usually with the next upcoming conceptcms release after we have released the YAML download.

If you want to be sure on the version currently fully supported, you might look for the directory

../../external/yaml/

in your installation. The following subdirectory is the version (scheme /v_3.1/). If you feel comfortable with this, of course you could at least add the new structure on your own, just following the logic you see for the existing one/s. However, this would maybe not help you with automatic re-writing, but you could do this manually, too.

Please note that every conceptcms version supports exactly one YAML version as regards the automatic re-writing of paths. Once updated to a specific version of YAML, all paths will be re-writen for this version. However, this does not affect your existing implementation at all, as for your existing YAML CSS, all re-writing has been done already and will go on pointing to the version you have used. We will always preserve the structure for all former versions and they won't stop working. Only if you would now take e.g. code from YAML Builder and would copy it into one of your YAML CSS, the re-writing would now re-write it to the current version (which even could be desired and of course can be manually corrected).