Skip to content

Commit

Permalink
Merge pull request #12 from vtex-apps/guerreirobeatriz-patch-1
Browse files Browse the repository at this point in the history 
Update README.md
  • Loading branch information
@guerreirobeatriz
guerreirobeatriz authored Apr 14, 2020
2 parents 514e1ee + b7de91e commit b0c96ec
Show file tree
Hide file tree
Showing 2 changed files with 43 additions and 97 deletions.
3 changes: 3 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.

## [Unreleased]

### Fixed
- README.md documentation

## [0.4.1] - 2020-03-04
### Fixed
- Potential runtime error on ImageList component.
Expand Down
137 changes: 40 additions & 97 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,29 +1,29 @@
# VTEX Store Image
📢 Use this project, [contribute](https://github.com/vtex-apps/store-image) to it or open issues to help evolve it using [Store Discussion](https://github.com/vtex-apps/store-discussion).

This app exports a set of blocks to work with images inside of our Store Framework.
# Store Image

## Blocks API
<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
[![All Contributors](https://img.shields.io/badge/all_contributors-0-orange.svg?style=flat-square)](#contributors-)
<!-- ALL-CONTRIBUTORS-BADGE:END -->

Documentation on the `image` interface can be found at: <https://vtex.io/docs/app/vtex.store-components/image>
The Store Image app exports the `list-context.image-list` block, which is responsible for working with image content in the store's theme.

A few interfaces are exported by this app. For now, only `image-slider` and `image-list` are documented and allowed for use inside of `store`.
![store-image](https://user-images.githubusercontent.com/52087100/78939489-a3c69f00-7a8a-11ea-8c66-7475f1a3f69e.png)

There's a common `ImageObject` type used by both blocks:

### ImageObject
## Configuration

| Prop name | Type | Description | Default value |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ------------- |
| `image` | `String` | Link for the image | N/A |
| `mobileImage` | `String` | Link for the mobile image | N/A |
| `description` | `String` | The image's description | N/A |
| `link` | [`Link`](https://github.com/vtex-apps/native-types/blob/f63aeeb8f6e62f4a9aaec052a8be34973be7389b/pages/contentSchemas.json#L52-L74) | Specifies the link the image will redirect when clicked on |
1. Add the `store-image` app to your theme's dependencies in the `manifest.json`, for example:

### ImageList
```diff
"dependencies ": {
+ "vtex.store-image": "0.x"
}
```

The `list-context.image-list` interface is a stance of the `list-context` interfaces, which means its part of a set of special interfaces that enables you to create lists of content that can be edited via Site Editor.
You are now able to use the `list-context.image-list` block, exported by the Store Image app. The block allows you to display images in your store with a higher degree of composability, since you can use it along with other `list-context` blocks to create a more flexible and customizable image slider.

Currently, this should be used to create a block analogous to an `ImageSlider`, but in a more composable way, since you could use it along with other `list-context` blocks to create a more flexible and customizable slider. The following example shows how you could use this to replicate an `ImageSlider`:
2. In any desired theme template, add the `list-context.image-list` block, declaring the `slider-layout` block as child. For example:

```json
"list-context.image-list#demo": {
Expand Down Expand Up @@ -55,94 +55,37 @@ Currently, this should be used to create a block analogous to an `ImageSlider`,
},
```

Now, for a more complex scenario, this is what you would do to create a slider with images, products and `flex-layout`s, which is possible because of `slider-layout`:
Note that the `slider-layout` block, exported from the Slider Layout app, is given as a child of `list-context.image-list`. It is responsible for defining which images will be displayed, as well as their behavior once rendered.

```json
"product-list-block#demo2": {
"blocks": ["product-summary.shelf#demo2", "list-context.product-list#demo2"]
},
"list-context.product-list#demo2": {
"children": ["list-context.image-list#demo2"]
},
"list-context.image-list#demo2": {
"children": ["slider-layout#demo-lists"],
"props": {
"height": 650,
"images": [
{
"image": "https://storecomponents.vteximg.com.br/arquivos/banner-infocard2.png",
"description": "something something"
},
{
"image": "https://storecomponents.vteximg.com.br/assets/vtex.file-manager-graphql/images/Group%207%20(1)%20(1)%20(1)%20(1)%20(1)___c6b3ed853fb16a08b265753b50e0c57a.png",
"description": "something something"
}
]
}
},
"slider-layout#demo-lists": {
"children": ["flex-layout.row#about-us", "flex-layout.row#about-us2"],
"props": {
"itemsPerPage": {
"desktop": 1,
"tablet": 1,
"phone": 1
},
"infinite": true
}
},
```

### ImageSlider

To configure an `image-slider`, these are the props you should edit at your theme:
### `list-context.image-list` props

| Prop name | Type | Description | Default value |
| -------------------- | --------------------------------------- | ------------------------------------------------------- | ---------------- |
| `height` | `String`&#124;`Number` | The maximum height for the images inside of the slider. | `'none'` |
| `sliderLayoutConfig` | `Object` (described below) | Controls slider's behavior. | Described below. |
| `images` | `Array (ImageObject)` (described below) | An array of images to be rendered as a slider. | `null` |
| Prop name | Type | Description | Default value |
| ------------- | ----- | ---------------------------------------------------------- | ------------- |
| `images` | `array` | Array of objects declaring all desired images to be rendered. | `undefined` |
| `height` | `number` | Image height for all images declared in the `image` object. | `undefined` |

#### sliderLayoutConfig object
- **`images` array:**

| Prop name | Type | Description | Default value |
| ---------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------ |
| `infinite` | `Boolean` | Controls if the slider should or should not be infinite. | `true` |
| `usePagination` | `Boolean` | Toggles whether or not to use a fluid scroll for navigation, disabling the notion of a "page". | `true` |
| `itemsPerPage` | `{ destop: Number, tablet: Number, phone: Number }` | Controls how many slides should be shown on each type of device. | `{ destop: 1, tablet: 1, phone: 1 }` |
| `showNavigationArrows` | `mobileOnly`&#124;`desktopOnly`&#124;`always`&#124;`never` | Controls when should navigation arrows be rendered. | `'always'` |
| `showPaginationDots` | `mobileOnly`&#124;`desktopOnly`&#124;`always`&#124;`never` | Controls when should pagination dots be rendered. | `'always'` |
| Prop name | Type | Description | Default value |
| ------------- | ------- | ---------------------------------------------------------- | ------------- |
| `image` | `string` | Image URL. | `undefined` |
| `mobileImage` | `string` | Mobile image URL. | `undefined` |
| `description` | `string` | Image description. | `undefined` |
| `link` | `object` | Links an URL to the image being rendered. | `undefined` |

- **`link` object:**

## Styles API

This app provides some CSS classes as an API for style customization.

To use this CSS API, you must add the `styles` builder and create an app styling CSS file.

1. Add the `styles` builder to your `manifest.json`:

```json
"builders": {
"styles": "1.x"
}
```

2. Create a file called `vtex.store-image.css` inside the `styles/css` folder. Add your custom styles:

```css
.imageElement {
margin-top: 10px;
}
```
| Prop name | Type | Description | Default value |
| ------------- | ------- | ---------------------------------------------------------- | ------------- |
| `url` | `string` | URL users will be redirected to when clicking on the image. | `undefined` |
| `noFollow` | `boolean` | Whether the linked URL is endorsed by the owner of the page the user was navigating on i.e. if there is a commercial relationship between both pages (`true`) or not (`false`). | `false` |
| `openNewTab` | `string` | Whether a new tab on browser will be opened (`true`) or not (`false`) . | `undefined` |
| `title` | `string` | Text label used to identify the image in the admin's Site Editor. | `undefined` |

### CSS namespaces
:information_source: Use the **admin's Site Editor** to manage all images declared in the `list-context.image-list` block.

Below, we describe the namespaces that are defined by `store-image`.
## Customization

| CSS Handle |
| ------------------ |
| `imageElement` |
| `imageElementLink` |
The block still doesn't have CSS Handles for its specific customization.

Note that the `image-slider` uses our `vtex.slider-layout` app, so all the CSS namespaces defined by it are also available for `image-slider`. Take a look at [Slider-Layout](https://vtex.io/docs/app/vtex.slider-layout).
All CSS Handles available for the Image block are the ones available for the `slider-layout` block. Take a look at the Customization section in the [**Slider Layout documentation**](https://vtex.io/docs/app/vtex.slider-layout).

0 comments on commit b0c96ec

Please sign in to comment.