docs/_templates/started.html - mdl-1.x - githubmirror/material-design-lite

docs/_templates/started.html
260 строк15 KB
Surma
Merge pull request #744 from paulirish/patch-1
18 янв 2016, 15:27
18 янв 2016, 15:27bf74144
{% extends 'layout.html' %}

{% block content %}
<script src="{{page.include_prefix}}assets/snippets.js"></script>

<div class="docs-text-styling">
  <section class="docs-toc">
    <h3>Contents</h3>
    <nav class="section-content">
      <ul>
        <li><a href="#download">Include the master CSS &amp; JavaScript</a></li>
        <li><a href="#use-components">Use the components</a></li>
        <li><a href="#general-rules">General rules and principles</a></li>
        <li><a href="#dynamic">Use MDL on dynamic websites</a></li>
        <li><a href="#responsibilities">What are MDL's responsibilities?</a></li>
        <li><a href="#whats-next">What's next?</a></li>
        <li><a href="#license">License</a></li>
      </ul>
    </nav>
  </section>

  <section id="download">
    <h3>Include the master CSS &amp; JavaScript</h3>
    <div class="section-content">
      <p>
        Include the Material Lite CSS and JavaScript files in each HTML page in your project. We recommend that you use the <strong>files hosted on our CDN</strong>. You can also <strong>customize and download</strong> them to host them yourself, <strong>build</strong> them from our source code or install them in your <strong>npm</strong>/<strong>Bower</strong> project.
      </p>

      <div class="mdl-tabs mdl-js-tabs">
        <div class="mdl-tabs__tab-bar">
          <a href="#tab1" class="mdl-tabs__tab is-active">Hosted</a>
          <a href="#tab2" class="mdl-tabs__tab">Download</a>
          <a href="#tab3" class="mdl-tabs__tab">Build</a>
          <a href="#tab4" class="mdl-tabs__tab">Bower</a>
          <a href="#tab5" class="mdl-tabs__tab">npm</a>
        </div>
        <div class="mdl-tabs__panel is-active" id="tab1">
          <div class="code-with-text">
            Just add the following <code>&lt;link&gt;</code> and <code>&lt;script&gt;</code> elements into your HTML pages (27kB gzipped):
            <pre class="language-markup"><code>&lt;link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons"&gt;
&lt;link rel="stylesheet" href="$$hosted_libs_prefix$$/$$version$$/material.indigo-pink.min.css"&gt;
&lt;script defer src="$$hosted_libs_prefix$$/$$version$$/material.min.js"&gt;&lt;/script&gt;</code></pre>
          </div>
          <h4>Choose color scheme</h4>
          <p>
            <a href="http://www.google.com/design/spec/style/color.html">Color schemes used in Material Design</a> are based on a primary and an accent colors which you may want to personalize. These colors are specified in the CSS file name by following this pattern: <code>material.{primary}-{accent}.min.css</code> (e.g. <code>material.indigo-pink.min.css</code>). Our CDN hosts a number of color combinations based on common Material Design colors. To discover and preview available color combinations use our <a href="../customize/index.html">Customize and Preview tool</a>.
          </p>
        </div>
        <div class="mdl-tabs__panel" id="tab2">
          <p>
            Download the minified CSS and Javascript now (27kB gzipped):
          </p>
          <div class="download-button-container">
            <a href="$$hosted_libs_prefix$$/$$version$$/mdl.zip">
              <button class="mdl-button mdl-js-button mdl-button--raised mdl-js-ripple-effect">
                Download MDL v$$version$$
              </button>
            </a>
          </div>
          <div class="code-with-text">
            Refer to these files by adding a <code>&lt;link&gt;</code> and a <code>&lt;script&gt;</code> elements into your HTML pages and also include the Material Icon font:
            <pre class="language-markup"><code>&lt;link rel="stylesheet" href="./material.min.css"&gt;
&lt;script src="./material.min.js"&gt;&lt;/script&gt;
&lt;link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons"&gt;</code></pre>
          </div>
          <h4>Choose color scheme</h4>
          <p>
            <a href="http://www.google.com/design/spec/style/color.html">Color schemes used in Material Design</a> are based on a primary and an accent colors which you may want to personalize. Use the <a href="../customize/index.html">Customize and Preview tool</a> to select and preview primary and accent colors combinations for your site. Then download your customized Material Design Lite CSS using the button and simply replace the `material.min.css` with the customized one.
          </p>
        </div>
        <div class="mdl-tabs__panel" id="tab3">
          <p>
            Our source code is hosted <a href="https://github.com/google/material-design-lite">on GitHub</a>. You'll need to download the code and build it.
          </p>
          <div class="code-with-text">
            Run the following commands in a shell:
            <pre class="language-bash"><code># Clone/copy the Material Design lite source code.
