PageRenderTime 53ms CodeModel.GetById 19ms RepoModel.GetById 0ms app.codeStats 0ms

/docs/docs.html

https://github.com/conzi/lessphp
HTML | 347 lines | 273 code | 74 blank | 0 comment | 0 complexity | 366d447dbb21fc4ea7c4c0f8c93f6b27 MD5 | raw file
    

  1. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    2. 

  2. "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
    3. 

  3. 

  4. <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
    5. 

  5.   <head>
    6. 

  6. 	<meta http-equiv="Content-type" content="text/html; charset=utf-8" />
    7. 

  7. 	<link rel="stylesheet" type="text/css" href="style.css" media="screen" />
    8. 

  8. 	<link rel="alternate" type="application/rss+xml" title="lessphp changelog feed" href="http://leafo.net/lessphp/feed/" /> 
    9. 

  9. 	<title>Documentation - lessphp</title>
    10. 

  10.   </head>
    11. 

  11.   <body>
    12. 

  12. 	
    13. 

  13. 	<h1>Documentation - lessphp v0.2.0</h1>
    14. 

  14. 	<div class="content">
    15. 

  15. 

  16. 	<ul id="nav">
    17. 

  17. 		<li><a href="#start">Getting Started</a></li>
    18. 

  18. 		<li><a href="#language">The Language</a>
    19. 

  19. 			<ul><li><a href="#vars">Abstract Properties (Variables)</a></li></ul>
    20. 

  20. 			<ul><li><a href="#pvalues">Property Values &amp; Expressions</a></li></ul>
    21. 

  21. 			<ul><li><a href="#nested">Nested Blocks</a></li></ul>
    22. 

  22. 			<ul><li><a href="#mixins">Mixins &amp; Namespace Access</a></li></ul>
    23. 

  23. 			<ul><li><a href="#ablocks">Abstract Blocks</a></li></ul>
    24. 

  24. 			<ul><li><a href="#args">Mixin Arguments</a></li></ul>
    25. 

  25. 			<ul><li><a href="#import">Import Statement</a></li></ul>
    26. 

  26. 			<ul><li><a href="#strings">String Mixins</a></li></ul>
    27. 

  27. 			<ul><li><a href="#misc">Miscellaneous</a></li></ul>
    28. 

  28. 			<ul><li><a href="#differences">Differences from Ruby LESS</a></li></ul>
    29. 

  29. 		</li>
    30. 

  30. 		<li><a href="#interface">The Interface</a></li>
    31. 

  31. 	</ul>
    32. 

  32. 

  33. 	<p><strong>lessphp</strong> is a compiler that generates css from a small superset language that adds
    34. 

  34. 	many additional features seen in other languages. It is based off an original Ruby implementation
    35. 

  35. 	called <a href="http://lesscss.org/">LESS</a>. For the most part, <strong>lessphp</strong> is syntactically
    36. 

  36. 	compatible with LESS, with the exception of a few things noted below.</p>
    37. 

  37. 

  38. 	<a name="start"></a>
    39. 

  39. 	<h2>Getting Started</h2>
    40. 

  40. 	<p>Download the latest version of <strong>lessphp</strong> <a href="http://leafo.net/lessphp/">here</a>.</p>
    41. 

  41. 	<p>You can also find the latest development version in the <a href="http://github.com/leafo/lessphp">git repository</a>.</p>
    42. 

  42. 

  43. 	</div>
    44. 

  44. 

  45. 	<a name="language"></a>
    46. 

  46. 	<h1>The Language</h1>
    47. 

  47. 	<div class="content">
    48. 

  48. 		<br />
    49. 

  49. 		<p><strong>lessphp</strong> is a data description language built on top of CSS. The two major components of the language are 
    50. 

  50. 		blocks and property-value pairs. A block is a scope for a collection of property-value pairs.</p>
    51. 

  51. 

  52. 		<p>Blocks and properties have special characteristics depending on how they are named.</p>
    53. 

  53. 

  54. 		<p>It is important to realize that a block's state does not change over time. When a block is defined, all of its properties are constant. The best way to demonstrate this is to look at the following LESS snippet:</p>
    55. 

    56. 

  56. <pre class="code">
    57. 

  57. body {
    58. 

  58.     color: @val; 
    59. 

  59.     @val: blue;
    60. 

  60. }</pre>
    61. 

  61. 

  62. 		<p>Because the state of the block is not changing over time, but constant after its creation, 
    63. 

  63. 	the color property is printed with the value <code>blue</code>.
    64. 

  64. 

  65. 		<a name="vars"></a>
    66. 

  66. 		<h2>Abstract Properties (Variables)</h2>
    67. 

  67. 		<p>Abstract properties are defined with a name starting with <code>@</code>. These types of properties are special in two ways: first, they are not included in the output of the compiler. Second, they can be easily accessed in the values of other properties just by writing their name. If a property is referenced but can not be found, a blank string is returned.</p> 
    68. 

  68. 		<p>As a LESS programmer, it means that you can define a collection of hidden values that can be referenced in other locations.</p>
    69. 

  69. 

  70. <pre class="code">
    71. 

  71. @mycolor: #fff;
    72. 

  72. body {
    73. 

  73.     color: @mycolor; 
    74. 

  74. }
    75. 

  75. pre {
    76. 

  76.     color: @mycolor;
    77. 

  77. }</pre>
    78. 

  78. 

  79. 	<p>Also take note that you can define abstract properties in the global scope.</p>
    80. 

  80. 

  81. 	<a name="pvalues"></a>
    82. 

  82. 	<h2>Property Values & Expressions</h2>
    83. 

  83. 	<p>All properties have at least one value. The value is a list of expressions separated by spaces or commas.
    84. 

  84. 	An expression is any CSS value with optional mathematical operators applied to it. The operators only function
    85. 

  85. 	with number and color value types.<p>
    86. 

  86. 

  87. 	<p>Operations on units will keep the unit of the rightmost value, 
    88. 

  88. 	unless it is unit-less, then the leftmost unit will be kept for the result. See the following examples below.<p>
    89. 

  89. 

  90. <pre class="code">body {
    91. 

  91.     color: #001 + #abc;        // evaulates to #aabbdd:
    92. 

  92.     width: 3430px + 22;        // evaluates to 3452px;
    93. 

  93.     margin: (1.5em / 2) + 2px; // evaluates to 2.85px;
    94. 

  94.     margin: 20 + 2px;          // evaluates to 22px;
    95. 

  95.     font-family: "Some " + "Family"; // evaluates to "Some Family"
    96. 

  96. }</pre>
    97. 

  97. 

  98. 	<p>It is important to notice that in the example above the output will print the margin property twice. 
    99. 

  99. A single property name can hold more than one value; older values are not overwritten.</p>
    100. 

  100. 

  101. 	<a name="nested"></a>
    102. 

  102. 	<h2>Nested Blocks</h2>
    103. 

  103. 	<p>Blocks can be nested inside of each other in order to achieve the same effect as listing out the
    104. 

  104. 	path of identifiers in CSS. This can help to increase organization of your LESS code and reduce
    105. 

  105. 	the amount of repeated tag names you have to type.</p>
    106. 

  106. 

  107. <pre class="code">body {
    108. 

  108.     a {
    109. 

  109.         color: green;
    110. 

  110.         :hover {
    111. 

  111.             color: blue;
    112. 

  112.         }
    113. 

  113.     }
    114. 

  114. }</pre>
    115. 

  115. 

  116. 

  117. 	<a name="mixins"></a>
    118. 

  118. 	<h2>Mixins & Namespace Access</h2>
    119. 

  119. 	
    120. 

  120. 	<p>Any block can be "mixed" into the current block. This means that all properties and blocks 
    121. 

  121. 	in the target block are brought into the current block. It is possible to achieve the same effect
    122. 

  122. 	with just CSS and HTML, but there are some additional features discussed below that make it worthwhile
    123. 

  123. 	to utilize LESS-style mixing.</p>
    124. 

  124. 	<p>The syntax is as follows:<p>
    125. 

  125. 

  126. <pre class="code">
    127. 

  127. .myclass {
    128. 

  128.     @fonts: Helvetica, Arial;
    129. 

  129.     margin: 1.0em;	
    130. 

  130.     line-spacing: 150%;
    131. 

  131. 

  132.     a {
    133. 

  133.         background-color: black;
    134. 

  134.     }
    135. 

  135. }
    136. 

  136. 

  137. pre {
    138. 

  138.     .myclass;
    139. 

  139.     font-family: @fonts; // uses the mixed in variable
    140. 

  140. }
    141. 

  141. 

  142. div.notice {
    143. 

  143.     .myclass;
    144. 

  144. }</pre>
    145. 

  145. 

  146. 	<p>If you want to mix in a specific block within another block you can use the <code>&gt;</code> namespace operator. 
    147. 

  147. 	Additionally you can pull out specific values of properties from blocks using the <code>[ ]</code> operator.
    148. 

  148. 

  149. <pre class="code">// using .myclass from above
    150. 

  150. li {
    151. 

  151.     .myclass &gt; a; // just mix in properties from 'a' tag in .myclass
    152. 

  152.     fonts: .myclass[@fonts];
    153. 

  153.     padding: .myclass['margin'];
    154. 

  154. }</pre>
    155. 

  155. 

  156. 

  157. 	<a name="ablocks"></a>
    158. 

  158. 	<h2>Abstract Blocks</h2>
    159. 

  159. 

  160. 	<p>Abstract blocks are like any other blocks, but their names start with a <code>@</code>. Like abstract properties, they are not 
    161. 

  161. 	included in the compiler's output. This allows you to utilize mixins without adding any unused blocks to the output. 
    162. 

  162. 	You can also use an abstract class to define a package of invisible, but extractable blocks and properties.<p>
    163. 

  163. 

  164. <pre class="code">@mypackage {
    165. 

  165.     .coolColors {
    166. 

  166.         color: pink;
    167. 

  167.         background-color: green;
    168. 

  168.     }
    169. 

  169. 

  170.     .hotColors {
    171. 

  171.         color: red;
    172. 

  172.         background-color: orange;
    173. 

  173.     }
    174. 

  174. }
    175. 

  175. 

  176. p {
    177. 

  177.     @mypackage &gt; .coolColors;
    178. 

  178. }
    179. 

  179. 

  180. div {
    181. 

  181.     @mypackage; // inserts both classes into this block 
    182. 

  182. }</pre>
    183. 

  183. 

  184. 	<p>It is possible to give an abstract block the same name as an abstract property; their names will not collide.
    185. 

  185. 	Block names and property names exist in different spaces. For example:</p>
    186. 

  186. 

  187. <pre class="code">@color(@color:red) { color: @color; } // this is valid
    188. 

  188. </pre>
    189. 

  189. 

  190. 	<a name="args"></a>
    191. 

  191. 	<h2>Mixin Arguments</h2>
    192. 

  192. 	<p>All blocks have the option of taking argument lists, and the arguments can have default values.</p>
    193. 

  193. 

  194. <pre class="code">@some_mixin(@width: 200px;@radius) {
    195. 

  195.     border-radius: @radius;
    196. 

  196.     width: @width
    197. 

  197. }
    198. 

  198. 

  199. .first {
    200. 

  200.     @some_mixin(300px; 2em);
    201. 

  201. }
    202. 

  202. 

  203. .second {
    204. 

  204.     @some_mixin(;4px); // blank argument takes default value
    205. 

  205. }</pre>
    206. 

  206. 

  207. 	<a name="import"></a>
    208. 

  208. 	<h2>Import Statement</h2>
    209. 

  209. 	<p>If you have multiple LESS files, you can combine them into a single CSS file during compilation using the 
    210. 

  210. 	<code>@import</code> directive. LESS import uses the same syntax as CSS import. If it can find the file specified 
    211. 

  211. 	then it will pull it into the compiler in place of the statement. If the file can't be found, the statement is 
    212. 

  212. 	printed to the output. The following are all valid:</p>
    213. 

  213. 

  214. <pre class="code">@import "file";
    215. 

  215. @import 'file.less';
    216. 

  216. @import url("file");
    217. 

  217. @import url('file');
    218. 

  218. @import url(file); </pre>
    219. 

  219. 

  220. 	<p>Note that if it fails to find a file  it will append <code>.less</code> to the filename and try again. 
    221. 

  221. 	This means <code>@import 'somefile'</code> and <code>@import 'somefile.less'</code> will
    222. 

  222. 	both import the file <code>somefile.less</code>.
    223. 

  223. 

  224. 

  225. 	<a name="strings"></a>
    226. 

  226. 	<h2>String Mixins</h2>
    227. 

  227. 	<p>It is possible to access the value of an abstract property from a string using <code>{ }</code> operators.</p>
    228. 

  228. 

  229. <pre class="code">@image_folder: darktheme;
    230. 

  230. .header {
    231. 

  231.     background-image: url(/images/{@image_folder}/header.png);
    232. 

  232. }</pre>
    233. 

  233. 

  234. 	<p>The <code>{ }</code> syntax will also work in any string value type, which is any text 
    235. 

  235. 	wrapped in single or double quotes</p>
    236. 

  236. 

  237. 

  238. 	<a name="misc"></a>
    239. 

  239. 	<h2>Miscellaneous</h2>
    240. 

  240. 	<p>As mentioned before, all properties hold constant data. This includes abstract values. While it may be convenient to 
    241. 

  241. 	think of them as variables, they don't have the ability to vary. For convenience, some tricks were implemented to
    242. 

  242. 	make self referencing properties evaluate in order as if they had changing state. Consider the following statement:</p>
    243. 

  243. 

  244. <pre class="code">
    245. 

  245. @what: 1;
    246. 

  246. body { 
    247. 

  247.     @what: @what + 1;
    248. 

  248.     @what: @what + 2;
    249. 

  249.     .class {
    250. 

  250.         @what: @what + 1;
    251. 

  251. 		width: @what;
    252. 

  252.     }
    253. 

  253. }
    254. 

  254. 

  255. #something {
    256. 

  256.     @what: 200;
    257. 

  257.     body > .class;	
    258. 

  258. }</pre>
    259. 

  259. 

  260. 	<p>In the output, <code>body .class</code> has width set to 5, and <code>#something</code> has width set to 201. It appears from that result that
    261. 

  261. 	the property <code>@what</code> is being incremented. But, as mentioned above, the name <code>@what</code> stores a series of unchanging values.
    262. 

  262. 	The values use delayed evaluation, so each value holds an equation.</p>
    263. 

  263. 

  264. 	<p>What this means is that the values of the properties don't change while the block is parsed, only additional property-value pairs are added
    265. 

  265. 	to the block's definition.
    266. 

  266. 	When the block's is compiled into CSS, the equations and property references are solved using the data in the scope. Technically, it is 
    267. 

  267. 	ambiguous what value to use for referencing a variable, because the single name can store multiple values.<p>
    268. 

  268. 

  269. 	<p>The approach taken in <strong>lessphp</strong> is to use the most recent value. This gives the appearance that the block is parsed line by line. 
    270. 

  270. 	In order to prevent infinite loops when a variable references itself, a single value in the set of all values for a given name can only be used once in
    271. 

  271. 	the chain of dereferencing.</p>
    272. 

  272. 

  273. 

  274. 	<a name="differences"></a>
    275. 

  275. 	<h2>Differences from Ruby LESS</h2>
    276. 

  276. 	<p class="important">Report missing ones <a href="http://github.com/leafo/lessphp/issues">here</a>.</p>
    277. 

  277. 	<ul>
    278. 

  278. 		<li>Arguments to mixins are separated by <code>;</code> instead of <code>,</code>.
    279. 

  279. 			<p><b>Rationale</b>: the value of a css property can contain commas, so by using a comma as an argument separator you limit the kinds of input you can pass to a mixin.</p>
    280. 

  280. 		</li>
    281. 

  281. 	</ul>
    282. 

  282. 

  283. 	</div>
    284. 

  284. 

  285. <a name="interface"></a>
    286. 

  286. <h1>The PHP Interface</h1><br />
    287. 

  287. 	<div class="content">
    288. 

  288. <p>There are a few ways to interface with the compiler. The easiest is to have it
    289. 

  289. compile a LESS file when the page is requested. The static function 
    290. 

  290. <code>less::ccompile</code>, checked compile, will compile the inputed LESS file only when it
    291. 

  291. is newer than the output file.<p>
    292. 

  292. 

  293. <pre class="code">
    294. 

  294. <span class="PreProc">require</span> '<span class="String">lessc.inc.php</span>';
    295. 

  295. 

  296. <span class="Statement">try</span> <span class="Delimiter">{</span>
    297. 

  297.     lessc<span class="Operator">::</span>ccompile<span class="Delimiter">(</span>'<span class="String">input.less</span>', '<span class="String">out.css</span>'<span class="Delimiter">)</span>;
    298. 

  298. <span class="Delimiter">}</span> <span class="Statement">catch</span> <span class="Delimiter">(</span><span class="Function">exception</span> <span class="Operator">$</span><span class="Identifier">ex</span><span class="Delimiter">)</span> <span class="Delimiter">{</span>
    299. 

  299.     <span class="Statement">exit</span><span class="Delimiter">(</span>'<span class="String">lessc fatal error:&lt;br /&gt;</span>'<span class="Operator">.</span><span class="Operator">$</span><span class="Identifier">ex</span><span class="Type">-&gt;</span>getMessage<span class="Delimiter">())</span>;
    300. 

  300. <span class="Delimiter">}</span>
    301. 

  301. </pre>
    302. 

  302. 

  303. <br />
    304. 

  304. <p>Note that all failures with lessc are reported through exceptions.
    305. 

  305. If you need more control then you can make your own instance of <code>lessc</code>.</p>
    306. 

  306. <pre class="code">
    307. 

  307. <span class="PreProc">require</span> '<span class="String">lessc.inc.php</span>';
    308. 

  308. 

  309. <span class="Operator">$</span><span class="Identifier">less</span> <span class="Operator">=</span> <span class="PreProc">new</span> lessc<span class="Delimiter">(</span>'<span class="String">path/to/style.less</span>'<span class="Delimiter">)</span>;
    310. 

  310. <span class="Function">file_put_contents</span><span class="Delimiter">(</span>'<span class="String">path/to/style.css</span>', <span class="Operator">$</span><span class="Identifier">less</span><span class="Type">-&gt;</span>parse<span class="Delimiter">())</span>;
    311. 

  311. </pre>
    312. 

  312. 

  313. <br />
    314. 

  314. <p>In addition to loading from a file, you can also parse from a string like so:</p>
    315. 

  315. <pre class="code">
    316. 

  316. <span class="PreProc">require</span> '<span class="String">lessc.inc.php</span>';
    317. 

  317. 

  318. <span class="Operator">$</span><span class="Identifier">less</span> <span class="Operator">=</span> <span class="PreProc">new</span> lessc<span class="Delimiter">()</span>;
    319. 

  319. <span class="Operator">$</span><span class="Identifier">style</span> <span class="Operator">=</span> '<span class="String">&lt;style type=&quot;text/css&quot;&gt;</span>'<span class="Operator">.</span>
    320. 

  320.     <span class="Operator">$</span><span class="Identifier">less</span><span class="Type">-&gt;</span>parse<span class="Delimiter">(</span>'<span class="String">.block { padding: 3 + 4px }</span>'<span class="Delimiter">)</span><span class="Operator">.</span>
    321. 

  321.     '<span class="String">&lt;/style&gt;</span>';
    322. 

  322. </pre>
    323. 

  323. 

  324. 

  325. 	<h2>Import Directoy</h2>
    326. 

  326. 	<p>When using the <code>@import</code> directive, the compiler searches for files 
    327. 

  327. 	in the <code>$importDir</code> public property of <code>lessc</code>. If the compiler is loaded with a filename
    328. 

  328. 	(either in the constructor or using <code>ccompile</code>) it will extract the directory and set that as the 
    329. 

  329. 	import directory</p>
    330. 

  330. 

  331. 

  332. 	<h2>Library Functions</h2>
    333. 

  333. 	<p>Functions within the compiler class that are prefixed with <code>lib_</code> are visible visible to the less
    334. 

  334. 	code while it is being parsed. The easiest way to add your own functions is to subclass <code>lessc</code> and insert
    335. 

  335. 	the implementations.</p>
    336. 

  336. 

  337. 	<br />
    338. 

  338. 	<br />
    339. 

  339. 	<hr />
    340. 

  340. 	<p class="foot">
    341. 

  341. 		<a href="http://leafo.net/lessphp/">http://leafo.net/lessphp</a> - Last updated March 9th 2010</p>
    342. 

  342. 

  343. 	</div>
    344. 

  344. 

  345.   </body>
    346. 

  346. </html>
    347. 

  347. 

  348.