From ca0fb4191057bf7ccd9f112ac56f5f90238f0437 Mon Sep 17 00:00:00 2001 From: Johannes Raggam Date: Fri, 23 Dec 2022 16:02:25 +0100 Subject: [PATCH 1/4] maint(Docs): Improve documentation. --- src/core/basepattern.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/core/basepattern.md b/src/core/basepattern.md index 3fdbc881d..2c582f21c 100644 --- a/src/core/basepattern.md +++ b/src/core/basepattern.md @@ -38,9 +38,13 @@ Also see: https://github.com/Patternslib/pat-PATTERN_TEMPLATE } } - // Register Pattern class in the global pattern registry + // Register Pattern class in the global pattern registry and make it usable there. registry.register(Pattern); - // Make it available + // Export Pattern as default export. + // You can import it as ``import AnyName from "./{{{ pattern.name }}}";`` export default Pattern; + // Export BasePattern as named export. + // You can import it as ``import { Pattern } from "./{{{ pattern.name }}}";`` + export { Pattern }; From 32a59d1d513361f581163a1820d2e5aaa5252ee1 Mon Sep 17 00:00:00 2001 From: Johannes Raggam Date: Fri, 23 Dec 2022 17:32:33 +0100 Subject: [PATCH 2/4] maint(Docs): Remove sections which do not apply from patterns.rst. --- docs/developer/patterns.rst | 130 ++++++------------------------------ 1 file changed, 22 insertions(+), 108 deletions(-) diff --git a/docs/developer/patterns.rst b/docs/developer/patterns.rst index d71b22b7d..2d03f4299 100644 --- a/docs/developer/patterns.rst +++ b/docs/developer/patterns.rst @@ -1,12 +1,32 @@ Creating a new pattern ====================== -Patterns are implemented as javascript objects that are registered with the -patterns library. Below is a minimal skeleton for a pattern. +Patterns are implemented as JavaScript classes that are registered with the patterns library. +Below is a minimal skeleton for a pattern. .. code-block:: javascript :linenos: + import { BasePattern } from "@patternslib/patternslib/src/core/basepattern"; + import registry from "@patternslib/patternslib/src/core/registry"; + + class Pattern extends BasePattern { + static name = "test-pattern"; + static trigger = ".pat-test-pattern"; + + init() { + } + } + + // Register Pattern class in the global pattern registry and make it usable there. + registry.register(Pattern); + + // Export Pattern as default export. + // You can import it as ``import AnyName from "./{{{ pattern.name }}}";`` + export default Pattern; + // Export BasePattern as named export. + // You can import it as ``import { Pattern } from "./{{{ pattern.name }}}";`` + export { Pattern }; define([ 'require' '../registry' @@ -60,72 +80,6 @@ possible to call ``init`` again to reactivate the pattern. Methods must always return ``this`` to facilitate their use as jQuery widgets. -jQuery plugins --------------- - -Patterns can also act as jQuery plugins. This can be done by providing a -``jquery_plugin`` option in the pattern specification. - -.. code-block:: javascript - :linenos: - :emphasize-lines: 3 - - var pattern_spec = { - name: "mypattern", - jquery_plugin: true, - - init: function($el) { - ... - }, - - destroy: function($el) { - ... - }, - - othermethod: function($el, options) { - ... - } - }; - - -Line 3 tells the patterns framework that this pattern can be used as a jQuery -plugin named ``patMypattern``. You can then interact with it using the -standard jQuery API: - -.. code-block:: javascript - - // Initialize mypattern for #title - $("#title").patMypattern(); - - // Invoke othermethod for the pattern - $("#title").patMypattern("othermethod", {option: "value"}); - - -Injection actions ------------------ - -The injection mechanism supports invoking arbitrary actions after loading new -content. This is handled through *injection actions*. These are handled by an -``inject`` method on a pattern. - -.. code-block:: javascript - :linenos: - :emphasize-lines: 3 - - var pattern_spec = { - name: "mypattern", - - inject: function($trigger, content) { - ... - } - }; - -The inject methods gets a number of parameters: - -* ``$trigger`` is the element that triggered the injection. -* ``content`` is an array containing the loaded content. - - Pattern configuration --------------------- @@ -163,43 +117,3 @@ parser instance and add our options with their default values. In the init method we use the parser to parse the ``data-mypattern`` attribute for the element. Finally we combine that with the options that might have been provided through the jQuery plugin API. - -Creating a JavaScript API -------------------------- - -Sometimes you may want to create a JavaScript API that is not tied to DOM -elements, so exposing it as a jQuery plugin does not make sense. This can -be done using the standard RequireJS mechanism by creating and returning an -API object. - -.. code-block:: javascript - :linenos: - :emphasize-lines: 13-17 - - define([ - 'require', - '../registry' - ], function(require, registry) { - var pattern_spec = { - init: function($el) { - ... - }; - }; - - registry.register(pattern_spec); - - var public_api = { - method1: function() { .... }, - method2: function() { .... } - }; - return public_api; - }); - - -You can then use the API by using require to retrieve the API object for -the pattern: - -.. code-block:: javascript - - var pattern_api = require("patterns/mypattern"); - pattern_api.method1(); From 6915ba7e367277bd76c6d0ccdd86ba8c5e1f69e1 Mon Sep 17 00:00:00 2001 From: Johannes Raggam Date: Fri, 23 Dec 2022 17:34:00 +0100 Subject: [PATCH 3/4] fixup! --- docs/developer/patterns.rst | 9 --------- 1 file changed, 9 deletions(-) diff --git a/docs/developer/patterns.rst b/docs/developer/patterns.rst index 2d03f4299..9be7d1e47 100644 --- a/docs/developer/patterns.rst +++ b/docs/developer/patterns.rst @@ -27,16 +27,7 @@ Below is a minimal skeleton for a pattern. // Export BasePattern as named export. // You can import it as ``import { Pattern } from "./{{{ pattern.name }}}";`` export { Pattern }; - define([ - 'require' - '../registry' - ], function(require, registry) { - var pattern_spec = { - name: "mypattern", - }; - registry.register(pattern_spec); - }); This skeleton does several things: From fa4d20a4b8e4f355dab1fb724a5b69c9bc97c54b Mon Sep 17 00:00:00 2001 From: Johannes Raggam Date: Sat, 12 Aug 2023 01:29:24 +0200 Subject: [PATCH 4/4] Continue improving the docs. --- docs/developer/index.md | 6 +++ docs/developer/patterns.rst | 79 +++++++++++++++---------------------- src/core/basepattern.md | 4 +- 3 files changed, 39 insertions(+), 50 deletions(-) create mode 100644 docs/developer/index.md diff --git a/docs/developer/index.md b/docs/developer/index.md new file mode 100644 index 000000000..6396eaa21 --- /dev/null +++ b/docs/developer/index.md @@ -0,0 +1,6 @@ +# Developer documentation + +- [Patternslib overview](overview.md) +- [The structure of a pattern](patterns.md) +- [Configuring a pattern](patterns-configuration.md) +- [Styleguide](styleguide.md) diff --git a/docs/developer/patterns.rst b/docs/developer/patterns.rst index 9be7d1e47..5edf115a6 100644 --- a/docs/developer/patterns.rst +++ b/docs/developer/patterns.rst @@ -1,20 +1,46 @@ -Creating a new pattern -====================== +The structure of a pattern +========================== -Patterns are implemented as JavaScript classes that are registered with the patterns library. -Below is a minimal skeleton for a pattern. +Patterns are implemented as JavaScript classes that are registered with the patterns registry. +Below is a minimalistic skeleton for a pattern with explanations as inline comments. .. code-block:: javascript :linenos: import { BasePattern } from "@patternslib/patternslib/src/core/basepattern"; + import Parser from "@patternslib/patternslib/src/core/parser"; import registry from "@patternslib/patternslib/src/core/registry"; + export const parser = new Parser("test-pattern"); + // Define an argument with a default value. You can configure the value via + // data-attributes. + parser.addArgument("example-option", "Hollareidulio"); + class Pattern extends BasePattern { + + // Define a name for the pattern which is used as key in the pattern + // registry. static name = "test-pattern"; + + // Define a CSS selector. The pattern will be initialized on elements + // matching this selector. static trigger = ".pat-test-pattern"; + // The parser instance from above. + static parser = parser; + init() { + import("./test-pattern.scss"); + + // Try to avoid jQuery, but here is how to import it, asynchronously. + // eslint-disable-next-line no-unused-vars + const $ = (await import("jquery")).default; + + // The options are automatically created, if parser is defined. + const example_option = this.options.exampleOption; + this.el.innerHTML = ` +

