README

这是一个 PhileCMS 插件，它扩展了 Markdown 语法，以方便地将链接、图片、视频或其他内容添加到您的页面。这些“片段”易于添加和自定义，并且该插件自带大量有用的片段。

此插件与默认的 Markdown 解析器兼容，但也应该与提供 Markdown 替代方案的任何其他插件兼容。如果应用于常规 HTML 文件，它也应该可以工作。

安装

使用 composer

php composer.phar require infostreams/snippets:*

下载

• 安装 Phile
• 将此存储库克隆到 plugins/infostreams/snippets

激活

在您已安装插件后，您需要将以下行添加到您的 config.php 文件中

$config['plugins']['infostreams\\snippets'] = array('active' => true);

功能说明

使用此插件，您可以在 Markdown 中包含预定义的 HTML 片段。这意味着您可以编写类似以下内容

This is some text before I introduce you to the main point of this example, the YouTube video
that I want to include here:

(youtube: https://www.youtube.com/watch?v=mSB71jNq-yQ)

In case you can't see that video, you can have a look at the slideshow that I'll include for
your pleasure: (slideshow: [images/a.jpg, images/b.jpg, images/c.jpg] heading: Awesome slideshow)

I've taken these images from (link: site.com text: this site)

基本上，它扩展了标准 Markdown 语法，以便更容易地使用比基本格式化更多的交互式网页。Markdown 很适合向您的页面添加标题、粗体文本、链接和列表，但它几乎没有提供添加其他元素到页面的方案。使用 Snippets，您可以轻松添加这些元素。您可以使用其中许多包含的片段，也可以轻松定义自己的新片段。

支持的语法

一般说明：片段标签可以指定在多行中，属性值可以是标量值（字符串或整数）或值的列表（数组）- 在这种情况下，它们将被解析为这样的。

链接

您可以链接到外部网站和您自己的网站上的页面

(link: cnn.com)
(link: products/mastergrill5000)

如下指定链接文本

(link: cnn.com text: the site I was talking about)

添加一个当您将鼠标移至链接时显示的标题

(link: cnn.com title: click to visit!)

通过添加“popup”属性，链接在弹出窗口中打开

(link: cnn.com popup: true)

您可以指定用于样式的自定义 CSS 类

(link: cnn.com class: my-css-class)

可以组合这些属性，或者省略属性

(link: cnn.com class: my-css-class popup:true text:CNN title:Click to go to the CNN homepage)

电子邮件地址

您可以如下链接到电子邮件地址

(email: someone@example.com)

为链接提供文本

(email: someone@example.com text:My email address)

添加一个当您将鼠标移至链接时显示的标题

(email: someone@example.com title:Click to email me)

您可以指定用于样式的自定义 CSS 类

(email: someone@example.com class: my-css-class)

图片

您可以包含来自您自己的网站或外部网站上的图片

(image: products/mastergrill5000/grilling.jpg)
(image: https://raw.githubusercontent.com/dcurtis/markdown-mark/master/png/66x40-solid.png)

设置宽度和高度

(image: products/mastergrill5000/grilling.jpg width:400)
(image: products/mastergrill5000/grilling.jpg width:400 height:600)

指定 alt 文本

(image: products/mastergrill5000/grilling.jpg alt:Smoking!)

添加标题

(image: products/mastergrill5000/grilling.jpg caption:Grilling on the MasterGrill5000)

指定 CSS 类

(image: products/mastergrill5000/grilling.jpg class:highlight)

将图片链接到页面或外部网站

(image: products/mastergrill5000/grilling.jpg link:products/mastergrill5000)
(image: products/mastergrill5000/amazon.jpg link:amazon.com/buy-the-mg5000)

添加“srcset”属性以处理响应式图片

(image: products/mastergrill5000/grilling.jpg srcset:products/mastergrill5000/grilling@2x.jpg 2x)

文件

包含来自您自己的网站或外部网站上的文件

(file: products/brochure.pdf)
(file: https://bitcoin.org/bitcoin.pdf)

指定链接的文本

(file: products/brochure.pdf text:our brochure)

强制下载文件（遗憾的是，浏览器支持有限）

(file: products/brochure.pdf download:true)

指定 CSS 类

(file: products/brochure.pdf class:highlight)

YouTube 视频

在文档中嵌入 YouTube 视频

(youtube: https://www.youtube.com/watch?v=mSB71jNq-yQ)

指定宽度和/或高度

(youtube: https://www.youtube.com/watch?v=mSB71jNq-yQ width:640)
(youtube: https://www.youtube.com/watch?v=mSB71jNq-yQ width:640 height:480)

Vimeo 视频

在文档中嵌入 Vimeo 视频

(vimeo: http://vimeo.com/63968108)

指定宽度和/或高度

(vimeo: http://vimeo.com/63968108 width:700)
(vimeo: http://vimeo.com/63968108 width:700 height:393)

包括肖像、标题和作者信息的选项

(vimeo: http://vimeo.com/63968108 portrait:false)
(vimeo: http://vimeo.com/63968108 portrait:false byline:false)
(vimeo: http://vimeo.com/63968108 portrait:false byline:false title:true)

Twitter

嵌入 Twitter 个人资料的链接

(twitter: @nytimes)

嵌入 Twitter 标签的链接

(twitter: #superimportant)

嵌入 Twitter 搜索链接

(twitter: #superimportant keywords)

指定链接的文本

(twitter: @nytimes text:The New York Times on Twitter)

指定 CSS 类

(twitter: @nytimes class:twitter-button)

Gist

嵌入 Github Gist

(gist: https://gist.github.com/1)

显示该 gist 中的特定文件

(gist: https://gist.github.com/1 file: gistfile1.txt)

电话号码

添加电话号码的链接

(tel: 555-0100)

指定用于链接的文本

(tel: 555-0100 text:Call me!)

您可以指定用于样式的自定义 CSS 类

(tel: 555-0100 class:phone)

添加您自己的片段

定义自己的代码片段非常简单。你很可能会通过PhileCMS配置文件来完成这项操作。

简单案例

示例

$config['plugins']['infostreams\\snippets']['snippets'] = array(
    'skype' => function($name, $action="call", $text=null) {
                   if (is_null($text)) {
                     $text = "Contact '$name' on Skype";
                   }
                   return "<a href='skype:$name?$action'>$text</a>";
               }
);

这将为'Skype'添加一个代码片段，您可以在（Markdown）中如下使用它：

(skype: myfriend)

这将渲染为：

<a href='skype:myfriend?call'>Contact 'myfriend' on Skype</a>

PHP函数有两个额外的参数，这意味着'Skype'代码片段允许指定两个额外的属性，如下所示：

(skype: my.account.on.skype action:chat text:Chat to me on Skype!)

这将生成以下HTML：

<a href='skype:my.account.on.skype?chat'>Chat to me on Skype!</a>

使用现有函数

首先，在某个类中定义您的代码片段，并确保它被包含。

class MySnippets {
    public function skype($name, $action="call", $text=null) {
        if (is_null($text)) {
            $text = "Contact '$name' on Skype";
        }
        return "<a href='skype:$name?$action'>$text</a>";
    }
}

然后，将'Skype'代码片段添加到代码片段配置中。

$config['plugins']['infostreams\\snippets']['snippets'] = array(
    'skype' => array(new MySnippets(), 'skype'),
);

使用代码片段类

您还可以定义一个具有多个代码片段的类，并一次性将它们全部添加。首先，定义您的类，并确保它继承自\Phile\Plugin\Infostreams\Snippets\Snippets类（这为您提供了某些常用功能）。然后，确保PhileCMS包含它。有关如何正确操作的步骤指南在此。

class MySnippets extends \Phile\Plugin\Infostreams\Snippets\Snippets {
    public function skype($name, $action="call", $text=null) {
        if (is_null($text)) {
            $text = "Contact '$name' on Skype";
        }
        return "<a href='skype:$name?$action'>$text</a>";
    }

    public function facebook($who, $attribute, $other_attribute) {
        // ...
    }

    public function scroller($pictures) {
        // ...
    }

    public function youtube_popup($link) {
        // ...
    }
}

现在，您可以通过将以下代码添加到PhileCMS的配置文件中，添加skype、facebook、scroller和youtube_popup代码片段（以及您定义的任何未来代码片段）：

$config['plugins']['infostreams\\snippets']['snippets'] = array(
    new MySnippets(),
    'some_other_snippet' => function($a, $b) { },
    'yet_another_snippet' => array(new MyOtherClass(), 'method')
);

出于方便和美观的考虑，名称中包含下划线的代码片段（如youtube_popup）也可以使用破折号代替。因此，您不仅可以写作(youtube_popup: ....)，还可以写作(youtube-popup: ....)。

属性值：数组与JSON

参数值不仅限于字符串或数字，也可以是数组！您甚至可以提供JSON字符串——它们将被解析并转换为可以在代码片段内部使用的格式。以下代码定义了一个'slideshow'代码片段：

$config['plugins']['infostreams\\snippets']['snippets'] = array(
    'slideshow' => function($images, $header="") {
                   $html = "";
                   if (!is_null($text)) {
                     $html .= "<h1>" . $header . "</h1>";
                   }
                   if (is_array($images)) {
                     $html .= "\n<ul>";
                     foreach ($images as $key=>$value) {
                       if (is_numeric($key)) {
                         $filename = $value;
                         $description = "";
                       } else {
                         $filename = $key;
                         $description = "<span class='description'>" . $value . "</span>";
                       }
                       $html .= "\n<li><img src='$filename' />$description</li>";
                     }
                     $html .= "\n<ul>";
                   }
                   return "<div class='slideshow'>" . $html . "</div>";
               }
);

此代码生成了一个简单幻灯片的HTML。可以使用如下方式使用它：

(slideshow: [content/images/a.jpg, content/images/b.jpg, content/images/c.jpg] heading: It's a slideshow!)

在这里，您可以看到如何为单个字段提供多个值。上面的示例将创建一个由a.jpg、b.jpg和c.jpg组成的幻灯片。

然而，代码片段也可以用来给幻灯片中的每张图片添加描述。这可以这样操作。为了可读性，代码片段被分成了多行：

(slideshow: [
    content/images/a.jpg: This is my description,
    content/images/b.jpg: "This one description, it contains a comma -- so we wrap it in quotes"
    content/images/c.jpg: However\, if you don't want to quote\, you don't need to
                          - it could get ugly quickly though
    ]
    heading: It's a slideshow!)

图片列表现在是一个类似PHP的（键，值）对的数组。'键'是图片的文件名，'值'是图片的描述。这样，您可以为只有当作者提供多个值时才起作用的代码片段编写代码——例如幻灯片。您可以使用此语法构建复杂的数据结构。

文本转义

您会发现，在大多数情况下，您不需要将描述用引号包围。如果您想这么做，也是可以的——如第二个描述（b.jpg的描述）所示。

只要文本不包含逗号、冒号或'[', '{', '}', ']'中的一个，您就不需要引号。如果它包含这些字符中的一个，您可以通过在该字符之前放置一个反斜杠来“转义”它，如第三个描述（c.jpg的描述）所示。

JSON

最后，如果您不喜欢上述语法，您也可以使用纯JSON。

(slideshow:  {
     "content\/images\/a.jpg":"This is my description",
     "content\/images\/b.jpg":"This one description, it contains a comma -- so we wrap it in quotes",
     "content\/images\/c.jpg":"However, if you don't want to quote, you don't need to - it could get ugly quickly though"
    }
    heading: It's a slideshow!)

Kirbytext

此插件是对Kirbytext的MIT许可开源重实现和扩展。

它正确解析了Kirbytext的大部分语法，尽管生成的HTML可能有所不同。两者之间没有兼容性的保证，尽管高水平的向后兼容性是设计目标之一。