Page "Proposals/BEP-0007" was changed by antonia.horincar Diff URL: <https://issues.apache.org/bloodhound/wiki/Proposals/BEP-0007?action=diff&version=2> Revision 2 Changes: -------8<------8<------8<------8<------8<------8<------8<------8<-------- Index: Proposals/BEP-0007 ========================================================================= --- Proposals/BEP-0007 (version: 1) +++ Proposals/BEP-0007 (version: 2) @@ -1,86 +1,82 @@ --placeholder for Antonia's proposal- - -= BEP <BEP number> : <BEP title> #overview += BEP 7 : Embeddable tickets/objects #overview [[PageOutline]] -|| '''BEP''' || <BEP number> || -|| '''Title''' || <BEP title> || -|| '''Version''' || <leave blank> || -|| '''Last-Modified''' || <leave blank> || -|| '''Author''' || Author With Email <[email protected]>, Author Name Only, or The Bloodhound project (see [wiki:/Proposals#bep-header-preamble BEP preamble explained]) || +|| '''BEP''' || 7 || +|| '''Title''' || Embeddable tickets/objects || +|| '''Version''' || || +|| '''Last-Modified''' || || +|| '''Author''' || Antonia Horincar <[email protected]> || || '''Status''' || Draft || -|| '''Type''' || <BEP type (see [wiki:/Proposals#bep-types BEP types explained])> || +|| '''Type''' || Standards Track || || '''Content-Type''' || [wiki:PageTemplates/Proposals text/x-trac-wiki] || -|| '''Created''' || <leave blank> || -|| '''Post-History''' || <leave blank> || +|| '''Created''' || || +|| '''Post-History''' || || ---- + + == Abstract #abstract -<Delete text in this section and add a short (~200 word) description of the technical issue being addressed. Take a look at sample abstract below> -This template provides a boilerplate or sample template for creating your -own BEPs. In conjunction with the [wiki:/Proposals general content guidelines] and the [wiki:/Proposals/Formats/WikiFormatting WikiFormatting BEP guidelines] -, this should make it easy for you to conform your own -BEPs to the format outlined below. See [#howto How to Use This Template] for further instructions. +Being able to reference tickets or other objects in a clear, nice manner would be a great feature for the application, as many users share content on external websites. Posting a plain link requires other users to follow it individually, which isn’t very engaging for them. Also, posting the static content of the objects is not a good solution as the states of the object change very often, and the description becomes outdated. -**Note**: if you are reading this template via the web, you should first try to create a new wiki page by selecting `ProposalsRst` |page template guide|. **DO NOT EDIT THIS WIKI PAGE IN ORDER TO CREATE A NEW BEP! ** -If you would prefer not to use WikiFormatting markup in your BEP, please see [wiki:/Proposals/Formats/RestructuredText reStructuredText BEP guidelines]. - -== Motivation == - -<The motivation is critical for BEPs that want to change the copy of ''Trac'' patched using vendor branch . It should clearly explain why the existing ''Bloodhound'' solution is inadequate to address the problem that the ''BEP'' solves. ''BEP'' submissions without sufficient motivation may be rejected outright. > == Proposal #proposal -<The technical specification should describe any new features , detail its impact on the components architecture , mention what plugins will be included as a result , whether they are hosted by [http://trac-hacks.org trac-hacks.org] or not , and any other relevant technical subject . The specification should be detailed enough to allow competing, interoperable implementations for any of the current supported database platforms (e.g. ''SQLite'', ''Postgres'', ''MySQL'') and server technologies (e.g. ''Apache HTTPD server'', ''nginx'', ''mod_wsgi'', ''CGI'').. > + +The implementation of the project can be splitted into two distinct parts, the front-end part, and the back-end part. + +The front-end side of the project will include generating the HTML snippet of embeddable code. Similarly to other websites like Twitter and !YouTube, there will be an “Embed object” button. Clicking the button will bring up a pop-up containing the HTML snippet that can be copied and later pasted into an external website. + +The front-end of the application will be coded using !JavaScript. Since most of Bloodhound’s design is done using the Twitter Bootstrap framework, the pop-up displaying the code can also be designed using Twitter Bootstrap. The embeddable HTML code, and the URL within the iframe tag will be generated based on the resource’s type and unique id. + +For instance, the HTML snippet “<iframe width="260" height="515" src="!https://bh-demo2.apache.org/embed/ticket/273"; frameborder="0"></iframe>” would be an example of how the HTML embeddable code will look like. This snippet embeds the ticket with the unique id 273. There are also other attributes that can be added based on the user’s choice. + +The back end side of the project will consist of building a REST API for interacting with the objects from external sources. The IRequestHandler interface will be extended by a class that will match, process and deal with the information retrieved. Several other interfaces, such as IPermissionRequestor (for checking what the permissions for a specific ticket/object are) and ITemplateProvider might need to be extended as well. + +Ideally the system could display any arbitrary Bloodhound widgets, so some of the previous code used for developing Bloodhound widgets can be reused. The Bloodhound widgets can currently be displayed by their name (e.g. !TicketQuery, !WidgetDoc, etc.), and some possible parameters (e.g. query=”status=opened”). The solution described above can be extended to be more generic. All kinds of widgets could be embedded using iframe tags presented in the previous paragraphs. + + == Rationale #rationale -<The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other issue trackers or ''Trac'' hacks . The rationale should provide evidence of consensus within the community and discuss important objections or concerns raised during discussion. Take a look at sample rationale below> -''BEP'' submissions come in a wide variety of forms, not all adhering to the format guidelines set forth below. Use this template, in conjunction with the [wiki:/Proposals general content guidelines] and the [wiki:/Proposals/Formats/WikiFormatting WikiFormatting BEP guidelines], to ensure that your ''BEP'' submission is easy to read and understand. +When considering embedding objects, there are more solutions possible, each of them having its advantages and drawbacks. -This template allows to create BEPs and is very similar to [http://www.python.org/dev/peps/pep-0012 PEP 12] . However it has been optimized by moving long explanations to the [wiki:/Proposals/Formats/WikiFormatting WikiFormatting BEP guidelines] . If you are interested take a look at the [?action=diff&old_version=1 differences]. The goal is to redact new BEPs just by following in-line instructions between angle brackets (i.e. **<** **>**) . Even if this will allow to write BEPs faster , it is highly recommended to read the [wiki:/Proposals/Formats/WikiFormatting WikiFormatting BEP guidelines] at least once in your lifetime to be aware of good practices and expected style rules . +One of the possible solutions would be the one used by Twitter, which is generating an HTML snippet containing the plain content of the embedded ticket or object. This way, static information about the objects is generated, and later passed to external websites. The advantage of this approach is that minimum changes on the back-end are needed, as the snippet is generated through !JavaScript. The drawback is that the content is static and does not change when the referenced object is updated. -== How to Use This Template #howto +Another possible solution would be using AJAX (Asynchronous !JavaScript And XML) to retrieve the state of the embeddable objects. The HTML snippet would have a script tag containing the !JavaScript code which retrieves the information. Even though the content would be updated every time, this approach has a series of drawbacks. Since the browsers do not allow AJAX calls on external websites, the information about the objects would need to be retrieved using a JSONP approach. Even if this would solve the problem, it still has security concerns, as it allows external malicious code to be executed on the host server. -<BEPs may include further sections. This is an example.> +The solution that best fits the requirements is using iframe tags in order to include elements from an external website, this approach being used by many web applications, like !YouTube or Kickstarter. By generating iframe tags when a user chooses to embed an object, the content will always be up to date because when the page loads the object will be retrieved from Bloodhound’s website. This method allows posting an embeddable object on external websites or services without implying major security issues. -Quick edits will consist in following the instructions inside angle brackets (i.e. **<** **>**) . That should be everything needed to write new BEPs. To be more informed about advanced considerations please read the [wiki:/Proposals general content guidelines] and the [wiki:/Proposals/Formats/WikiFormatting WikiFormatting BEP guidelines] . If there is no point in including one of the sections in this document then feel free to remove it. +This solution fulfils the requirements presented in the project brief, as the embedded objects can be seen on external websites and their content is not static because it changes when the state of the objects. It is also a safe solution for both the external website and Bloodhound’s website. -== Backwards Compatibility #backwards-compatibility -<All BEPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The ''BEP'' must explain how to deal with these incompatibilities. ''BEP'' submissions without a sufficient backwards compatibility treatise may be rejected outright. > - -== Reference Implementation #reference-implementation - -< The reference implementation **must** be completed before any ''BEP'' is given status **Final**, but it need not be completed before the ''BEP'' is accepted. It is better to finish the specification and rationale first and reach consensus on it before writing code. The final implementation **must** include test code and documentation appropriate for either the wiki pages in ''Bloodhound'' users guide or an specific wiki page in the [http://issues.apache.org/bloodhound issue tracker] . > == Resources #resources -<Provide links to useful resources related to the subject discussed. See sample text below> -See WikiFormatting for more help on the markup used to write wiki pages. +Bloodhound Widgets: https://issues.apache.org/bloodhound/wiki/BloodhoundWidgets + + == References #references -<List the references included in BEP body> - 1. PEP 1, PEP Purpose and Guidelines, Warsaw, Hylton - http://www.python.org/dev/peps/pep-0001/ - 2. PEP 9, Sample Plaintext PEP Template, Warsaw - http://www.python.org/dev/peps/pep-0009 - 2. PEP 12, Sample reStructuredText ''PEP'' Template, Goodger, Warsaw - http://www.python.org/dev/peps/pep-0012/ - 3. http://www.opencontent.org/openpub/ +1. IRequestHandler interface + http://trac.edgewall.org/wiki/TracDev/PluginDevelopment/ExtensionPoints/trac.web.api.IRequestHandler +2. IPermissionRequestor interface + http://trac.edgewall.org/wiki/TracDev/PluginDevelopment/ExtensionPoints/trac.perm.IPermissionRequestor +3. ITemplateProvider interface + http://trac.edgewall.org/wiki/TracDev/PluginDevelopment/ExtensionPoints/trac.web.chrome.ITemplateProvider + + == Copyright #copyright -<In this section all licensing issues should be meticulously exposed . Library and plugin dependencies are among the most important topics . On the other hand each BEP will be explicitly labelled with a copyright statement like shown below, so should not change that. Requests for a different copyright statement have to be posted to [email protected] . For more details consult [wiki:/Proposals#what-belongs-in-a-successful-bep BEP structure explained] .> Copyright © 2009-2012 The [http://www.apache.org Apache Software Foundation] [[BR]] Licensed under the [http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0]. -------8<------8<------8<------8<------8<------8<------8<------8<--------
-- Page URL: <https://issues.apache.org/bloodhound/wiki/Proposals/BEP-0007> Apache Bloodhound <https://issues.apache.org/bloodhound/> The Apache Bloodhound issue tracker This is an automated message. Someone added your email address to be notified of changes on 'Proposals/BEP-0007' page. If it was not you, please report to .
