README

SiteBundle 执行以下操作

• 定义用于显示网页的布局
• 使用变量来显示与网站、名称等相关的数据
• 只需设置 URL 和 ID，即可添加 Matomo JavaScript
• 只需添加数据即可添加 CookieConsent
• 允许覆盖 TwigBundle/Exception 模板
• 允许使用预定义的使用条款、销售条款等

SiteBundle 专用网页.

SiteBundle API 文档.

包安装

### 第 1 步：下载包

使用 Composer 安装库

    composer require c975L/site-bundle

### 第 2 步：配置包

c975LSiteBundle v2.0+ 使用 c975L/ConfigBundle 来管理配置参数。使用带有适当用户角色的路由 "/site/config" 来修改它们。

从 v1.x 升级？请检查 UPGRADE.md

### 第 3 步：启用路由

然后，将它们添加到您项目的 config/routes.yaml 文件中，以启用路由

c975_l_site:
    resource: "@c975LSiteBundle/Controller/"
    type: annotation
    prefix: /
    #Multilingual website use the following
    #prefix: /{_locale}
    #defaults:   { _locale: '%locale%' }
    #requirements:
    #    _locale: en|fr|es

### 第 4 步：将资源安装到网页文件夹

通过运行以下命令安装资源

php bin/console assets:install --symlink

它将在您的网页文件夹中创建一个从 Resources/public/ 文件夹的链接。这些文件在 layout.html.twig 中使用。

### 使用方法

您必须在 app/Resources/views/ 中创建一个名为 layout.html.twig 的文件，并使其扩展 @c975LSite/layout.html.twig，因此只需在顶部添加此 {% extends '@c975LSite/layout.html.twig' %} 即可。

SiteBundle 使用以下变量，这些变量是按页面进行的，这意味着它们会随着每个页面而改变。如果您想使用它们，只需在每个扩展您的 app/Resources/views/layout.html.twig 的页面上声明它们即可。

{% set title = 'YOUR_PAGE_TITLE' %}
{% set description = 'YOUR_PAGE_DESCRIPTION' %}

注意：如果您使用 c975L/PageEdit，变量已经传递到 layout.html.twig。

### 覆盖一个块

您可以在模板中覆盖任何块，要这样做，只需在您的 app/Resources/views/layout.html.twig 中添加以下内容即可

