# 十一、附录 A：PixieApp 快速参考

本附录是开发人员快速参考指南，提供了所有 PixieApp 属性的摘要。

# 注解

*   `@PixieApp`: 必须添加到任何 PixieApp 类的类注解。

    参数：无

    例子：

    ```py
    from pixiedust.display.app import *
    @PixieApp
    class MyApp():
        pass
    ```

*   `@route`: 需要使用方法注解来表示方法（可以具有任何名称）与路由相关联。

    参数：`**kwargs`。 表示路由定义的关键字参数（键值对）。 PixieApp 调度器将根据以下规则将当前内核请求与路由进行匹配：

    *   参数数量最多的路由将首先被评估。
    *   所有参数都必须匹配才能选择路由。 参数值可以使用`*`表示任何值都将匹配。
    *   如果未找到路由，则选择默认路由（不带参数的路由）。
    *   `route`参数的每个键可以是过渡状态（由`pd_options`属性定义），也可以是持久状态（PixieApp 类的字段，在显式更改之前一直存在）。
    *   该方法可以具有任意数量的参数。 调用方法时，PixieApp 调度器将尝试将方法参数与具有相同名称的路由参数进行匹配。

    返回值：该方法必须返回将注入到前端的 HTML 片段（除非使用`@captureOutput`注解）。 该方法可以利用 Jinja2 模板语法生成 HTML。 HTML 模板可以访问一定数量的变量：

    *   `this`：引用 PixieApp 类（请注意，由于 Jinja2 框架本身已使用`self`，因此我们使用`this`代替了`self`）
    *   **前缀**：PixieApp 实例唯一的字符串 ID
    *   **实体**：请求的当前数据实体
    *   **方法参数**：可以在 Jinja2 模板中以变量形式访问方法的所有参数

        ```py
        from pixiedust.display.app import *
        @PixieApp
        class MyApp():
            @route(key1="value1", key2="*")
            def myroute_screen(self, key1, key2):
                return "<div>fragment: Key1 = {{key1}} - Key2 = {{key2}}"
        ```

    例子：

    ### 注意

    [您可以在此处找到代码文件](https://github.com/DTAIEB/Thoughtful-Data-Science/blob/master/chapter%205/sampleCode25.py)。

*   `@templateArgs`: 允许在 Jinja2 模板中使用任何局部变量的注解。 请注意，不能将`@templateArgs`与`@captureOutput`结合使用：

    参数：无

    例子：

    ```py
    from pixiedust.display.app import *
    @PixieApp
    class MyApp():
        @route(key1="value1", key2="*")
        @templateArgs
        def myroute_screen(self, key1, key2):
            local_var = "some value"
            return "<div>fragment: local_var = {{local_var}}"
    ```

    ### 注意

    [您可以在此处找到代码文件](https://github.com/DTAIEB/T4houghtful-Data-Science/blob/master/chapter%205/sampleCode26.py)。

*   `@captureOutput`: 可以使用路由方法更改合同的注解，这样就不必再返回 HTML 片段。 相反，方法主体可以像在笔记本单元中那样简单地输出结果。 该框架将捕获输出并将其作为 HTML 返回。 请注意，在这种情况下，您不能使用 Jinja2 模板。

    参数：无

    例子：

    ```py
    from pixiedust.display.app import *
    import matplotlib.pyplot as plt
    @PixieApp
    class MyApp():
        @route()
        @captureOutput
        def main_screen(self):
            plt.plot([1,2,3,4])
            plt.show()
    ```

    ### 注意

    [您可以在此处找到代码文件](https://github.com/DTAIEB/Thoughtful-Data-Science/blob/master/chapter%205/sampleCode27.py)。

*   `@Logger`: 通过向类中添加日志记录方法来添加日志记录函数：`debug`, `warn`, `info`, `error`, `critical`, `exception`。

    参数：无

    例子：

    ```py
    from pixiedust.display.app import *
    from pixiedust.utils import Logger
    @PixieApp
    @Logger()
    class MyApp():
        @route()
        def main_screen(self):
            self.debug("In main_screen")
            return "<div>Hello World</div>"
    ```

    ### 注意

    [您可以在此处找到代码文件](https://github.com/DTAIEB/Thoughtful-Data-Science/blob/master/chapter%205/sampleCode28.py)。

    ### 注意

    [您可以在此处找到代码文件](https://github.com/DTAIEB/Thoughtful-Data-Science/blob/master/chapter%205/sampleCode28.py)。

# 自定义 HTML 属性

这些可以与任何常规 HTML 元素一起使用以配置内核请求。 当元素接收到点击或更改事件时，或者在 HTML 片段完成加载后，PixieApp 框架可以触发这些请求。

*   `pd_options`: 根据以下格式定义用于内核请求的瞬时状态的键值对列表：`pd_options="key1=value1;key2=value2;..."`。 当与`pd_entity`属性结合使用时，`pd_options`属性将调用 PixieDust `display()`API。 在这种情况下，您可以从使用`display()` API 的单独笔记本单元的元数据中获取值。 当在`display()`模式下使用`pd_options`时，为方便起见，建议通过创建名为`<pd_options>`的子元素并使用 JSON 值作为文本来使用`pd_options`的 JSON 表示法。

    以`pd_options`作为子元素调用`display()`的示例：

    ```py
    <div pd_entity>
        <pd_options>
            {
                "mapboxtoken": "XXXXX",
                "chartsize": "90",
                "aggregation": "SUM",
                "rowCount": "500",
                "handlerId": "mapView",
                "rendererId": "mapbox",
                "valueFields": "IncidntNum",
                "keyFields": "X,Y",
                "basemap": "light-v9"
            }
        </pd_options>
    </div>
    ```

    ### 注意

    [您可以在此处找到代码文件](https://github.com/DTAIEB/Thoughtful-Data-Science/blob/master/chapter%205/sampleCode29.html)。

    以`pd_options`作为 HTML 属性的示例：

    ```py
    <!-- Invoke a route that displays a chart -->
    <button type="submit" pd_options="showChart=true" pd_target="chart{{prefix}}">
        Show Chart
    </button>
    ```

    ### 注意

    [您可以在此处找到代码文件](https://github.com/DTAIEB/Thoughtful-Data-Science/blob/master/chapter%205/sampleCode30.html)。

*   `pd_entity`：仅用于在特定数据上调用`display()` API。 必须与`pd_options`结合使用，其中键值对将用作`display()`的参数。 如果未为`pd_entity`属性指定任何值，则假定该实体为传递给启动 PixieApp 的`run`方法的实体。 `pd_entity`值可以是在笔记本中定义的变量或 PixieApp 的字段（例如`pd_entity="df"`），也可以是使用点表示法的对象的字段（例如`pd_entity="obj_instance.df"`）。
*   `pd_target`: 默认情况下，内核请求的输出会注入到整个输出单元格或对话框中（如果您使用`runInDialog = "true"`作为`run`方法的参数）。 但是，您可以使用`pd_target = "elementId"`指定将接收输出的目标元素。 （请注意，`elementId`必须存在于当前视图中。）

    例子：

    ```py
    <div id="chart{{prefix}}">
    <button type="submit" pd_options="showChart=true" pd_target="chart{{prefix}}">
        Show Chart
    </button>
    </div>
    ```

    ### 注意

    [您可以在此处找到代码文件](https://github.com/DTAIEB/Thoughtful-Data-Science/blob/master/chapter%205/sampleCode31.html)。

*   `pd_script`: 这将调用任意 Python 代码作为内核请求的一部分。 可以与其他属性（例如`pd_entity`和`pd_options`）结合使用。 请务必注意，必须遵守 [Python 缩进规则](https://docs.python.org/2.0/ref/indentation.html)以避免运行时错误。

    如果 Python 代码包含多行，建议使用`pd_script`作为子元素并将代码存储为文本。

    例子：

    ```py
    <!-- Invoke a method to load a dataframe before visualizing it -->
    <div id="chart{{prefix}}">
    <button type="submit"
        pd_entity="df"
        pd_script="self.df = self.load_df()"
        pd_options="handlerId=dataframe"
        pd_target="chart{{prefix}}">
        Show Chart
    </button>
    </div>
    ```

    ### 注意

    [您可以在此处找到代码文件](https://github.com/DTAIEB/Thoughtful-Data-Science/blob/master/chapter%205/sampleCode32.html)。

*   `pd_app`: 这将通过其完全限定的类名称动态调用一个单独的 PixieApp。 `pd_options`属性可用于传递路由参数以调用 PixieApp 的特定路由。

    例子：

    ```py
    <div pd_render_onload
         pd_option="show_route_X=true"
         pd_app="some.package.RemoteApp">
    </div>
    ```

    ### 注意

    [您可以在此处找到代码文件](https://github.com/DTAIEB/Thoughtful-Data-Science/blob/master/chapter%205/sampleCode33.html)。

*   `pd_render_onload`: 与用户单击元素或发生更改事件时相反，这应用于在加载时触发内核请求。 `pd_render_onload`属性可以与定义请求的任何其他属性组合，例如`pd_options`或`pd_script`。 请注意，此属性仅应与`div`元素一起使用。

    例子：

    ```py
    <div pd_render_onload>
        <pd_script>
    print('hello world rendered on load')
        </pd_script>
    </div>
    ```

    ### 注意

    [您可以在此处找到代码文件](https://github.com/DTAIEB/Thoughtful-Data-Science/blob/master/chapter%205/sampleCode34.html)。

*   `pd_refresh`: 即使没有事件（单击或更改事件）发生，它也用于强制 HTML 元素执行内核请求。 如果未指定任何值，则刷新当前元素，否则，将刷新具有在值中指定的 ID 的元素。

    例子：

    ```py
    <!-- Update state before refreshing a chart -->
    <button type="submit"
        pd_script="self.show_line_chart()"
        pd_refresh="chart{{prefix}}">
        Show line chart
    </button>
    ```

    ### 注意

    [您可以在此处找到代码文件](https://github.com/DTAIEB/Thoughtful-Data-Science/blob/master/chapter%205/sampleCode35.html)。

*   `pd_event_payload`: 这将发出具有指定有效内容的 PixieApp 事件。 该属性遵循与`pd_options`相同的规则：

    *   每个键值对必须使用`key=value`表示法进行编码
    *   该事件将在点击或更改时触发
    *   支持`$val()`指令以动态注入用户输入的输入
    *   使用`<pd_event_payload>`子项输入原始 JSON。

        ```py
        <button type="submit" pd_event_payload="type=topicA;message=Button clicked">
            Send event A
        </button>
        <button type="submit">
            <pd_event_payload>
            {
                "type":"topicA",
                "message":"Button Clicked"
            }
            </pd_event_payload>
            Send event A
        </button>
        ```

    例子：

    ### 注意

    [您可以在此处找到代码文件](https://github.com/DTAIEB/Thoughtful-Data-Science/blob/master/chapter%205/sampleCode36.html)。

*   `pd_event_handler`: 订阅者可以通过声明一个`<pd_event_handler>`子元素来监听事件，该子元素可以接受任何 PixieApp 内核执行属性，例如`pd_options`和`pd_script`。 这个元素必须使用`pd_source`属性来过滤他们想要处理的事件。 `pd_source`属性可以包含以下值之一：

    *   `targetDivId`：仅接受来自具有指定 ID 的元素的事件
    *   `type`：仅接受指定类型的事件。

        ```py
        <div class="col-sm-6" id="listenerA{{prefix}}">
            Listening to button event
            <pd_event_handler
                pd_source="topicA"
                pd_script="print(eventInfo)"
                pd_target="listenerA{{prefix}}">
            </pd_event_handler>
        </div>
        ```

    例子：

    ### 注意

    [您可以在此处找到代码文件](https://github.com/DTAIEB/Thoughtful-Data-Science/blob/master/chapter%205/sampleCode37.html)。

    **注意**：将`pd_source`用作`*`表示将接受所有事件。

*   `pd_refresh_rate`: 这用于以毫秒为单位的指定间隔重复执行元素。 当您要轮询特定变量的状态并在 UI 中显示结果时，这很有用。

    例子：

    ```py
    <div pd_refresh_rate="3000"
        pd_script="print(self.get_status())">
    </div>
    ```

    ### 注意

    [您可以在此处找到代码文件](https://github.com/DTAIEB/Thoughtful-Data-Science/blob/master/chapter%205/sampleCode38.html)。

# 方法

*   `setup`: 这是由 PixieApp 实现的用于初始化其状态的可选方法。 在 PixieApp 运行之前将被自动调用。

    参数：无

    例子：

    ```py
    def setup(self):
        self.var1 = "some initial value"
        self.pandas_dataframe = pandas.DataFrame(data)
    ```

    ### 注意

    [您可以在此处找到代码文件](https://github.com/DTAIEB/Thoughtful-Data-Science/blob/master/chapter%205/sampleCode39.py)。

*   `run`: 这将启动 PixieApp。

    参数：

    *   **实体**：（可选）数据集作为输入传递到 PixieApp。 可以用`pd_entity`属性引用，也可以直接作为`pixieapp_entity`字段引用。
    *   `**kwargs`：运行时传递给 PixieApp 的关键字参数。 例如，使用`runInDialog="true"`将在对话框中启动 PixieApp。

        ```py
        app = MyPixieApp()
        app.run(runInDialog="true")
        ```

    例子：

*   `invoke_route`: 这用于以编程方式调用路由。

    参数：

    *   **路由方法**：要调用的方法。
    *   `**kwargs`：要传递给`route`方法的关键字参数。

        ```py
        app.invoke_route(app.route_method, arg1 = "value1", arg2 = "value2")
        ```

    例子：

*   `getPixieAppEntity`：用于检索调用`run()`方法时传递的当前 PixieApp 实体（可以为`None`）。 通常从 PixieApp 内部调用`getPixieAppEntity()`，即：

    ```py
    self.getPixieAppEntity()
    ```