diff options
Diffstat (limited to 'files/pt-pt/mdn/structures')
6 files changed, 639 insertions, 0 deletions
diff --git a/files/pt-pt/mdn/structures/api_references/barras_laterais_de_referencia_da_api/index.html b/files/pt-pt/mdn/structures/api_references/barras_laterais_de_referencia_da_api/index.html new file mode 100644 index 0000000000..8e28e33556 --- /dev/null +++ b/files/pt-pt/mdn/structures/api_references/barras_laterais_de_referencia_da_api/index.html @@ -0,0 +1,109 @@ +--- +title: Barras laterais de referência da API +slug: MDN/Structures/API_references/Barras_laterais_de_referencia_da_API +tags: + - API + - Guía + - Referencia + - barras laterais + - groupdata + - onboarding +translation_of: MDN/Structures/API_references/API_reference_sidebars +--- +<div>{{MDNSidebar}}</div><p class="summary">Pode incluir uma barra lateral personalizada nas páginas de referência da API para exibir as hiperligações para as 'Interfaces' relacionadas, tutoriais, e outros recursos relevantes, apenas para essa API. Este artigo explica como.</p> + +<h2 id="O_que_precisa_de_fazer">O que precisa de fazer?</h2> + +<p>You need to take the following three steps to create your API sidebar:</p> + +<ol> + <li>Create your API reference pages.</li> + <li>Add an entry for your particular API into the <a href="https://github.com/mdn/kumascript">KumaScript repo</a>'s GroupData.json data file.</li> + <li>Use the \{{APIRef}} macro to insert the sidebar into each page you want to display it on.</li> +</ol> + +<p>Let's run through each of these steps in turn. The example we'll refer to in this article is the <a href="/en-US/docs/Web/API/Fetch_API">Fetch API</a>.</p> + +<h3 id="Criar_páginas_de_referência_da_sua_API">Criar páginas de referência da sua API</h3> + +<p>Before you can add sidebars to your pages, you'll need to create the pages themselves (see our <a href="/en-US/docs/MDN/Contribute/Structures/API_references/What_does_an_API_reference_need">What does an API reference need?</a> guide for more guidance).</p> + +<h3 id="Adicionar_uma_entrada_para_GroupData.json">Adicionar uma entrada para GroupData.json</h3> + +<p>The <a href="https://github.com/mdn/kumascript/blob/master/macros/GroupData.json">GroupData.json</a> file holds all the data relating to what links should appear in API reference sidebars. When invoked, the \{{APIRef}} macro takes an API name given to it as a parameter, looks up that name in GroupData.json, builds a sidebar as appropriate, and inserts it in the page.</p> + +<p>To add an entry to GroupData.json, you need to:</p> + +<ol> + <li>Make sure you have a <a href="https://github.com/">GitHub</a> account.</li> + <li>Fork the KumaScript repo, create a new branch to contain your changes, and clone the repo locally.</li> + <li>Checkout your new branch before starting work, and make sure you push changes to it after finishing.</li> + <li>Create a pull request so that the MDN team can review your work, and ask for changes if necessary.</li> +</ol> + +<p>If you need help with using GitHub, a more detailed guide can be found at our <a href="/en-US/docs/MDN/Contribute/Structures/Compatibility_tables#The_new_way_The_browser_compat_data_repo_and_dynamic_tables">compatibility tables guide</a>.</p> + +<p>The <a href="https://github.com/mdn/kumascript/blob/master/macros/GroupData.json">GroupData.json</a> file can be found inside the macros directory of the KumaScript repo. Looking at it, you'll see a giant JSON structure, with each API having its own member. The name is the API name, and the value is an object containing several submembers defining the sidebar links to be created.</p> + +<p>For example, look at the <a href="/en-US/docs/Web/API/Fetch_API">Fetch API</a> page on MDN. The corresponding entry in GroupData.json looks like this:</p> + +<pre class="brush: json notranslate">"Fetch API": { + "overview": [ "Fetch API"], + "interfaces": [ "Body", + "Headers", + "Request", + "Response", + "FetchController", + "FetchObserver", + "FetchSignal", + "ObserverCallback" ], + "methods": [ "WindowOrWorkerGlobalScope.fetch()" ], + "properties": [], + "events": [] +},</pre> + +<p>As you can see, we've used "Fetch API" for the name, and inside the object value we include a number of submembers.</p> + +<h4 id="Submembers_to_include_inside_a_GroupData_entry">Submembers to include inside a GroupData entry</h4> + +<p>This section lists all the submembers you could include in a GroupData entry.</p> + +<p>Note that Most of the values included inside the listed submembers equate to both the link text, and slugs appended to the end of the main API index page — https://developer.mozilla.org/<em><language-code></em>/docs/Web/API — to create the final URL for the displayed link. So for example, "Body" will result in a link being created like so in the <em>en-US</em> locale:</p> + +<pre class="brush: html notranslate"><li><a href="https://developer.mozilla.org/en-US/docs/Web/API">Body</a></li></pre> + +<p>There are a few exceptions. For example the "guides" submember contains one or more sets of link information (title and slug) that defines links to associated guides/tutorials. In this case the slugs are appended to the end of the MDN docs root — https://developer.mozilla.org/<em><language-code></em>/docs — allowing an article anywhere on MDN to be included.</p> + +<p>Here are the available members. In each case, an example is included that assumes that the local is <em>en-US</em>.</p> + +<ol> + <li> + <p>"overview" — the value is an array, inside of which you include the slug of the API overview page, if there is one. "Fetch API" results in a link being made to <a href="/en-US/docs/Web/API/Fetch_API">https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API</a>.</p> + </li> + <li> + <p>"interfaces" — the value is an array in which you should list all of the interfaces that form part of that API. "Body" results in a link being made to <a href="/en-US/docs/Web/API/Body">https://developer.mozilla.org/en-US/docs/Web/API/Body</a>.</p> + </li> + <li> + <p>"methods" — the value is an array that should contain all of the methods associated with the API. This can include methods that are members of interfaces defined in the API spec, and methods the API defines on other interfaces. If there are a huge number of methods, you might want to consider only listing the most popular ones, or putting them first in the list. "WindowOrWorkerGlobalScope.fetch()" results in a link being made to <a href="/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch">https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch</a>.</p> + </li> + <li> + <p>"properties" — the value is an array that should contain all of the properties associated with the API. This can include properties that are members of interfaces defined in the API spec, and properties the API defines on other interfaces. If there are a huge number of properties, you might want to consider only listing the most popular ones, or putting them first in the list. "Headers.append" results in a link being made to <a href="/en-US/docs/Web/API/Headers/append">https://developer.mozilla.org/en-US/docs/Web/API/Headers/append</a>.</p> + </li> + <li> + <p>"events" — the value is an array that should contain all of the events associated with the API, defined in the API spec, or elsewhere. If there are a huge number of events, you might want to consider only listing the most popular ones, or putting them first in the list. "animationstart" results in a link being made to <a href="/en-US/docs/Web/Events/animationstart">https://developer.mozilla.org/en-US/docs/Web/Events/animationstart</a>.</p> + </li> + <li> + <p>"guides" — the value is an array containing one or more objects that define links to guides explain how to use the API. Each object contains two submembers — "url", which contains the partial URL pointing to the guide article, and "title", which defines the link test for the link. As an example, the following object:</p> + + <pre class="brush: json notranslate">{ "url": "/docs/Web/API/Detecting_device_orientation", +"title": "Detecting device orientation" }</pre> + + <p>Creates a link with the title "Detecting device orientation", which points to <a href="/en-US/docs/Web/API/Detecting_device_orientation">https://developer.mozilla.org/en-US/docs/Web/API/Detecting_device_orientation</a>.</p> + </li> +</ol> + +<h3 id="Inserir_a_barra_lateral_nas_suas_páginas">Inserir a barra lateral nas suas páginas</h3> + +<p>Once you've added an entry for your API into GroupData.json, submitted it as a pull request and had the change accepted into the main repo, you can include it in your API reference pages using the \{{APIRef}} macro, which takes the name you used for your API in GroupData as a parameter. As an example, the <a href="/en-US/docs/Web/API/WebVR_API">WebVR API</a>'s sidebar is included in its pages with the following:</p> + +<p>\{{APIRef("WebVR API")}}</p> diff --git a/files/pt-pt/mdn/structures/api_references/index.html b/files/pt-pt/mdn/structures/api_references/index.html new file mode 100644 index 0000000000..a7a7b21004 --- /dev/null +++ b/files/pt-pt/mdn/structures/api_references/index.html @@ -0,0 +1,58 @@ +--- +title: API references +slug: MDN/Structures/API_references +tags: + - API + - Contribute + - Guide + - NeedsTranslation + - Reference + - TopicStub +translation_of: MDN/Structures/API_references +--- +<div>{{MDNSidebar}}</div><div>{{IncludeSubnav("/en-US/docs/MDN")}}</div> + +<p class="summary">Client-side JavaScript APIs form a large part of the technology available on the web, and MDN includes extensive reference material to explain what functionality is available in these APIs, and how to use it. In this set of guides we explain how to create API reference material on MDN.</p> + +<h2 id="Prerequisite_resources">Prerequisite resources</h2> + +<p>Before starting to document an API, you should have available:</p> + +<ol> + <li>The latest spec: Whether it is a W3C Recommendation or an early editor's draft, you should refer to the latest available draft of the spec that covers (or specs that cover) that API. To find it, you can usually do a Web search. The latest version will often be linked to from all versions of the spec, listed under "latest draft" or similar.</li> + <li>The latest modern web browsers: These should be experimental/alpha builds such as <a href="https://nightly.mozilla.org/">Firefox Nightly</a>/<a href="https://www.google.com/intl/en/chrome/browser/canary.html">Chrome Canary</a> that are more likely to support the features you are documenting. This is especially pertinent if you are documenting a nascent/experimental API.</li> + <li>Demos/blog posts/other info: Find as much info as you can. It is useful to start by spending time familiarizing yourself with how the API works — learn what the main interfaces/properties/methods are, what the primary use cases are, and how to write simple functionality with it.</li> + <li>Useful engineering contacts: It is really useful to find yourself a friendly engineering contact to ask questions about the spec, someone who is involved in the standardization of the API, or its implementation in a browser. Good places to find them are: + <ul> + <li>Your internal company address book, if you work for a relevant company.</li> + <li>A public mailing list that is involved in the discussion of that API, such as Mozilla's <a href="https://lists.mozilla.org/listinfo/dev-platform">dev-platform</a> or <a href="https://lists.mozilla.org/listinfo/dev-webapi">dev-webapi</a> lists, or a W3C list like <a href="https://lists.w3.org/Archives/Public/public-webapps/">public-webapps</a>.</li> + <li>The spec itself. For example, the <a href="https://webaudio.github.io/web-audio-api/">Web Audio API spec</a> lists the authors and their contact details at the top.</li> + </ul> + </li> +</ol> + +<h2 id="High_level_structure">High level structure</h2> + +<dl> + <dt><a href="/en-US/docs/MDN/Contribute/Structures/API_references/What_does_an_API_reference_need">What does an API reference need?</a></dt> + <dd>This article explains what pages are required for a complete API reference.</dd> + <dt><a href="/en-US/docs/MDN/Contribute/Structures/Page_types">Page types</a></dt> + <dd>There are a number of types of pages that are used repeatedly on MDN. This article describes these page types, their purpose, and gives examples of each and templates to use when creating a new page.</dd> +</dl> + +<h2 id="Individual_page_features">Individual page features</h2> + +<p>These articles explain how to create the individual page features required for API reference pages.</p> + +<dl> + <dt><a href="/en-US/docs/MDN/Contribute/Structures/API_references/API_reference_sidebars">API reference sidebars</a></dt> + <dd>When including a sidebar on your MDN API reference articles, you are able to customize it so that it displays links to related Interfaces, tutorials, and other resources relevant just to that API. This article explains how.</dd> + <dt><a href="/en-US/docs/MDN/Contribute/Structures/Syntax_sections">Syntax sections</a></dt> + <dd>The syntax section of an MDN reference page contains a syntax box defining the exact syntax that a feature has (e.g. what parameters can it accept, which ones are optional?) This article explains how to write syntax boxes for refererence articles.</dd> + <dt><a href="/en-US/docs/MDN/Contribute/Structures/Code_examples">Code examples</a></dt> + <dd>On MDN, you'll see numerous code examples inserted throughout the pages to demonstrate usage of web platform features. This article discusses the different mechanisms available for adding code examples to pages, along with which ones you should use and when.</dd> + <dt><a href="/en-US/docs/MDN/Contribute/Structures/Specification_tables">Specification tables</a></dt> + <dd>Every reference page on MDN should provide information about the specification or specifications in which that API or technology was defined. This article demonstrates what these tables look like and explains how to construct them.</dd> + <dt><a href="/en-US/docs/MDN/Contribute/Structures/Compatibility_tables">Compatibility tables</a></dt> + <dd>MDN has a standard format for compatibility tables for our open web documentation; that is, documentation of technologies such as the DOM, HTML, CSS, JavaScript, SVG, and so forth, that are shared across all browsers. This article covers how to use our features to add compatibility data to MDN pages.</dd> +</dl> diff --git a/files/pt-pt/mdn/structures/api_references/o_que_e_que_uma_referencia_de_api_precisa/index.html b/files/pt-pt/mdn/structures/api_references/o_que_e_que_uma_referencia_de_api_precisa/index.html new file mode 100644 index 0000000000..986791e813 --- /dev/null +++ b/files/pt-pt/mdn/structures/api_references/o_que_e_que_uma_referencia_de_api_precisa/index.html @@ -0,0 +1,162 @@ +--- +title: O que é que uma referência de API precisa? +slug: MDN/Structures/API_references/O_que_e_que_uma_referencia_de_API_precisa +translation_of: MDN/Structures/API_references/What_does_an_API_reference_need +--- +<div>{{MDNSidebar}}</div><p class="summary">Este artigo explica quais as páginas que são necessárias para uma referência completa da API .</p> + +<div class="note"> +<p><strong>Nota</strong>: It is a good idea to create the list of documents you need to write or update when you are working on an API reference, then check them off as you complete them.</p> +</div> + +<h2 id="API_pages_at_a_glance">API pages at a glance</h2> + +<p>An API reference will generally contain the following pages. You can find more details of what each page contains, examples, and templates, in our <a href="/en-US/docs/MDN/Contribute/Structures/Page_types">Page types</a> article.</p> + +<ol> + <li>Overview page</li> + <li>Interface pages</li> + <li>Constructor pages</li> + <li>Method pages</li> + <li>Property pages (including event handlers properties)</li> + <li>Event pages</li> + <li>Concept/guide pages</li> + <li>Examples</li> +</ol> + +<div class="note"> +<p><strong>Nota</strong>: We'll be referring to the <a href="/en-US/docs/Web/API/Web_Audio_API">Web Audio API</a> for examples in this article.</p> +</div> + +<div class="note"> +<p><strong>Nota</strong>: To create a page as specified below, the easiest way is to go to the parent page you want it to hang off, and choose <em>Cog icon > New sub-article</em>. If you haven't got this option available on your MDN interface, you'll need to request this privilege (ask at <code>mdn-admins@mozilla.org</code>), or ask another MDN contributor to create them for you.</p> +</div> + +<h3 id="Página_de_sinopse">Página de sinopse</h3> + +<p>A single API overview page is used to describe the role of the API, its top-level interfaces, related features contained in other interfaces, and other high level details. Its name and slug should be the name of the API plus "API" on the end. It is placed at the top level of the API reference, as a child of <a href="/en-US/docs/Web/API">https://developer.mozilla.org/en-US/docs/Web/API</a>.</p> + +<p>Example:</p> + +<ul> + <li>Title: <em>Web Audio API</em></li> + <li>Slug: <em>Web_Audio_API</em></li> + <li>URL: <a href="https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API">https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API</a></li> +</ul> + +<h3 id="Páginas_da_interface">Páginas da interface</h3> + +<p>Each interface will have its own page too, describing the purpose of the interface, listing any members (constructors, methods, properties, etc. it contains), and showing what browsers it is compatible with. A page's name and slug should be the name of the interface, exactly as written in the spec. Each page is placed at the top level of the API reference, as a child of <a href="/en-US/docs/Web/API">https://developer.mozilla.org/en-US/docs/Web/API</a>.</p> + +<p>Exemplos:</p> + +<ul> + <li>Title: <em>AudioContext</em></li> + <li>Slug: <em>AudioContext</em></li> + <li>URL: <a href="https://developer.mozilla.org/en-US/docs/Web/API/AudioContext">https://developer.mozilla.org/en-US/docs/Web/API/AudioContext</a></li> +</ul> + +<ul> + <li>Title: <em>AudioNode</em></li> + <li>Slug: <em>AudioNode</em></li> + <li>URL: <a href="https://developer.mozilla.org/en-US/docs/Web/API/AudioNode">https://developer.mozilla.org/en-US/docs/Web/API/AudioNode</a></li> +</ul> + +<div class="note"> +<p><strong>Nota:</strong> We document every member appearing in the interface. You should bear the following rules in mind:</p> + +<ul> + <li>We document methods defined on the <u>prototype</u> of an object implementing this interface (instance methods), and methods defined on the actual class itself (static methods). On the rare occasions that they both exist on the same interface, you should list them in separate sections on the page (Static methods/Instance methods). Usually only instance methods exist, in which case you can put these under the title "Methods".</li> + <li>We do not document inherited properties and methods of the interface: they are listed on the respective parent interface. We do hint at their existence though.</li> + <li>We do document properties and methods defined in mixins, though we use the mixin name as interface name. (This is not optimal as the mixin name will not appear in the console, but it prevents the duplication of documentation. We may revisit this in the future.)</li> + <li>Special methods like the stringfier (<code>toString()</code>) and the jsonizier (<code>toJSON()</code>) are also listed if they do exist.</li> + <li>Named constructors (like <code>Image()</code> for {{domxref("HTMLImageElement")}} ) are also listed, if relevant.</li> +</ul> +</div> + +<h3 id="Páginas_de_constructor">Páginas de <em>constructor</em></h3> + +<p>Each interface has 0 or 1 constructors, documented on a subpage of the interface's page. It describes the purpose of the constructor and shows what its syntax looks like, usage examples, browser compatibility information, etc. Its slug is the name of the constructor, which is exactly the same as the interface name, and the title is interface name, dot, constructor name, then parentheses on the end.</p> + +<p>Example:</p> + +<ul> + <li>Title: <em>AudioContext.AudioContext()</em></li> + <li>Slug: <em>AudioContext</em></li> + <li>URL: <a href="https://developer.mozilla.org/en-US/docs/Web/API/AudioContext/AudioContext">https://developer.mozilla.org/en-US/docs/Web/API/AudioContext/AudioContext</a></li> +</ul> + +<h3 id="Páginas_de_propriedade">Páginas de propriedade</h3> + +<p>Each interface has zero or more properties, documented on subpages of the interface's page. each page describes the purpose of the property and shows what its syntax looks like, usage examples, browser compatibility information, etc. Its slug is the name of the property, and the title is interface name, dot, then property name.</p> + +<p>Examples:</p> + +<ul> + <li>Title: <em>AudioContext.state</em></li> + <li>Slug: <em>state</em></li> + <li>URL: <a href="/en-US/docs/Web/API/AudioContext/state">https://developer.mozilla.org/en-US/docs/Web/API/AudioContext/state</a></li> +</ul> + +<ul> + <li>Title: <em>AudioContext.onstatechange</em></li> + <li>Slug: <em>onstatechange</em></li> + <li>URL: <a href="/en-US/docs/Web/API/AudioContext/onstatechange">https://developer.mozilla.org/en-US/docs/Web/API/AudioContext/onstatechange</a></li> +</ul> + +<div class="note"> +<p><strong>Nota:</strong> Event handler properties are treated in the same way as regular properties; they are generally listed in a separate section on the interface page though.</p> +</div> + +<ul> +</ul> + +<h3 id="Páginas_de_método">Páginas de método</h3> + +<p>Each interface has zero or more methods, documented on subpages of the interface's page. each page describes the purpose of the method and shows what its syntax looks like, usage examples, browser compatibility information, etc. Its slug is the name of the method, and the title is interface name, dot, method name, then parentheses.</p> + +<p>Examples:</p> + +<ul> + <li>Title: <em>AudioContext.close()</em></li> + <li>Slug: <em>close</em></li> + <li>URL: <a href="/en-US/docs/Web/API/AudioContext/close">https://developer.mozilla.org/en-US/docs/Web/API/AudioContext/close</a></li> +</ul> + +<ul> + <li>Title: <em>AudioContext.createGain()</em></li> + <li>Slug: <em>createGain</em></li> + <li>URL: <a href="/en-US/docs/Web/API/AudioContext/createGain">https://developer.mozilla.org/en-US/docs/Web/API/AudioContext/createGain</a></li> +</ul> + +<h3 id="Páginas_de_evento">Páginas de evento</h3> + +<p>Each event handler property you create will have a corresponding event page, describing the event that causes the handler to fire, documented on a subpage of <a href="/en-US/docs/Web/Events">https://developer.mozilla.org/en-US/docs/Web/Events</a>. Each page describes the purpose of the event and shows what its syntax looks like, usage examples, browser compatibility information, etc. Its slug and title is the name of the event.</p> + +<p>Example:</p> + +<ul> + <li>Title: <em>statechange</em></li> + <li>Slug: <em>statechange</em></li> + <li>URL: <a href="/en-US/docs/Web/Events/statechange">https://developer.mozilla.org/en-US/docs/Web/Events/statechange</a></li> +</ul> + +<h3 id="Páginas_de_conceitoguia">Páginas de conceito/guia</h3> + +<p>Most API references have at least one guide and sometimes also a concept page to accompany it. At minimum, an API reference should contain a guide called "Using the <em>name-of-api</em>", which will provide a basic guide to how to use the API. More complex APIs may require multiple usage guides to explain how to use different aspects of the API.</p> + +<p>If required, you can also including a concepts article called "<em>name-of-api</em> concepts", which will provide explanation of the theory behind any concepts related to the API that developers should understand to effectively use it.</p> + +<p>These articles should all be created as subpages of the API overview page. For example, the Web Audio has four guides and a concept article:</p> + +<ul> + <li><a href="/en-US/docs/Web/API/Web_Audio_API/Using_Web_Audio_API">https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Using_Web_Audio_API</a></li> + <li><a href="/en-US/docs/Web/API/Web_Audio_API/Visualizations_with_Web_Audio_API">https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Visualizations_with_Web_Audio_API</a></li> + <li><a href="/en-US/docs/Web/API/Web_Audio_API/Web_audio_spatialization_basics">https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Web_audio_spatialization_basics</a></li> + <li><a href="/en-US/docs/Web/API/Web_Audio_API/Porting_webkitAudioContext_code_to_standards_based_AudioContext">https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Porting_webkitAudioContext_code_to_standards_based_AudioContext</a></li> + <li><a href="/en-US/docs/Web/API/Web_Audio_API/Basic_concepts_behind_Web_Audio_API">https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Basic_concepts_behind_Web_Audio_API</a></li> +</ul> + +<h3 id="Exemplos">Exemplos</h3> + +<p>You should create some examples that demonstrate at least the most common use cases of the API. You can put these anywhere that is appropriate, although the recommended place is the <a href="https://github.com/mdn/">MDN GitHub repo</a>.</p> diff --git a/files/pt-pt/mdn/structures/exemplos_live/index.html b/files/pt-pt/mdn/structures/exemplos_live/index.html new file mode 100644 index 0000000000..91295fc37c --- /dev/null +++ b/files/pt-pt/mdn/structures/exemplos_live/index.html @@ -0,0 +1,248 @@ +--- +title: Exemplos live +slug: MDN/Structures/Exemplos_live +tags: + - Estruturas + - Guia(2) + - Intermediário + - Metadados MDN +translation_of: MDN/Structures/Live_samples +--- +<div>{{MDNSidebar}}</div><p><span class="seoSummary">Exemplos MDN supports turning sample code displayed in articles into running samples the reader can look at in action. These live samples can include HTML, CSS, and JavaScript in any combination.</span> Note that "live" samples are <em>not interactive</em>; however, they do ensure that the output displayed for a sample matches the code of the sample exactly, because it is actually generated by the code sample.</p> + +<h2 id="Como_é_que_os_exemplos_live_funcionam">Como é que os exemplos <em>live </em>funcionam</h2> + +<p>The live sample system gathers up all the code in a group, merges it into one HTML file, and then renders that HTML in an {{HTMLElement("iframe")}}. A live sample therefore consists of two pieces:</p> + +<ul> + <li>A group of code blocks</li> + <li>The macro call that (creates the frame or the link that) displays the result of the code blocks</li> +</ul> + +<p>A "group" of code blocks, in this context, is identified by the ID of a heading or a block element (such as a {{HTMLElement("div")}}).</p> + +<ul> + <li>If the ID belongs to a block element, the group includes all the code blocks within the enclosing block element whose ID is used. </li> + <li>If the ID belongs to a heading, the group includes all the code blocks that are after that heading and before the next heading of the same heading level. Note that code blocks under subheadings of the specified heading are all used; if this is not the effect you want, use an ID on a block element instead.</li> +</ul> + +<p>The macro uses a special URL to fetch the sample code for a given group: <code>http://<em>url-of-page</em>$samples/<em>group-id</em></code>, where <code>group-id</code> is the ID of the heading or block where the code is located. The resulting frame (or page) is sandboxed, secure, and technically may do anything that works on the Web. Of course, as a practical matter, the code must contribute to the point of the page that contains it; random stuff running on MDN will be removed by the editor community.</p> + +<div class="note"> +<p><strong>Nota:</strong> You <strong>must</strong> use the macro for presenting the live sample's output. MDN's editor will strip out any direct use of the <code><iframe></code> element in order to ensure security.</p> +</div> + +<p>Each {{HTMLElement("pre")}} block containing code for the sample has a class on it that indicates whether it's HTML, CSS, or JavaScript code; these are "brush: html", "brush: css", and "brush: js". These classes must be on the corresponding blocks of code so that the wiki can use them correctly; fortunately, these are added for you automatically when you use the syntax highlighter features in the editor's toolbar.</p> + +<p>The live sample system has lots of options available, and we'll try to break things down to look at them a bit at a time.</p> + +<h3 id="Macros_de_exmplo_live">Macros de exmplo <em>live</em></h3> + +<p>There are two macros that you can use to display live samples:</p> + +<ul> + <li><span class="templateLink"><code><a href="/en-US/docs/Template:EmbedLiveSample">EmbedLiveSample</a> </code></span>embeds a live sample into a page</li> + <li><span class="templateLink"><code><a href="/en-US/docs/Template:LiveSampleLink">LiveSampleLink</a></code></span> creates a link that opens the live sample in a new page</li> +</ul> + +<p>In many cases, you may be able to add the <span class="templateLink"><code><a href="/en-US/docs/Template:EmbedLiveSample">EmbedLiveSample</a></code></span> or <span class="templateLink"><code><a href="/en-US/docs/Template:LiveSampleLink">LiveSampleLink</a></code></span> macro to pages with little or no additional work! As long as the sample can be identified by a heading's ID or is in a block with an ID you can use, simply adding the macro should do the job.</p> + +<h4 id="EmbedLiveSample_macro">EmbedLiveSample macro</h4> + +<pre class="syntaxbox notranslate"> \{{EmbedLiveSample(<em>block_ID</em>, <em>width</em>, <em>height</em>, <em>screenshot_URL</em>, <em>page_slug</em>)}}</pre> + +<dl> + <dt>block_ID</dt> + <dd>Required: The ID of the heading or enclosing block to draw the code from. The best way to be sure you have the ID right is to look at the URL of the section in the page's table of contents.</dd> + <dt>width</dt> + <dd>The width of the {{HTMLElement("iframe")}} to create, specified in <code>px</code>. This is optional; a reasonable default width will be used if you omit this. Note that if you want to use a specific width, you <em>must</em> also specify the height parameter.</dd> + <dt>height</dt> + <dd>The height of the {{HTMLElement("iframe")}} to create, specified in <code>px</code>. This is optional; a reasonable default height will be used if you omit this. Note that if you want to use a specific height, you <em>must</em> also specify the width parameter. If you use only one of them, the default frame size is used.</dd> + <dt>screenshot_URL</dt> + <dd>The URL of a screenshot that shows what the live sample should look like. This is optional, but can be useful for new technologies that may not work in the user's browser, so they can see what the sample would look like if it were supported by their browser. If you include this parameter, the screenshot is shown next to the live sample, with appropriate headings.</dd> + <dt>page_slug</dt> + <dd>The slug of the page containing the sample; this is optional, and if it's not provided, the sample is pulled from the same page on which the macro is used.</dd> +</dl> + +<ol> +</ol> + +<h4 id="LiveSampleLink_macro">LiveSampleLink macro</h4> + +<pre class="syntaxbox notranslate"> \{{LiveSampleLink(<em>block_ID</em>, <em>link_text</em>)}}</pre> + +<dl> + <dt>block_ID</dt> + <dd>The ID of the heading or enclosing block to draw the code from. The best way to be sure you have the ID right is to look at the URL of the section in the page's table of contents.</dd> + <dt>link_text</dt> + <dd>A string to use as the link text.</dd> +</dl> + +<h2 id="Utilizar_o_sistema_de_exemplo_live">Utilizar o sistema de exemplo <em>live</em></h2> + +<p>The sections below describe a few common use cases for the live sample system.</p> + +<p>In all of these cases, to see the results of the live sample, you must click <strong>Save Changes</strong> in the editor (which takes you out of edit mode). Because of the reflexive, <a href="http://www.imdb.com/title/tt1375666/?ref_=nv_sr_1"><em>Inception</em></a>-like nature of live samples, the <strong>Preview Changes</strong> functionality is <em>not</em> able to display live samples.</p> + +<h3 id="Turning_snippets_into_live_samples">Turning snippets into live samples</h3> + +<p>One common use case is to take existing code snippets already shown on MDN and turn them into live samples.</p> + +<h4 id="Preparar_os_exemplos_de_código">Preparar os exemplos de código</h4> + +<p>The first step is to either add code snippets or ensure that existing ones are ready to be used as live samples, in terms of the content and in terms of their mark-up. The code snippets, taken together, must comprise a complete, runnable example. For example, if the existing snippet shows only CSS, you might need to add a snippet of HTML for the CSS to operate on.</p> + +<p>Each piece of code must be in a {{HTMLElement("pre")}} block, with a separate block for each language, properly marked as to which language it is. Most of the time, this has already been done, but it's always worth double-checking to be sure each piece of code is configured with the correct syntax. Next to the <strong>PRE</strong> icon in the toolbar is a drop-down menu icon (tooltip: Syntax Highlighter) with the various languages that MDN does syntax highlighting for. Setting the language for the block for syntax highlighting also correlates it with a language for the purposes of the live sample system.</p> + +<div class="note"> +<p><strong>Nota:</strong> You may have more than one block for each language; they are all concatenated together. This lets you have a chunk of code, followed by an explanation of how it works, then another chunk, and so forth. This makes it even easier to produce tutorials and the like that utilize live samples interspersed with explanatory text.</p> +</div> + +<p>So make sure the {{HTMLElement("pre")}} blocks for your HTML, CSS, and/or JavaScript code are each configured correctly for that language's syntax highlighting, and you're good to go.</p> + +<div class="note"> +<p><strong>Nota:</strong> When pasting content into MDN, please be aware that if pasting styled content (including, for example, syntax highlighting in code being copied from another site) that you may be bringing along unwanted and unneeded additional styles or classes. Please be careful not to do this; if necessary, review your edit in source mode to remove these unnecessary styles and classes (or check it before pasting, or use the "Paste as plain text" option instead).</p> +</div> + +<h4 id="Inserir_a_macro_de_exemplo_live">Inserir a macro de exemplo <em>live</em></h4> + +<p>Once the code is in place and properly configured to identify each block's language, you need to insert the macro that creates the iframe.</p> + +<ol> + <li>Click the <strong>Insert Live Code Sample iFrame</strong> button in the toolbar; it looks like this: <img alt="" src="https://mdn.mozillademos.org/files/5383/insert-live-sample-btn.png" style="height: 18px; width: 19px;">. This opens a dialog box for configuring your live sample frame:<img alt="" src="https://mdn.mozillademos.org/files/5385/sample-finder.png" style="height: 358px; width: 405px;"></li> + <li>Under <strong>Document</strong>, enter the title of the article that contains the sample you wish to embed. By default, it's the article you're currently editing, but you can choose an article elsewhere on MDN, too. This makes it possible to reuse samples on multiple pages if needed. (If you type new text in this field, a menu of partially matching pages appears; select the title of the page you want.)</li> + <li>In the <strong>Sections in Document</strong> menu, select the section in the article that contains the code blocks of the sample you want to embed.</li> + <li>Click the <strong>OK</strong> button to generate and insert the macro call that creates the sample frame for you. The macro call looks something like this:<br> + <strong>\{{ EmbedLiveSample('Live_sample_demo') }}</strong></li> +</ol> + +<h3 id="Adicionar_um_novo_exemplo_live">Adicionar um novo exemplo <em>live</em></h3> + +<p>If you're writing a new page, and want to insert code that you want to present as a live sample, even more of the work can be done for you by the editor! </p> + +<ol> + <li>Click the <strong>Insert Code Sample Template</strong> button in the toolbar, which looks like this: <img alt="" src="/files/4265/live-sample-button.png" style="height: 19px; width: 21px;">. This presents a simple dialog asking you to name your live sample:<br> + <img alt="" src="https://mdn.mozillademos.org/files/5387/insert-live-sample-template.png" style="height: 155px; width: 251px;"></li> + <li>Enter the title of the sample; this is used as the heading for the sample. Make sure that your title makes sense within the context of the page you're on.</li> + <li>Click <strong>OK</strong>. A new heading with the title you entered is created, with sub-headings and empty code blocks for HTML, CSS, and JavaScript.</li> + <li>Delete any headings and code blocks you don't need.</li> + <li>Enter the code that makes up your sample in the appropriate code blocks</li> + <li><a href="#conventions">Check conventions</a></li> +</ol> + +<h3 id="Utilizar_o_Localizador_de_Exemplo">Utilizar o 'Localizador de Exemplo'</h3> + +<p>As mentioned above, the Sample Finder is activated by clicking the<strong> Insert Live Code Sample iFrame</strong> icon. Unfortunately the the Sample Finder may produce a macro that is NOT usable without editing. There are two problem areas that should be carefully checked and edited if necessary.</p> + +<ol> + <li><strong>Document </strong>field. This field will search as you type and present a list of documents that match your string. But the list presented will NOT include the sub-page. For example, say you are working on the subpage for <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/@counter-style/negative">Negative </a>under the main page <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/@counter-style">@counter-style</a>. The Sample Finder search will not find Negative but will find the main page @counter-style. When @counter-style is selected the field background turns green. See below for the issue this creates.</li> + <li><strong>Sections in Document</strong>. The pull-down menu Sections in Document may not show the section that you need. Just pick one, say Examples, and it can be fixed with a simple edit.</li> +</ol> + +<p>Here is what the Sample Finder produced:</p> + +<pre class="notranslate"><code>\{{ EmbedLiveSample('Examples', '', '', '', 'Web/CSS/@counter-style') }}</code></pre> + +<p>This macro will not work. The block_ID is Examples and it should be Example in this case (check the source ID for this section to verify which block_ID you need to use. Similarly the page_slug is @counter-style and it should be @counter-style/negative. These corrections can be done directly in the page with Edit active.</p> + +<p>After editing the macro now looks like this:</p> + +<pre class="notranslate"><code>\{{ EmbedLiveSample('Example', '', '', '', 'Web/CSS/@counter-style/negative') }}</code></pre> + +<p>This edited macro will work correctly. If the macro is working correctly you will see the <strong>Open in CodePen</strong> button. A thumbnail of the example should appear above the Open in CodePen button. If the button is there but there isn't a thumbnail, just wait a few minutes. It may take some time for the server to generate it.</p> + +<h2 id="Live_sample_demo" name="Live_sample_demo">Encontrar exemplos que precisam de ser atualizados</h2> + +<p>When looking for existing samples to update, there are three main kinds of updating you may wish to do:</p> + +<ul> + <li>Turn an existing non-live example snippet into a live sample.</li> + <li>Correct bugs in an existing live sample.</li> + <li>Improve an existing live sample, or update a sample based on technology changes.</li> +</ul> + +<div class="note"> +<p><strong>Note</strong><strong>:</strong> If you find an article that has samples in need of being updated to use the live sample system, please add the tag "NeedsLiveSample" to the page.</p> +</div> + +<h3 id="Encontrar_exemplos_para_os_transformnar_em_exemplos_live">Encontrar exemplos para os transformnar em exemplos <em>live</em></h3> + +<p>MDN has lots of older examples that don't yet use the live sample system. Our goal is to update most or all of these to be live samples. This will improve consistency and usability. You will almost certainly find many of these as you use MDN on a daily basis; however, how can you find them if you're specifically looking for them to update? Unfortunately, there's not an easy way to do that. But there are some guidelines you can follow to help track them down:</p> + +<ul> + <li>Start by looking at this <a href="/en-US/docs/tag/NeedsLiveSample" title="/en-US/docs/tag/NeedsLiveSamples">list of pages tagged with "NeedsLiveSample"</a>. These are pages that users have marked as needing updating. You should add this tag yourself, if you see a page that needs to be updated to use live samples but don't have time to fix right away.</li> + <li>Browse through documentation trees that are likely to include examples, such as the <a href="/en-US/docs/Web/JavaScript/Guide" title="/en-US/docs/Web/JavaScript/Guide">JavaScript Guide</a>, <a href="/en-US/docs/Web/HTML" title="/en-US/docs/Web/HTML">HTML documentation</a>, and <a href="/en-US/docs/Web/CSS/Reference" title="/en-US/docs/Web/CSS/Reference">CSS reference</a>.</li> + <li>Search for terms like "<a href="/en-US/search?q=example" title="/en-US/search?q=example">example</a>" or "<a href="/en-US/search?q=sample" title="/en-US/search?q=sample">sample</a>" and look through the results for pages to update.</li> +</ul> + +<h2 id="Live_sample_demo" name="Live_sample_demo">Demonstração de exemplo <em>live</em></h2> + +<p>This section is the result of using the live sample template button to create not only the main heading ("Live sample demo"), but also subheadings for our HTML, CSS, and JavaScript content. You're not limited to one block of each; in addition, they don't even need to be in any particular order. Mix and match!</p> + +<p>You may choose to delete any of these you wish; if you don't need any script, just delete that heading and its {{HTMLElement("pre")}} block. You can also delete the heading for a code block ("HTML", "CSS", or "JavaScript"), since these are not used by the live sample macro.</p> + +<p>Now that the template has been inserted, we can put in some code, and even some explanatory text.</p> + +<h3 id="HTML">HTML</h3> + +<p>This HTML creates a paragraph and some blocks to help us position and style a message.</p> + +<pre class="brush: html notranslate"><p>A simple example of the live sample system in action.</p> +<div class="box"> + <div id="item">Hello world!</div> +</div> +</pre> + +<h3 id="CSS">CSS</h3> + +<p>The CSS code styles the box as well as the text inside it.</p> + +<pre class="brush: css notranslate">.box { + width: 200px; + height: 100 px; + border-radius: 6px; + background-color: #ffaabb; +} + +#item { + width: 100%; + font-weight: bold; + text-align: center; + font-size: 2em; +} +</pre> + +<h3 id="JavaScript">JavaScript</h3> + +<p>This code is very simple. All it does is attach an event handler to the "Hello world!" text that makes an alert appear when it is clicked.</p> + +<pre class="brush: js notranslate">var el = document.getElementById('item'); +el.onclick = function() { + alert('Owww, stop poking me!'); +} +</pre> + +<h3 id="Resultado">Resultado</h3> + +<p>Here is the result of running the code blocks above via<code> \{{EmbedLiveSample('Live_sample_demo')}}</code>:</p> + +<p>{{EmbedLiveSample('Live_sample_demo')}}</p> + +<p>Here is a link that results from calling these code blocks via <code>\{{LiveSampleLink('Live_sample_demo', 'Live sample demo link')}}</code>:</p> + +<p>{{LiveSampleLink('Live_sample_demo', 'Live sample demo link')}}</p> + +<h2 id="Convenções_sobre_exemplos_live"><a id="conventions" name="conventions">Convenções sobre exemplos <em>live</em></a></h2> + +<div class="note"> +<p><strong>Nota:</strong> This is currently (Feb. 2016) under discussion on the dev-mdc mailing list (see <a href="https://groups.google.com/forum/#!topic/mozilla.dev.mdc/49oqJAHFnWQ">this thread</a>). Any input is welcome. If this note persists after some month (Apr. 2016), please reach the author of the first email in this thread for updating this page.</p> +</div> + +<dl> + <dt>Ordem dos blocos de código</dt> + <dd>When adding a live sample, the code blocks should be sorted so that the first one corresponds to the main language for this sample (if there is one). For example, when adding a live sample for the HTML Reference, the first block should be HTML, when adding a live sample for the CSS Reference, it should be CSS and so on.</dd> + <dt>Nomeação de cabeçalhos</dt> + <dd>When there is no ambiguity (e.g. the sample is under a "Examples" section), headings should be straightforward with the sole name of the corresponding language: HTML, CSS, JavaScript, SVG, etc. (see above). Headings like "HTML Content" or "JavaScript Content" should not be used. However if such a short heading makes content unclear, one can use a more thoughtful title.</dd> + <dt>Utilizar um bloco de "Resultado"</dt> + <dd>After the different code blocks, please use a last "Result" block before using the <code>EmbedLiveSample</code> macro (see above). This way, the semantic of the example is made clearer for both the reader and any tools that would parse the page (e.g. screen reader, web crawler).</dd> +</dl> diff --git a/files/pt-pt/mdn/structures/index.html b/files/pt-pt/mdn/structures/index.html new file mode 100644 index 0000000000..b8df701dac --- /dev/null +++ b/files/pt-pt/mdn/structures/index.html @@ -0,0 +1,16 @@ +--- +title: Document structures +slug: MDN/Structures +tags: + - Landing + - MDN Meta + - NeedsTranslation + - Structures + - TopicStub +translation_of: MDN/Structures +--- +<div>{{MDNSidebar}}</div><div>{{IncludeSubnav("/en-US/docs/MDN")}}</div> + +<p>Throughout MDN, there are various document structures that are used repeatedly, to provide consistent presentation of information in MDN articles. Here are articles describing these structures, so that, as an MDN author, you can recognize, apply, and modify them as appropriate for documents you write, edit, or translate.</p> + +<p>{{LandingPageListSubPages()}}</p> diff --git a/files/pt-pt/mdn/structures/macros/index.html b/files/pt-pt/mdn/structures/macros/index.html new file mode 100644 index 0000000000..984483ee1e --- /dev/null +++ b/files/pt-pt/mdn/structures/macros/index.html @@ -0,0 +1,46 @@ +--- +title: Macros +slug: MDN/Structures/Macros +tags: + - Estruturas + - Guía + - Kuma + - KumaScript + - Metadados MDN +translation_of: MDN/Structures/Macros +--- +<div>{{MDNSidebar}}</div><p><span class="seoSummary">A plataforma <a href="/en-US/docs/Project:MDN/Kuma" title="/en-US/docs/Project:MDN/Kuma">Kuma</a> </span> na qual a MDN é executada, fornece um sistema de macro poderoso, <span class="seoSummary"><a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Tools/KumaScript" title="/en-US/docs/Project:MDN/Kuma/KumaScript_guide">KumaScript</a>,</span> que torna possível realizar uma grande variedade de coisas automaticamente. Este artigo fornece informação sobre como invocar as macros da MDN dentro dos artigos<span class="seoSummary">.</span></p> + +<p>O <a href="/en-US/docs/MDN/Contribute/Tools/KumaScript" title="/en-US/docs/Project:MDN/Kuma/KumaScript_guide">guia de KumaScript</a> fornece uma visão detalhada de como utilizar as macros na MDN, deste modo, esta secção é mais um breve resumo.</p> + +<h2 id="Como_as_macros_são_implementadas">Como as macros são implementadas</h2> + +<p>Macros on MDN are implemented using server-executed <a href="/en-US/docs/Web/JavaScript" title="/en-US/docs/Web/JavaScript">JavaScript</a> code, interpreted using <a href="https://nodejs.org/en/" title="https://nodejs.org/en/">Node.js</a>. On top of that we have a number of libraries we've implemented that provide wiki-oriented services and features to let macros interact with the wiki platform and its contents. If you're interested in learning more, see the <a href="/en-US/docs/MDN/Contribute/Tools/KumaScript" title="/en-US/docs/Project:MDN/Kuma/KumaScript_guide">KumaScript guide</a>.</p> + +<h2 id="Utilização_uma_macro_no_conteúdo">Utilização uma macro no conteúdo</h2> + +<p>To actually use a macro, you simply enclose the call to the macro in a pair of double-braces, with its parameters, if any, enclosed in parentheses; that is:</p> + +<pre class="notranslate">\{{macroname(parameter-list)}}</pre> + +<p>A few notes about macro calls:</p> + +<ul> + <li>Macro names are case-sensitive, but some attempt is made to correct for common capitalization errors; you may use all lowercase even if the macro name uses caps within it, and you may capitalize a macro whose name normally starts with a lower-case letter.</li> + <li>Parameters are separated by commas.</li> + <li>If there are no parameters, you may leave out the parentheses entirely; <code>\{{macroname()}}</code> and <code>\{{macroname}}</code> are identical.</li> + <li>Numeric parameters can be in quotes, or not. It's up to you (however, if you have a version number with multiple decimals in it, it needs to be in quotes).</li> + <li>If you get errors, review your code carefully. If you still can't figure out what's going on, see <a href="/en-US/docs/MDN/Kuma/Troubleshooting_KumaScript_errors">Troubleshooting KumaScript errors</a> for help.</li> +</ul> + +<p>Macros are heavily cached; for any set of input values (both parameters and environmental values such as the URL for which the macro was run), the results are stored and reused. This means that the macro is only actually run when the inputs change.</p> + +<div class="note"> +<p><strong>Nota:</strong> You can force all the macros on a page to be re-evaluated by force-refreshing the page in your browser (that is, a shift-reload).</p> +</div> + +<p>Macros can be as simple as just inserting a larger block of text or swapping in contents from another part of MDN, or as complex as building an entire index of content by searching through parts of the site, styling the output, and adding links.</p> + +<p>You can read up on our most commonly-used macros on the <a href="/en-US/docs/MDN/Contribute/Structures/Macros/Commonly-used_macros" title="/en-US/docs/Project:MDN/Contributing/Custom_macros">Commonly-used macros</a> page; also, there's a <a href="https://developer.mozilla.org/en-US/docs/templates" title="https://developer.mozilla.org/en-US/docs/templates">complete list of all macros</a> here. Most macros have documentation built into them, as comments at the top.</p> + +<p>{{EditorGuideQuicklinks}}</p> |