PHPackages                             raphievila/pinned-image - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Image & Media](/categories/media)
4. /
5. raphievila/pinned-image

ActiveLibrary[Image & Media](/categories/media)

raphievila/pinned-image
=======================

A new advance image mapping system that allows to pin an image with animated help tips by user interaction

025PHP

Since Feb 22Pushed 7y ago1 watchersCompare

[ Source](https://github.com/raphievila/pinned-image)[ Packagist](https://packagist.org/packages/raphievila/pinned-image)[ RSS](/packages/raphievila-pinned-image/feed)WikiDiscussions master Synced 2d ago

READMEChangelogDependenciesVersions (1)Used By (0)

Pinned Image
=============

[](#pinned-image-)

- [Summary](#summary)
    - [Note For Developers](#note-for-developers)
- [Basic Functionality](#basic-functionality)
- [Implementation](#implementation)
- [Using PinnedImage Class (PHP)](#using-pinnedimage-class-php)
    - [Required Parameters](#required-parameters)
    - [Renderign as HTML](#renderign-as-html)
        - [Standard Template (.pinned-container)](#standard-template-pinned-container)
        - [Full Template (.pinned-container-full)](#full-template-pinned-container-full)
- [TODO](#todo)

Summary
-------

[](#summary)

`PinnedImage` purpose is to create a more friendly and responisive image mapping simulating a pinned map mechanism but with any image. My main goal is to add functionalities and capabilities, but for now, will do basic functionalities.

I'm still debating if should implement JavaScript for interaction and animation, for the moment, all animations will be handle using Cascade Stylesheet methods and rules, and interactions through JavaScript.

If JavaScript is disable a legend will be added under the **`.pinned-container`** DOM division. My suggestion would be for you to set the container inside a container you can control and won't break your template's look specially when on mobile, legend will be posted between a `noscript` tag unless it is forced to show up always.

```
...

            ...
            ...

```

### Note For Developers

[](#note-for-developers)

To manipulate or customize the styling, you require to have Ruby and Sass installed and initialized on your developing system. Also this plug-in requires raphievila/xtags and raphievila/utils which are going to be installed when your run:

```
$ cd /your-project-location/
$ /your-project-location/composer require raphievila/pinned-image
```

Also, if you use the PinnedImage object this render the HTML with [Bootstrap](https://getbootstrap.com) classes if you would like to implement it or already implemented on your project. If so you are required by Bootstrap to use [jQuery](https://jquery.com) and [Popper](https://popper.js.org).

I tried keep the use of JavaScript to minimum to provide you with a light nicely formatted experience that is mobile and desktop friendly. But this should not stop you of letting your creativity run wild. The code is not intrusive which is made in purpose to be used as a bootstrap that you can manipulate at your own taste.

Basic Functionality
-------------------

[](#basic-functionality)

Find `coords.json` and modify to liking, the default file would look like this:

```
[
    {
        "id": "PointOne",
        "label": 1,
        "title": "Pinned One",
        "tip": "First pinned point on map",
        "uri": "#",
        "class": "extra classes",
        "x": 20,
        "y": 20
    },
    {
        "id": "PointTwo",
        "label": 2,
        "title": "Pinned Two",
        "tip": "Second pinned point on map",
        "uri": "#",
        "class": "extra classes",
        "x": 40,
        "y": 40
    }
]
```

Not all paremeters are required except: `id, tip, x and y`. The value type is explained as follow:

```
[
    {
        "id": "String or Number - should comply with DOM id standards",
        "label": "[optinal] String or Number - The label will be shown when the pin is on default state",
        "title": "[optional] String - The title of the tip",
        "tip": "[required] String - Full tip description or instruction",
        "uri": "[optional] STRING URL - If tip link to anywhere, add the URL address here",
        "class": "[optional] STRING - To include special styling to overwrite code default",
        "x": "[required] NUMBER - From Left - percentage value base of container origin do not include [%]",
        "y": "[required] NUMBER - From Top - percentage value base of container origin do not include [%]"
    }
]
```

The `JSON` should be an array list with each pin item as objects ***(key => value)*** structure.

Implementation
--------------

[](#implementation)

To use `PinnedImage` with your website you need to include the following into the `head` tag of your HTML project:

```

```

The any where inside the `body` tag, it is recommended at the very end right before the closing '</body>` tag:

```

```

If this has been implemented properly your code should look something like this:

```
>

    Pinned Image Home Page

```

Also, you need to set two globals required by the `pinned-image.js` that are set to prepare for a coming Auto Load feature not yet implemented. Set these right before embedding the `pinned-image.js` as follow:

```

    'use strict';
    var AUTOLOAD = false,
        MYCOORDS = false;

```

**Note**: To avoid getting console errors and not wanting to set these globals all the time, you can add them as editable globals in the `pinned-image.js` file.

Using PinnedImage Class (PHP)
-----------------------------

[](#using-pinnedimage-class-php)

The `PinnedImage` class can be loaded through Composer as:

```
require 'your/composer/loader/location/vendor/autoload.php';
use raphievila\ImageTools\PinnedImage;
$pi = new PinnedImage();
```

If you have your own loader solution you can use it as:

```
//Location depends where the PinnedImage src diretory is located
require 'pinned-image/src/assets/controllers/PinnedImage.php';
use raphievila\ImageTools\PinnedImage;
$pi = new PinnedImage();
```

Just remember that this object require 2 additional objects [raphievila\\xtags](https://github.com/raphievila/xtags) and [raphievila\\utils](https://github.com/raphievila/utils), which will be installed when you run the command:

```
$ > composer require raphievila/pinned-image
```

### Required Parameters

[](#required-parameters)

The object above will display an error if its rendered. You have to pass the image required parameter `imageURL` at least to be able to render using the default `JSON` file. You can set parameters as follow:

```
$params = array(
    'imageURL' => '/your/image/url.jpg'
);

$pi = new PinnedImage($params);
```

For a full list of parameters visit [raphievila/pinned-image/wiki/Parameters](https://github.com/raphievila/pinned-image/wiki/Parameters).

As usual, when you use a reusable code is because you probably need to use it multiple times at a time, for this you need to use the `reload` method.

### Renderign as HTML

[](#renderign-as-html)

Once are parameters are set, they you an echo the final `HTML` using the `PinnedImage::render` method:

```
echo $pi->render();
```

Depending the parameters sent the code can be rendered in two different formats: *Standard or Full Template*

#### Standard Template (.pinned-container)

[](#standard-template-pinned-container)

When rendered this tiny piece of code will be replaced with the following structure:

```

            json->label

                json->title
                json->tip

```

#### Full Template (.pinned-container-full)

[](#full-template-pinned-container-full)

If you set parameter `containerClass` with value `pinned-container-full`, when the render method is requested will be replaced with:

```

        json->label

            json->title
            json->tip

```

**NOTE:** If you pay attention, and this is important when you are applying a custom styling, on the full template version each pin is not contained inside the container `.pinned-point`, this container is removed and the pin (`.pinned-point-label`) along with the tip label container (`.pinned-point-tip`) are set as childs of the main pinned image container `.pinned-container`.

For this scenario I will replace the previous parameter with the following:

```
$params = array(
    'imageURL' => '/your/image/url.jpg',
    'containerClass' => 'pinned-container-full'
);

$pi = new PinnedImage($params);

echo $pi->render();
```

For now the containerClass parameter can only be `pinned-container` (default) or `pinned-container-full`. Only set this up for full template only. For more information see [Templating](https://github.com/raphievila/pinned-image/wiki/Templating.md).

TODO
----

[](#todo)

Things I need to do and will be added shortly:

1. Ajax requested PinnedImage render.
2. Automatic localization adjustment for tip blocks depending on corner proximity.
3. Color Coded Themes.
4. Pin Icons.
5. The ability to create custom pins.
6. Map-like draggable content.
7. Zoom-In / Zoom-Out. (Probably)

###  Health Score

19

—

LowBetter than 10% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity6

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity38

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/08919338e3e0c70087b6db2241a9da1acd1918c1fec0c11978061df46dedda52?d=identicon)[raphievila](/maintainers/raphievila)

---

Top Contributors

[![raphievila](https://avatars.githubusercontent.com/u/6283126?v=4)](https://github.com/raphievila "raphievila (28 commits)")

### Embed Badge

![Health badge](/badges/raphievila-pinned-image/health.svg)

```
[![Health](https://phpackages.com/badges/raphievila-pinned-image/health.svg)](https://phpackages.com/packages/raphievila-pinned-image)
```

###  Alternatives

[milon/barcode

Barcode generator like Qr Code, PDF417, C39, C39+, C39E, C39E+, C93, S25, S25+, I25, I25+, C128, C128A, C128B, C128C, 2-Digits UPC-Based Extention, 5-Digits UPC-Based Extention, EAN 8, EAN 13, UPC-A, UPC-E, MSI (Variation of Plessey code)

1.5k13.3M39](/packages/milon-barcode)[bkwld/croppa

Image thumbnail creation through specially formatted URLs for Laravel

510496.0k23](/packages/bkwld-croppa)[goat1000/svggraph

Generates SVG graphs

132849.6k3](/packages/goat1000-svggraph)[cohensive/embed

Media Embed (for Laravel or as a standalone).

120370.4k](/packages/cohensive-embed)[netresearch/rte-ckeditor-image

Image support in CKEditor for the TYPO3 ecosystem - by Netresearch

63991.3k4](/packages/netresearch-rte-ckeditor-image)[humanmade/tachyon-plugin

Rewrites WordPress image URLs to use Tachyon

87338.5k2](/packages/humanmade-tachyon-plugin)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)