CKEditor 3.x/Developers Guide/Styles - Revision history

Anna: /* Stylesheet Parser Plugin */ Some clarification about styles added

2011-06-28T06:36:52Z

‎Stylesheet Parser Plugin: Some clarification about styles added

Anna: /* Limiting the CSS Selectors */ Some clarification added

2011-06-28T06:33:28Z

‎Limiting the CSS Selectors: Some clarification added

Anna: /* Stylesheet Parser Plugin */ API links added

2011-06-02T09:34:31Z

‎Stylesheet Parser Plugin: API links added

Anna: /* Stylesheet Parser Plugin */ Configuration values explained

2011-06-01T12:46:41Z

‎Stylesheet Parser Plugin: Configuration values explained

Anna: /* Stylesheet Parser Plugin */ Sample reference added

2011-05-31T11:35:26Z

‎Stylesheet Parser Plugin: Sample reference added

Anna: /* Stylesheet Parser Plugin */

2011-05-31T11:32:41Z

‎Stylesheet Parser Plugin

Anna: Stylesheet Parser Plugin section added

2011-05-31T11:32:24Z

Stylesheet Parser Plugin section added

Anna: Some clarification added

2011-05-31T08:20:08Z

Some clarification added

Anna: /* Style Types */ Article section proof-read

2011-03-08T18:30:18Z

‎Style Types: Article section proof-read

Anna: /* Style Rules */ Article section proof-read

2011-03-08T18:28:25Z

‎Style Rules: Article section proof-read

@@ Line 82: / Line 82: @@
 == Stylesheet Parser Plugin ==
-'''CKEditor 3.6''' introduced a simplified method of populating the '''Styles''' drop-down list with style definitions added in an external CSS stylesheet file. The '''Stylesheet Parser''' plugin (<code>stylesheetparser</code>) lets you use your existing CSS styles without the need to define the styles specifically for CKEditor in the format presented above.
+'''CKEditor 3.6''' introduced a simplified method of customizing the styles for the document created in CKEditor and populating the '''Styles''' drop-down list with style definitions added in an external CSS stylesheet file. The '''Stylesheet Parser''' plugin (<code>stylesheetparser</code>) lets you use your existing CSS styles without the need to define the styles specifically for CKEditor in the format presented above.
 To use the new style definition method you need to activate the <code>stylesheetparser</code> plugin for your CKEditor instances by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html#.extraPlugins extraPlugins]</code> configuration setting:

@@ Line 116: / Line 116: @@
 === Limiting the CSS Selectors ===
-You can also customize the default Stylesheet Parser plugin settings by setting the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html#.stylesheetParser_skipSelectors stylesheetParser_skipSelectors]</code> configuration value. The plugin will then ignore the CSS rules that match the regular expression and will not display them in the '''Styles''' drop-down list. The default value excludes all rules for the <code><body></code> element as well as classes defined for no specific element, but you can modify it to ignore a wider set of elements, like in the example below.
+You can also customize the default '''Stylesheet Parser''' plugin configuration by setting the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html#.stylesheetParser_skipSelectors stylesheetParser_skipSelectors]</code> configuration value. The plugin will then ignore the CSS rules that match the regular expression and will not display them in the '''Styles''' drop-down list nor use them to output the document content. The default value excludes all rules for the <code><body></code> element as well as classes defined for no specific element, but you can modify it to ignore a wider set of elements, like in the example below.
 <source lang="javascript">
 // Ignore rules for <body> and <caption> elements, classes starting with "high", and any class defined for no specific element.
 config.stylesheetParser_skipSelectors = /(^body\.|^caption\.|\.high|^\.)/i;
 </source>

@@ Line 84: / Line 84: @@
 '''CKEditor 3.6''' introduced a simplified method of populating the '''Styles''' drop-down list with style definitions added in an external CSS stylesheet file. The '''Stylesheet Parser''' plugin (<code>stylesheetparser</code>) lets you use your existing CSS styles without the need to define the styles specifically for CKEditor in the format presented above.
-To use the new style definition method you need to activate the <code>stylesheetparser</code> plugin for your CKEditor instances:
+To use the new style definition method you need to activate the <code>stylesheetparser</code> plugin for your CKEditor instances by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html#.extraPlugins extraPlugins]</code> configuration setting:
 <source lang="javascript">
 config.extraPlugins = 'stylesheetparser';
 </source>