{% block share %}
    {# You can also use {{ parent() }} #}
    {# YOUR_OWN_TEXT #}
{% endblock %}

查看 Resources/views/layout.html.twig，以查看所有可用的块。

### 禁用块

要禁用块，只需在您的 app/Resources/views/layout.html.twig 中添加以下内容即可

{% block share %}
{% endblock %}

查看 Resources/views/layout.html.twig，以查看所有可用的块。

### 使用显示变量

在您的 app/Resources/views/layout.html.twig 中，您可以使用以下内容来包含（或不禁用）模板

{% if display == 'pdf' %}
    {% include 'header-pdf.html.twig' %}
{% else %}
    {% include 'header.html.twig' %}
{% endif %}

如果未定义 display，则将其定义为 html。

### Matomo JavaScript

您可以通过在您的 app/Resources/views/layout.html.twig 中添加以下内容来轻松添加对 matomo 的调用

{%
    set matomo = {
        'id': YOUR_MATOMO_ID,
        'url': 'YOUR_MATOMO_URL'
    }
%}

### CookieConsent

您可以通过在您的 app/Resources/views/layout.html.twig 中添加以下内容来轻松添加对 CookieConsent 的调用

{%
    set cookieConsent = {
        'message': 'YOUR TEXT',
        'dismiss': 'YOUR_DISMISS_TEXT',
        'link': 'YOUR_COOKIES_POLICY_LINK_TEXT',
        'href': 'YOUR_COOKIES_POLICY_LINK'
    }
%}
{# or use the texts defined in SiteBundle #}
{%
    set cookieConsent = {
        'message': 'text.cookies_banner'|trans,
        'dismiss': 'text.cookies_dismiss'|trans,
        'link': 'label.cookies_policy'|trans,
        'href': 'YOUR_COOKIES_POLICY_LINK'
    }
%}

### 其他语言

您可以通过在您的 app/Resources/views/layout.html.twig 中设置 languagesAlt 数组来定义元 <link rel="alternate" hreflang="YOUR_LANGUAGE" href="URL_WITH_ALTERNATE_LANGUAGE">

{%
set languagesAlt = {
    en: { title: 'English' },
    fr: { title: 'Français' },
    es: { title: 'Español' }
    }
%}

它将使用以下方案替换当前语言：https://example.com/LANGUAGE/pages/XXX。

设置此数组后，您还可以在导航栏中使用 navbarLanguagesDropdownMenu.html.twig 来显示一个下拉菜单以选择可用语言。

### ogImage

您可以使用以下代码在页面基础上定义 ogImage

{% set ogImage = absolute_url(asset('PATH_TO_YOUR_IMAGE')) %}

### 动画

在public/css/目录中有一个CSS文件，您可以通过链接使用一些动画。

<link rel="stylesheet" href="bundles/c975lsite/css/animations.min.css">

{# or  using c975L/IncludeLibrary #}
{{ inc_lib(absolute_url(asset('bundles/c975lsite/css/animations.min.css')), 'local') }}

### 错误页面

您还可以使用常见错误页面的模板。为此，您需要遵循如何自定义错误页面来创建结构app/Resources/TwigBundle/views/Exception和每种类型错误的文件。当然，您仍然可以停留在覆盖TwigBundle/Exception的水平，但如果您想使用预定义的错误模板，请执行以下操作

SiteBundle覆盖的错误类型

• error
• error401
• error403
• error404
• error410
• error500

在每个文件中复制/粘贴以下代码

{% extends 'layout.html.twig' %}

{% block content %}
    {# Take care to modify the error code in the included template name, i.e. "404" given here #}
    {% include('@c975LSite/Exception/error404.html.twig') %}
{% endblock %}

{% block share %}
{% endblock %}

### 添加样式表

要添加样式表，只需在您的app/Resources/views/layout.html.twig中添加以下内容

{% block stylesheets %}
    {{ parent() }}
    {# Using c975L/IncludeLibraryBundle #}
    {# With url #}
    {{ inc_lib('SUPPORTED_LIBRARY', 'css', 'SUPPORTED_VERSION_SELECTOR') }}
    {# Local file #}
    {{ inc_lib(absolute_url(asset('YOUR_STYLESHEET.css')), 'local') }}

    {# Of course you can provide the full "link" html data #}
{% endblock %}

### 添加JavaScript

要添加JavaScript，只需在您的app/Resources/views/layout.html.twig中添加以下内容

{% block javascripts %}
    {{ parent() }}
    {# Using c975L/IncludeLibraryBundle #}
    {# With url #}
    {{ inc_lib('SUPPORTED_LIBRARY', 'js', 'SUPPORTED_VERSION_SELECTOR') }}
    {# Local file #}
    {{ inc_lib(absolute_url(asset('YOUR_JAVASCRIPT_FILE.js')), 'local') }}

   {# Of course you can provide the full "script" html data #}
{% endblock %}

## 完整布局示例

您可以将此完整布局示例作为您项目的起点

{% extends '@c975LSite/layout.html.twig' %}

{%
set languagesAlt = {
    en: { title: 'English' },
    fr: { title: 'Français' },
    es: { title: 'Español' }
    }
%}
{%
    set matomo = {
        'id': YOUR_MATOMO_ID,
        'url': 'YOUR_MATOMO_URL'
    }
%}
{%
    set cookieConsent = {
        'message': 'text.cookies_banner'|trans,
        'dismiss': 'text.cookies_dismiss'|trans,
        'link': 'label.cookies_policy'|trans,
        'href': 'YOUR_COOKIES_POLICY_LINK'
    }
%}

{# Meta #}
{% block meta %}
    {{ parent() }}
{# Facebook app_id #}
    <meta property="fb:app_id" content="YOUR_FACEBOOK_APP_ID">
{% endblock %}

{# Css #}
{% block stylesheets %}
    {{ parent() }}
    {% if display == 'pdf' %}
        {{ inc_content(absolute_url(asset('css/styles.min.css')), 'local') }}
    {% else %}
        {{ inc_font('Wendy One') }}
        {{ inc_lib(absolute_url(asset('css/styles.min.css')), 'local') }}
    {% endif %}
{% endblock %}

{# Navigation #}
{% block navigation %}
    {{ include('navbar.html.twig') }}
{% endblock %}

{# Title #}
{% block title %}
    {% if app.request.get('_route') != null %}
        <h1>
            {{ title }}
        </h1>
    {% endif %}
{% endblock %}

{# Container #}
{% block container %}
    <div class="container">
        {% block content %}
        {% endblock %}
    </div>
{% endblock %}

{# Share #}
{% block share %}
    {# YOUR SHARING TOOL  #}
{% endblock %}

{# Footer #}
{% block footer %}
    {{ include('footer.html.twig') }}
{% endblock %}

{# Javascript #}
{% block javascripts %}
    {{ parent() }}
    {% if display == 'html' %}
        {{ inc_lib(absolute_url(asset('js/functions.min.js')), 'local') }}
    {% endif %}
{% endblock %}

## 使用预定义模型

使用预定义模型有两种方式，include或embed，两者都基于国家语言：{% include '@c975LSite/models/COUNTRY/LANGUAGE/terms-of-sales.html.twig' %}。以下是一个示例，展示了fr（法语）中法国的销售条款。

如果您有一个多语言网站，您可以通过省略语言来调用：{% include '@c975LSite/models/COUNTRY/terms-of-sales.html.twig' %}，SiteBundle将检查您的当前语言是否可用，如果不可用，则显示默认语言。

使用整个文件（include）

您想使用整个文件，请在您的模板中放置此代码

{% extends 'YOUR_LAYOUT.html.twig' %}

{% trans_default_domain 'site' %}
{# Title value is made of 'label.' + name of page, replacing "-" by "_" #}
{# i.e. page 'terms-of-sales' gives title = 'label.terms_of_sales' #}
{% set title = 'label.terms_of_sales'|trans %}

{% block content %}
    {# set the defined data (indicated at the top of the template file) before including #}
    {% set latestUpdate = '2018-03-08' %}

    {% include '@c975LSite/models/france/fr/terms-of-sales.html.twig' %}

    {# You can your own data at the end #}
    <h2>Achat de crédits</h2>
    <p class="text-justify">
        L’achat de crédits ...
    </p>
{% endblock %}

### 选择块（embed）

您想选择要显示的块，请在您的模板中放置此代码。注意您必须在embed函数中指定语言

{% extends 'YOUR_LAYOUT.html.twig' %}

{% trans_default_domain 'site' %}
{% set title = 'label.terms_of_sales'|trans %}

{% block content %}
    {# set the defined data (indicated at the top of the template file) before including #}
    {% set latestUpdate = '2018-03-08' %}

    {% embed '@c975LSite/models/france/fr/terms-of-sales.html.twig' %}
        {# Then you can disable block #}
        {% block acceptation %}
        {% endblock %}

        {# Or append information to it #}
        {% block acceptation %}
            {{ parent() }}
            Your added content
        {% endblock %}

        {# Or replace content #}
        {% block acceptation %}
            Your replacing content
        {% endblock %}
    {% endembed %}
{% endblock %}

### 可用的模型

以下表格包含每个国家和语言的全部模型。 请随意更新它们，添加翻译或国家。按照惯例，文件使用英文名称和“-”命名。

为了便于阅读，模型还以Markdown格式提供。如果您进行修改，可以使用命令php bin/console models:twig2md将Twig模型模板转换为它们的Markdown等价物。

如果这个项目帮助您缩短开发时间，您可以通过顶部的“赞助”按钮赞助我：）

AssetController

您可以使用此路由来提供资产文件，在您的Twig模板中使用以下代码：{{ path('asset_file', {'file': 'your/path/your_file.ext[.ext2]'}) }}。

文件名可以包含大写、小写、带重音的字母、“-”、“_”、“/”、“.”，但仅限空格不允许。您还可以使用2个文件扩展名。

如果您想允许注册用户访问您的资产，这将很有帮助。您只需将- { path: ^/your/path, roles: ROLE_USER }添加到config/packages/security.yaml > access_control部分。您还可以在资产文件夹本身上添加HTTP基本认证。

DownloadController

您可以使用此路由强制下载资产文件，在您的Twig模板中使用以下代码：{{ path('download_file', {'file': 'your/path/your_file.ext[.ext2]'}) }}。

文件名可以包含大写、小写、带重音的字母、“-”、“_”、“/”、“.”，但仅限空格不允许。您还可以使用2个文件扩展名。

这在处理像json或 whatever.nt这样的文本文件时很有帮助，允许注册用户访问您的资产。您还可以通过将- { path: ^/your/path, roles: ROLE_USER }添加到config/packages/security.yaml > access_control部分来保护您的路由。您还可以在下载文件夹本身上添加HTTP基本认证。

Twig组件

有一些Twig组件可供使用，请查看templates/components以了解它们。每个组件文件中都有一个使用示例。