diff --git a/docs/built-in/directives.md b/docs/built-in/directives.md index 5a6649d7..f45655a6 100644 --- a/docs/built-in/directives.md +++ b/docs/built-in/directives.md @@ -2,13 +2,13 @@ ## Directives -Blits comes with a few built-in attributes that tap into specific behaviour provided by the framework - also kn ows as _directives_. Most of them can be used in the template on both Elements and Components. +Blits comes with a few built-in attributes that tap into specific behaviour provided by the framework - also known as _directives_. Most of them can be used in the template on both Elements and Components. ### Show-directive -The `show`-attribute allows you to conditionally show and hide Components and Elements. +The `show` attribute allows you to conditionally show and hide Components and Elements. -When passed a _truthy_ value, such as `true` or `1`, the element will be made visible. And when passed a _falsy_ value (`false` or `0`) it will not be visible. +When passed a _truthy_ value, such as `true` or `1`, the element will be made visible. And when passed a _falsey_ value (`false` or `0`) it will not be visible. ```xml diff --git a/docs/components/component_state.md b/docs/components/component_state.md index 515ba1b1..c5fcceb4 100644 --- a/docs/components/component_state.md +++ b/docs/components/component_state.md @@ -47,8 +47,7 @@ For nested objects, you can use _dot notation_ (e.g., `$style.dimensions.w`). In your component's code, you can reference state variables directly within the `this`-scope. For instance, a state variable named `color` can be accessed (and modified) by referencing `this.color`. It's important to note that unlike in the template, you should _not_ use the dollar sign when accessing state variables within the component's code. - -Also remember that there is no need to explicitely reference the `state`-key. Blits automatically maps all state variables directly on the `this`-scope, for easy access. +Also, remember that there is no need to explicitly reference the `state`-key. Blits automatically maps all state variables directly on the `this`-scope, for easy access. The example below gives a full example of defining and using a component's state: diff --git a/docs/components/computed_properties.md b/docs/components/computed_properties.md index e95800c5..cf4e9206 100644 --- a/docs/components/computed_properties.md +++ b/docs/components/computed_properties.md @@ -4,9 +4,8 @@ So far we've learned how to utilize a Component's [internal state](./component_state.md) and [props](./props.md) passed by a parent into a child component. -We've also seen how we can perform simple operations like `Math.max()` or `str.toUpperCase()` directly within an argument of a template on the Component's internal state or passed props . - -However as these operations become more complex it's more clear and more maintainable to abstract these operations into what we call _computed properties_. +We've also seen how we can perform simple operations like `Math.max()` or `str.toUpperCase()` directly within an argument of a template on the Component's internal state or passed props. +However, as these operations become more complex it's more clear and more maintainable to abstract these operations into what we call _computed properties_. Computed properties are a powerful tool for enhancing the readability of your component code. By abstracting complex or frequently used calculations from your template into computed properties, you can make your code more concise and easier to understand. @@ -17,7 +16,7 @@ Within the `computed`-key of the Component configuration object, you can specify A computed property function should always _return_ a value. -In your template, you can reference these computed properties exactly the same as you would with _state_ variable and _props_, by prefixing them with a dollar sign (e.g., `$offset`). +In your template, you can reference these computed properties exactly the same as you would with _state_ variables and _props_, by prefixing them with a dollar sign (e.g., `$offset`). In the rest of your app's code, you can access these computed properties (but not modify them!) using `this.offset`. Note that similar to Component state and props, you do not need to prefix with `computed` to access the computed property. diff --git a/docs/components/methods.md b/docs/components/methods.md index 3662b5a3..a4e4dd32 100644 --- a/docs/components/methods.md +++ b/docs/components/methods.md @@ -2,9 +2,9 @@ ## Methods -Within a Blits component you have quite some freedom where to put specific logic. +Within a Blits component, you have quite some freedom where to put specific logic. -Template related logic can be either be placed directly in a _reactive / interpolated_ attribute or you can move it out to a _computed property_ if the logic is more complex. +Template related logic can be either placed directly in a _reactive / interpolated_ attribute or you can move it out to a _computed property_ if the logic is more complex. Business logic for your App can be placed directly in a _watcher_, a _lifecycle hook_ or an _input handling_ function. @@ -12,7 +12,7 @@ If you notice that you're duplicating logic in these different places, or if you You can reference your Component's methods in the template by using a `$`-sign (for example in the `@loaded`-attribute when your element has a `src` attribute). -In the javascript code of a Component you can reference methods directly on the `this`-scope (i.e. `this.getData()`). Similar as with `internal` state and `props`, there is no need to prefix with `methods`, for easy access. +In the javascript code of a Component, you can reference methods directly on the `this`-scope (i.e. `this.getData()`). Similar to `internal` state and `props`, there is no need to prefix with `methods`, for easy access. ```js export default Blits('Carousel', { diff --git a/docs/components/props.md b/docs/components/props.md index a5f87157..d08f6f4d 100644 --- a/docs/components/props.md +++ b/docs/components/props.md @@ -22,7 +22,7 @@ The simplest way to define props is to just list their names within the `props` Once specified, you can refer to these props inside the template of your component using the `$` sign, similar to how you would reference variables defined within the component's [internal state](./component_state.md) (i.e. ``). -You can als access a prop inside a component's code using `this.color` (without a dollar sign!). And similar to component `state` variables, +You can also access a prop inside a component's code using `this.color` (without a dollar sign!). And similar to component `state` variables, there is no need to specifically reference the `props`-key. Blits automatically maps all props directly on the `this`-scope, for easy access. Since props are used to pass information from a parent to a child, it's important not to attempt to _modify_ props inside your child component. If changes based on the prop from the parent are needed, you should probably use the prop in a so called [computed property](./computed_properties.md). diff --git a/docs/components/user_input.md b/docs/components/user_input.md index de723ed2..f2a63e60 100644 --- a/docs/components/user_input.md +++ b/docs/components/user_input.md @@ -11,7 +11,7 @@ Blits offers an intuitive and straightforward interface to handle key input in C Before diving into the specifics of key handling, it is important to understand the basic concept of _focus_. -In a Blits app, there is always _one_ Component that has the focus. By default this will be the root Application component. +In a Blits app, there is always _one_ Component that has the focus. By default, this will be the root Application component. The component that has focus, is the one that is responsible for handling the user input at that moment. @@ -81,7 +81,7 @@ Blits comes with a default keycode mapping. This mapping is a sensible default t But it's possible that the keycodes and mapping of your target device are slightly or even completely different. -In Blits you can easily configure the key mapping to match your needs. In the `src/index.js` file where we instaniate the App via the `Blits.Launch` function, we can add an extra key, called `keys`, to the _settings object_. +In Blits, you can easily configure the key mapping to match your needs. In the `src/index.js` file where we instantiate the App via the `Blits.Launch` function, we can add an extra key, called `keys`, to the _settings object_. The `keys` item should be an object literal, where you map a `key` or `keyCode` (from the `KeyboardEvent`) to an event name that you can use in your Components. diff --git a/docs/components/watchers.md b/docs/components/watchers.md index 5644615c..7a9c9d27 100644 --- a/docs/components/watchers.md +++ b/docs/components/watchers.md @@ -4,7 +4,7 @@ In some cases, you may want to execute specific actions whenever the value of a state variable, a prop, or a computed property changes. These actions could involve dispatching an event or updating another state variable. -You might be tempted to handle this functionality inside a computed property, but this is not recommended. Computed properties should not have side effects, to prevent the risk of falling into and endless loop. +You might be tempted to handle this functionality inside a computed property, but this is not recommended. Computed properties should not have side effects, to prevent the risk of falling into an endless loop. Instead, Blits allows you to specify **watchers** to trigger functionality when certain variables change. diff --git a/docs/essentials/application_root.md b/docs/essentials/application_root.md index 6a84503b..e29113f2 100644 --- a/docs/essentials/application_root.md +++ b/docs/essentials/application_root.md @@ -6,7 +6,7 @@ Every Blits App starts with a base Application component. Ultimately this Application is a component like any regular Blits component. But it is augmented with some extra functionality. `Blits.Application` is responsible for setting up the listeners for keyhandling for example. -You can only have 1 Application component per App. By default this file is named `App.js` and it is placed in the root of the `src`-folder. +You can only have 1 Application component per App. By default, this file is named `App.js` and it is placed in the root of the `src`-folder. `src/App.js` will look something like this: diff --git a/docs/essentials/components.md b/docs/essentials/components.md index d0301e59..7e72c92b 100644 --- a/docs/essentials/components.md +++ b/docs/essentials/components.md @@ -20,11 +20,11 @@ Let's see how to create a new component and explore the basic anatomy of a compo A new component is created using the `Blits.Component()` function that is exported from the `@lightningjs/blits` package. This function accepts two arguments: -- The first argument is the _name_ of the component. This name will be used in debug log messages, so make sure to choose a unique and descriptive name for your component, such as `Homepage`, `Loader` or `SidebarMenuItem`. +- The first argument is the _name_ of the component. This name will be used in debug log messages, so make sure to choose a unique and descriptive name for your component, such as `Homepage`, `Loader`, or `SidebarMenuItem`. -- The second argument is a _Component configuration object_, represented as an `object literal`. This Component configuration object can contain a predefined set of key-value pairs, that defines how your Component looks and behaves. +- The second argument is a _Component configuration object_, represented as an `object literal`. This Component configuration object can contain a predefined set of key-value pairs, that define how your Component looks and behaves. -Some of the common used Component configuration options include: +Some of the commonly used Component configuration options include: - `template`: to define the template for the component. - `state`: to specify the component instance's internal state. diff --git a/docs/essentials/displaying_images.md b/docs/essentials/displaying_images.md index 1fba249f..cc1e3869 100644 --- a/docs/essentials/displaying_images.md +++ b/docs/essentials/displaying_images.md @@ -25,7 +25,7 @@ For the best performance, it's important to keep your source images as small as You also have the option to _colorize_ an image on the fly. Just add a `color` attribute to the Element with a `src` attribute. You can use a single color, or apply a gradient. -By default all Elements with a `src` attribute get the a solid white background, with the result that the actual colors of the image will be shown. +By default, all Elements with a `src` attribute get a solid white background, with the result that the actual colors of the image will be shown. ```xml `-tag is used define which font family should be used for a certain piece of text. +The `font`-attribute on the ``-tag is used to define which font family should be used for a certain piece of text. When you create a new Blits app using the available [getting started boilerplate](../getting_started/getting_started.md) you'll be able to use the `lato` (Lato regular) and `raleway` (Raleway ExtraBold) fonts out of the box. -But of course you can also use any custom font that you want, to give your App the unique look and feel that fits with the design. +But of course, you can also use any custom font that you want, to give your App the unique look and feel that fits with the design. -Adding is custom font to a Blits App is quite straightforward. First you'll need to place a `.ttf` version of your font in the `public` folder (i.e. `public/fonts/comic-sans.ttf`). +Adding is custom font to a Blits App is quite straightforward. First, you'll need to place a `.ttf` version of your font in the `public` folder (i.e. `public/fonts/comic-sans.ttf`). Then you'll need to register the custom font in the Launch settings of your app (in `src/index.js`). The `fonts`-key in the settings is an `Array` that specifies all available fonts in your App. -Just add a new font object with the necesarry details: +Just add a new font object with the necessary details: ```js fonts: [ diff --git a/docs/essentials/element_attributes.md b/docs/essentials/element_attributes.md index 0226b6ab..6a8599da 100644 --- a/docs/essentials/element_attributes.md +++ b/docs/essentials/element_attributes.md @@ -4,14 +4,14 @@ The core building block of a Blits template is the ``-tag. The Element tag corresponds directly to a node in the Lightning 3 Renderer. You can style and position Elements via _attributes_, much like you would do in plain HTML. -Blits Elements have a specific set of attributes that can be used. The available attributes are loosely modeled after the properties of a Lightning 3 renderer node. In certain cases Blits provides more developer friendly names or accepts a wider range of values, and transparently takes care of the translation into L3 renderer instructions. +Blits Elements have a specific set of attributes that can be used. The available attributes are loosely modeled after the properties of a Lightning 3 renderer node. In certain cases, Blits provides more developer friendly names or accepts a wider range of values, and transparently takes care of the translation into L3 renderer instructions. ### Positioning and Dimensions In order to position and set the dimensions of an Element, the following attributes can be used. - - `x` - the x position of the Element in pixels, relative to it's parent - allows negative values and decimals - - `y` - the y position of the Element in pixels, relative to it's parent - allows negative values and decimals + - `x` - the x position of the Element in pixels, relative to its parent - allows negative values and decimals + - `y` - the y position of the Element in pixels, relative to its parent - allows negative values and decimals - `z` - the z index of the element (optionally `zIndex` can be used as an alias) - `w` - the width of the element in pixels (optionally `width` can be used as an alias) - `h` - the height of the element in pixels (optionally `height` can be used as an alias) @@ -40,9 +40,9 @@ And the percentage specified for `h` and `y` will use the _height_ (`h`) of the ### Colors -By default Elements have a transparent background color. The `color` attribute can be used to give an Element a color. +By default, Elements have a transparent background color. The `color` attribute can be used to give an Element a color. -If you are familiar with Lightning 2: colors have gotten a lot easier with Blits. Under the hood the Lightning 3 renderer still uses the somewhat unfamiliar (but efficient) `0xffc0ffee` syntax. In Blits you can specify colors as you are used to in HTML and CSS. +If you are familiar with Lightning 2: colors have gotten a lot easier with Blits. Under the hood, the Lightning 3 renderer still uses the somewhat unfamiliar (but efficient) `0xffc0ffee` syntax. In Blits, you can specify colors as you are used to in HTML and CSS. Blits accepts the following color formats and makes sure that they are converted in a way the Lightning 3 renderer can understand. @@ -83,9 +83,9 @@ Again, you can use "normal" notation for the colors (like hexadecimal or rgba) a ### Alpha and visibility -The opacity of an Element, can be controlled by setting the `alpha` attribute. This attribute accepts a value between `0` (fully transparent) and `1` (completely visible). +The opacity of an Element can be controlled by setting the `alpha` attribute. This attribute accepts a value between `0` (fully transparent) and `1` (completely visible). -The value of alpha is also being applied recursively to the children of the Element that has its alpha set. If you just want the background color of an Element to be semi-transparent, you should set the alpha channel in the `color` instead of applying the `alpha` attribute. +The value of alpha is also applied recursively to the children of the Element that has its alpha set. If you just want the background color of an Element to be semi-transparent, you should set the alpha channel in the `color` instead of applying the `alpha` attribute. ```xml @@ -107,13 +107,13 @@ The rotation of an Element is also automatically applied to any children down th For scaling an Element the `scale` attribute is used. -This attribute either accepts a single numeric value for scaling evenly accross width and height. Or an _object literal_, if you want to apply a different scaling for the `x` and the `y` axis. +This attribute either accepts a single numeric value for scaling evenly across width and height. Or an _object literal_, if you want to apply a different scaling for the `x` and the `y` axis. The value should be higher than `0` and the default value is `1`, which means no scaling. Any value below `1` will scale _down_ the element and values greater than `1` will scale the element _up_. -Similar to rotation, scale is also applied recursively to children down the tree of the Element that has it's `scale` attribute set. +Similar to rotation, scale is also applied recursively to children down the tree of the Element that has its `scale` attribute set. ```xml @@ -123,13 +123,13 @@ Similar to rotation, scale is also applied recursively to children down the tree ### Mounting point -For advanced positioning the `mount` attribute can come in handy. By default when you set the `x` and `y` position of an Element, the _top-left_ corner will be set to that position. But in some cases you may want to align the position starting at a different corner, or even any arbitrary point in between. +For advanced positioning, the `mount` attribute can come in handy. By default when you set the `x` and `y` position of an Element, the _top-left_ corner will be set to that position. But in some cases, you may want to align the position starting at a different corner, or even any arbitrary point in between. The `mount` attribute accepts an _object literal_ that allows you to precisely control the mount position on the _x-axis_ and the mount position on the _y-axis_. The default value is `{x: 0, y: 0}`, which refers to the _top-left_ corner. In order to align the position starting at the _bottom-right_ corner, we would set `mount` to `{x: 1, y: 1}` and `{x: 0.5, y: 0.5}` would align the position at the _center_ of the Element. -If you omit either the `x` or the `y` key from the _object literal_, it's value will default to `0`. +If you omit either the `x` or the `y` key from the _object literal_, its value will default to `0`. In the case where the `x` and `y` values are the same (i.e. centering with `{x: 0.5, y: 0.5}`), you can also just supply a single value (`mount="0.5"`) instead of the object literal notation. @@ -143,7 +143,7 @@ In the case where the `x` and `y` values are the same (i.e. centering with `{x: The pivot point of an Element comes into play when it's rotated or scaled. The pivot point defaults to the _center_ of the Element, which means that when setting `rotation` it rotates around the middle. And when the Element is scaled it scales from the center out. -But sometimes you may want rotate around the left corner, or scale from the right side out. This can be controlled by adding the `pivot` attribute to the Element and, similar to the `mount` attribute, specify an _object literal_ with a `x` and a `y` key. +But sometimes you may want to rotate around the left corner, or scale from the right side out. This can be controlled by adding the `pivot` attribute to the Element and, similar to the `mount` attribute, specify an _object literal_ with an `x` and a `y` key. Both `y` and `x` values should be anything between `0` and `1`, where `{x: 0, y: 0}` sets the pivot point to the _top-left_ corner and `{x: 1, y: 1}` refers to the _bottom-right_ corner. The default pivot value is `{x: 0.5, y: 0.5}` (i.e. the center) and if you omit `x` or `y` in your pivot object, it will default to `0.5`. diff --git a/docs/essentials/template_syntax.md b/docs/essentials/template_syntax.md index 73ca873a..1fa15dbd 100644 --- a/docs/essentials/template_syntax.md +++ b/docs/essentials/template_syntax.md @@ -4,11 +4,11 @@ Blits uses an easy-to-read _XML-style_ template syntax. The syntax is inspired by frameworks like VueJS, so if you are familiar with Vue, you will probably recognize certain concepts. -The `template` key in the _Component configuration object_ is used to specify a string with this XML-like template structure. Templates can often span multiple lines. In those cases it's advisable to use `template literals` (enclosed by backticks). +The `template` key in the _Component configuration object_ is used to specify a string with this XML-like template structure. Templates can often span multiple lines. In those cases, it's advisable to use `template literals` (enclosed by backticks). Similar to HTML you can use arguments and nested tags. Self-closing tags and HTML-style comments are also supported in Blits templates. -The default tag that can be used a template is the `` tag. The Element tag corresponds to a node in the Lightning 3 renderer. +The default tag that can be used in templates is the `` tag. The Element tag corresponds to a node in the Lightning 3 renderer. For each element, there is a set of predefined render properties, such as `x`, `y`, `w`, `color` that define how the element looks and where it is positioned. Detailed information on all the attributes supported by the `` tag can be found [here](./element_attributes.md). @@ -40,13 +40,13 @@ on screen. For that you will need to use _reactive_ arguments. ### Reactive arguments If you look at the template example above you'll notice that certain arguments are prefixed with a colon sign (`:`). Prefixing an argument -with a colon makes it not only dynamic, but also _reactive_. +with a colon makes it not only dynamic but also _reactive_. Reactive arguments are set with the initial state value when your component first renders, exactly as a dynamic argument does. The difference is that a _re-render_ of (a portion of) the template will be triggered whenever the referenced value in your Component's internal state changes. -This concept of _reactive data binding_ eliminates the need for manual template patching, and allows for a declarative way of programming. +This concept of _reactive data binding_ eliminates the need for manual template patching and allows for a declarative way of programming. Reactive arguments also support _interpolation_. This enables the use of simple JavaScript instructions, such as ternary conditions or basic String and Math manipulations, right inside your template arguments. @@ -54,15 +54,15 @@ For more complex logic, it's recommended to abstract this into a [Component meth ## Abstracting template portions to custom components -As your template grows in complexity, you may want to orgnize your codebase with custom components, abstracting a complex template into smaller, resuable pieces. +As your template grows in complexity, you may want to organize your codebase with custom components, abstracting a complex template into smaller, reusable pieces. -When you've abstrated a portion of a template into a separate component, a _Menu_ component for example, you'll first need to `import` the file that contains the Menu component. +When you've abstracted a portion of a template into a separate component, a _Menu_ component for example, you'll first need to `import` the file that contains the Menu component. -Next you have to _register_ the imported custom component. The `components`-key in the _configuration object_ is used for this. +Next, you have to _register_ the imported custom component. The `components`-key in the _configuration object_ is used for this. The `components` key is an _object literal_, where the value is the reference to the custom Blits component and the key will correspond with the _tag_ that can be used in the template to insert the component. -Once this is done, the tag (`` for example) is available for use in your component's template. You can use the component tag as many times as you want. For each tag a new Component instance will be created. +Once this is done, the tag (`` for example) is available for use in your component's template. You can use the component tag as many times as you want. For each tag, a new Component instance will be created. The example below shows how to use a custom `Menu` and `Button` (aliased to `MyButton`) component inside a template. diff --git a/docs/getting_started/file_structure.md b/docs/getting_started/file_structure.md index 0b500d52..c0fa4218 100644 --- a/docs/getting_started/file_structure.md +++ b/docs/getting_started/file_structure.md @@ -8,23 +8,23 @@ Let's review the basic file structure, and take a closer look at the important o ### package.json -In the root of your newly created app you will obviously find a `package.json` with all the necessary (dev) dependencies. +In the root of your newly created app, you will obviously find a `package.json` with all the necessary (dev) dependencies. In order to build a Blits based Lightning 3 app, all you need is `@lightningjs/blits` as a dependency. Blits will take care of hooking up the Lightning 3 renderer for you behind the scenes. -Feel free to install and import any custom library that your App may need. But always be mindful of the size and impact an external dependency may have - especially when developing for low powered devices (as if often the case with Lightning apps). +Feel free to install and import any custom library that your App may need. But always be mindful of the size and impact an external dependency may have - especially when developing for low powered devices (as is often the case with Lightning apps). ### index.html -You will also find an `index.html` in the root of your project. This is where the browser will be pointed to in order to launch your Blits App. +You will also find an `index.html` at the root of your project. This is where the browser will be pointed to, in order to launch your Blits App. -If you inspect the source you will see some minimal html. The essential parts of the html are the `
` where the canvas will be injected into, and the `