README

摘要
- 开发者注意事项
基本功能
实现
使用 PinnedImage 类 (PHP)
- 所需参数
- 作为 HTML 渲染
  - 标准模板 (.pinned-container)
  - 完整模板 (.pinned-container-full)
待办事项

摘要

PinnedImage 的目的是创建一个更友好且响应式的图像映射，模拟固定地图机制，但适用于任何图像。我的主要目标是添加功能和能力，但暂时只做基本功能。

我还在考虑是否应该实现 JavaScript 以进行交互和动画，但目前，所有动画将通过层叠样式表方法和规则处理，交互通过 JavaScript 完成。

如果禁用 JavaScript，将在 .pinned-container DOM 分区下方添加一个图例。建议您将容器设置在您可以控制的容器中，并且不会破坏您的模板外观，特别是在移动设备上，图例将放在 noscript 标签之间，除非强制显示。

<div id="myPinnedImage" class="pinned-container">...</div>
<noscript>
    <div id="PinOne-legend" class="pinned-flex">
        <div class="pinned-flex-row">
            <div class="pinned-flex-item-key">...</div>
            <div class="pinned-flex-item-value">...</div>
        </div>
    </div>
</noscript>

开发者注意事项

要操作或自定义样式，您需要在您的开发系统上安装并初始化 Ruby 和 Sass。此外，此插件需要安装 raphievila/xtags 和 raphievila/utils，这些将在您运行时安装。

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

此外，如果您使用 PinnedImage 对象，则会在具有 Bootstrap 类的 HTML 中进行渲染，如果您想要在项目中实现或已经实现它。如果是这样，您需要按照 Bootstrap 的要求使用 jQuery 和 Popper。

我尽量将 JavaScript 的使用量降至最低，以提供轻量级且格式良好的体验，该体验对移动设备和桌面都友好。但这不应阻止您尽情发挥创造力。代码不具侵入性，这是故意为之，以便您可以按自己的喜好操作。

基本功能

找到 coords.json 并进行修改，默认文件将如下所示

[
    {
        "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
    }
]

不是所有参数都是必需的，除了：id, tip, x 和 y。值类型解释如下

[
    {
        "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 [%]"
    }
]

该 JSON 应该是一个包含每个固定项目对象（键 => 值 结构）的数组列表。

实现

要使用 PinnedImage 与您的网站，您需要在您的 HTML 项目的 head 标签中包含以下内容

<link href="location/to/you/css/dir/pinned-image.css" rel="stylesheet" type="text/css" />

在 body 标签的任何地方，建议在关闭 '</body>' 标签之前放置

<script type="text/javascript" src="location/of/your/script/library/pinned-image.js"></script>

如果正确实现了，则您的代码应类似于以下内容

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>Pinned Image Home Page</title>
    <link href="location/to/you/css/dir/pinned-image.css" rel="stylesheet" type="text/css" />
</head>
<body>

    <!-- your template goes here -->

    <script type="text/javascript" src="location/of/your/script/library/pinned-image.js"></script>
</body>
</html>

此外，您需要设置两个由 pinned-image.js 要求的全局变量，这些变量用于为即将推出的自动加载功能做准备（尚未实现）。如下在嵌入 pinned-image.js 之前设置这些变量

<script type="text/javascript">
    'use strict';
    var AUTOLOAD = false,
        MYCOORDS = false;
</script>
<script type="text/javascript" src="location/of/your/script/library/pinned-image.js"></script>

注意：为了避免获取控制台错误并且不想经常设置这些全局变量，您可以在 pinned-image.js 文件中添加它们作为可编辑的全局变量。

使用 PinnedImage 类 (PHP)

您可以通过 Composer 加载 PinnedImage 类

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

如果您有自己的加载解决方案，则可以使用它

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

请记住，此对象需要2个额外的对象 raphievila\xtags 和 raphievila\utils，这些对象将在您运行命令时安装。

$ > composer require raphievila/pinned-image

所需参数

上面的对象在渲染时将显示错误。您必须传递所需的图像参数 imageURL，至少才能使用默认的 JSON 文件进行渲染。您可以设置以下参数：

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

$pi = new PinnedImage($params);

有关参数的完整列表，请访问 raphievila/pinned-image/wiki/Parameters。

通常，当您使用可重用代码时，是因为您可能需要同时多次使用它，为此您需要使用 reload 方法。

作为 HTML 渲染

一旦设置好参数，您就可以使用 PinnedImage::render 方法回显最终的 HTML。

echo $pi->render();

根据发送的参数，代码可以以两种不同的格式渲染：标准格式或完整模板。

标准模板 (.pinned-container)

当渲染这个小小的代码片段时，它将被以下结构替换：

<!-- standard format -->
<div id="PinnedID" class="pinned-container">
    <img src="imageURL" alt="imageALT" class="pinned-image" />

    <!-- pin structure -->
    <div id="json->id" class="pinned-point" data-x="json->x%" data-y="json->y%">
        <a alt="json->label" class="pinned-point-label">
            <span>json->label</span>
        </a>
        <div class="pinned-point-tip">
            <div class="pinned-point-sticker">
                <h3 class="pinned-point-title">json->title</div>
                <p class="pinned-point-banner">json->tip</div>
            </div>
        </div>
    </div>
</div>

完整模板 (.pinned-container-full)

如果您设置参数 containerClass 的值为 pinned-container-full，当请求渲染方法时，将替换为：

<!-- standard format -->
<div id="PinnedID" class="pinned-container">
    <img src="imageURL" alt="imageALT" class="pinned-image" />

    <!-- pin structure -->
    <a alt="json->label" class="pinned-point-label" rel="json->id">
        <span>json->label</span>
    </a>
    <div id="json->id" class="pinned-point-tip">
        <div class="pinned-point-sticker">
            <h3 class="pinned-point-title">json->title</div>
            <p class="pinned-point-banner">json->tip</div>
        </div>
    </div>
</div>

注意：如果您注意到了，这在应用自定义样式时很重要，在完整模板版本中，每个标签都不是包含在 .pinned-point 容器内，此容器被移除，标签（《.pinned-point-label》）以及标签容器（《.pinned-point-tip》）被设置为父级标签容器 .pinned-container 的子项。

对于这个场景，我将替换之前的参数为以下：

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

$pi = new PinnedImage($params);

echo $pi->render();

目前，containerClass 参数只能是 pinned-container（默认）或 pinned-container-full。仅为此完整模板设置此选项。有关更多信息，请参阅 Templating。

待办事项

我需要做的事情和将很快添加

Ajax 请求 PinnedImage 渲染。
根据角落的邻近性自动调整提示块的本地化。
彩色主题。
标签图标。
创建自定义标签的能力。
类似地图的可拖动内容。
缩放/缩放。 (可能是)

raphievila / pinned-image

维护者

详细信息