README

这是一个用于 Symfony 框架的网格组件。

twigs 读取应用程序的全局变量

gridTwig: 在 grid 中扩展

gridBlock: 在 gridTwig 中的块，用于放置网格

配置

步骤 1: 注册组件。

在 AppKernel.php 中

public function registerBundles()
{
    $bundles = array(
            ...
        new Lighthart\GridBundle\LighthartGridBundle(),
    );
...
}

步骤 2: 连接 assetic。

在 config.yml 中

    assetic:
    ...
        bundles:
                    ...
            - LighthartGridBundle
        ...

如果需要在 PostgreSQL 中使用聚合字段，必须添加操作符。

    doctrine:
        orm:
        #...
                    dql:
                        string_functions:
                            ARRAYAGG: Lighthart\GridBundle\DQL\Postgres\ArrayAgg
                            ARRAYAGGDISTINCT: Lighthart\GridBundle\DQL\Postgres\ArrayAggDistinct

目前不支持除 PostgreSQL 以外的任何平台。

创建网格

步骤 1: 编写查询。

根实体的表别名必须是 'root'。在所有连接的表中，您可以使用您喜欢的任何别名。

    $em = $this->getDoctrine()->getManager();
    $rep = $em->getRepository('ApplicationBundle:Student');
    $root = 'root';
    $qb = $rep->createQueryBuilder($root);
    $qb->join($root . '.snowflake', 'f');
    $qb->join('f.school', 's');
    $qb->join('s.district', 'd');
    $qb->join('root.biller', 'b');
    $qb->addOrderBy('f.lastName');
    $qb->addOrderBy('f.firstName');

注意：此查询将被大幅重写，以根据第三步中指定的列获取部分实体。

步骤 2: 初始化网格。

    $query = $qb->getQuery();
    $gm = $this->get('lg.maker');
    $gm->initialize(array(
        'table' => 'table table-bordered table-condensed table-hover table-striped',
        'html' => true,
        'massAction' => true,
        'request' => $request
    ));
    $gm->setQueryBuilder($qb);

注意：传递请求是可选的，但可以使控制器操作中的 $Request->query 参数作为动态网格布局的标志 cookie 可用

网格配置:

table:          Classes applied to table

html:           Indicates if the table is html

massAction:     If evaluates to true, mass action column is included

步骤 3: 开始添加字段/列。

    $gm->addField('b', 'shortName', array(
        // 'search' => false,
        // 'filter' => false,
        'attr' => array(
            'class' => '',
            'entity_id' => true,
            'html' => true
        ) ,
        'title' => 'Biller:<br/> ~d.shortName~<br/>~s.shortName~',
    ));

字段配置:

search:         Setting to true will add the column to the fields searched via the
                global search tool. Optionally, you can also specify the kind of search
                filter to use on this filed. Valid types are: date, number, and string.
                If a true is used, the field will be highlighted on search without
                modifying query.  This is useful for compound fields such as made with
                the otherGroups config (below)

filter:         Setting to true will add a search filter box to the column header which
                only searches on this field. Optionally, you can also specify the kind
                of search filter to use on this filed. Valid types are: date, number,
                and string.  If filter is not set, it will default to false, and no
                input box will be displayed. 

                ~ is for date ranges ~Date ends at Date. Date~ begins from Date.

sort:           true enables column sort.

attr:           Sets the html attributes.

html:           Indicates the title should be interpreted as html, i.e., the twig raw
                filter is applied.

entityId:       Evaluating to true stores the entity id on the individual cell. This
                is mostly useful for javascript related associated entities.

parentId:       Evaluating to true stores the parent id on the row header. This is
                mostly useful for javascript related associated entities.

title:          Sets the title of the column.  Note: the title field sets the on-hover
                title.

header:         Sets the display title of the column.  Note: the title field sets the
                on-hover title.  If not set the header is the same as the title.

hidden:         Evaluating to true hides the column.

filterHidden:   Filter on a column which is hidden.  Useful for concatenating fields
                filtering the end result, such as lastname/firstname combos.  In this
                case hide the firstname column and add 'filterHidden' =>
                'alias.firstname' to the lastname column.  Hiddens columns must be
                set filterable.  Item must be an array or semicolon-separated list

