Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add docs for the new Cards API #280

Merged
merged 1 commit into from
Feb 4, 2020
Merged

Add docs for the new Cards API #280

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
123 changes: 25 additions & 98 deletions docs/components/card.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,63 +16,27 @@ You can also add an image to the card using the `@image` parameter:

```html
<ul class="list-unstyled layout">
<EsCard @image="/ember-logo.png" class="lg:col-2">
<EsCard @image={{hash src="/ember-logo.png"}} class="lg:col-2">
This is a card
</EsCard>
</ul>
```

By default images will be considered decorative and ignored by screen readers, but if you want to provide an alt text for the image you can provide it with the `@alt` parameter:
By default images will be considered decorative and ignored by screen readers, but if you want to provide an alt text for the image you can provide it with the `alt` key in the `@image` hash:

```html
<ul class="list-unstyled layout">
<EsCard @image="/ember-logo.png" @alt="Ember Logo" class="lg:col-2">
<EsCard @image={{hash src="/ember-logo.png" alt="Ember Logo"}} class="lg:col-2">
This is a card
</EsCard>
</ul>
```

By default the card will have the image to the left of the content. If you want to make the card a **vertical** card you can apply the `vertical` attribute;
Here is a fuller example of a card that has more structure in the card body

```html
<ul class="list-unstyled layout">
<EsCard class="lg:col-2" @image="/ember-logo.png" vertical>
This is a card
</EsCard>
</ul>
```

It is unlikely that you will be using this vertical display of a card with a full width container so you might want to use a layout grid to contain the card:

```html
<ul class="list-unstyled layout">
<EsCard @image="/ember-logo.png" vertical class="lg:col-2">
this is a card
</EsCard>
<EsCard @image="/ember-logo.png" vertical class="lg:col-2">
this is another card
</EsCard>
</ul>
```

If you want the image to take up the full available width of the card you can apply the `full-image` attribute:

```html
<ul class="list-unstyled layout">
<EsCard @image="/ember-logo.png" vertical full-image class="lg:col-2">
this is a card
</EsCard>
<EsCard @image="/ember-logo.png" vertical full-image class="lg:col-2">
this is another card
</EsCard>
</ul>
```

And here is a fuller example of a vertical, full-image card that has more structure in the card body

```html
<ul class="list-unstyled layout">
<EsCard @image="/ember-logo.png" vertical full-image class="lg:col-2">
<EsCard @image={{hash src="/ember-logo.png"}} class="lg:col-2">
<h3>Ember.js</h3>
<p>A framework for ambitious web developers. Try it out!</p>
<div class="flex-horizontal-between">
Expand All @@ -83,85 +47,48 @@ And here is a fuller example of a vertical, full-image card that has more struct
</ul>
```

You can also create a card that allows a link to an external resource using `<a href=""></a>` somewhere in the card body, most likely in the header:
And here is a full card based page layout (which also makes use of the [ESLinkCard](/components/link-card) component) that might be useful when building sites using this component:

```html
<ul class="list-unstyled layout">
<EsCard class="lg:col-3" @image="/images/icons/discuss-logo.svg">
<h3>
<a href="http://discuss.emberjs.com">Discussion Forum</a>
</h3>
<p>Post and search longer-form questions in our public forum.</p>
</EsCard>
</ul>
```

But if you would like the whole card to become interactive and act as a link you can add the `card-link` attribute. This will stretch the link to be the full area of the card:

```html
<ul class="list-unstyled layout">
<EsCard class="lg:col-3" @image="/images/icons/discuss-logo.svg" card-link>
<h3>
<a href="http://discuss.emberjs.com">Discussion Forum</a>
</h3>
<p>Post and search longer-form questions in our public forum.</p>
</EsCard>
</ul>
```

Here is what that looks like on a dark background

```html
<div class="bg-dark">
<ul class="list-unstyled layout">
<EsCard class="lg:col-3" @image="/images/icons/mic-icon.svg" card-link>
<h3>
<a href="http://discuss.emberjs.com">Discussion Forum</a>
</h3>
<p>Post and search longer-form questions in our public forum.</p>
</EsCard>
</ul>
</div>
```

And here is a full card based page layout that might be useful when building sites using this component:

```html
<ul class="list-unstyled layout">
<EsCard class="lg:col-3" @image="/images/icons/discuss-logo.svg" card-link>
<h3>
<a href="http://discuss.emberjs.com">Discussion Forum</a>
</h3>
<ul class="list-unstyled layout my-3">
<EsLinkCard
class="lg:col-3"
@href="http://discuss.emberjs.com"
@title="Discussion Forum"
@icon="discuss-logo"
>
<p>Post and search longer-form questions in our public forum.</p>
</EsCard>
<EsCard class="lg:col-3" @image="/images/icons/discord-logo.svg" card-link>
<h3>
<a href="https://discord.gg/emberjs">Discord community chat</a>
</h3>
</EsLinkCard>
<EsLinkCard
class="lg:col-3"
@href="https://discord.gg/emberjs"
@title="Discord community chat"
@icon="discord-logo"
>
<p>Join our real-time chat server to connect with other developers and get answers.</p>
</EsCard>
</EsLinkCard>
</ul>

<p>
Beyond our core online channels, you can dig deeper with these learning resources from the
community members
</p>

<ul class="list-unstyled layout">
<EsCard class="lg:col-2 text-center" vertical @image="/images/icons/mic-icon.svg">
<ul class="list-unstyled layout my-3">
<EsCard class="lg:col-2 text-center" @icon="mic-icon">
<h3>Podcasts</h3>
<ul class="list-unstyled">
<li><a href="embermap somewhere">Ember Weekly</a></li>
<li><a href="embermap somewhere">Ember Map Podcast</a></li>
</ul>
</EsCard>
<EsCard class="lg:col-2 text-center" vertical @image="/images/icons/book-icon.svg">
<EsCard class="lg:col-2 text-center" @icon="book-icon">
<h3>Books</h3>
<ul class="list-unstyled">
<li><a href="embermap somewhere">Rock and Roll with Ember.js</a></li>
</ul>
</EsCard>
<EsCard class="lg:col-2 text-center" vertical @image="/images/icons/tv-icon.svg">
<EsCard class="lg:col-2 text-center" @icon="tv-icon">
<h3>Videos</h3>
<ul class="list-unstyled">
<li><a href="embermap somewhere">Ember Map</a></li>
Expand Down
42 changes: 42 additions & 0 deletions docs/components/link-card.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
# Link Card

An `<EsLinkCard />` is a card that allows a link to an external resource.

```html
<ul class="list-unstyled layout">
<EsLinkCard class="lg:col-3" @href="http://discuss.emberjs.com" @title="Discussion Forum">
<p>Post and search longer-form questions in our public forum.</p>
</EsLinkCard>
</ul>
```

You can add an icon to the card with `@icon`

```html
<ul class="list-unstyled layout">
<EsLinkCard
class="lg:col-3"
@href="http://discuss.emberjs.com"
@title="Discussion Forum"
@icon="discuss-logo"
>
<p>Post and search longer-form questions in our public forum.</p>
</EsLinkCard>
</ul>
```

Here is what that looks like on a dark background

```html
<div class="bg-dark">
<ul class="list-unstyled layout">
<EsLinkCard
class="lg:col-3"
@href="http://discuss.emberjs.com"
@title="Discussion Forum"
>
<p>Post and search longer-form questions in our public forum.</p>
</EsLinkCard>
</ul>
</div>
```