# 🇺🇸 English

## Introduction

This documentation will give you an understanding of how the files are structured and guide you in performing common functions.

**Sham** has been crafted on top of Bootstrap 4.x. The included docs don't replace the official ones, but provide a clear view of all extended styles and new components that this template provides on top of Bootstrap 4.x.

If you have any questions that are beyond the scope of this documentation, please feel free contact me via e-mail: `hussam3bd@gmail.com`. Enjoy!

## **Quick start**

The theme includes a custom **Webpack** file, which can be used to quickly recompile and minify theme assets while developing or for deployment. You'll need to install [Node.js](https://nodejs.org/en/) before using Webpack.

Once Node.js is installed, run `npm install` to install the rest of Sham's dependencies.

{% hint style="info" %}
All dependencies will be downloaded to the `node_modules` directory.
{% endhint %}

```
npm install
```

Now you're ready to modify the source files and generate new `dist/` files, Sham is using webpack and [laravel-mix](https://laravel-mix.com/) to automatically detect file changes.

if you have the NPM script within your `package.json`, you may do:

```
npm run dev
```

To watch your JavaScript for changes, run:

```
npm run watch
```

{% hint style="info" %}
You may also use `mix.browserSync('localhost')` to automatically reload the browser when any relevant file in your Laravel app is changed.
{% endhint %}

If you are ready and you wnat to build for production, run:

```
npm run production
```

## File Structure

The template contains 26 HTML files. You will find them in the root directory of the download package.

In the `assets` folder your find all the style and script for this theme.

* `~/root`
  * **`📂 assets`**
    * **`img`**
    * **`sass`**
      * `components`
      * `libs`
      * `sections`
      * \_helpers.scss
      * \_mixins.scss
      * \_variables.scss
      * **app.scss**  _/_ _The main style file_&#x20;
    * **`js`**
      * `libs`
      * bootstrap.js
      * **app.js** _/ The main script file_\

  * ~~**`📂 dist`**~~ _This folder is auto-generated by the **webpack** after rendering and minify all of the theme styles and scripts._\

  * **package.json**
  * **webpack.mix.js**
  * **\*.html** _/ the rest of the theme pages._\

*   **`📂 sass`**

    The template comes with a number of SASS files, many of which you will likely never touch.

    There is 1 file that you will most likely edit since you are going to apply some degree of customization to your site.

    1.  **`app.scss`**

        &#x20;This is the main stylesheet for the template and includes all styles relating to the appearance of the elements you see inside each page.\
        This stylesheets has been commented for ease of use and all style rules are grouped under particular headings such as

        ```
        /*----------------------------------------------*\
        	03- GENERAL STYLES
        \*----------------------------------------------*/
        ```
*   **`📂 js`**

    &#x20;Sham, comes with a number of JS files, many of which you will never edit. If you don't know your way around javascript please don't edit them, these files will break parts of your site.

    1.  **`app.js`**

        This is the main scripts file for the template, that includes all functions specific to the theme such as control of the slider and initialize map and Carousel among other things.

## Grid System