security:       A primitive boolean, or an anonymous function.  If the value evaluates
                to true, the button is rendered.  Default is true.  For the anonymous
                function, the result tuple for the current row is sent as the first
                parameter, and an alias translation table for the original alias and
                the new alias in the query is sent as the second parameter. The
                tildes (see below) function as columns forming indexes, to base the
                appearance on portions of the tuple.

transform:      An anonymous function.  The result tuple for the current row is sent
                as the first parameter, and an alias translation table for the original
                alias and the new alias in the query is sent as the second parameter.
                The tildes (see below) function as columns forming indexes, to base the
                appearance on portions of the tuple.  The function is applied to the
                value of the column.

value:          Multiple fields may be added using tildes, as with example for title.
                Passing an array (instead of a string) of values takes the first
                truthy value, similar to a postgres concat operator.

boolean:        Field is a boolean, will render with boolean twigs.  If value is a
                string boolean value will be determined by a == comparison.  If value
                is an anonymous function, the result tuple for the current row is
                sent as the first parameter, and an alias translation table for the
                original alias and the new alias in the query is sent as the second
                parameter, and the function should return the boolean value.  For
                example:

    $gm->addField('consentStatus', 'shortName', [
        'filter'   => 'number',
        'entityId' => true,
        'boolean'  => function($result, $columns){
            return
                ('Agreed' == $result[$columns['consentStatus.shortName']])
                ? true
                : (
                    ('Declined' == $result[$columns['consentStatus.shortName']])
                    ? false
                    : null
                    )
            ;
        },
        // 'hidden'   => true,
        'attr'     => [
            'class' => '',
        ],
        'title' => 'Consent',
        'value' => ['~consentStatus.shortName~', null]
    ]);

trunc:          get first value of trunc characters

dql:            Adds a pseudo column which returns the result of the DQL indicated.
                The second parameter should be an empty string.  This allows the use
                of raw dql functions.  For example:

        $gm->addField('BILLERCONSENT', '', [
            'dql'      => 'arrayAgg(
                                concat(
                                    concat(biller.shortName,\' : \'),
                                    consentStatus.shortName
                                      )
                                   ) AS BILLERCONSENT'
                           ,
            'attr'     => [
                'class' => '',
            ],
            'title' => 'Consent',
        ]);

group:          Column is part of a group.  Will automatically put arrayAgg in as
                function, grouping the field indicated.  Fields which are part of DQL
                aggregates should be grouped on something.

count:          Column is part of a group.  If true, will automatically put count in as
                function on the indicated field.  Id is normally a good choice.

otherGroup:     Column displays a group of composite fields.  Field must be an array
                of fields which will me recursively mapped through a DQL concat
                function.  To display a , use a double semicolon as a display element.
                If the field is also a filter, the otherGroup display elements will
                be automatically added.

            $gm->addField('subordinate_othergroup', 'otherGroup', [
            'filter'   => 'string',
            // automatically has:
            // 'filterHidden' => 'subordinate.firstName;subordinate.lastName',
            'header' => 'Subordinate',
            'title' => 'Subordinate',
            'otherGroup' => ['subordinate.lastName','\';; \'','subordinate.firstName'],
        ]);

波浪号的用法:

对于 'value'、'entityId'、'parentId'、'title' 和 'attr' 的所有元素，将字符串的任何部分用波浪号 (~) 包围将捕获查询中的相应列并将该文本插入。此插值将忽略 HTML 标签。示例上面的标题文本将添加

    Biller:
    <District Name>
    <School Name>
    to the table header cell.

步骤 4: 添加操作。

    $gm->addAction(array(
        'icon' => 'fa-rocket',
        'route' => array(
            'student_show' => array(
                'id' => '~t.id~'
            )
        ) ,
        'security' => function($result, $columns){
            return 'F' == $result[$columns['g.shortName']];
        },
        'attr' => array(
            'title' => 'Star3'
        )
    ));

可以渲染任意数量的按钮。默认情况下，如果有超过 4 个，则将自动渲染一个折叠按钮。这可以通过覆盖 twigs 中的 'buttonNum' 值来控制

注意：操作以标签的形式渲染

操作配置:

