From da736ff33c2fa18fd42b89d83de330b29612e7d0 Mon Sep 17 00:00:00 2001 From: aFuzzyBear Date: Thu, 17 Mar 2022 12:26:01 +0000 Subject: [PATCH 1/2] Updating the Induction folder - Includes Sarahs late night edits - All the recent changes to the documents in here --- docs/induction/events.md | 69 ---------- docs/induction/getting-started.md | 186 -------------------------- docs/induction/interactivity.md | 109 ++++++++++++--- docs/induction/introduction.md | 58 +++++--- docs/induction/methods.md | 6 +- docs/induction/my-first-components.md | 180 +++++++++++++++++++++++++ docs/induction/observations.md | 52 ++++--- docs/induction/overview.md | 72 +++++----- docs/induction/polymorphism.md | 155 +++++++++++---------- docs/induction/web-apis.md | 39 ++++++ 10 files changed, 511 insertions(+), 415 deletions(-) delete mode 100644 docs/induction/events.md delete mode 100644 docs/induction/getting-started.md create mode 100644 docs/induction/my-first-components.md create mode 100644 docs/induction/web-apis.md diff --git a/docs/induction/events.md b/docs/induction/events.md deleted file mode 100644 index 43f915b..0000000 --- a/docs/induction/events.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: "XElement Event Handlers" -api_title: "@events" -meta_title: "XElement-@events" -description: "Overview on XElement's Event Handlers, gain a better insight on how XElement lets you use any* Event behaviors that you wish your XElement to react to" -page_number: 3 -next_page: "/docs/api/methods/animate" -previous_page: "/docs/api/methods/observers" ---- - -# XElement Events Handlers - -XElement is able to react to any `Event` possible. - -The vast majority of `Event`'s are able to be subscribed to by using the `@` decorator followed by the 'name' of the event you wish the payload to execute on. - -Certain events only work on certain parts of the document. - -Given that we wont restrict you from writing out all the 180+ different events known, not including the synthetic ones that can be use. We suggest you use the `Events` with some diligence. - -Any non applicable events themselves will fail silently. - -It is best to only apply events outside of any [`customEvent`](https://developer.mozilla.org/en-US/docs/Web/Events/Creating_and_triggering_events) that might be declared in the [`@do`](/docs/api/methods/do) method, to the right element that you are consuming. - -This would help you react to the right events on the element without to much difficulty. - -For a full list of Events that are available and which elements they are fired on, please visit [MDN's Event Reference guide](https://developer.mozilla.org/en-US/docs/Web/Events) - -It works by applying the relevant `add` or `removeEventListeners` in JavaScript over using inline html [`GlobalEventTargets`](https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers). - -We expose some options on customizing the nature of the Event Handler itself, providing you with control over the Event [bubbling and capturing](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Building_blocks/Events#event_bubbling_and_capture) phases of the event action. - - -## DOM Event Interfaces - -The browser provides many types of DOM specific `Event` interfaces. These allow you to access and interact with the browser making it provide additional functionality to the user. - -There is a whole raft of standardized browser API's and their subsequent `Event` interfaces that you can freely utilize with `XElement`. - -Interacting with events that are located on the `window` or `document` it is as easy to use as it is calling them. - -```astro - - -``` - -The above example demonstrates using two different types of XElements the first being a standard html `` and the other, an interactive ` - - 0 - - - -``` -### `@` decorators -To start enhancing our component, we use one of the many `@` decorators recognized by `XElement` to specify what type of action we wish it to perform. - -`@do` is a common instruction to "do" something. And in our buttons, we will use `@click` to describe an `onClick` action. - -### `store` - -XElement also provides a `store`: a special non-persistent data object that is available to all `XElement` components. This lets you *store* your data and allows it to be used elsewhere on the page. We are keeping track of our counter's `count` in this store object. - -### `id` - -Giving an `id` to an XElment, as we have done with ``, allows us to target that element from elsewhere in the component tree. In this example, we can update the counter's displayed count by referencing, then changing the `` element's `textContent`. - -### Summary -In this example, what we are asking our parent element, the `` to **do** is initialise the `store` with a `count` of `0`. - -And, we are telling the buttons that when they receive a `click` event, they should increment or decrement the `store.count` and update the `display.textContent`. - -This `` example renders the following HTML to the page: -```html - - - 0 - - - -``` - -## Next Steps: - -## API reference - -Visit the API reference doc to find all the `XElement` API reference points and information on how to use each one correctly. - -## Guides -Explore our guides to see common/popular ways to use XElement in your project. - -## Tutorials -Learn about using XElement by building some sample web components in an example site. - - diff --git a/docs/induction/interactivity.md b/docs/induction/interactivity.md index 7f0ef9d..b1c9bd4 100644 --- a/docs/induction/interactivity.md +++ b/docs/induction/interactivity.md @@ -1,26 +1,101 @@ +# Client Side Interactivity + +Client side interactivity (using JS on the browser) in Astro can be achieved in a number of ways. + +Let's see how this is currently achieved in Astro, and how XElement gives you an additional tool to make applying client-side interactions easier. + +## Astro & UI Frameworks + +Astro lets you create statically generated content on the server with islands of interactivity using a mix of UI frameworks. + +This process is unique among current website frameworks, as it lets you apply, for example, a React component alongside a Vue component and even alongside a Svelte component, on a single page. + +```astro +--- +import MyReactComp from './MyReactComp.jsx' +import MyVueComp from './MyVueComp.vue' +import MySvelteComp from './MySvelteComp.svelte' +import MySolidComp from './MySolidComp.tsx' --- -title: - page : "Client Side Interactivity Explained" - meta : "Client Side Interactivity with XElement Explained" -description: - page: "A brief explanation over how XElement provides it's Client sided interactivity. Here we discuss some the methods that we used to deliver XElement" - meta: "A brief explanation over XElement's Client side Interactivity and how it is achieved " -page: - number : - next : "" - previous : "" +
+ + + + +
+``` +This example demonstrates multiple different UI Frameworks, each independently sending JavaScript to the client at different times, in a single `.astro` component file. + +> Read more about Astro's [partial hydration](https://docs.astro.build/en/core-concepts/partial-hydration/) of [framework UI components](https://docs.astro.build/en/core-concepts/framework-components/). + +This helps developers reuse existing UI components, tools and experience from other projects within Astro. But, it does not achieve client-side interactivity natively in Astro. + +## JS in Astro + +The developer authoring experience in Astro is much better and more powerful than other meta-frameworks that exist. Astro is able to avoid shipping parts of our UI frameworks to the client, reducing the JavaScript load and improving performance. + +Astro can also use a ` +``` + +XElement makes this experience one step better, easier, friendlier and simpler for developers using Astro. + +## Interactivity with XElement + +XElement takes writing your own client-side code in Astro to a whole new level of experience. + +XElement enhances existing HTML elements, using either **JavaScript** or **TypeScript**, all without the need for any UI framework or client-side renderer. + +Let's see how we can recreate the above `.astro` file's functionality with XElement: + +```astro +--- +import XElement from 'astro-xelement' + +const { Div , Button } = XElement + +const answer = await fetch('deepthought.ai') +--- +
console.log(element)}> +

The answer is : {answer}

+ +
+``` + +Each XElement is rendered at build time, with a total cost of 98bytes per element of XElement boilerplate, perhaps one of the fastest fast time to interactivity among UI frameworks! + +All client-side code is packaged as independent, async `