You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

133 lines
5.7 KiB

  1. ---
  2. layout : 'default'
  3. css : 'guide'
  4. title : ' Getting Started'
  5. type : 'UI Specification'
  6. ---
  7. <div class="segment">
  8. <div class="container">
  9. <h1 class="ui header">Getting Started</h1>
  10. </div>
  11. </div>
  12. <div class="main container">
  13. <div class="peek">
  14. <div class="ui vertical pointing secondary menu">
  15. <a class="active item">Installing</a>
  16. <a class="item">Usage</a>
  17. <a class="item">Why Use Semantic?</a>
  18. </div>
  19. </div>
  20. <h2 class="ui header">Installing</h2>
  21. <p>Semantic uses an eponymous package manager written in node. To begin you must <a href="http://howtonode.org/how-to-install-nodejs">install nodejs and npm</a> for your platform.</p>
  22. <p>After these dependencies are ready to go, you can install semantic using npm
  23. <div class="code" data-type="text" data-label="true">
  24. npm install -g semantic
  25. </div>
  26. <h2 class="ui header">Usage</h2>
  27. <p>Components are given a namespace. This makes sure the css rules dont interfere with other rules on your page.</p>
  28. <div class="code" data-type="text" data-label="true">
  29. semantic add button
  30. </div>
  31. <div class="code" data-type="html" data-label="true">
  32. <div class="ui button">Button</div>
  33. </div>
  34. <div class="code" data-type="css" data-label="true">
  35. .ui.button {
  36. font-size: 14px;
  37. }
  38. </div>
  39. <p>If multiple components are available of the same type, you can specify which one to use by adding the package's name before. A package name is different than its namespace, for example there may be many types of buttons.</p>
  40. <div class="code" data-type="text" data-label="true">
  41. semantic search button
  42. >> 2 buttons were found:
  43. >> fancy button - a collection of buttons formatted for a blog - 15 variations, 3 types
  44. >> semantic button - the official button collection of semantic - 10 variations, 5 types
  45. </div>
  46. <p>Components will download inside a directory. To use these components, simply link to their javascript and css in a web page</p>
  47. <div class="code" data-type="html">
  48. <link rel="stylesheet" type="text/css" class="ui" href="/ui/elements/button.css">
  49. </div>
  50. <h3>So I downloaded a component, now what?</h3>
  51. <p>Semantic components are self documenting, that means documentation are generated automatically after you download. You can see the element and code samples by simply opening up the corresponding html file.
  52. <div class="code" data-type="html">
  53. /ui/specification/button.html
  54. </div>
  55. <p>You can view an example of an element definition by checking out the docs for semantic's first party button definition</p>
  56. <a class="ui teal right labeled icon button" href="/elements/button.html">
  57. View button definition <i class="right arrow icon"></i>
  58. </a>
  59. <div class="ui divider"></div>
  60. <h2 class="ui header">Why Use Semantic?</h2>
  61. <p>
  62. Semantic sees website development as the coallescence of two things: <b>Re-usable UI Components + Discardable Page Glue</b>
  63. </p>
  64. <p>Semantic is a framework for writing portable UI components, which helps you and others re-use and re-skin your ui elements in their projects.</p>
  65. <h3 class="ui header">Definitions and Language</h3>
  66. <p>Natural language is <em>particularly good</em> at describing visual scenes, i.e. dogs, trees, flowers and hard at defining abstractions: behavior, emotions, etc. Where programming languages are <em>particularly good</em> at describing behavior, but can be more obtuse at describing layouts.</p>
  67. <p>Semantic adopts concepts from natural languages like: plurals, adjectives, and tense so web developers can enjoy some of the more useful features of natural language. Semantic also aspires for developers to make decision based on common usage instead of deciding arbitrarily how to name things.</p>
  68. <p>For example if a developer wants to include a set of red buttons with icons on a page he can simple grab the semantic button and icon component:</p>
  69. <div class="code" data-type="text">
  70. semantic add button
  71. semantic add icon
  72. </div>
  73. and then include in html:
  74. <div class="code" data-type="html">
  75. <div class="red ui icon buttons">
  76. <div class="ui button">
  77. <i class="grid layout icon"></i>
  78. </div>
  79. <div class="ui button">
  80. <i class="block layout icon"></i>
  81. </div>
  82. <div class="ui button">
  83. <i class="list layout icon"></i>
  84. </div>
  85. </div>
  86. </div>
  87. <div class="red ui icon buttons">
  88. <div class="ui button"><i class="grid layout icon"></i></div>
  89. <div class="ui button"><i class="block layout icon"></i></div>
  90. <div class="ui button"><i class="list layout icon"></i></div>
  91. </div>
  92. <h3 class="ui header">Authoring</h3>
  93. <p>Creating a component in semantic requires two steps:
  94. <ol class="ui list">
  95. <li>Defining how your element can look.</li>
  96. <li>Writing code to match your definitions</li>
  97. </ol>
  98. <p>These steps can be completed in either order. If you enjoy Test-Driven-Development, you can write your specification before coding, or if you prefer a more ad-hoc approach you can swap the order, defining your element only after you finish describing it.</p>
  99. <h3 class="ui header">Consuming</h3>
  100. <p>Semantic is a package manager, created by other people is a simple process</p>
  101. <ol class="ui list">
  102. <li>Search semantic for a type of UI component</li>
  103. <li>Open up its specification to see what it can do and how to use it.</li>
  104. </ol>
  105. Semantic components are self documenting, giving you the ability to download a component, and get working immediately. Each component contains a spec file, which describes what a component can do. This is used to generate documentation automatically that lives alongside your project, making sure you know exactly what exists in your CSS.</p>
  106. </div>