icon:       A font awesome icon for the button.  Note: Font Awesome is not installed
            as part of this bundle. Without Font Awesome, this feature puts a
            <span class="fa [icon]"></span> tag into the <a> for the action button.

name:       Text for the button.  Works with icon, with icon being leftmost.  If no
            name is specified, empty space is rendered so the button has some width.

security:   A primitive boolean, or an anonymous function.  If the value evaluates to
            true, the button is rendered.  Default is true.  For the anonymous
            function, the result tuple for the current row is sent as the first
            parameter, and an alias translation table for the original alias and the
            new alias in the query is sent as the second parameter.  The tildes
            function as columns forming indexes, to base the appearance on portions
            of the tuple.

severity:   Adds a bootstrap class such as btn-primary to the <a>

attr:       Sets the html attributes.  Note: the title key of the 'attr' field sets
            the hover-over title.

route:      Either raw text for the route, or an array of data with the key being a
            symfony alias for a route, and the value being an array of parameters for
            said route.

post:       Buttons renders as submit inside a form and issues a post request.

警告：为什么我的按钮丢失？如果路由失败，异常将被捕获，并且按钮将静默省略。

步骤 5: 充分充电网格并将其传递给一个 twig。

    $gm->hydrateGrid($request);
    return $this->render('ApplicationBundle:Test:test3.html.twig', array(
        'grid'      => $gm->getGrid() ,
        'flags'     => $flags,
        'newPath'   => $url,
        'export'    => 1000,
        'noResults' => 'No Results'
        'addForm'   => $addForm->createView(),
        'addTitle'  => 'Label for AddForm',
    ));

渲染配置:

newPath:    Path for 'new' to add something to the grid.

newIcon:    A font awesome icon for the new button.  Note: Font Awesome is not
            installed as part of this bundle. Without Font Awesome, this feature puts
            a <span class="fa [icon]"></span> tag into the <a> for the new button.

flags:      An array of labels for flags to be rendered as check boxes above grid, to
            be used to modify the grid query.  Flags specified as:

            $flags['Flag name']    = 'Flag Name Title';
            $flags['Another Flag'] = 'Another Flag Title';
            $flags['thirdFlag']    = 'thirdFlag Title';
            $flags['ALLCAPSFLAG']  = 'ALLCAPSFLAG Title';

            'flags' => $flags;

            Would be fetched in a Symfony controller by:

            $flagName    = $request->query->get('flag_name');
            $anotherFlag = $request->query->get('another_flag');
            $thirdFlag = $request->query->get('thirdflag');
            $ALLCAPSFLAG = $request->query->get('allcapsflag');

            That is, all letters will be lower-cased, and all spaces will become
            underscores.  The original presentation of the keys in the flags
            array will be used for displaying labels next to checkboxes.  Titles
            will be added to html title attribute for hoverover captioning.

export:     Adds export limited to the number of lines specified by the value.  'all'
            returns all results for export.

noResults:  String to display when there are no results.  Defaults to
            'No Results'

addForm:    A symfony form view to process adding things to the grid

addTitle:   Title/label for widget to open and close addForm

注意：与表格一起渲染了大量信息，包括用于其他处理（如javascript或其他ajax）的类名和 id。

步骤 6: 在您的 twig 中。

    {% include 'LighthartGridBundle:Grid:grid.html.twig' %}

或者

    {% embed 'LighthartGridBundle:Grid:grid.html.twig' %}
    < over-write certain blocks >
    {% endembed %}

步骤 7: 配置路由。

    test3:
        pattern:  /test3/
        defaults: { _controller: "ApplicationBundle:Test:test3" }

步骤 8: 调试助手

有三个函数，setResultsDump()、setQueryDump() 和 setDebugDump() 可以在网格制作器上调用以输出调试输出并终止。setDebugDump() 执行另外两个操作。在控制器中或在网格构建后进行此操作：例如

    $gm = $this->get('lg.maker');
    $gm->setDebugDump();

步骤 8: 自定义 twig

有一些默认设置控制按钮的显示。Num 是显示的总数，包括如果需要展开按钮的话。

    {% set buttonNum = 4 %}
    {% set buttonWidth = 25 %}
    {% set buttonPadding = 6 %}