Introducing components in Markdown webdocs

In continuation of the introductory part of habrahabr.ru/post/196248 , in this article I will review the mechanism of the component system implemented in the controls.js library and used in Markdown webdocs for creating and inserting active content into a text document.

Technically, components of Markdown webdocs are controls in terms of controls.js organized into separate modules and provided with additional resources. In practice, Markdown webdocs components are an extended analog of the templates widely used in web design, implemented in such a way that they can be called directly from the page text.

A component is initially some kind of JavaScript object having parameters, attributes containing data, a template function of the html code, and of course, those properties and methods that we define in its code.

Some basic set of ready-made components are embedded in document.js and are available immediately after initialization, it is also possible to automatically download by the component name from the predefined / components folder or by connecting external scripts containing a component module to the page.
')
Elementary components do not contain auxiliary code and styles and do not change their behavior and presentation, complex components can contain code and styles, manage their state, behavior and presentation, interact with the document and the outside world, and even mutate into other components and turn completely into another component. Independent components allow you to fully remove all dependencies in a separate module. Universal components in their habitat are not limited to the browser. A good, usable component can be interpreted on the server, and executed in the browser, or transferred from one frame to another. Reliable components do not depend on the order of loading resource files on the page. Smart components can cache data or preload, lazy components do not interfere with other components to work.

Hello World! in a component way

(function() { function HelloWorld(parameters, attributes) { $ENV.controls.controlInitialize(this, 'hello', parameters, attributes, $ENV.default_template, $ENV.default_inner_template); this.text('# Hello World!'); // ← Markdown }; HelloWorld.prototype = $ENV.controls.control_prototype; controls.typeRegister('hello', HelloWorld); // ←   })(); 

In order for a function to become a component object designer in Markdown webdocs, several conditions must be met:
- in the chain of prototypes should be controls.control_prototype, this gives the object general properties and methods of control.
- the function must be registered by calling controls.typeRegister () or controls.factoryRegister ()
- in the constructor module, initialization is required by calling controls.controlInitialize ()
- it is desirable to assign special templates at initialization that understand Markdown markup. $ ENV.default_template and $ ENV.default_inline_template are such control templates that are compatible with Markdown webdocs and can be used in most custom components.

In the example above, only the string this.text ('# Hello World!'); is a problem area code.

Background dynamic component loading

Dynamic loading is convenient for prototyping and debugging purposes. If you create a file controls.hello-world.js with an example code Hello World! and place along the components / controls / hello-world / controls.hello-world.js path in the site folder, in the text of the pages of this site you can use the call notation for this component:% hello ()% hello, the script will be loaded only with this call At the time from the moment of executing the initialization code to the actual loading of the script (and this time may be noticeable), the stub component will be located in the specified place of the document instead of the component.

Component manifest

The component system mechanism is based on rather simple, systematic and universal basic principles:

Modular construction principle

A module represents an infrastructure for a component; in one module, several components can be created using common data.
The module encapsulates styles and resources; a properly constructed component should allow managing and connecting resources by this component, for example, to disable the uniquely used styles when a component is deleted.

Modifications

The main purpose of the parameters is the choice of component modification. A modification may be a different representation of the same component, or it may be a separate component. Parameters are also used to transfer attribute values ​​to objects, where it is convenient.
Examples:
% page-layout # scheme = centered ()% page-layout - here scheme is a parameter that allows you to select one or another modification, which for this component means choosing a page layout scheme.
% block # $ class = m41 ()% block - assigning a class name to a block, this is an example of passing an attribute value through parameters.

HTML code generation, DOM element management, event handling

All this is the responsibility of the component, for this the base library provides the corresponding functionality that reduces the required amount of code. DOM acts as a visualization tool and completely abstracts from data objects. In the simplest case, the developer does not need to do anything, the component already has a default template and corresponding behavior when it is created.

Arbitrary nesting, fractality, systematic

Each part of the document is similar to the entire document and can act as a separate document. A component, as part of a document, has the same properties. A document may be part of another document.

Why is all this necessary?

In this place I propose to look through the site of the project Components section in order to get an idea about the capabilities of the components.

In my opinion, today technically this is the most optimal way to create complex web documents and it avoids a number of fundamental flaws inherent in other technologies. (And simplify the code). Using the technology of external components, it was possible to add, almost seamlessly, to the two already familiar Markdown and html markups used together, adding a third one that complements them with the missing elements - templates, modularity and structured active code.

And those few flaws that are present in all JavaScript sites now have confidence in the near future, they will be resolved, because the JavaScript sites are increasing and their support on the network only increases over time.

Perhaps after reading you got the wrong impression that the system is very complex. But I want to say that it is not. If you look at the source code of the components listed on the site, you will see that relatively little code is used in the component itself to create quite complex effects on the site. This system seems difficult at the first acquaintance, to start you need to remember a few basic things.

If you don’t understand anything about what I’ve written here ... I’ll write and eventually I will try to clearly convey everything and answer all the questions that arise.

Project

During this time, the project got the name Markdown webdocs, I hope this will be a new word in network technologies. You can leave comments and suggestions on a githaba, in a blog or a Vkontakte group. If you want to assist the project or take advantage of the special offer, but do not know how to do it, please contact me directly, all contacts are published in my profile.
Project site aplib.imtqy.com/markdown-site-template
Repository github.com/aplib/markdown-site-template