@innovastudio/contentbox 1.4.19 → 1.4.21

package/README.md

@@ -39,6 +39,12 @@ Then import into your project:
 import ContentBox from '@innovastudio/contentbox';
 ```
 
+### Asset Files
+
+Asset files (eg. template or snippet files) are also needed to run the ContentBox. They are located in the **assets** folder in the package.
+
+**Note**: location of asset related files are flexible and can be configured. For example, you can move the asset files on different server (eg. CDN server).
+
 ## Additional Includes for Viewing Content
 
 For viewing content, additional includes are also needed. 
@@ -114,6 +120,8 @@ ContentBox.js is written in pure Javascript (ES6) so you can use it in most situ
 
 React and Vue project examples are provided in separate downloads in the user area.
 
+To run the HTML example, open using your browser: **public/example.html** from localhost or from your server.
+
 ## Folder Structure
 
 - public/
@@ -137,7 +145,7 @@ React and Vue project examples are provided in separate downloads in the user ar
 - ...
 
 
-## Predesigned Sections (Templates)
+## Templates (Predesigned Sections)
 
 To start building a page, you can click the (+) button on the top left sidebar. This will open a selection of predesigned sections that you can add into your page.
 
@@ -145,21 +153,68 @@ To start building a page, you can click the (+) button on the top left sidebar.
 
 ![Quick Start](docs/predesigned-sections2.png)
 
-There are 2 predesigned section categories: 
+![All Categories](docs/section-categories.png)
+
+If you click **ALL CATEGORIES**, 2 sets of templates will be displayed:
+
 - Simple Start (to start from a basic/clean design)
 - Quick Start (to start with examples)
 
-The predesigned section files are located in the folder:
+These 2 set of templates are located in the folder:
 
-**assets/designs/**
+- **assets/simplestart/**
+- **assets/quickstart/**
 
-It contains:
-- basic.js (a JSON file containing a list of simple designs)
-- examples.js (a JSON file containing a list of ready made designs)
-- images (contains assets for the designs)
-- preview (contains design thumbnails)
+Each folder contains:
+
+- templates.js (a JSON file containing a list of ready made designs)
+- images/ (contains assets for the designs)
+- preview/ (contains design thumbnails)
+
+The templates are loaded using the following configuration: 
 
-You can configure the file location by setting the **designUrl1**, **designUrl2** and **designPath** parameters:
+```javascript
+const builder = new ContentBox({
+    wrapper: '.is-wrapper',
+    templates: [
+        {   
+            url: 'assets/simplestart/templates.js', 
+            path: 'assets/simplestart/', 
+            pathReplace: [ ]
+        },
+        {   
+            url: 'assets/quickstart/templates.js',
+            path: 'assets/quickstart/', 
+            pathReplace: [ ]
+        },
+    ],
+});
+```
+Using the **templates** parameter, you can configure the template file (**url**), the asset location (**path**), and optionally, use **pathReplace** property to replace string found on the template file.
+
+Here is an example of a different assets location:
+
+```javascript
+const builder = new ContentBox({
+    wrapper: '.is-wrapper',
+    templates: [
+        {   
+            url: 'https://path-to/assets/simplestart/templates.js', 
+            path: 'https://path-to/assets/simplestart/', 
+            pathReplace: [ ]
+        },
+        {   
+            url: 'https://path-to/assets/quickstart/templates.js',
+            path: 'https://path-to/assets/quickstart/', 
+            pathReplace: [ ]
+        },
+    ],
+});
+```
+
+#### For old version of ContentBox
+
+In the old ContentBox, you can configure the template location by setting the **designUrl1**, **designUrl2** and **designPath** parameters. These still work. Note that in the old version, templates are located in **assets/designs/** folder.
 
 ```javascript
 const builder = new ContentBox({
@@ -186,6 +241,195 @@ In this example, the default location is changed to https://path-to/assets/desig
 
 With this, you can place all the assets in a separate server or different host (e.g. from a CDN).
 
+### Template Files
+
+Let’s see one of the template file, the Simple Start template: assets/simplestart/templates.js.
+
+```javascript
+var data_templates = {
+    name: 'Simple Start',
+    categories: [
+        { id: 1, name: 'Basic' }, 
+        { id: 2, name: 'Slider' }, 
+        { id: 3, name: 'Video' }, 
+        { id: 4, name: 'Custom' }, 
+    ],
+    designs: [
+
+		{
+		    'thumbnail': 'preview/simple-01.png',
+		    'category': '1',
+		    'contentCss': 'type-poppins.css',
+		    'contentClass': 'type-poppins',
+		    'html': `
+			<div class="is-section is-box is-section-100 type-poppins">
+            ...
+            </div>`
+		},
+        // ...
+
+	]
+};
+
+try {
+    template_list.push(data_templates);
+} catch(e) {
+    //
+}
+```
+
+With the same format, you can create your own template set and load it in ContentBox.
+
+In this JSON format, you can define the template set **name**, **categories**, and the template collection (**designs**).
+
+Ini this set, we have 4 categories:
+1. Basic
+2. Slider
+3. Video 
+4. Custom
+
+For each section template, you need to specify:
+
+- **thumbnail**
+- **category**: see the **categories** definition **id**.
+- **contentCss**: css file for typography (there are many css files you can choose from **assets/styles/** folder. Please choose the file with prefix **type-*****.
+- **contentClass**: css class name (just use the css file name without extension)
+- **html**: the HTML template.
+Within the html, you can use **[%IMAGE_PATH%]** tag that will be replaced with the asset location/path. For example:
+```html
+<img src="[%IMAGE_PATH%]images/photo.jpg">
+```
+will become:
+```html
+<img src="assets/simplestart/images/photo.jpg">
+```
+
+Let's the other template file, the Quick Start template: **assets/quickstart/templates.js**.
+
+```javascript
+var data_templates = {
+    name: 'Simple Start',
+    categories: [
+        { id: 1, name: 'Basic' }, 
+        { id: 2, name: 'Slider' }, 
+        { id: 3, name: 'Video' }, 
+        { id: 4, name: 'Custom' }, 
+    ],
+    designs: [
+
+		{
+		    'thumbnail': 'preview/simple-01.png',
+		    'category': '1',
+		    'contentCss': 'type-poppins.css',
+		    'contentClass': 'type-poppins',
+		    'html': `
+			<div class="is-section is-box is-section-100 type-poppins">
+            ...
+            </div>`
+		},
+        // ...
+
+	]
+};
+
+try {
+    template_list.push(data_templates);
+} catch(e) {
+    //
+}
+```
+
+Ini this set, we have 18 categories, from Header, Article, to Footer.
+
+The two template files (**assets/simplestart/templates.js** and **assets/quickstart/templates.js**) are loaded by registering them in the **templates** parameter:
+
+
+```javascript
+const builder = new ContentBox({
+    wrapper: '.is-wrapper',
+    templates: [
+        {   
+            url: 'assets/simplestart/templates.js', 
+            path: 'assets/simplestart/', 
+            pathReplace: [ ]
+        },
+        {   
+            url: 'assets/quickstart/templates.js',
+            path: 'assets/quickstart/', 
+            pathReplace: [ ]
+        },
+    ],
+});
+```
+
+Template loading is asynchronous so it won’t block the initial page loading. In this configuration, we load the **simplestart/templates.js** set first and then the **quickstart/templates.js**.
+
+#### Featuring Certain Categories
+
+You can feature certain categories that will be displayed on the front using **featuredCategories** parameter:
+
+```javascript
+const builder = new ContentBox({
+    // ...
+
+    featuredCategories: [
+        { id: 1, designId: 1, name: 'Basic' }, 
+        { id: 2, designId: 1, name: 'Slider' },
+        { id: 1, designId: 2, name: 'Header' },
+        { id: 2, designId: 2, name: 'Article' },
+        { id: 3, designId: 2, name: 'Photos' },
+    ],
+});
+```
+
+The **simplestart** set has designId=1 and the **quickstart** set has designId=2 (according to the load order).
+
+The **id** refers to the category id.
+
+Then choose which category to display on the first open:
+
+```javascript
+const builder = new ContentBox({
+    // ...
+
+    defaultCategory: {
+        id: 1,
+        designId: 1
+    },
+});
+```
+
+Here we choose the **Basic** category (id: 1), from the **simplestart** set (designId: 1).
+
+![Featured Categories](docs/featured-categories.png)
+
+#### Adjusting the thumbnail size
+
+To adjust the template’s thumbnail size, use **templateThumbnailSize** parameter:
+
+```javascript
+const builder = new ContentBox({
+    ...
+
+    templateThumbnailSize: 'small',
+});
+```
+
+The default is empty string (means dynamic or auto adjust based on the screen size).
+For specific size, use: **small**, **medium**, or **large**.
+
+![Small](docs/template-small.png)
+
+Small
+
+![Medium](docs/template-medium.png)
+
+Medium
+
+![Large](docs/template-large.png)
+
+Large
+
 ## Snippets
 
 Snippets are predesigned blocks that you can add or drag & drop into your content. 
@@ -304,9 +548,9 @@ _txt['Italic'] = 'Italic';
 
 You can create your own language file by copying/modifying this file. 
 
-## Adding Custom Buttons to the Sidebar
+## Adding Custom Buttons on the Sidebar
 
-To add custom buttons to the sidebar, use the **addButton** method.
+To add custom buttons on the sidebar, use the **addButton** method.
 
 Here is an example of adding the Undo & Redo button. For the undo and redo operation, we call the **undo()** and **redo()** methods.
 
@@ -568,7 +812,140 @@ const builder = new ContentBox({
 });
 ``` 
 
-More configuration options can be found in the ContentBuilder.js documentation: https://innovastudio.com/docs/contentbuilder.pdf
+#### Preview
+
+The editing toolbar from ContentBuilder.js has a **Preview** button to view the page result in a modal.
+In ContentBox, you can define the preview URL using **previewURL** parameter. The default value is ‘preview.html’.
+
+```javascript
+const builder = new ContentBox({
+    wrapper: '.is-wrapper',
+
+    previewURL: 'preview.html'
+});
+``` 
+
+![Preview Button](docs/cb-preview.png)
+
+The preview.html is used to view the edited page result (without the builder). The file is located in **public** folder.
+
+More configuration options can be found in the ContentBuilder.js documentation: 
+
+https://innovastudio.com/docs/contentbuilder.pdf
+
+## Extending ContentBox with Custom Panel for Adding Custom Content
+
+We will look on how to add a button on the sidebar that opens a custom panel. You can create your own custom panel by creating a simple html page. In this example, we will have a panel with multiple buttons that can add a custom content/section into your page. You can try the example in the package by opening: **public/example-custom.html**. (from localhost or from your server).
+
+![Extending ContentBox](docs/extending.png)
+
+Click the buttons to try adding a new custom content/section into the page.
+
+Let’s look at the code.
+
+To add a button on the sidebar, use **addButton()** method (this method has been explained in the previous chapter: **Adding Custom Buttons on the Sidebar**):
+
+```javascript
+builder.addButton({ 
+    'pos': 0,
+    'title': 'Products',
+    'src': 'mypanel.html', 
+    'html': '<svg style="width:17px;height:17px;" viewBox="0 0 2048 2048" xmlns="http://www.w3.org/2000/svg">' +
+        '<g id="document" transform="matrix(1,0,0,1,1024.0,1024.0)"><path d="M178.271,508.452 L303.32,508.452 L303.32,-735.688 L178.271,-735.688 L178.271,508.452 Z " fill="#000000" fill-opacity="1.00" /><path d="M862.865,-51.0932 L862.865,-176.143 L-381.274,-176.143 L-381.274,-51.0933 L862.865,-51.0932 Z " fill="#000000" fill-opacity="1.00" /><path d="M-1020.43,275.099 L-1020.43,400.148 L-85.2735,400.148 L-85.2735,275.099 L-1020.43,275.099 Z " fill="#000000" fill-opacity="1.00" /><path d="M-1020.43,559.907 L-1020.43,684.956 L-85.2735,684.956 L-85.2735,559.907 L-1020.43,559.907 Z " fill="#000000" fill-opacity="1.00" /><path d="M-1024,844.714 L-1024,969.764 L-88.8389,969.764 L-88.8389,844.714 L-1024,844.714 Z " fill="#000000" fill-opacity="1.00" /></g>' +
+        '</svg>',
+    'class': 'sidebar-sections' 
+});
+``` 
+
+The **src** property is set with your custom html page, **mypanel.html**. This simple html page contains the buttons for adding content. Each button simply calls the **addSection()** method.
+
+
+```javascript
+parent.contentbox.addSection(html, css)
+``` 
+
+The **addSection()** method accepts two parameters:
+
+- **html**: your content
+- **css**: css file for typography that you can choose from the folder **assets/styles/**
+(choose the file with prefix **type-**).
+
+Example:
+
+```javascript
+parent.contentbox.addSection(`
+    <div class="is-section is-box is-section-100 type-rufina-oxygen">
+        <div class="is-boxes">
+            <div class="is-box-centered">
+
+                <div class="is-container v2 is-content-960 leading-13 size-17">
+                    <div class="row">
+                        <div class="column full">
+                            <h1 class="text-center leading-09 size-92">Product One</h1>
+                        </div>
+                    </div>
+                </div>
+
+            </div>
+        </div>
+    </div>
+    `, 'type-rufina-oxygen.css');
+``` 
+
+Here we choose **type-rufina-oxygen.css** for the typography css. Then we added **type-rufina-oxygen** class in the **div.is-section** element. This will format the content with the Rufina & Oxygen fonts.
+
+```html
+<div class="is-section is-box is-section-100 type-rufina-oxygen">
+...
+</div>
+```
+
+Use the same format as in the example if you want to create your own content. Please leave the other classes in the example as they are needed by ContentBox to format the content.
+
+To make the content protected (non editable), please add **protected** class on the **div.is-section**. and do not use **is-container** class. The **is-container** class is used for text content inside the section and it is always editable.
+
+```html
+<div class="is-section is-box is-section-100 type-rufina-oxygen protected">
+...
+</div>
+```
+
+If you need to add custom Javascript, please use the following format:
+
+```html
+<div class="is-section is-box is-section-100 type-rufina-oxygen protected">
+    <div class="is-overlay">
+        <div class="is-overlay-content" 
+            data-module="code" 
+            data-module-desc="My Code" 
+            data-html="[... encoded custom script here ...]">      
+        </div>
+    </div>
+</div>
+```
+
+Here is an example:
+
+```javascript
+parent.contentbox.addSection(`
+    <div class="is-section is-box is-section-100 is-light-text type-rufina-oxygen protected">
+        <div class="is-overlay">
+            <div class="is-overlay-content" 
+                data-module="code" 
+                data-module-desc="Custom HTML or Javascript " 
+                data-html="${encodeURIComponent(`
+
+                    <!-- custom script here -->
+ 
+            `)}">
+                
+            </div>
+        </div>
+    </div>
+    `, 'type-rufina-oxygen.css');
+```
+
+For the complete code, please open the **mypanel.html** with your code editor. 
 
 
 ## Credits

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@innovastudio/contentbox",
   "type": "module",
-  "version": "1.4.19",
+  "version": "1.4.21",
   "description": "",
   "main": "public/contentbox/contentbox.esm.js",
   "files": [
@@ -46,7 +46,7 @@
     "webpack-dev-server": "^4.0.0"
   },
   "dependencies": {
-    "@innovastudio/contentbuilder": "^1.3.13",
+    "@innovastudio/contentbuilder": "^1.3.14",
     "js-beautify": "^1.14.0"
   }
 }

package/public/contentbox/contentbox.css

@@ -643,3 +643,7 @@
 .is-section.is-section-navbar .is-topbar {
   width: calc(100% - 60px);
 }
+
+.is-section.protected .is-box-tool {
+  display: none !important;
+}