不朽情缘正规网站

書名： concrete5 Cookbook
作者名： David Strack
本章字數： 1072字
更新時間： 2021-08-13 16:16:00

Creating a custom block type

Creating block types is a great way to add custom functionality to a website. This is the preferred way to add things like calendars, dealer locators, or any other type of content that is visible and repeatable on the frontend of the website.

Getting ready

The code for this recipe is available to download from the book's website for free. We are going to create a fully functioning block type that will display content on our website.

How to do it...

The steps for creating a custom block type are as follows:

First, you will need to create a directory in your website's root /blocks directory. The name of the directory should be underscored and will be used to refer to the block throughout the code. In this case, we will create a new directory called /hello_world.
Once you have created the hello_world directory, you will need to create the following files:
- controller.php
- db.xml
- form.php
- add.php
- edit.php
- view.php
- view.css
Now, we will add code to each of the files. First, we need to set up the controller file. The controller file is what powers the block. Since this is a very basic block, our controller only will contain information to tell concrete5 some details about our block, such as its name and description.

Add the following code to controller.php:

class HelloWorldBlockController extends BlockController {
  protected $btTable = "btHelloWorld";
  protected $btInterfaceWidth = "300";
  protected $btInterfaceHeight = "300";
  public function getBlockTypeName() {
    return t('Hello World');
  }
  public function getBlockTypeDescription() {
    return t('A basic Hello World block type!');
  }
}

Notice that the class name is HelloWorldBlockController. concrete5 conventions dictate that you should name your block controllers with the same name as the block directory in camel case (for example: CamelCase) form, and followed by BlockController. The btTable class variable is important, as it tells concrete5 what database table should be used for this block. It is important that this table doesn't already exist in the database, so it's a good idea to give it a name of bt (short for "block type") plus the camel cased version of the block name.
Now that the controller is set up, we need to set up the db.xml file. This file is based off of the ADOXMLS format, which is documented at http://phplens.com/lens/adodb/docs-datadict.htm#xmlschema. This XML file will tell concrete5 which database tables and fields should be created for this new block type (and which tables and fields should get updated when your block type gets updated).

Add the following XML code to your db.xml file:

<?xml version="1.0"?>
<schema version="0.3">
  <table name="btHelloWorld">
    <field name="bID" type="I">
      <key />
      <unsigned />
    </field>
      <field name="title" type="C" size="255">
      <default value="" />
    </field>
      <field name="content" type="X2">
      <default value="" />
    </field>
  </table>
</schema>

concrete5 blocks typically have both an add.php and edit.php file, both of which often do the same thing: show the form containing the block's settings. Since we don't want to repeat code, we will enter our form HTML in a third file, form.php, and include that file in both add.php and edit.php.
```
<?php 
  $form = Loader::helper('form');
?>
<div>
  <label for="title">Title</label>
  <?php echo $form->text('title', $title); ?>
</div>
<div>
  <label for="content">Content</label>
  <?php echo $form->textarea('content', $content); ?>
</div>
```
Once that is all set, add this line of code to both add.php and edit.php to have this HTML code appear when users add and edit the block:
```
<?php include('form.php') ?>
```

Add the following HTML to your view.php file:

<h1><?php echo $title ?></h1>
<div class="content">
   <?php echo $content ?>
</div>

Finally, for a little visual appeal, add the following code to view.css:

content {
  background: #eee;
  padding: 20px;
  margin: 20px 0;
  border-radius: 10px;
}

Now all of the files have been filled with the code to make our Hello World block function. Now we need to install this block in concrete5 so we can add it to our pages.
To install the new block, you will need to sign into your concrete5 website and navigate to /dashboard/blocks/types/. If you happen to get a PHP fatal error here, clear your concrete5 cache by visiting /dashboard/system/optimization/clear_cache (it is always a good idea to disable the cache while developing in concrete5).
At the top of the Block Types screen, you should see your Hello World block, ready to install. Click on the Install button.
Now the block is installed and ready to add to your site!

How it works...

Let's go through the code that we just wrote, step-by-step.

In controller.php, there are a few protected variables at the top of the class. The $btTable variable tells concrete5 which table in the database holds the data for this block type. The $btInterfaceWidth and $btInterfaceHeight variables determine the initial size of the dialog window that appears when users add your block to a page on their site.

We put the block's description and name in special getter functions for one reason, to potentially support for translations down the road. It's best practice to wrap any strings that appear in concrete5 in the global t() function.

The db.xml file tells concrete5 what database tables should be created when this block gets installed. This file uses the ADOXMLS format to generate tables and fields. In this file, we are telling concrete5 to create a table called btHelloWorld. That table should contain three fields, an ID field, the title field, and the content field. The names of these fields should be noted, because concrete5 will require them to match up with the names of the fields in the HTML form.

In form.php, we are setting up the settings form that users will fill out to save the block's content. We are using the Form Helper to generate the HTML for the various fields. Notice how we are able to use the $title and $content variables without them being declared yet. concrete5 automatically exposes those variables to the form whenever the block is added or edited. We then include this form in the add.php and edit.php files.

The view.php file is a template file that contains the HTML that the end users will see on the website. We are just wrapping the title in an <h1> tag and the content in a <div> with a class of .content.

concrete5 will automatically include view.css (and view.js, if it happens to exist) if they are present in your block's directory. Also, if you include an auto.js file, it will automatically be included when the block is in edit mode. We added some basic styling to the .content class and concrete5 takes care of adding this CSS file to your site's <head> tag.

官术网_书友最值得收藏!

Creating a custom block type

Getting ready

How to do it...

How it works...

See also

官术网_书友最值得收藏!

concrete5 Cookbook

Creating a custom block type

Getting ready

How to do it...

How it works...

See also