ar\css

This is a simple css generation and manipulation module.

Example:

<pinp>
  echo ar('css')->stylesheet()
  ->rule( 'h1', array(
    'font-family' => 'Georgia',
    'font-size'   => '20px'
  ) );
</pinp>

Results in:

<style type="text/css">
h1 {
  font-family: Georgia;
  font-size: 20px;
}
</style>

This module is meant for simple css for use in generic libraries. It allows you to fairly easily change generated css. It doesn't allow more than one entry of the same rule ( selector ) or a style in a rule. It does have support for variables in style values, e.g:

<pinp>
  echo ar('css')->stylesheet()
  ->rule( 'h1', array(
    'color' => 'var(menuColor)'
  ) )
  ->bind('menuColor', 'black');
</pinp>

Results in:

<style type="text/css">
h1 {
  color: black;
}
</style>

methods

(object) stylesheet Returns a stylesheet object

stylesheet

(object) ar('css')->stylesheet()

Returns a stylesheet object, which implements the ar_htmElement class. This object has the following additional properties:

(object) rules A list of css rules.

The rules object can be accessed as an array and has the form:

array( 'selector' => array( 'style' => 'value' ) )

The stylesheet object implements the following methods:

(object) add Adds the given styles to the rule with the given selector or adds a new rule.
(object) bind Adds a value for a given variable or a list of values for a list of variables.
(object) copy Copies the styles from a given rule and adds them to a new or existing rule.
(object) delete Removes the styles from a given rule or the entire rule.
(object) find Searches the rules for matching selectors and returns a subset of the stylesheet object.
(object) import Parses a string in css format and adds the styles in it to the rules property.
(object) rename Renames a given selector to a new selector.
(object) rule Sets the rule with the given selector to the given styles or creates a new rule.

add

(object) $cssStyleSheet->add( $selector, $styles )

(string) $selector The selector for the rule.
(array) $styles The styles to add to the rule.

Adds the given styles to the rule with the given selector. If a style in the $styles array already exists in the existing rule, the existing style will be overwritten with the supplied style. Returns the stylesheet object.

bind

(object) $cssStyleSheet->bind( $variable, $value = null )

(string) $variable The name of the variable used in the css style values or a list of variables with their values.
(string) $value The value to substitute for the variable.

Adds a variable with the given value to the stylesheet. Style values can use this value as follows:

<pinp>
  echo ar('css')
  ->rule( 'h1', array( 'border' => '1px solid var(borderColor)' ) )
  ->bind( 'borderColor', 'black' );
</pinp>

You can add a list of variables with values in one call like this:

<pinp>
  echo ar('css')
  ->rule( ... )
  ->bind( array( 
    'borderColor' => 'black', 
    'fontColor' => 'white' 
  ) );
</pinp>

Returns the stylesheet object.

copy

(object) $cssStyleSheet->copy( $selector, $newSelector )

(string) $selector The selector of the rule to copy.
(string) $newSelector The new selector for the copied rule.

Copies the rule with the given selector to a new rule with the new selector. If a rule exists with that new selector, the styles will be added to it. Returns the stylesheet object.

delete

(object) $cssStyleSheet->delete( $selector, $styles = null )

(string) $selector The selector of the rule to delete.
(array) $styles The styles to delete from this rule. If not set the entire rule will be removed.

Removes the rule or the specified styles from the rule. Returns the stylesheet object.

The $styles array must only contain the style to remove, e.g:

<pinp>
  $css->delete( 'h1', array( 'border', 'font' ) );
</pinp>

find

(object) $cssStyleSheet->find( $search )

(string) $search The regular expression to search for. Must be in the format used by preg_match().

Returns a search result object (ar_cssSearch) with all the rules with a matching selector. The search result object has the following methods:

(object) add Adds the given styles to all the matching rules.
(object) apply Applies the changes to the original stylesheet and returns that.
(object) delete Removes the styles from the matching rules, or removes the matching rules.
(object) rename Renames the matching rules. The new name may contain back references to the regular expression used in find, just like in preg_replace().
(object) rule Overwrites the styles of the matching rules with new styles.

You must use 'apply()' to apply the changes to the original stylesheet. e.g.:

<pinp>
  $css->find( '/(.*)h1(.*)/i' )->rename( '$1h2$2' )->apply();
</pinp>

add

(object) $cssSearch->add( $styles )

Adds the given styles to all the matching rules.

apply

(object) $cssSearch->apply()

Applies the changes made to the original stylesheet and returns that.

delete

(object) $cssSearch->delete( $styles = null )

Removes the given styles from the matching rules. If no styles are given all matching rules are removed entirely.

rename

(object) $cssSearch->rename( $newSelector )

Renames the matching rules to the new selector. $newSelector may include back references to the original regular expression used by find(), just like in preg_replace().

rule

(object) $cssSearch->rule( $styles )

Sets the styles of the matching rules to $styles. Overwrites any previous values.

import

(object) $cssStyleSheet->import( $cssText )

(string) $cssText The css to import.

Parses the given css and adds the rules to the stylesheet. It can only parse correct css. It has no support for linked stylesheets or media rules (@import and @media). If the same selector occurs multiple times, only one rule will be added for it. If the same style is set multiple times with the same selector, only the last value is kept. Returns the stylesheet object.

rename

(object) $cssStyleSheet->rename( $selector, $newSelector )

(string) $selector The selector of the rule to rename.
(string) $newSelector The new selector for the renamed rule.

Renames the rule with the given selector to the new selector. If a rule exists with the new selector, the styles will be added to it. Returns the stylesheet object.

rule

(object) $cssStyleSheet->rule( $selector, $styles )

(string) $selector The selector for the rule.
(array) $styles The styles to set in the rule.

Sets the style of the given rule to the given styles. If a rule with the given selector already exists, it will be removed first. Returns the stylesheet object.