Hitch "Native" - out of the box:
Version 0.5

Hitch Native Docs

This document describes additional expressive capabilities that come with the hitch library itself and are gained by the inclusion of hitch.js.

Table of Contents

  1. 1. CSS
    1. 1.1 @ Rules
      1. 1.1.2 @-hitch-requires
      2. 1.1.1 @-hitch-const
    2. 1.2 Predefined Constants/Variables
      1. 1.2.1 -hitch-beta
      2. 1.2.2 :-hitch-args
    3. 1.3 Pseduo Selectors
      1. 1.3.1 Logical
        1. 1.3.1.1 :-hitch-anyof
        2. 1.3.1.2 :-hitch-allof
        3. 1.3.1.3 :-hitch-noneof
        4. 1.3.1.4 :-hitch-oneof
      2. 1.3.2 Structural
        1. 1.3.2.1 :-hitch-has
  2. 2. HTML
    1. 2.1 data-hitch-interpret attribute
    2. 2.2 data-hitch-widget attribute

1. CSS

Hitch adds numerous expressive capabilities to CSS (when the stylesheet is appropriately tagged - see data-hitch-interpret) immediately, these are listed and described below. Note that all of these extensions use the vendor prefix -hitch- in accordance with CSS's Vendor Specific Extensions and conform to CSS's Forward Compatible Parsing Rules, as, though they are currently pre-processed, at least parts of the hitch approach could be adopted in a more native fasion. Hitch is designed with this in mind.

1.1 @ Rules

Hitch adds two new preprocessor at-rules. Like other pre-processor rules, they should appear at the top of your sheet by convention:

1.1.1 @-hitch-requires

The requires at-rule begins with the @ symbol, followed by "-hitch-requires" followed by whitespace, followed by a url or "package url" (described below) and is terminated with a semi-colon. This rule allows the author of CSS to require new selector hitches for use within the sheet. These are downloaded and 'hitched' on providing new expressive capabilities.

The @-hitch-requires rule is not bound by the same origin policy.

A number of hitches publicly available for use can be found in the Public Hitch Repo. The Repository also allows registration of short, memorable names of modules which are well documented, versioned and available in a public version control system. Registration allows use of package urls in requires as well as browseability and automatic caching / placement into a CDN.

Given the rules:

@-hitch-requires  http://www.foo.com/myHitch.js;
@-hitch-requires  package:bkardell.math/1;

