README

简介

这个Html助手是一个遵守PSR-2的框架无关助手，旨在用于模板系统中，以帮助创建有时可能是一项繁重工作的HTML元素！

需求

Composer

HTML助手需要以下内容

• "php": ">=5.4.0"

如果你想在开发模式下运行并运行测试，则需要以下内容。

• "phpunit/phpunit": "~4.0"
• "squizlabs/php_codesniffer": "~2.0"

安装

Composer

最简单的安装方法是使用composer。

composer require snscripts/html-helper 1.*

或者将以下内容添加到项目的 composer.json 文件中。

{
    "require": {
        "snscripts/html-helper": "1.*"
    }
}

设置

按照以下方式设置助手

$Html = new \Snscripts\HtmlHelper\Html(
    new \Snscripts\HtmlHelper\Helpers\Form(
        new \Snscripts\HtmlHelper\Services\Basic\Data
    ),
    new \Snscripts\HtmlHelper\Services\Basic\Router,
    new \Snscripts\HtmlHelper\Services\Basic\Assets
);

主要对象是Html对象，它包含助手的骨架，具有用于生成HTML标签的tag()方法。它还包含用于某些HTML元素的快捷方法（有关可用标签的列表，请参见以下内容）。

第一个参数是表单对象，它包含创建和填充HTML表单所需的所有方法。表单对象需要一个实现\Snscripts\HtmlHelper\Interfaces\Data的实例，该实例由Services\Basic\Data实现。

第二个和第三个参数也应为\Snscripts\HtmlHelper\Interfaces\Router和\Snscripts\HtmlHelper\Interfaces\Assets的实例，分别由Services\Basic\Router和Services\Basic\Assets实现。

接口

接口提供了一种使此Html助手框架无关的方法。每个框架都提供了获取表单数据/资产和路由自己的方式，因此接口为每个框架的执行提供了一种方法。

Services\Basic\Assets和Services\Basic\Router简单地将传递给资产方法或链接方法的参数返回，在框架中，路由接口将编写为加载其路由器并将从链接方法接收的数据传递给路由器，从而使框架返回URL。

Services\Basic\Data简单地将点表示法路径转换为POST变量，并在该点查找数据，并返回找到的内容。同样，在框架中，这将编写为检查请求对象以获取表单数据。

框架示例

即将推出。

用法

假设我们已经按照上述方式设置了对象，要调用的最基本方法是

/**
 * render a tag
 *
 * @param   string      tag to render
 * @param   array       attributes for the tag
 * @param   string      contents of tag when not self closing
 * @param   bool        close the tag?
 * @return  string
 */
public function tag($tag, $attr = null, $content = null, $close = false)

可以像这样调用

$Html->tag('div', array('class' => 'myDiv'), 'Div Contents', true);

如文档块所示，第一个参数是你希望渲染的标签。

第二个参数应是一个关联数组，包含要放置在标签上的任何属性。

第三个参数（如果需要）应包含标签的内容，这仅在第四个参数设置为true以创建一个闭合标签时使用。

一个自闭合标签的示例是

$Html->tag('input', array('type' => 'text', 'name' => 'my_name'));

这将生成一个简单的文本输入框。

这个简单的方法为Html助手提供了动力，所有其他方法和助手都旨在使生活更轻松！下面是可用方法的列表。

可用方法

// create a div tag
$Html->div('Div Contents Here', array('class' => 'attributes'));

// create a p tag
$Html->p('Paragraph contents', array('id' => 'intro'));

// create a ul list
// See the list section for more examples
$Html->ul(array('this', 'is', 'a', 'list'), array('data-foo' => 'bar'));

// create an ol list
// See the list section for more examples
$Html->ol(array('this', 'is', 'a', 'list'), array('data-foo' => 'bar'));

// create a hyperlink
// The second param will be passed to RouterInterface::getUrl
$Html->link('My Link', '/pages/about-us', array('target' => '_blank'));

// create an image
// the first param will be passed to AssetsInterface::getImage
$Html->image('/assets/img/logo.png', array('alt' => 'Our Logo'));

// create a stylesheet link
// the first param will be passed to AssetsInterface::getStyle
$Html->style('/assets/css/print.css', array('media' => 'print'));

// create a script tag
// the first param will be passed to AssetsInterface::getScript
$Html->script('/assets/js/validate.js');

可用表单方法

// Open the form
// See form section below for more info
$Html->Form->open('post', '/search', array('class' => 'validate'));

// close the form
$Html->Form->close();

// create a label
$Html->Form->label('My Label', array('for' => 'InputID'));

// create an input
// This will create full input element wrapped in a div tag with it's own label
$Html->Form->input(
	'dot.notation.input.name',
	// translates to $_POST['dot']['notation']['input']['name']
	'Inputs Label',
	array(
		'type' => 'text',
		'class' => 'myInput'
	)
);

// The following simply wrap the input method above and override the 'type' attribute

// create a hidden field
$Html->Form->hidden('hidden.field', array('value' => 'foobar'));

// create a password field
$Html->Form->password('user.password', 'Your Password', array('class' => 'required'));

// create a textarea
$Html->Form->textarea('user.bio', 'Bio', array('cols' => 10, 'rows' => 5));

// create a file input
$Html->Form->file('user.cv', 'CV', array('class' => 'required'));

// create a checkbox
$Html->Form->checkbox(
	'read_terms',
	'Read and agree to terms',
	array('onclick' => 'someJs()')
);