The template is based on [Bootstrap v4.x](https://getbootstrap.com/docs/4.4), 12 column grid system. Is flexible and easy to understand.\
For more info [here](https://getbootstrap.com/docs/4.4/layout/grid/).

### How it works

Bootstrap’s grid system uses a series of containers, rows, and columns to layout and align content. It’s built with [flexbox](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flexible_Box_Layout/Basic_Concepts_of_Flexbox) and is fully responsive. Below is an example and an in-depth look at how the grid comes together.

**New to or unfamiliar with flexbox?** [Read this CSS Tricks flexbox guide](https://css-tricks.com/snippets/css/a-guide-to-flexbox/#flexbox-background) for background, terminology, guidelines, and code snippets.One of three columnsOne of three columnsOne of three columnsCopy

```
<div class="container">
  <div class="row">
    <div class="col-sm">
      One of three columns
    </div>
    <div class="col-sm">
      One of three columns
    </div>
    <div class="col-sm">
      One of three columns
    </div>
  </div>
</div>
```

The above example creates three equal-width columns on small, medium, large, and extra large devices using our predefined grid classes. Those columns are centered in the page with the parent `.container`.

Breaking it down, here’s how it works:

* Containers provide a means to center and horizontally pad your site’s contents. Use `.container` for a responsive pixel width or `.container-fluid` for `width: 100%` across all viewport and device sizes.
* Rows are wrappers for columns. Each column has horizontal `padding` (called a gutter) for controlling the space between them. This `padding` is then counteracted on the rows with negative margins. This way, all the content in your columns is visually aligned down the left side.
* In a grid layout, content must be placed within columns and only columns may be immediate children of rows.
* Thanks to flexbox, grid columns without a specified `width` will automatically layout as equal width columns. For example, four instances of `.col-sm` will each automatically be 25% wide from the small breakpoint and up. See the [auto-layout columns](https://getbootstrap.com/docs/4.4/layout/grid/#auto-layout-columns) section for more examples.
* Column classes indicate the number of columns you’d like to use out of the possible 12 per row. So, if you want three equal-width columns across, you can use `.col-4`.
* Column `width`s are set in percentages, so they’re always fluid and sized relative to their parent element.
* Columns have horizontal `padding` to create the gutters between individual columns, however, you can remove the `margin` from rows and `padding` from columns with `.no-gutters` on the `.row`.
* To make the grid responsive, there are five grid breakpoints, one for each [responsive breakpoint](https://getbootstrap.com/docs/4.4/layout/overview/#responsive-breakpoints): all breakpoints (extra small), small, medium, large, and extra large.
* Grid breakpoints are based on minimum width media queries, meaning **they apply to that one breakpoint and all those above it** (e.g., `.col-sm-4` applies to small, medium, large, and extra large devices, but not the first `xs` breakpoint).
* You can use predefined grid classes (like `.col-4`) or [Sass mixins](https://getbootstrap.com/docs/4.4/layout/grid/#sass-mixins) for more semantic markup.

Be aware of the limitations and [bugs around flexbox](https://github.com/philipwalton/flexbugs), like the [inability to use some HTML elements as flex containers](https://github.com/philipwalton/flexbugs#flexbug-9).

## Map

Sham uses Google maps plugin. If you want to add a map to any page you have to first call the Google maps API after the footer and before the ending body tag like this:

```
<script src="https://maps.googleapis.com/maps/api/js?v=3.exp&key=YOUR_API_KEY"></script>
```

{% hint style="info" %}
Do not forget to add your **`api_key`** in the url, otherwise the map would not work.
{% endhint %}

Then add a div with the id `#map`, with attributes `data-lat=""` for latitude and `data-long=""` for longitude and `data-title=""` for title and `data-subtitle=""` for subtitle. Like this:

```
<div id="map" data-lat="40.9803480" data-long="28.7270580" data-title="YOUR_TITLE" data-subtitle="YOUR_SUBTITLE"></div>
```

## Icons

Sham using [Boxicons](https://boxicons.com/) iconset.

Using ([Boxicons](https://boxicons.com/)) pack is a very easy and simple, Let's take an example:

`<i class="bx bx-ICON_NAME"></i>` Example: `<i class="bx bx-search"></i>`

## Slider

Sham uses Bootstrap Carousel Plugin as its primary slider manager. You can view all available options for the carousel at their [website](http://getbootstrap.com/javascript/#carousel)

The basic structure implemented in Sham template is as follows:

```
<div class="slider">
	<div id="YOUR_SILDER_ID" class="carousel slide" data-ride="carousel">
		<!-- Indicators -->
		<ol class="carousel-indicators">
			<li data-target="#YOUR_SILDER_ID" data-slide-to="0" class="active"></li>
			<li data-target="#YOUR_SILDER_ID" data-slide-to="1"></li>
		</ol>

		<div class="carousel-inner">

			<!-- SLIDE WITH TEXT -->
			<div class="carousel-item active">
				<img src="dist/img/slides/02.jpg" class="d-block w-100" alt="...">
				<div class="carousel-caption d-none d-md-block">
					<div class="mask-left col-lg-8 m-auto">
						<h1>YOUR TITLE HERE.</h1>
						<p>YOUR PARAGRAPH HERE</p>
						<div class="button-group">
							<a href="#!" class="btn btn-primary">Shop Now</a>
							<a href="products-sidebar-left.html" class="btn btn-primary">Products</a>
						</div>
					</div>
				</div>
			</div><!-- /.carousel-item-->

			<!-- SLIDE WITHOUT TEXT -->
			<div class="carousel-item">
				<img src="dist/img/slides/01.jpg" class="d-block w-100" alt="...">
			</div><!-- /.carousel-item-->
		</div>
	</div>
</div>
```

## Flying to cart

> &#x20;If you are need add the product to your Application by AJAX just follows simple steps.

1. Open `app.js` file - Located in `js` folder.
2. You will find `addToCart` function.
3. Inside this function you will find comment `1- [Add product to 'Application' by AJAX]`
4. Add your AJAX code here :)

For get product ID, add the `product-id="ID"` attribute in `div` tag have an class `product`. For Example:

```
<div class="product" product-id="ITEM_ID">
  ....
</div>
```

Now you can use `productId` variable in `addToCart` function. (this variable will get `product-id` from attribute). `productId` variable defined in `app.js`

## Slide Toggle

> &#x20;Slide Toggle effect very easy and flexible with sham theme, Let's go to understanding how it works.

If are you need see example go to `checkout.html` file and click on "Click here to login" link, or try change (Payment Method).

#### How it works:

1. Create an element and add `data-slide-toggle="#YOUR_SELECTOR"` attribute.
2. Create `div` tag have that selector `<div id="YOUR_SELECTOR"></div>`

For Example:

```
<a href="#" data-slide-toggle=".login-form">Click here to login</a>
<div class="login-form">
	<!-- YOUR CONTENT HERE -->
</div>
```

## Helpers Classes

> Sham comes with a number of helpers classes along with the [Bootstrap utilities](https://getbootstrap.com/docs/4.4/utilities/borders/) classes.

| **Class**         | **Description**                                                                                                               |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `mask-left`       | Add nice mask as background.                                                                                                  |
| `browser-default` | You can add this class to get the browser default `checkbox` or `radio`.                                                      |
| `typed-cursor`    | typing animation cursor                                                                                                       |
| `align-vertical`  | You can easily vertically center things by adding this class to the container holding the items you want to vertically align. |
| `fullscreen`      | To set window height.                                                                                                         |

## Plugins

### &#x20;Slim Scroll

> &#x20;Small jQuery plugin that transforms any div into a scrollable area with a nice scrollbar. Demo and more: [Click Here](http://rocha.la/jQuery-slimScroll).

For use slimScroll with Sham theme option, just add `slim-scroll` attribute for user `div`, For Example:

```
<div slim-scroll>
    <!-- YOUR CONTENT -->
</div>
```

### Owl Carousel

> &#x20;Touch enabled jQuery plugin that lets you create a beautiful, responsive carousel slide. Demo and more: [Click Here](https://owlcarousel2.github.io/OwlCarousel2/).

Sham theme comes with a number of ready carousel, Like (Brands and Related Products).

#### Brands carousel structure:

Add `div` with `id="logos"` attribute, example:

```
<section class="section brands" id="brands">
	<div class="container">
		<div class="row">
			<div id="logos">
				<div class="item">
					<a href="#!"><img src="img/brands/1.png" class="img-fluid"></a>
				</div>
				<div class="item">
					<a href="#!"><img src="img/brands/2.png" class="img-fluid"></a>
				</div>
				<!-- MORE AND MORE BRANDS -->
			</div>
		</div>
	</div>
</section><!-- /#brands -->
```

#### Related Products carousel structure:

Add `div` with `id="related-products"` attribute, example:

```
<div id="related-products">
	<div class="product" product-id="1">
		<div class="inner-product">
			<span class="onsale">Sale!</span>
			<div class="product-thumbnail">
				<img src="img/18.jpg" class="img-fluid">
			</div>
			<div class="product-details text-center">
				<div class="align-vertical">
					<h3 class="product-title">PRODUCT TITLE</h3>
					<p>SOME TEXT HERE</p>
					<p class="product-price">
						<ins>
							<span class="amount">$450</span>
						</ins>
						<del>
							<span class="amount">$750</span>
						</del>
					</p>
					<div class="product-btns">
						<span data-toggle="tooltip" data-placement="top" title="Add To Cart">
							<a href="#!" class="li-icon add-to-cart"><i class="bx bxs-cart"></i></a>
						</span>
						<span data-toggle="tooltip" data-placement="top" title="View">
							<a href="#!" class="li-icon view-details"><i class="bx bx-search"></i></a>
						</span>
					</div>
				</div>
			</div>
		</div>
	</div><!-- /.product -->

	<!-- MORE AND MORE AMAZING PRODUCTS -->
</div>
```

### fancyBox

> &#x20;fancyBox is a tool that offers a nice and elegant way to add zooming functionality for images, html content and multi-media on your webpages. Demo and more: [Click Here](https://fancyapps.com/fancybox/3/).

For use fancyBox: Create link elements whose `href` attributes will contain the path of the element you wish to open within the fancyBox, then add `data-fancybox="images"`. Like this:

```
<a href="dist/img/products/1.jpg" data-fancybox="images">
    <img src="dist/img/products/1.jpg" class="img-fluid" alt="">
</a>
```

&#x20;If you have a set of related items that you would like to group, additionally include a group name in the `rel` (or `data-fancybox-group`) attribute.

If you need a caption, you may use:

```
<figure class="item">
	<a href="dist/img/products/1.jpg" data-fancybox="images">
		<img src="dist/img/products/1.jpg" class="img-fluid" alt="">
	</a>
	<figcaption class="d-none">
		<h6 class="text-white">This is an example with caption</h6>
		<a href="https://gum.co/fJYob">Photo by Hussam Abd</a>
	</figcaption>
</figure>
```