-You then need to supply the location of the CSS file that contains your style definitions:
+You then need to supply the location of the CSS file that contains your style definitions by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html#.contentsCss contentsCss]</code> configuration setting:
 <source lang="javascript">
 config.contentsCss = 'sample_CSS_file.css';

← Older revision		Revision as of 12:46, 1 June 2011
Line 106:		Line 106:

	For an example of this usage scenario check the "Stylesheet Parser plugin" (<code>stylesheetparser.html</code>) sample from the <code>_samples</code> folder of your CKEditor installation package.		For an example of this usage scenario check the "Stylesheet Parser plugin" (<code>stylesheetparser.html</code>) sample from the <code>_samples</code> folder of your CKEditor installation package.
		+
		+	=== Choosing the CSS Selectors ===
		+	The '''Stylesheet Parser''' plugin can be fine-tuned to only take into account the CSS selectors that match the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html#.stylesheetParser_validSelectors stylesheetParser_validSelectors]</code> configuration value. The default regular expression accepts all CSS rules in a form of <code>''element''.''class''</code>, but you can modify it to refer to a limited set of elements, like in the example below.
		+
		+	<source lang="javascript">
		+	// Only add rules for <p> and <span> elements.
		+	config.stylesheetParser_validSelectors = /\^(p\|span)\.\w+/;
		+	</source>
		+
		+	=== Limiting the CSS Selectors ===
		+	You can also customize the default Stylesheet Parser plugin settings by setting the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html#.stylesheetParser_skipSelectors stylesheetParser_skipSelectors]</code> configuration value. The plugin will then ignore the CSS rules that match the regular expression and will not display them in the '''Styles''' drop-down list. The default value excludes all rules for the <code><body></code> element as well as classes defined for no specific element, but you can modify it to ignore a wider set of elements, like in the example below.
		+	<source lang="javascript">
		+	// Ignore rules for <body> and <caption> elements, classes starting with "high", and any class defined for no specific element.
		+	config.stylesheetParser_skipSelectors = /(^body\.\|^caption\.\|\.high\|^\.)/i;
		+	</source>

← Older revision		Revision as of 11:35, 31 May 2011
Line 103:		Line 103:
	<note>Please note that the '''Stylesheet Parser''' plugin is available in CKEditor 3.6 and later.		<note>Please note that the '''Stylesheet Parser''' plugin is available in CKEditor 3.6 and later.
	</note>		</note>
		+
		+
		+	For an example of this usage scenario check the "Stylesheet Parser plugin" (<code>stylesheetparser.html</code>) sample from the <code>_samples</code> folder of your CKEditor installation package.

← Older revision		Revision as of 11:32, 31 May 2011
Line 101:		Line 101:
	The new solution lets you configure the editor to use existing CSS stylesheet rules without the need to create separate style definitions for CKEditor. On the other hand, the previously used approach offers more control over which styles are available for the users, so both solutions can be employed interchangeably, according to your needs.		The new solution lets you configure the editor to use existing CSS stylesheet rules without the need to create separate style definitions for CKEditor. On the other hand, the previously used approach offers more control over which styles are available for the users, so both solutions can be employed interchangeably, according to your needs.

−	<note>Please note that the '''Stylesheet Parser''' plugin is available in CKEditor 3.6 and later.</note>	+	<note>Please note that the '''Stylesheet Parser''' plugin is available in CKEditor 3.6 and later.
		+	</note>