// create a selection of radio options
$Html->Form->radio(
	'user.plan',
	'Membership Plan',
	array(
		'plan-1' => 'PLAN 1!',
		'plan-2' => 'PLAN 2!'
	),
	array(
		'class' => 'radio-options'
	)
);

// Or can do the same as above with a select box
$Html->Form->select(
	'user.plan',
	'Membership Plan',
	array(
		'plan-1' => 'PLAN 1!',
		'plan-2' => 'PLAN 2!'
	),
	array(
		'class' => 'select-box'
	)
);

// create a multi select box
$Html->Form->multiselect(
	'user.plan',
	'Membership Plan',
	array(
		'plan-1' => 'PLAN 1!',
		'plan-2' => 'PLAN 2!'
	),
	array(
		'class' => 'select-all-the-plans'
	)
);

// create a submit button
$Html->Form->submit('submit', 'Log Me In!', array('class' => 'btn'));

// create a standard button
$Html->Form->button(
	'someAction',
	'Perform Actions',
	array('class' => 'btn btn-danger')
);

高级

列表

两种列表方法被创建得如此之好，以至于您还可以为列表中的单个 li 标签定义属性，并且还可以定义子列表（以及随后的子 ul 和子 li 项的属性！）

echo $Html->ul(
    array(
        'this is a list item',
        'this is a list item 2',
        'sub-item' => array(
            'will they work?',
            'or won\'t they, who knows?'
        ),
        'subitem attr!' => array(
            'attr' => array(
                'id' => 'listID'
            ),
            'ulAttr' => array(
                'id' => 'sub-list'
            ),
            'list' => array(
                'this is a sub item',
                'this list should have attributes'
            )
        )
    ),
    array(
        'id' => 'main ul'
    )
);

这同样适用于 ol 列表！

表单开放标签

开放方法可以接受三个不同的第一个参数值来设置表单方法。其中两个是标准的 post 和 get。第三个是 file。定义此值将设置操作为 post 并定义 $attr['enctype'] = 'multipart/form-data';。

表单输入

所有快捷包装器都只是调用输入方法并覆盖属性数组中的 type 属性。其他输入类型可以通过设置此类型值获得，例如 HTML5 元素如 email、range 和 datetime，但没有创建快捷包装器。

输入方法将返回的 HTML 结构将类似于

<div class="input text">
	<label for="DataUserName">Name:</label>
	<input id="DataUserName" type="text" name="data[User][name]">
</div>

复选框

默认情况下，复选框将返回一个隐藏输入，该输入位于实际复选框之前，以确保在复选框未选中时设置有效值。

<div class="input checkbox">
	<input type="hidden" id="_DataReadterms" value="0" name="data[readterms]">
	<input type="checkbox" id="DataReadterms" name="data[readterms]" value="1">
	<label for="DataReadterms">Read the Terms?</label>
</div>

可以通过传递 hiddenCheckbox => false 作为属性来禁用此功能

$Html->Form->checkbox(
	'read_terms',
	'Read and agree to terms',
	array(
		'hiddenCheckbox' => false
	)
);

选择框

选择框选项数组可以接受一个多维数组，该数组将被转换为 optgroups。

$Html->Form->select(
	'foobar',
	'Foo-Bar:',
	array(
		'Group 1' => array(
			'1' => 'Option 1',
			'3' => 'Option 3'
		),
		'Group 2' => array(
			'2' => 'Option 2',
			'4' => 'Option 4'
		)
	)
);

包装元素

默认情况下，包装元素是一个应用了 2 或 3 个类的 div。第一个类总是 input，第二个类是输入类型。第三个类被添加到多选类型中，以表示它是一个多选，以便在 CSS 中定位。这些类可以被覆盖，以及标签本身（或如果您不需要包装元素，可以将其关闭）。

标签可以像类一样被覆盖，也可以覆盖标签本身（或者如果您不需要包装元素，可以将其关闭）。

$Html->Form->input(
	'input_box',
	'My Input',
	array(
		'wrapper' => array(
			'tag' => 'span',
			'class' => 'wrapper-class',
			'id' => 'SpanTagId'
		)
	)
);

// Or turn it off with
$Html->Form->input(
	'input_box',
	'My Input',
	array(
		'wrapper' => false
	)
);

标签

当将标签传递给输入时，您可以将它作为一个字符串传递以简单地渲染该字符串作为标签，或者您可以将一个数组传递以便能够定义标签标签的属性。

$Html->Form->input(
	'input_box',
	array(
		'value' => 'My Input',
		'class' => 'label-class'
	),
	array(
		'wrapper' => false
	)
);

注入

由于方法返回完整的 div/label/input，如果您需要在标签和输入之间放置文本，手动进行每个方法可能很困难或很耗时。

因此，提供了 before、between 和 after 注入点，以便您可以在其中放置文本/HTML。

$Html->Form->input(
	'amount',
	'Price',
	array(
		'before' => 'Enter the',
		'between' => 'you want in UK Pence',
		'after' => 'p'
	)
);

// would return
<div class="input text">
	Enter the
	<label for="Amount">Price:</label>
	you want in UK Pence
	<input id="Amount" type="text" name="amount">
	p
</div>

贡献

有关详细信息，请参阅 CONTRIBUTING。

许可证

MIT 许可证（MIT）。有关更多信息，请参阅 许可证文件。