Components are pieces of HTML, CSS, and JS that can be added to posts or other components. They allow for customization by giving users custom fields to input data into. This post will discuss all parts of a component.
Title
The title is required, and must be 4 to 20 characters long.
Description
The description is required, and must be 20 to 255 characters. It appears in searches, so it should describe the purpose it serves, and any benefits and limits to using it. For instance, if you were creating a bar graph, it would be useful to mention if it allows for certain customizations such as colors of the bars, and if there is a limit on the number of bar that may be added.
Details
The details section is optional. It displays after a component has been selected, and above the data that is requested from the user. Relevant info about how the component works, and customization options go here. Continuing with the bar graph example, you could write that if a bar color is not specified, blue is used, and that for customization, the bars have the class 'bar' that may be edited by adding a <style> element to their post.
Line breaks are conserved in details, so you can separate topics into different parts.
User-Entered Data
User-Entered Data is also optional. When used, each field in the row is required. The fields are:
The different data types are:
All user-entered data becomes a part of an object for your code. Each component has a unique id, and this id is embedded into the variable of this user-entered data object. If the component's id is "iOK0H", the variable for your component is "dataiOK0H" (will be used as an example throughout this doc). This is done to prevent collisions with other components, and it is recommended that "dataiOK0H" or "iOK0H" be used in your variables, html ids, and class names.
Multiple Instances of a Component in a Post
To allow for multiple instances of your component to be added to one post, every instance of "dataiOK0H" has the localId of your component in that post inserted into the middle. Use "dataiOK0H" in ids, classes, and variables to make it unique. If you wish for all instances to be customized at the same time, use "iOK0H" in the class name. This allows you to have a class name unique to your component, but not unique to that instance.
When a component is added to a post, it is given a localId (starts at 0 and auto-increments). This localId is visible in the code editor, so the user can use it if necessary (described later). If your component is the third added, it will have a localId of 2. Before your code is run, all instances of "dataiOK0H" will be replaced with "data2iOK0H".
Style customization of components
You can let users custom style your components by mentioning class names and ids in the Detail section of the component page. If you give classes unique names (by using "dataiOK0H" in them), you'll have to tell users that they have to insert the localId into the class name. So if your class is named "dataiOK0H-wrapper", you can tell users to customize it by using the class "data{localId}iOK0H-wrapper".
Approval of components
Unlike posts, components cannot be used or seen in search results until they are approved. This is to prevent malicious code from becoming widespread before being deleted, and potentially diminishing the UX for users visiting posts that had a component deleted retroactively. To ensure your component is approved, refrain from using external JS files that could be changed maliciously in the future. Only repositories on unpkg.com - like jQuery, React, and other npm packages - will be allowed. Aside from common social media, all other script urls are blocked by our Content-Security-Policy. If you have another site you'd like to include scripts from, please submit feedback (in the dropdown menu in the upper right hand corner when you log in).
Add the following to enable react:
<script src='https://unpkg.com/react/umd/react.production.min.js'></script> <script src='https://unpkg.com/react-dom/umd/react-dom.production.min.js'></script>
When testing, use the following:
<script src='https://unpkg.com/react/umd/react.development.js'></script> <script src='https://unpkg.com/react-dom/umd/react-dom.development.js'></script>
Example of React in a component
Versioning
When a new version of a component is approved, changes will not automatically propagate to posts using that component. Posts will have to be updated individually. This was done because updated components may no longer fit in as well with the post, and can change user-entered data formatting.
Coding details
Caveats
Single Page App with Server Side Rendering
Because pages are loaded two different ways, you must plan accordingly. If you need to wait for the page to load to examine or manipulate elements, you will have to check to see if the document has loaded already before adding a window load event listener:
if (document.readyState !== 'complete') { this.listenerSet = true; // when using React window.addEventListener('load', this.loadData); } else { this.listenerSet = false; // when using React this.loadData(); }
For removing the listener in React:
componentWillUnmount() { if (this.listenerSet) { window.removeEventListener('load', this.loadData); } }
Without React:
if (document.readyState !== 'complete') { window.addEventListener('beforeunload', function (event) { window.removeEventListener('load', this.loadData); }); }
