README

LSJS 被设计和使用作为电子商务系统 Merconis 的 JavaScript 框架。

然而，LSJS 可以独立使用，并且已经在一些 Web 应用程序中这样使用。由于目前我们只能为在 Merconis 项目中使用 LSJS 提供支持，因此目前不建议独立使用。

未来我们可能会积极推广 LSJS 的独立使用，如果您有兴趣使用它，我们当然愿意听取您的意见。

LSJS 是什么？它有什么好处？

LSJS 帮助您编写强大的 JS 应用程序，并以一种使您的工作变得更轻松的方式组织应用程序代码。

您使用 LSJS 编写的每个应用程序都有一个名为 "app.js" 的主应用程序文件。您的应用程序文件协调一切，但不负责实际的功能。这就是 LSJS 模块发挥作用的地方。

示例：假设您有一个网站，其中包含一个漂亮的幻灯片效果，一个可以拖放排序元素的表格和一个通过 AJAX 加载新条目的新闻横幅。在这种情况下，您将编写三个模块，例如 "my-slideshow"、"fancy-table"、"new-ticker"。在您的应用程序文件中，您将加载这些模块，但幻灯片功能等完全位于您的模块中。

模块不仅是一个单一的 JS 文件。它是一个包含为您的模型、视图、控制器和模板分别存储的 JS 文件的文件夹。

将一切组织得井井有条的文件和文件夹会使您的工作变得轻松，但当然 LSJS 不会以这种方式将应用程序交付到浏览器。LSJS 随附一个绑定脚本，它将所有内容合并到一个单独的文件中，并对其进行优化、最小化和缓存。

除了强大的模板引擎外，LSJS 还提供 MVC 架构、双向数据绑定、有用的核心模块等。

如何使用 LSJS

以下说明可以很容易地与位于 "examples" 文件夹中的小示例项目一起进行。

要在网站上使用 LSJS，必须加载 LSJS 核心，并至少加载一个 LSJS 应用程序。

LSJS 可以以两种方式加载。您使用哪种方式取决于您的网站是否使用 PHP 渲染。

在 PHP 环境中使用 LSJS

如果网站使用 PHP 渲染，LSJS 的 binderController 脚本可以实例化并使用来渲染 LSJS 输出文件，然后应在 script 元素的 src 属性中引用此输出文件的路径。实例化 binderController 时，定义要加载等参数的参数作为数组传递给构造函数。

示例 _00 显示了这是如何工作的。

请打开：http://yourdomain.com/assets/lsjs/examples/_00/index.php

在非 PHP 环境中使用 LSJS

如果您无法使用之前显示的方法使用 PHP 渲染和包含 LSJS，您仍然可以使用 LSJS。在这种情况下，您必须将 binder.php 作为 script 元素的 src 引用，并作为 GET 参数提供所有参数。

示例 _01 展示了这是如何工作的。

请打开： http://yourdomain.com/assets/lsjs/examples/_01/index.html

请注意：应用程序的路径必须相对于 binder.php 的位置指定。因此，路径可能以以下之一开始："../"。

虽然引用应用程序的路径绝对不是安全风险，因为服务器永远不会在引用位置执行任何文件，而只是将它们组合并作为纯JS代码交付，但一些服务器保护系统（例如 BitNinja）可能会将包含类似"../../../../"的URL视为可疑，并在多次尝试加载URL后阻止请求甚至用户的IP。为了防止这种情况，binder.php 支持一个“目录向上别名”。因此，在“pathToApp”参数中，“../”可以写成 _dup1_（"dup"代表“目录向上”，后面的数字代表我们想要上升的步数）。因此，_dup_4 就代表 ../../../../。

使用调试模式

参数 debug=1 激活调试模式，允许我们找出生成组合LSJS输出时使用的任何模板文件的精确位置。

这对于我们使用第三方LSJS应用程序，并希望修改其输出非常有用。为了能够修改输出，我们首先需要找到负责输出的模板，然后我们可以使用LSJS提供的更新安全定制技术来修改该输出。

激活调试功能后，注释将添加到LSJS生成的HTML输出中，指示输出中的哪个部分是由哪个模板创建的。如下所示

和

使用应用程序定制

如果我们在网站上使用第三方LSJS应用程序，我们可能希望更改其外观或行为，但我们不能（或者至少我们绝对不应该）更改原始应用程序代码，因为未来的更新可能会成为真正的问题或甚至变得不可能。

