and more...
40 |
41 |
42 | You can use the widget multiple times on one page.
43 |
44 | ### 2. Backend.
45 |
46 | Yii 2 ContentTools saves content and uploaded images asynchronously and it requires some preparation on the backend side.
47 |
48 | You have to create few controllers' actions:
49 | - "upload new image" action,
50 | - "rotate uploaded image" action,
51 | - "insert & crop uploaded image" action,
52 | - "save content" action.
53 |
54 | Three first actions are already prepared if you don't want any special operations. You can find them in 'actions' folder.
55 | - _UploadAction_ - takes care of validating the uploaded images using `\bizley\contenttools\models\ImageForm`
56 | (jpg, png and gif images are allowed, maximum width and height is 1000px and maximum size is 2 MB), images are saved
57 | in `content-tools-uploads` folder accessible from web.
58 | - _RotateAction_ - takes care of rotating the uploaded image using Imagine library (through `yii2-imagine` extension
59 | required in the composer.json).
60 | - _InsertAction_ - takes care of inserting image into the content with optional cropping using Imagine library.
61 |
62 | The default option for the image URLs is:
63 |
64 | 'imagesEngine' => [
65 | 'upload' => '/site/content-tools-image-upload',
66 | 'rotate' => '/site/content-tools-image-rotate',
67 | 'insert' => '/site/content-tools-image-insert',
68 | ],
69 |
70 | So if you don't want to change the `imagesEngine` parameter add in your SiteController:
71 |
72 | public function actions()
73 | {
74 | return [
75 | 'content-tools-image-upload' => \bizley\contenttools\actions\UploadAction::className(),
76 | 'content-tools-image-insert' => \bizley\contenttools\actions\InsertAction::className(),
77 | 'content-tools-image-rotate' => \bizley\contenttools\actions\RotateAction::className(),
78 | ];
79 | }
80 |
81 | See [Standalone Actions section in Yii 2 Guide](https://www.yiiframework.com/doc/guide/2.0/en/structure-controllers#standalone-actions)
82 | for more info about adding actions.
83 |
84 | The last "save content" action is not prepared because it depends on the business logic of your application.
85 | See *Saving content* part at the end of this file.
86 |
87 | Default configuration for this is:
88 |
89 | 'saveEngine' => [
90 | 'save' => '/site/save-content',
91 | ],
92 |
93 |
94 | ## Options
95 |
96 | You can add options for the widget by passing the configuration array in the `begin()` method.
97 |
98 | ### id
99 |
100 | _default:_ `null`
101 | Identifier of the editable region (must be unique).
102 | If left empty it is automatically set to 'contentToolsXXX' where XXX is the number of next widget.
103 |
104 | ### page
105 |
106 | _default:_ `null`
107 | Page identifier. If `null` it is set to the current URL.
108 |
109 | ### tag
110 |
111 | _default:_ `'div'`
112 | HTML tag that is used to wrap the editable content.
113 |
114 | ### dataName
115 |
116 | _default:_ `'name'`
117 | Name of the `data-*` attribute that stores the identifier of editable region.
118 |
119 | ### dataInit
120 |
121 | _default:_ `'editable'`
122 | Name of the `data-*` attribute that marks the region as editable.
123 |
124 | ### options
125 |
126 | _default:_ `[]`
127 | Array of HTML options that are applied to editable region's tag.
128 |
129 | ### imagesEngine
130 |
131 | _default:_
132 |
133 | [
134 | 'upload' => '/site/content-tools-image-upload',
135 | 'rotate' => '/site/content-tools-image-rotate',
136 | 'insert' => '/site/content-tools-image-insert',
137 | ]
138 |
139 | Array of the URLs of the image actions *OR* `false` to switch off the default image engine (you will have to prepare JS
140 | for handling images on your own).
141 |
142 | ### saveEngine
143 |
144 | _default:_
145 |
146 | [
147 | 'save' => '/site/save-content',
148 | ]
149 |
150 | Array with the URL of the content saving action *OR* `false` to switch off the default saving engine (you will have to
151 | prepare JS for handling content saving on your own).
152 |
153 | ### styles
154 |
155 | _default:_ `[]`
156 | Array of styles that can be applied to the edited content.
157 | Every style should be added in separate array like:
158 |
159 | 'Name of the style' => [
160 | 'class' => 'Name of the CSS class',
161 | 'tags' => [Array of the html tags this can be applied to] or 'comma-separated list of the html tags this can be applied to'
162 | ],
163 |
164 | Example:
165 |
166 | 'Bootstrap Green' => [
167 | 'class' => 'text-success',
168 | 'tags' => ['p', 'h2', 'h1']
169 | ],
170 |
171 | `tags` key is optional and if omitted style can be applied to every element.
172 |
173 | ### language
174 |
175 | _default:_ `false`
176 | Boolean flag or language code of the widget translation.
177 | You can find the list of prepared translations in `@bower/contenttools/translations` folder.
178 | `false` means that widget will not be translated (default language is English).
179 | `true` means that widget will be translated using the application language.
180 | If this parameter is a string widget tries to load the translation file with the given name.
181 | If it cannot be found and string is longer that 2 characters widget tries again this time with parameter shortened to 2 characters.
182 | If again it cannot be found language sets back to default.
183 |
184 | ### globalConfig
185 |
186 | _default:_ `true`
187 | Boolean flag whether the configuration should be global.
188 | Global configuration means that every succeeding widget ignores `page`, `tag`, `dataName`, `dataInit`, `imagesEngine`,
189 | `saveEngine`, and `language` parameters and sets them to be the same as in the first one. Also `styles` are added only
190 | if they've got unique names.
191 |
192 | ### customJs
193 |
194 | _default:_ `null`
195 | String with custom JS to be initialized with editor.
196 | Use `editor` variable to point to instance of `ContentTools.EditorApp.get()`.
197 | See http://getcontenttools.com/api/content-tools for more details about CT API.
198 |
199 | ## Actions callbacks
200 |
201 | The default JS image callbacks assume the following action response:
202 |
203 | {
204 | 'size': [image-width-in-px, image-height-in-px],
205 | 'url': image-url
206 | }
207 |
208 | with optional `'alt'` for insert-action. In case of any errors response should be:
209 |
210 | {
211 | 'errors': [array-of-error-descriptions]
212 | }
213 |
214 | At the moment errors are only displayed in browser's console (user sees only the big transparent cross).
215 |
216 |
217 | ## Saving content
218 |
219 | Action responsible for saving the content should expect the array of every page region data in pairs
220 | `'region-identifier' => 'region-content'`.
221 |
222 | Typical structure could look like this:
223 |
224 | [
225 | 'contentTools0' => '...', // HTML content of the contentTools0 region
226 | 'contentTools1' => '...', // HTML content of the contentTools1 region
227 | '_csrf' => '...', // CRSF token value
228 | 'page' => '/site/index' // page identifier
229 | ]
230 |
231 | Now you just need to validate and save the regions linked to the page with the given identifier.
232 |
233 | **Example implementation of saving content can be found in the https://github.com/bizley/yii2-content-tools/blob/master/example.php**
234 |
--------------------------------------------------------------------------------
/composer.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "bizley/contenttools",
3 | "type": "yii2-extension",
4 | "description": "ContentTools editor implementation for Yii 2.",
5 | "keywords": ["contenttools", "yii2", "extension", "widget", "editor", "wysiwyg", "html"],
6 | "license": "Apache-2.0",
7 | "support": {
8 | "issues": "https://github.com/bizley/yii2-content-tools/issues",
9 | "source": "https://github.com/bizley/yii2-content-tools"
10 | },
11 | "authors": [
12 | {
13 | "name": "Pawel Bizley Brzozowski",
14 | "email": "pawel@positive.codes"
15 | }
16 | ],
17 | "require": {
18 | "bower-asset/contenttools": "^1.0",
19 | "yiisoft/yii2": ">=2.0.5 <2.1.0",
20 | "yiisoft/yii2-imagine": "^2.0"
21 | },
22 | "require-dev": {
23 | "roave/security-advisories": "dev-master"
24 | },
25 | "repositories": [
26 | {
27 | "type": "composer",
28 | "url": "https://asset-packagist.org"
29 | }
30 | ],
31 | "autoload": {
32 | "psr-4": {
33 | "bizley\\contenttools\\": "src/"
34 | }
35 | }
36 | }
37 |
--------------------------------------------------------------------------------
/example.php:
--------------------------------------------------------------------------------
1 | \bizley\contenttools\actions\UploadAction::class,
25 | 'image-insert' => \bizley\contenttools\actions\InsertAction::class,
26 | 'image-rotate' => \bizley\contenttools\actions\RotateAction::class,
27 | ];
28 | }
29 |
30 | /**
31 | * This action handles displaying the content.
32 | * Here we fetch content stored for URL '/example/show' (or null if it's not saved yet) and pass it to the view.
33 | * @return string
34 | */
35 | public function actionShow()
36 | {
37 | $model = Content::findOne(['page' => '/example/show']);
38 |
39 | return $this->render('show', ['model' => $model]);
40 | }
41 |
42 | /**
43 | * This action handles saving the content.
44 | * Actual data is saved in database and represented by Content model.
45 | * @return string
46 | */
47 | public function actionSave()
48 | {
49 | if (Yii::$app->request->isPost) {
50 | // By default widget sends page key indicating the URL where the data was changed.
51 | $page = Yii::$app->request->post('page');
52 |
53 | // In case data has been previously saved let's find it for an update
54 | $model = Content::findOne(['page' => $page]);
55 |
56 | // In case it's not found because this is first time of saving it let's take new object instance
57 | if ($model === null) {
58 | $model = new Content();
59 | }
60 |
61 | // By default yii2-content-tools saves each editable region in 'contentToolsX' POST array key
62 | // where X is the next number starting from 0. In this example we've got only one region.
63 | $model->setAttributes([
64 | 'data' => Yii::$app->request->post('contentTools0'),
65 | 'page' => $page,
66 | ]);
67 |
68 | if (!$model->save()) {
69 | return $this->asJson(['errors' => $model->errors]);
70 | }
71 |
72 | return $this->asJson(true);
73 | }
74 |
75 | return $this->asJson(['errors' => ['No data sent in POST.']]);
76 | }
77 | }
78 |
79 | use yii\db\ActiveRecord;
80 | use yii\helpers\HtmlPurifier;
81 |
82 | /**
83 | * This model represents data stored in DB.
84 | * In example let's use very simple table with only two columns.
85 | *
86 | * @property string $page Primary key of the table, identifies page URL
87 | * @property string $data Stored content
88 | */
89 | class Content extends ActiveRecord
90 | {
91 | /**
92 | * @return string
93 | */
94 | public static function tableName()
95 | {
96 | return 'content';
97 | }
98 |
99 | /**
100 | * In this example validation rules are simple:
101 | * - data and page are required,
102 | * - data is filtered using HtmlPurifier to prevent malicious HTML being saved,
103 | * - data must be a string with minimum 1 character length after purification,
104 | * - page must one of the allowed URLs (in this example only one).
105 | * @return array
106 | */
107 | public function rules()
108 | {
109 | return [
110 | [['page', 'data'], 'required'],
111 | ['data', 'filter', 'filter' => static function ($value) {
112 | return HtmlPurifier::process($value);
113 | }],
114 | ['data', 'string', 'min' => 1],
115 | ['page', 'in', 'range' => ['/example/show']],
116 | ];
117 | }
118 | }
119 |
120 | /**
121 | * ---------------------------------------------------------------------------------------------------------------------
122 | * 'show' view file below
123 | * ---------------------------------------------------------------------------------------------------------------------
124 | */
125 |
126 | use bizley\contenttools\ContentTools;
127 |
128 | /* @var $model Content */
129 | ?>
130 |
131 |
132 | [
134 | 'upload' => '/example/image-upload',
135 | 'rotate' => '/example/image-rotate',
136 | 'insert' => '/example/image-insert',
137 | ],
138 | 'saveEngine' => [
139 | 'save' => '/example/save',
140 | ]
141 | ]); ?>
142 |
143 | data ?>
144 |
145 |
This is heading example
146 |
Here is the default text that can be changed using yii2-content-tools.
147 |
148 |
149 |
and more...
35 | *
36 | * ~~~
37 | *
38 | * You can use the widget multiple times on one page.
39 | *
40 | * Yii 2 ContentTools saves content and uploaded images asynchronously and it requires some preparation on the backend side.
41 | * You have to create few controllers' actions:
42 | * - "upload new image" action,
43 | * - "rotate uploaded image" action,
44 | * - "insert & crop uploaded image" action,
45 | * - "save content" action.
46 | *
47 | * Three first actions are already prepared if you don't want any special operations. You can find them in
48 | * `/vendor/bizley/contenttools/actions` folder:
49 | *
50 | * - `UploadAction` - takes care of validating the uploaded images using `bizley\contenttools\models\ImageForm`
51 | * (jpg, png, and gif images are allowed, maximum width and height is 1000px and maximum size is 2 MB), images are
52 | * saved in `content-tools-uploads` folder accessible from web.
53 | * - `RotateAction` - takes care of rotating the uploaded image using Imagine library (through yii2-imagine extension
54 | * required in the composer.json).
55 | * - `InsertAction` - takes care of inserting image into the content with optional cropping using Imagine library.
56 | *
57 | * The default option for the image urls is:
58 | *
59 | * ~~~
60 | * 'imagesEngine' => [
61 | * 'upload' => '/site/content-tools-image-upload',
62 | * 'rotate' => '/site/content-tools-image-rotate',
63 | * 'insert' => '/site/content-tools-image-insert',
64 | * ],
65 | * ~~~
66 | *
67 | * So if you don't want to change the 'imagesEngine' parameter add in your SiteController:
68 | *
69 | * ~~~
70 | * public function actions()
71 | * {
72 | * return [
73 | * 'content-tools-image-upload' => \bizley\contenttools\actions\UploadAction::className(),
74 | * 'content-tools-image-insert' => \bizley\contenttools\actions\InsertAction::className(),
75 | * 'content-tools-image-rotate' => \bizley\contenttools\actions\RotateAction::className(),
76 | * ];
77 | * }
78 | * ~~~
79 | *
80 | * See Standalone Actions section in Yii 2 Guide for more info about adding actions
81 | * https://www.yiiframework.com/doc/guide/2.0/en/structure-controllers#standalone-actions
82 | *
83 | * The last "save content" action is not prepared because it depends on the business logic of your application.
84 | * Default configuration for this is:
85 | *
86 | * ~~~
87 | * 'saveEngine' => [
88 | * 'save' => '/site/save-content',
89 | * ],
90 | * ~~~
91 | */
92 | class ContentTools extends Widget
93 | {
94 | /**
95 | * @var string Page identifier. If null it is set as the current URL.
96 | */
97 | public $page;
98 |
99 | /**
100 | * @var string HTML tag that is used to wrap the editable content.
101 | */
102 | public $tag = 'div';
103 |
104 | /**
105 | * @var string Name of the data-* attribute that stores the identifier of editable region.
106 | */
107 | public $dataName = 'name';
108 |
109 | /**
110 | * @var string Name of the data-* attribute that marks the region as editable.
111 | */
112 | public $dataInit = 'editable';
113 |
114 | /**
115 | * @var array Array of HTML options that are applied to editable region's tag.
116 | */
117 | public $options = [];
118 |
119 | /**
120 | * @var array|bool Array of the URLs of the image actions OR false to switch off the default image engine
121 | * (you need to prepare JS for handling images on your own in the second case).
122 | */
123 | public $imagesEngine = [
124 | 'upload' => '/site/content-tools-image-upload',
125 | 'rotate' => '/site/content-tools-image-rotate',
126 | 'insert' => '/site/content-tools-image-insert',
127 | ];
128 |
129 | /**
130 | * @var array|bool Array with the URL of the content saving action OR false to switch off the default saving engine
131 | * (you need to prepare JS for handling content saving on your own in the second case).
132 | */
133 | public $saveEngine = [
134 | 'save' => '/site/save-content',
135 | ];
136 |
137 | /**
138 | * @var array Array of styles that can be applied to the edited content.
139 | * Every style should be added in separate array like:
140 | * ~~~
141 | * 'Name of the style' => [
142 | * 'class' => 'Name of the CSS class',
143 | * 'tags' => // [Array of the html tags this can be applied to] or
144 | * // 'comma-separated list of the html tags this can be applied to'
145 | * ],
146 | * ~~~
147 | * Example:
148 | * ~~~
149 | * 'Bootstrap Green' => [
150 | * 'class' => 'text-success',
151 | * 'tags' => ['p', 'h2', 'h1'], // or 'p,h2,h1'
152 | * ],
153 | * ~~~
154 | * 'tags' key is optional and if omitted style can be applied to every element.
155 | */
156 | public $styles = [];
157 |
158 | /**
159 | * @var bool|string Boolean flag or language code of the widget translation.
160 | * You can see the list of prepared translations in `@bower/contenttools/translations` folder.
161 | * `false` means that widget is not translated (default language is English).
162 | * `true` means that widget is translated using the application's language.
163 | * If this parameter is a string widget tries to load the translation file with the given name. If it can not be
164 | * found and string is longer that 2 characters widget tries again this time with parameter shortened to 2
165 | * characters. If again it can not be found language sets back to default.
166 | */
167 | public $language = false;
168 |
169 | /**
170 | * @var bool Boolean flag whether the configuration should be global.
171 | * Global configuration means that every succeeding widget instance ignores `tag`, `dataName`, `dataInit`,
172 | * `imagesEngine`, `saveEngine`, and `language` parameters and sets them to be the same as in the first one.
173 | * Also `styles` are added only if they've got unique names.
174 | */
175 | public $globalConfig = true;
176 |
177 | /**
178 | * @var string Custom JS to be initialized with editor.
179 | * Use `editor` variable to point to instance of ContentTools.EditorApp.get()
180 | * See http://getcontenttools.com/api/content-tools for more details about CT API
181 | * @since 1.3.0
182 | */
183 | public $customJs;
184 |
185 | /**
186 | * {@inheritdoc}
187 | */
188 | public static $autoIdPrefix = 'contentTools';
189 |
190 | const GLOBAL_PARAMS_KEY = 'content-tools-global-configuration';
191 |
192 | private $_global;
193 | private $_addedStyles = [];
194 |
195 | /**
196 | * Checks if global configuration array is set.
197 | * If so it sets properties for global values.
198 | * If not and the `globalConfig` is set to true the current properties are saved in global configuration.
199 | */
200 | public function globalConfig()
201 | {
202 | $this->_global = isset($this->getView()->params[self::GLOBAL_PARAMS_KEY]);
203 |
204 | if ($this->_global) {
205 | $globalConfig = $this->getView()->params[self::GLOBAL_PARAMS_KEY];
206 |
207 | $this->page = $globalConfig['page'];
208 | $this->dataName = $globalConfig['dataName'];
209 | $this->dataInit = $globalConfig['dataInit'];
210 | $this->imagesEngine = $globalConfig['imagesEngine'];
211 | $this->saveEngine = $globalConfig['saveEngine'];
212 | $this->language = $globalConfig['language'];
213 | $this->_addedStyles = $globalConfig['styles'];
214 | } elseif ($this->globalConfig) {
215 | $this->getView()->params[self::GLOBAL_PARAMS_KEY] = [
216 | 'page' => $this->page,
217 | 'dataName' => $this->dataName,
218 | 'dataInit' => $this->dataInit,
219 | 'imagesEngine' => $this->imagesEngine,
220 | 'saveEngine' => $this->saveEngine,
221 | 'language' => $this->language,
222 | 'styles' => [],
223 | ];
224 | }
225 | }
226 |
227 | /**
228 | * Returns the default JS part for saving the content if `saveEngine` is not set to `false`. `saveEngine` should be
229 | * boolean `false` or the array with `save` key.
230 | * @return string
231 | * @throws InvalidConfigException
232 | */
233 | public function initSaveEngine()
234 | {
235 | $js = '';
236 |
237 | if ($this->saveEngine !== false) {
238 | if (empty($this->saveEngine['save'])) {
239 | throw new InvalidConfigException('Invalid options for the saveEngine configuration!');
240 | }
241 |
242 | $csrfParam = Yii::$app->request->csrfParam;
243 | $csrfToken = Yii::$app->request->csrfToken;
244 |
245 | $page = $this->page;
246 | if (empty($page)) {
247 | $page = Url::current();
248 | }
249 |
250 | $js = <<