the-simplest-breadcrumb
Version:
The simplest Breadcrumb you always needed
278 lines (234 loc) • 8.54 kB
Markdown
[![Contributors][contributors-shield]][contributors-url]
[![Forks][forks-shield]][forks-url]
[![Stargazers][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]
[![MIT License][license-shield]][license-url]
[![LinkedIn][linkedin-shield]][linkedin-url]
<!-- PROJECT LOGO -->
<br />
<p align="center">
<h3 align="center">The simplest Breadcrumb you always needed</h3>
<p align="center">
Your website is just a one line away from having an awesome dynamic breadcrumb that actually WORKS
<br />
<a href="https://github.com/amans199/the-simplest-breadcrumb"><strong>Explore the docs »</strong></a>
<br />
<br />
<a href="https://github.com/amans199/the-simplest-breadcrumb">View Demo</a>
·
<a href="https://github.com/amans199/the-simplest-breadcrumb/issues">Report Bug</a>
·
<a href="https://github.com/amans199/the-simplest-breadcrumb/issues">Request Feature</a>
</p>
</p>
<!-- TABLE OF CONTENTS -->
## Table of Contents
* [Installation and Usage](#usage)
* [Options](#options)
* [Use Cases](#use-cases)
* [plain javascript](#options)
* [React](#options)
* [Vue](#options)
* [Notes](#notes)
* [Contributing](#contributing)
* [License](#license)
* [Contact](#contact)
## Installation and Usage
1- Installing
```sh
npm install the-simplest-breadcrumb --save
```
2- Import it
```sh
import BreadcrumbMaster from 'the-simplest-breadcrumb'
```
3- Add any wrapper tag to html
```sh
<ul id="breadcrumb199__list"></ul>
```
4- Add this to your script
```sh
BreadcrumbMaster({
wrapper_id: 'breadcrumb199__list',
splitter: '/',
strings: {
home: "Home",
},
});
```
## features
1. **wrapper_id**: (*Required*)
this the id for the breadcrumb's wrapper tag in your html... just like `breadcrumb199__list` in `<ul id="breadcrumb199__list"></ul>`
2. **splitter**:
the symbol you want to use between the breadcrumb items... if not provided, the " forwardslash /" will be used.
3. **styles**:
1. items_gab: margin between items
1. color: the color of the breadcrumb's items
1. color_selected: the color of the breadcrumb's items
1. splitter_color: the color of of the splitter between the items
4. customElements: an array of static items, just in case you want your breadcrumb to be static.
5.**strings**:
an object that contains any string you want to change in the breadcrumb... the first item have to be `home: "Home"` always.
6. **exceptions_list**:
an array of objects containing the pages you want to add a customElements in it instead of the breadcrumb's default behaviour.
example :
```
exceptions_list:[
{
page:"user",
customElements: [
{ index: 2, text: 'loremFirst', url: '#loremFirst' },
{ index: 3, text: 'loremSecond', url: '#loremSecond' },
{ index: 4, text: 'loremThird', url: '/amans199' },
],
}
]
```
## Use Cases
<br />
1. #### using the-simplest-breadcrumb in plain javascript to show a static breadcrumb
```sh
BreadcrumbMaster({
wrapper_id: 'breadcrumb199__list',
splitter: '/',
styles: {
items_gab: '5px',
color: '#fff',
color_selected: '#000',
splitter_color: '#fff'
},
customElements: [
{ index: 1, text: 'firstElement', url: '#' },
{ index: 2, text: 'secondElement', url: '#' },
{ index: 3, text: 'thirdElement', url: '#' },
{ index: 4, text: 'fourthElement', url: '#' },
],
exceptions_list:[
{
page:"user",
customElements: [
{ index: 2, text: 'loremFirst', url: '#loremFirst' },
{ index: 3, text: 'loremSecond', url: '#loremSecond' },
{ index: 4, text: 'loremThird', url: '/amans199' },
],
},
]
})
```
<br />
2. #### using the-simplest-breadcrumb with **React** to show a multilang dynamic breadcrumb
```sh
render(){
BreadcrumbMaster({
wrapper_id: 'breadcrumb199__test2',
splitter: '/',
styles: {
items_gab: '5px',
color: '#fff',
color_selected: '#000',
splitter_color: '#fff'
},
strings: {
home: "Home",
user: "المستخدم",
"users-list": "用户列表",
},
exceptions_list:[
{
page:"user",
customElements: [
{ index: 2, text: 'loremFirst', url: '#loremFirst' },
{ index: 3, text: 'loremSecond', url: '#loremSecond' },
{ index: 4, text: 'loremThird', url: '/amans199' },
],
},
]
})
return (
<div className="App">
<header className="App-header">
<ul id="breadcrumb199__test2"></ul>
</header>
</div>
);
}
```
<br />
* if you are using React-router then please don't forget to add the breadcrumb component inside a Switch ..
```
<Switch>
<App />
</Switch>
```
<hr />
----------------
3. #### using the-simplest-breadcrumb with **Vue** to show a multilang dynamic breadcrumb
```sh
data(){
return{
userString:"User String"
};
},
mounted(){
BreadcrumbMaster({
wrapper_id: 'breadcrumb199__test2',
splitter: ">",
styles: {
items_gab: '5px',
color: '#fff',
color_selected: '#000',
splitter_color: '#fff'
},
strings: {
home: "Home",
user: this.userString,
"users-list": "用户列表",
},
exceptions_list:[
{
page:"user",
customElements: [
{ index: 2, text: 'loremFirst', url: '#loremFirst' },
{ index: 3, text: 'loremSecond', url: '#loremSecond' },
{ index: 4, text: 'loremThird', url: '/amans199' },
],
},
]
})
}
```
<br />
## Notes
1. all the elements of the breadcrumb are injected to DOM in a way that makes it really easy tto be styled using plain css.
2. the-simplest-breadcrumb can be used with any type of application ( SPA or not SPA), and any type of javascript framework... whenever you place it in the right lifecycle, it will get the job done perfectly.
<br />
<!-- CONTRIBUTING -->
## Contributing
Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are **greatly appreciated**.
1. Fork the Project
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the Branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
See the [open issues](https://github.com/amans199/the-simplest-breadcrumb/issues) for a list of proposed features (and known issues).
<!-- LICENSE -->
## License
Distributed under the MIT License. See `LICENSE` for more information.
<!-- CONTACT -->
## Contact
Ahmed Mansour - [@amans199](https://twitter.com/amans199) - ahmed.ouda1997@gmail.com
Project Link: [https://github.com/amans199/the-simplest-breadcrumb](https://github.com/amans199/the-simplest-breadcrumb)
<!-- MARKDOWN LINKS & IMAGES -->
[contributors-shield]: https://img.shields.io/github/contributors/amans199/Best-README-Template.svg?style=flat-square
[contributors-url]: https://github.com/amans199/the-simplest-breadcrumb/graphs/contributors
[forks-shield]: https://img.shields.io/github/forks/amans199/Best-README-Template.svg?style=flat-square
[forks-url]: https://github.com/amans199/the-simplest-breadcrumb/network/members
[stars-shield]: https://img.shields.io/github/stars/amans199/Best-README-Template.svg?style=flat-square
[stars-url]: https://github.com/amans199/the-simplest-breadcrumb/stargazers
[issues-shield]: https://img.shields.io/github/issues/amans199/Best-README-Template.svg?style=flat-square
[issues-url]: https://github.com/amans199/the-simplest-breadcrumb/issues
[license-shield]: https://img.shields.io/github/license/amans199/Best-README-Template.svg?style=flat-square
[license-url]: https://github.com/amans199/the-simplest-breadcrumb/blob/master/LICENSE.txt
[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=flat-square&logo=linkedin&colorB=555
[linkedin-url]: https://linkedin.com/in/amans199
[product-screenshot]: images/screenshot.png