Before processing, the hitch engine will fetch the hitches above and make the capabilites that they describe available for use within the CSS. (See the documentation for bkardell.math/1 for for an example of the expressive capabilities that would be added by requiring that.

1.1.2 @-hitch-const

The const at-rule begins with the @ symbol, followed by "-hitch-const" followed by whitespace, followed by a token identifier (whitespace and ';' are explicitly disallowed) identifying some text to be replaced followed by whitespace, followed by text to replace it with (';' is explicitly disallowed) and terminated with ';'.

Note that pre-processing like this can only remain conformant to forward compatiable syntax if you make an effort to limit your tokens to compatible values. It may be worthwhile to use traditional programming practice to uppercase constanants, it may be useful to purposely break the syntax in order to "stand out in the code". Hitch makse no such value judgement, it merely provides a text-replacement capability. Use it as you will.

Given the rules:

@-hitch-const  -MAIN-COLOR  #f56789;
@-hitch-const -SECONDARY-COLOR  #8989f6;

div{ background-color: -MAIN-COLOR; border: 1px solid -SECONDARY-COLOR; }
span.title{ color: -SECONDARY-COLOR; }

Before processing, the hitch engine will perform the text replacements so that the browser will see the rules as:

div{ background-color: #f56789; border: 1px solid #8989f6; }
span.title{ color: #8989f6; }

Note that the example above uses a prefixed dash and traditional uppercase format for constants, however the tokens could just have easily been defined as "@main.color" or "$main_color". It's merely preference.

1.2 Predefined Constants/Variables

Hitch pre-defines potentially useful "constants" which perform simple text replacements.

1.2.1 @-hitch-beta

The beta constant is "-hitch-beta".Its purpose is to allow the author to selectively "un-prefix" features which are "compatible enough" across implementations for their purposesand nearing approval but have not yet been finalized by W3C and are therefore currently vendor prefixed. As the name implies, authors should use this rule with caution. It has the multiple advantages of working with the current system of prefixing, making it easier for authors to write and simultaneously not creating a necessary "break point" by not making the assumption that the final version will fully match the currently prefixed versions.

Given the rules:

div:-hitch-beta-any(.foo, .bar, .bat) span{  background-color: red;  }

.x:hover{
	-hitch-beta-transition-property:  background-color;
	-hitch-beta-transition-duration: 1.5s;
}
	   

Hitch will perform a text replacement where -hitch-beta is replaced by the viewer's browser's vendor prefix. For example, if the user is currently using Firefox, the rules would become:

div:-moz-any(.foo, .bar, .bat) span{  background-color: red;  }

.x:hover{
	-moz-transition-property:  background-color;
	-moz-transition-duration: 1.5s;
}
	   
1.2.2 :-hitch-args

The args constant is ":-hitch-args". It can only be used inside another constant and its purpose is to allow "wrapping" replacements that capture values that they wrap (in parenthesis).

Given the rules:

@-hitch-const -tab  .tabcontainer .tabpanel:nth-child(:-hitch-args);
	   
-tab(1){ background-color: red; }
-tab(2){ background-color: white; }
-tab(3){ background-color: blue; }

	   
	   

Hitch will perform a text replacement where :-hitch-args is replaced by the value captured in parenthesis at point of use, to create:

.tabcontainer .tabpanel:nth-child(1){ background-color: red; }
.tabcontainer .tabpanel:nth-child(2){ background-color: white; }
.tabcontainer .tabpanel:nth-child(3){ background-color: blue;  }

1.3 Pseudo Selectors

Hitch pre-defines a few potentially useful selector hitches "out of the box".

1.3.1 Logical

Logical selector hitches provide set and logic gate operations to add very powerful selectors.

All of the examples regarding Logical selectors are based on the following markup:

1.3.1.1 :-hitch-anyof

The "any of" hitch provides a way to filter elements based on whether they match ANY of the provided selector(s) (that is, selectors are OR'ed together) which may express different paths in the same tree.

Given the markup introduced at the top of section 1.3.1:

.cars div:-hitch-anyof(.foreign .used, .domestic .new) .cheap p{  background-color: red;  }

The following elements would have a red background:

<p class="car">2012 Ford Fiesta</p>
<p class="car">2009 Kia Forte</p>
<p class="car">2005 Toyota Camry</p>

Because each meets at least one of the criteria of being a descendant of .foreign that is .used OR a descendant of .domestic which is .new.

1.3.1.2 :-hitch-allof

The "all of" hitch provides a way to filter elements based on whether they match ALL of the provided selector(s) (that is, selectors are AND'ed together) which may express different paths in the same tree.

Given the markup introduced at the top of section 1.3.1:

.cars div:-hitch-allof(.new > div, .domestic .fast) p{ background-color: blue; }

The following elements would have a blue background:

<p class="car">2010 Dodge Charger</p>

Because it is both a <div> that is a child of .new AND is a descendant of .domestic and has the class .fast.

1.3.1.3 :-hitch-noneof

The "none of" hitch provides a way to filter elements based on whether they match NONE of the provided selector(s) (that is, selectors are NOR'ed together) which may express different paths in the same tree.

Given the markup introduced at the top of section 1.3.1:

.efficient:-hitch-noneof(.domestic .used, .foreign .new) p{  color: orange; }

The following elements would have orange text:

<p class="car">2012 Ford Fiesta</p>
<p class="car">2012 Chrysler 300</p>

<p class="car">2005 Toyota Camry</p>

Because they are neither descendants of .domestic which are .used NOR descendants of .foreign which are .new.

1.3.1.4 :-hitch-oneof

The "none of" hitch provides a way to filter elements based on whether they match EXACTLY ONE of the provided selector(s) (that is, selectors are XOR'ed together) which may express different paths in the same tree.

Given the markup introduced at the top of section 1.3.1:

.cars div:-hitch-oneof(.cheap, .small) p{  border: 1px solid green; }

The following elements would have a 1px solid green border:

<p class="car">2004 Chevy Malibu</p>
<p class="car">2012 Kia Forte</p>

<p class="car">2005 Toyota Camry</p>

Because they are .cheap OR .small exclusively (not both).

1.3.2 Structural

Structural selector hitches provide abilities to select based on structural criteria.

1.3.2.1 :-hitch-has

The "has" hitch provides a way to filter elements based on whether their descendants match any of the provided selector(s). Provided selectors may begin with a combinator, implying 'the element on which the has filter is being applied'

Given the markup introduced at the top of section 1.3.1:

 div:-hitch-has(>.fast){  background-color: red;  }

The following elements would have a red background:

<p class="car">2012 Ford Fiesta</p>

<div class="new" id="a" >...</div>
<div class="used" id="b" >...</div>

Because because they meet the criteria that they contain (has) a child which is .fast.

2. HTML

Hitch adds a small set of expressive capabilities to HTML by way of micro-data. All hitch html attributes follow the forward compatible parsing / vendor extension model of being prefixed with data-hitch-*.

2.1 data-hitch-interpret attribute

The data-hitch-interpret attribute is a boolean attribute which can be placed on <link> and <style> tags indicating that they require Hitch.

<style type="text/css" data-hitch-interpret > 
    ... anything in here can use hitch ...
</style>

2.2 data-hitch-widget attribute

The data-hitch-widget attribute provides a means to indicate a binding with a micro-data based hitch, allowing the element to be decorated or replaced accordingly. This is done by providing a URL or package: URI describing where the hitch definitions can be found and which hitch specifically to use here. The data-hitch-widget URL is not bound by the Same Origin Policy. Hitch takes care of ensuring that these files are requested only once.

<div data-hitch-widget="http://www.hitchjs.com/use/bkardell.paypal.simpledonate/1#simple-donate" 
	                data-paypal-email="[email protected]"
                    data-paypal-org="mycompany.com"> ... hitch will stick your paypal donation button here... </div>

See the describe documentation on this hitch for more information on the bkardell.paypal package version 1.