← Older revision		Revision as of 11:32, 31 May 2011
Line 80:		Line 80:
	* '''Object styles''' – applied to special selectable objects (not textual), whenever such selection is supported by the browser. These apply to the following elements: <code>a</code>, <code>embed</code>, <code>hr</code>, <code>img</code>, <code>li</code>, <code>object</code>, <code>ol</code>, <code>table</code>, <code>td</code>, <code>tr</code> and <code>ul</code>.		* '''Object styles''' – applied to special selectable objects (not textual), whenever such selection is supported by the browser. These apply to the following elements: <code>a</code>, <code>embed</code>, <code>hr</code>, <code>img</code>, <code>li</code>, <code>object</code>, <code>ol</code>, <code>table</code>, <code>td</code>, <code>tr</code> and <code>ul</code>.
	* '''Inline styles''' – applied to text selections for style rules using elements not defined in other style types.		* '''Inline styles''' – applied to text selections for style rules using elements not defined in other style types.
		+
		+	== Stylesheet Parser Plugin ==
		+	'''CKEditor 3.6''' introduced a simplified method of populating the '''Styles''' drop-down list with style definitions added in an external CSS stylesheet file. The '''Stylesheet Parser''' plugin (<code>stylesheetparser</code>) lets you use your existing CSS styles without the need to define the styles specifically for CKEditor in the format presented above.
		+
		+	To use the new style definition method you need to activate the <code>stylesheetparser</code> plugin for your CKEditor instances:
		+	<source lang="javascript">
		+	config.extraPlugins = 'stylesheetparser';
		+	</source>
		+
		+	You then need to supply the location of the CSS file that contains your style definitions:
		+	<source lang="javascript">
		+	config.contentsCss = 'sample_CSS_file.css';
		+	</source>
		+
		+	Finally, if you want to skip loading the styles that are used in CKEditor by default, you may set <code>stylesSet</code> to an empty value:
		+	<source lang="javascript">
		+	config.stylesSet = [];
		+	</source>
		+
		+	The new solution lets you configure the editor to use existing CSS stylesheet rules without the need to create separate style definitions for CKEditor. On the other hand, the previously used approach offers more control over which styles are available for the users, so both solutions can be employed interchangeably, according to your needs.
		+
		+	<note>Please note that the '''Stylesheet Parser''' plugin is available in CKEditor 3.6 and later.</note>

@@ Line 9: / Line 9: @@
 The following code shows how to register a sample style definition.
-<source language="js">
+<source language="javascript">
 CKEDITOR.stylesSet.add( 'my_styles',
+[
@@ Line 26: / Line 26: @@
 When the definitions are ready, you must instruct the editor to apply the newly registered styles by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html#.stylesSet stylesSet]</code> setting. This may be set in the <code>config.js</code> file, for example:
-<source language="js">
+<source language="javascript">
 config.stylesSet = 'my_styles';
 </source>
 === Using an External Styles Definition File ===
-The style definition registration call can be included in an external JavaScript file. This method is recommended, because it allows you to load the definitions only on opening the '''Styles''' drop-down list, thus decreasing the editor page loading time. This approach means, however, that the users opening the '''Styles''' list may feel a minor loading delay.
+The style definition registration call can be included in an external JavaScript file. This method is a recommended one, because it allows you to load the definitions only on opening the '''Styles''' drop-down list, thus decreasing the editor page loading time. This approach means, however, that the users opening the '''Styles''' list may feel a minor loading delay.
 By default, CKEditor uses the <code>plugins/styles/styles/default.js</code> file, which is a minified JavaScript file.
@@ Line 42: / Line 41: @@
 At that point, change the <code>stylesSet</code> setting to point the editor to your file:
-<source language="js">
+<source language="javascript">
 config.stylesSet = 'my_styles:/styles.js';
@@ Line 56: / Line 55: @@
 == Style Rules  ==
 The entries inside a style definition are called "style rules". Each rule defines the display name for a single style as well as the element, attributes, and CSS styles to be used for it. The following is the generic representation for it:
-<source language="js">
+<source language="javascript">
+{
-     name : 'Display name',
+     name : 'Name displayed in the Styles drop-down list',
-     element : 'tag name (for example "span")',
+     element : 'HTML element name (for example "span")',
      styles :
+     {
@@ Line 78: / Line 77: @@
 == Style Types  ==
 There are three kinds of style types, each one related to the element used in the style rule:
 * '''Block-level styles''' &ndash; applied to the text blocks (paragraphs) as a whole, not limited to the text selections. These apply to the following elements: <code>address</code>, <code>div</code>, <code>h1</code>, <code>h2</code>, <code>h3</code>, <code>h4</code>, <code>h5</code>, <code>h6</code>, <code>p</code>, and <code>pre</code>.
 * '''Object styles''' &ndash; applied to special selectable objects (not textual), whenever such selection is supported by the browser. These apply to the following elements: <code>a</code>, <code>embed</code>, <code>hr</code>, <code>img</code>, <code>li</code>, <code>object</code>, <code>ol</code>, <code>table</code>, <code>td</code>, <code>tr</code> and <code>ul</code>.
-* '''Inline styles''' &ndash; applied to text selections for style rules using elements not defined in the other style types.
+* '''Inline styles''' &ndash; applied to text selections for style rules using elements not defined in other style types.