因此，LSJS提供了一个简单的方式来定制应用程序的模块。

就像应用程序的路径可以作为参数指定一样，通过使用参数 pathToAppCustomization，可以指定应用程序模块定制版本的路径。

给定的定制路径需要指向一个目录，该目录包含与原始应用程序中完全相同的结构下的定制文件。

在组合应用程序代码时，LSJS会查找定制文件，并相应地替换原始代码的相应部分。甚至可以在定制文件夹中添加新的模板、模型甚至完整的模块。

查看示例 _02 以了解这是如何工作的。

在示例 _02 中，有一个非常简单的应用程序，它包含一个名为 "helloWorld" 的模块，该模块仅使用模板 "main.html" 在屏幕上打印 "Hello World!"。

示例 _02 不仅包含应用程序文件夹，还有一个名为 "appCustomization" 的文件夹，其中包含定制的模板。通过在参数 pathToAppCustomization 中引用定制文件夹的路径，应用了定制。

请打开： http://yourdomain.com/assets/lsjs/examples/_02/index.html

您将立即看到修改后的输出。

模块的控制器也被定制，并将 customized controller works in module "helloWorld" 打印到控制台。

甚至主应用程序文件 app.js 也被定制，并将 "customized app.js works" 打印到控制台。

打开示例的 index.html，并删除参数 pathToAppCustomization，以查看模块最初执行的操作。

在在原始版本和定制版本之间切换时，请查看生成的HTML源代码，并查看由于激活了调试模式，我们可以看到的模板位置如何发生变化。

使用核心模块自定义

以安全更新的方式自定义核心模块基本上与自定义应用程序模块的方式相同，这在本文档的早期部分已有描述。

使用参数 pathToCoreCustomization，可以指定包含自定义文件的文件夹。此文件夹需要包含一个名为 "modules" 的文件夹，其中自定义的工作方式与应用程序模块完全相同。

请打开示例 _03 以查看其实际效果： http://yourdomain.com/assets/lsjs/examples/_03/index.html

使用 LSJS 模板系统

LSJS 配备了一个强大的模板系统，该系统专为喜欢使用 PHP 代码创建 HTML 输出并希望以相同简单方式使用 JS 创建 HTML 输出的人设计。

LSJS 模板是 HTML 文件，其中可以嵌入如下 JS 代码

<div>
    <?
    var	i,
        str_text = 'Hello template!';
    
    for (i = 0; i <= 5; i++) {
        ?>
        <h3>This template says: <?= str_text =?></h3>
        <?
    }
    ?>
</div>

你可能从未在 JS 中看到这种情况，但在 PHP 中这是标准的

<div>
    <?php
    $str_text = 'Hello template!';
    
    for ($i = 0; $i <= 5; $i++) {
        ?>
        <h3>This template says: <?= str_text ?></h3>
        <?php
    }
    ?>
</div>

关于 LSJS 模板中的语法没有太多需要了解的

<? 开始一个 JS 代码块
?> 结束一个 JS 代码块
<?= 'some text or some ' + variable ?> 打印一些文本或变量

提示：由于 binder.php 会将 LSJS 模板转换为常规 JS 代码字符串连接，因此如果要在模板中使用单引号，必须对其进行转义

<p>这不会成为问题</p>

<p>但这不起作用</p>

模板包含

模板可以包含在其他模板中。有四种可能的方法来实现这一点

<div data-lsjs-replaceWithTemplate="sub01"></div>

或

<div data-lsjs-replaceWithElement="arg.__view.el_replacement01"></div>

或

/*
 * tplOutput can be used to output a rendered template in another template like this:
 */

<?= this.tplOutput({name: 'templatexyz', arg: {str_someValue: str_value}}) =?>

或

/*
 * This inserts the subtemplate in the main template when the template is converted into
 * actual JS code in the binder's template converter on the PHP side. Therefore, using this
 * including technique, you have full access to all variables that are available in the
 * main template even from the subtemplate.
 */

{{template::templatename}}

最小化器

默认情况下，LSJS 会最小化其输出以优化页面加载速度。此选项可以禁用，因为在开发过程中你可能不想使用它。

添加参数 no-minifier=1 以禁用最小化器。

缓存

在 LSJS 中，缓存是自动工作的。LSJS 源代码的更改以及定义如何渲染内容的参数将会被检测到，如果有更改，将渲染新的输出文件。

leadingsystems / lsjs

维护者

详细信息