git clone https://github.com/google/material-design-lite.git
# Go into the newly created folder containing the source code.
cd material-design-lite
# Install necessary dependencies.
npm install && npm install -g gulp
# Build a production version of the components.
gulp</code></pre>
          </div>
          <p>You'll find the Material Design Lite library's file in the <code>dist</code> folder. Copy them to your project.
          </p>
          <div class="code-with-text">
            Refer to these files by adding a <code>&lt;link&gt;</code> and a <code>&lt;script&gt;</code> element into your HTML pages and also include the Material Icon font:
            <pre class="language-markup"><code>&lt;link rel="stylesheet" href="./material.min.css"&gt;
&lt;script src="./material.min.js"&gt;&lt;/script&gt;
&lt;link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons"&gt;</code></pre>
          </div>
          <div class="caption">
            <h4>
              Note:
            </h4>
            Using this method you will not be able to customize the color scheme of the MDL elements. If you'd like to customize the color scheme prefer the CDN hosted or downloadable libraries. In this case use our <a href="../customize/index.html">Customize and Preview tool</a>.
          </div>
        </div>
        <div class="mdl-tabs__panel" id="tab4">
          <p>
            Simply install Material Design Lite files in your <a href="http://bower.io/">Bower</a> enabled project using:
          </p>
          <div class="code-with-text">
            Run the following command in a shell:
            <pre class="language-bash"><code>bower install material-design-lite --save</code></pre>
          </div>
          <p>
            This will install the Material Design Lite library files in your project's <code>bower_components</code> folder.
          </p>
          <div class="code-with-text">
            Refer to these files by adding a <code>&lt;link&gt;</code> and a <code>&lt;script&gt;</code> element into your HTML pages and also include the Material Icon font:
            <pre class="language-markup"><code>&lt;link rel="stylesheet" href="/bower_components/material-design-lite/material.min.css"&gt;
&lt;script src="/bower_components/material-design-lite/material.min.js"&gt;&lt;/script&gt;
&lt;link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons"&gt;</code></pre>
          </div>
          <div class="caption">
            <h4>
              Note:
            </h4>
            Using this method you will not be able to customize the color scheme of the MDL elements. If you'd like to customize the color scheme prefer the CDN hosted or downloadable libraries. In this case use our <a href="../customize/index.html">Customize and Preview tool</a>.
          </div>
        </div>
        <div class="mdl-tabs__panel" id="tab5">
          <p>
            Simply install Material Design Lite files in your <a href="https://www.npmjs.com/">npm</a> enabled project using:
          </p>
          <div class="code-with-text">
            Run the following command in a shell:
            <pre class="language-bash"><code>npm install material-design-lite --save</code></pre>
          </div>
          <p>
            This will install the Material Design Lite library files in your project's <code>node_modules</code> folder.
          </p>
          <div class="code-with-text">
            Refer to these files by adding a <code>&lt;link&gt;</code> and a <code>&lt;script&gt;</code> element into your HTML pages and also include the Material Icon font:
            <pre class="language-markup"><code>&lt;link rel="stylesheet" href="/node_modules/material-design-lite/material.min.css"&gt;