${example_option}, this is the ${this.name} pattern!

+ `; } } @@ -29,55 +55,12 @@ Below is a minimal skeleton for a pattern. export { Pattern }; -This skeleton does several things: - -* lines 1-4 use `RequireJS `_ to load the patterns - registry. -* lines 5-7 create an object which defines this pattern's specifications. -* line 9 registers the pattern. - - -Markup patterns ---------------- - -Most patterns deal with markup: they are activated for content that matches -a specific CSS selector. This is handled by adding two items to the -pattern specification: a ``trigger`` and an ``init`` function. - -.. code-block:: javascript - :linenos: - - var pattern_spec = { - name: "mypattern", - trigger: ".tooltip, [data-tooltip]", - - init: function($el) { - ... - }, - - destroy: function($el) { - ... - } - }; - -The trigger specified on line 3 is a CSS selector which tells the pattern -framework which elements this pattern is interested in. If new items are -discovered in the DOM that match this pattern, the ``init`` function will be -called with a jQuery wrapper around the element. - -While not required patterns are encouraged to include a ``destroy`` function -that undos the pattern initialisation. After calling ``destroy`` it should be -possible to call ``init`` again to reactivate the pattern. - -Methods must always return ``this`` to facilitate their use as jQuery widgets. - Pattern configuration --------------------- The configuration of a pattern is generally based on three components: the -default settings, configuration set on a DOM element via a data-attribute, and, -if the jQuery API is used, via options passed in via the jQuery plugin API. +default settings, configuration set on a DOM element via a data-attribute. The init method for patterns should combine these settings. Let's update our example pattern to do this: diff --git a/src/core/basepattern.md b/src/core/basepattern.md index 2c582f21c..3896f028c 100644 --- a/src/core/basepattern.md +++ b/src/core/basepattern.md @@ -16,7 +16,7 @@ Also see: https://github.com/Patternslib/pat-PATTERN_TEMPLATE import registry from "@patternslib/patternslib/src/core/registry"; export const parser = new Parser("test-pattern"); - parser.addArgument("example-option", "Stranger"); + parser.addArgument("example-option", "Hollareidulio"); class Pattern extends BasePattern { static name = "test-pattern"; @@ -33,7 +33,7 @@ Also see: https://github.com/Patternslib/pat-PATTERN_TEMPLATE // The options are automatically created, if parser is defined. const example_option = this.options.exampleOption; this.el.innerHTML = ` -

hello, ${example_option}, this is pattern ${this.name} speaking.

+

${example_option}, this is the ${this.name} pattern!

`; } }