&lt;script src="/node_modules/material-design-lite/material.min.js"&gt;&lt;/script&gt;
&lt;link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons"&gt;</code></pre>
          </div>
          <div class="caption">
            <h4>
              Note:
            </h4>
            Using this method you will not be able to customize the color scheme of the MDL elements. If you'd like to customize the color scheme prefer the CDN hosted or downloadable libraries. In this case use our <a href="../customize/index.html">Customize and Preview tool</a>.
          </div>
        </div>
      </div>
      <p>
        That's it! You are now ready to add MDL components on your site.
      </p>
    </div>
  </section>

  <section id="use-components">
    <h3>Use the components</h3>
    <div class="section-content">

      <p>
        You'll find below a couple of examples of MDL <a href="../components/index.html#buttons-section">Button</a> elements: a Button with ripples and a FAB Button. Just copy &amp; paste the corresponding source code in the <code>&lt;body&gt;</code> of an HTML page of your project and the elements will render as shown below.
      </p>

      <!-- Generating snippets -->
      {% for snippet_group in page.snippets %}
        {% include "./snippets.html" with snippet_group only %}
      {%- endfor %}

      <p>
        MDL elements can be tweaked and configured by adding CSS classes. For example adding <code>mdl-js-ripple-effect</code> to an MDL <a href="../components/index.html#buttons-section">Button</a> will add a Ripple effect when the button is clicked and adding <code>mdl-button--fab</code> will change the style of the button to a FAB button.
      </p>
      <p>
        There are many other elements available such as <a href="../components/index.html#cards-section">Card containers</a>, <a href="../components/index.html#sliders-section">Sliders</a>, <a href="../components/index.html#tables-section">Tables</a>, <a href="../components/index.html#menus-section">Menus</a>... For the complete set of MDL elements and options have a look at the <a href="../components/index.html">components</a> page.
      </p>
      <p>
        We also recommend that you check out our <a href="../templates/index.html">templates</a>. These are ready to use website templates using MDL components. Feel free to have a look at them to get started quickly on your next project.
      </p>
    </div>
  </section>

  <section id="general-rules">
    <h3>General rules and principles</h3>
    <div class="section-content">
      <p>
        In general, follow these basic steps to use an MDL component in your HTML page:
      </p>
      <ol>
        <li>Start with a standard HTML element, such as <code>&lt;button&gt;</code>, <code>&lt;div&gt;</code>, or <code>&lt;ul&gt;</code>, depending on the MDL component you want to use. This establishes the element in the page and readies it for MDL modification.</li>

        <li>Add one or more MDL-specific CSS classes to the element, such as <code>mdl-button</code> or <code>mdl-tabs__panel</code>, again depending on the component. The classes apply the MDL enhancements to the element and turn it into an MDL component.</li>
      </ol>

      <p>
        Remember to include the <a href="https://developers.google.com/speed/docs/insights/ConfigureViewport">meta viewport</a> tag in your document so mobile devices will render correctly.
      </p>
      <pre class="language-markup"><code>&lt;meta name="viewport" content="width=device-width, initial-scale=1.0"></code></pre>

      <div class="caption">
        <h4>
          A note about HTML elements and MDL CSS classes
        </h4>
        Material Design Lite uses namespaced <a href="https://en.bem.info/method/">BEM</a> classes—which can apply to almost any HTML element—to construct components. For some components you can use almost any element. The examples in <a href="../components/index.html">each component's documentation</a> use elements that perform well as that component. If you must use elements other than those shown in the examples, we encourage you to experiment to find the best combination of HTML elements and MDL CSS classes for your application.
      </div>
    </div>
  </section>

  <section id="dynamic">
    <h3>Use MDL on dynamic websites</h3>
    <div class="section-content">
      <p>
        Material Design Lite will automatically register and render all elements marked with MDL classes upon page load.
        However in the case where you are creating DOM elements dynamically you need to register new elements using the <code>upgradeElement</code> function. Here is how you can dynamically create the same raised button with ripples shown in the section above:
      </p>
      <pre class="language-markup codepen-button-enabled"><code>&lt;div id="container"/&gt;
&lt;script&gt;
  var button = document.createElement('button');
  var textNode = document.createTextNode('Click Me!');
  button.appendChild(textNode);
  button.className = 'mdl-button mdl-js-button mdl-js-ripple-effect';
  componentHandler.upgradeElement(button);
  document.getElementById('container').appendChild(button);
&lt;/script&gt;</code><form class="codepen-button" action="https://codepen.io/pen/define" method="POST" target="_blank"></form></pre>
    </div>
  </section>

  <section id="responsibilities">
    <h3>What are MDL's responsibilities?</h3>
    <div class="section-content">
      <p>
        Material Design Lite is built to provide a lightweight and basic set of Material Design components  and templates for web sites.
        The project does not intend to provide structures to create all possible UX needs, but to provide a low-friction Material Design implementation you can build on.
        Even within Material Design itself, cards specifically, it is unfeasible to provide every combination in a seamless manner.
        When you find something not provided, such as dropdowns in the drawer, you may need to code your own component.
      </p>
      <p>
        The team is committed to providing a great experience to developers while staying true to the promise of lite.
      </p>
    </div>
  </section>

  <section id="whats-next">
    <h3>What's next?</h3>
    <div class="section-content">
      <p>
        Detailed instructions for using the components, including MDL classes and their effects, coding considerations, and configuration options, can be found in the <a href="../components/index.html">components</a> page. Example of sites using MDL elements together can be found in the <a href="../templates/index.html">templates</a> page.
      </p>
    </div>
  </section>

  <section id="license">
    <h3>License</h3>
    <div class="section-content">
      <p>
        Copyright Google, 2015. Licensed under an Apache-2 license.
      </p>
    </div>
  </section>
</div>

{% endblock %}